From 2c686b35e46fc6c4243e2d4c0092202bd69afdef Mon Sep 17 00:00:00 2001 From: David Pine Date: Tue, 14 May 2024 13:59:40 -0500 Subject: [PATCH 1/8] Add troubleshooting content --- docs/toc.yml | 4 +++ .../unable-to-install-workload.md | 19 +++++++++++ .../untrusted-localhost-certificate.md | 33 +++++++++++++++++++ 3 files changed, 56 insertions(+) create mode 100644 docs/troubleshooting/unable-to-install-workload.md create mode 100644 docs/troubleshooting/untrusted-localhost-certificate.md diff --git a/docs/toc.yml b/docs/toc.yml index bc6f337b4d..9e359a0145 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -203,6 +203,10 @@ items: - name: Allow unsecure transport displayName: unsecure transport,http,non-tls href: troubleshooting/allow-unsecure-transport.md + - name: Untrusted localhost certificate + href: troubleshooting/untrusted-localhost-certificate.md + - name: Unable to install .NET Aspire workload + href: troubleshooting/unable-to-install-workload.md - name: .NET Aspire GitHub repository href: https://github.com/dotnet/aspire - name: Discord diff --git a/docs/troubleshooting/unable-to-install-workload.md b/docs/troubleshooting/unable-to-install-workload.md new file mode 100644 index 0000000000..53f7593f13 --- /dev/null +++ b/docs/troubleshooting/unable-to-install-workload.md @@ -0,0 +1,19 @@ +--- +title: Troubleshoot installing the .NET Aspire workload +description: Explore strategies for troubleshooting issues when installing the .NET Aspire workload. +ms.date: 05/14/2024 +--- + +# Troubleshoot installing the .NET Aspire workload + +This article provides guidance on how to troubleshoot issues that you might encounter when installing the .NET Aspire workload. + +## Symptoms + +When you install the .NET Aspire workload, you might encounter an installation error. The error message might indicate that the installation failed, or that the workload couldn't be installed. The error message might also indicate that a package source is unavailable, or that a package source is not found. + +## Possible solution + +Ensure that any recursive _Nuget.config_ files are correctly configured to specify the correct package sources and NuGet feeds. For example, if you have a _Nuget.config_ file in your user profile directory, ensure that it doesn't specify a package source that is no longer available. + + \ No newline at end of file diff --git a/docs/troubleshooting/untrusted-localhost-certificate.md b/docs/troubleshooting/untrusted-localhost-certificate.md new file mode 100644 index 0000000000..bb7c3a53ab --- /dev/null +++ b/docs/troubleshooting/untrusted-localhost-certificate.md @@ -0,0 +1,33 @@ +--- +title: Troubleshoot untrusted localhost certificate in .NET Aspire +description: Explore strategies for troubleshooting issues when working with untrusted localhost certificates in .NET Aspire. +ms.date: 05/14/2024 +--- + +# Troubleshoot untrusted localhost certificate in .NET Aspire + +This article provides guidance on how to troubleshoot issues that you might encounter when working with untrusted localhost certificates in .NET Aspire. + +## Symptoms + +Several .NET Aspire templates include ASP.NET Core projects that are configured to use HTTPS by default. If this is the first time you're running the project, ASP.NET Core prompts you to install a localhost certificate. There are situations in which you trust/install the development certificate, but you don't close all your browser windows. + +## Possible solution + +Close all browser windows. Then attempt to resolve this issue by trusting the self-signed development certificate. To trust the certificate, run the following commands. First, remove the existing certificates: + +```dotnetcli +dotnet dev-certs https --clean +``` + +Next, trust the certificate: + +```dotnetcli +dotnet dev-certs https --trust +``` + +## See also + +- [Trust the ASP.NET Core HTTPS development certificate on Windows and macOS](/aspnet/core/security/enforcing-ssl#trust-the-aspnet-core-https-development-certificate-on-windows-and-macos) +- [Trust HTTPS certificate on Linux](/aspnet/core/security/enforcing-ssl##trust-https-certificate-on-linux) +- [.NET CLI: dotnet dev-certs](/dotnet/core/tools/dotnet-dev-certs) From 9768efeed272e379159b885eadcd78d6c592fa01 Mon Sep 17 00:00:00 2001 From: David Pine Date: Tue, 14 May 2024 14:06:50 -0500 Subject: [PATCH 2/8] Add a few links --- docs/troubleshooting/unable-to-install-workload.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/troubleshooting/unable-to-install-workload.md b/docs/troubleshooting/unable-to-install-workload.md index 53f7593f13..9f60f5400e 100644 --- a/docs/troubleshooting/unable-to-install-workload.md +++ b/docs/troubleshooting/unable-to-install-workload.md @@ -16,4 +16,9 @@ When you install the .NET Aspire workload, you might encounter an installation e Ensure that any recursive _Nuget.config_ files are correctly configured to specify the correct package sources and NuGet feeds. For example, if you have a _Nuget.config_ file in your user profile directory, ensure that it doesn't specify a package source that is no longer available. - \ No newline at end of file + + +## See also + +- [NuGet: nuget.config reference](/nuget/reference/nuget-config-file) +- [.NET CLI: dotnet workload install](/dotnet/core/tools/dotnet-workload-install) From 8ad72989e8219b5ec8fa2532cd86c73667be8a72 Mon Sep 17 00:00:00 2001 From: David Pine Date: Tue, 14 May 2024 14:08:58 -0500 Subject: [PATCH 3/8] Link to troubleshooting from setup and get started --- docs/fundamentals/setup-tooling.md | 4 ++++ docs/get-started/build-your-first-aspire-app.md | 1 + 2 files changed, 5 insertions(+) diff --git a/docs/fundamentals/setup-tooling.md b/docs/fundamentals/setup-tooling.md index af83cae861..1f40e1c20f 100644 --- a/docs/fundamentals/setup-tooling.md +++ b/docs/fundamentals/setup-tooling.md @@ -282,3 +282,7 @@ Once you've created a new .NET Aspire project, you run and debug the app, steppi :::image type="content" source="media/setup-tooling/vscode-debugging.png" lightbox="media/setup-tooling/vscode-debugging.png" alt-text="A screenshot showing how to debug a .NET Aspire project in Visual Studio Code."::: :::zone-end + +## See also + +- [Unable to install .NET Aspire workload](../troubleshooting/unable-to-install-workload.md) diff --git a/docs/get-started/build-your-first-aspire-app.md b/docs/get-started/build-your-first-aspire-app.md index ca1afaf7ff..1b8a06df47 100644 --- a/docs/get-started/build-your-first-aspire-app.md +++ b/docs/get-started/build-your-first-aspire-app.md @@ -198,3 +198,4 @@ For more information, see [Make HTTP requests with the `HttpClient`](/dotnet/fun - [.NET Aspire service defaults](../fundamentals/service-defaults.md) - [Health checks in .NET Aspire](../fundamentals/health-checks.md) - [.NET Aspire telemetry](../fundamentals/telemetry.md) +- [Troubleshoot untrusted localhost certificate in .NET Aspire](../troubleshooting/untrusted-localhost-certificate.md) From 82970ee21beb5dcb1ee8101a00d13c96affbbb1c Mon Sep 17 00:00:00 2001 From: David Pine Date: Wed, 15 May 2024 09:05:54 -0500 Subject: [PATCH 4/8] Update a bit of the text to add some clarification --- .../unable-to-install-workload.md | 6 +++--- .../untrusted-localhost-certificate.md | 21 ++++++++++++++----- 2 files changed, 19 insertions(+), 8 deletions(-) diff --git a/docs/troubleshooting/unable-to-install-workload.md b/docs/troubleshooting/unable-to-install-workload.md index 9f60f5400e..6570e999c9 100644 --- a/docs/troubleshooting/unable-to-install-workload.md +++ b/docs/troubleshooting/unable-to-install-workload.md @@ -1,7 +1,7 @@ --- title: Troubleshoot installing the .NET Aspire workload description: Explore strategies for troubleshooting issues when installing the .NET Aspire workload. -ms.date: 05/14/2024 +ms.date: 05/15/2024 --- # Troubleshoot installing the .NET Aspire workload @@ -10,11 +10,11 @@ This article provides guidance on how to troubleshoot issues that you might enco ## Symptoms -When you install the .NET Aspire workload, you might encounter an installation error. The error message might indicate that the installation failed, or that the workload couldn't be installed. The error message might also indicate that a package source is unavailable, or that a package source is not found. +When you install the .NET Aspire workload, you might encounter an installation error. The error message might indicate that the installation failed, or that the workload couldn't be installed. The error message might also indicate that a package source is unavailable, or that a package source isn't found. ## Possible solution -Ensure that any recursive _Nuget.config_ files are correctly configured to specify the correct package sources and NuGet feeds. For example, if you have a _Nuget.config_ file in your user profile directory, ensure that it doesn't specify a package source that is no longer available. +Ensure that any recursive _Nuget.config_ files are configured to specify the correct package sources and NuGet feeds. For example, if you have a _Nuget.config_ file in your user profile directory, ensure that it doesn't specify a package source that is no longer available. diff --git a/docs/troubleshooting/untrusted-localhost-certificate.md b/docs/troubleshooting/untrusted-localhost-certificate.md index bb7c3a53ab..7540b6cd10 100644 --- a/docs/troubleshooting/untrusted-localhost-certificate.md +++ b/docs/troubleshooting/untrusted-localhost-certificate.md @@ -1,7 +1,7 @@ --- title: Troubleshoot untrusted localhost certificate in .NET Aspire description: Explore strategies for troubleshooting issues when working with untrusted localhost certificates in .NET Aspire. -ms.date: 05/14/2024 +ms.date: 05/15/2024 --- # Troubleshoot untrusted localhost certificate in .NET Aspire @@ -10,22 +10,33 @@ This article provides guidance on how to troubleshoot issues that you might enco ## Symptoms -Several .NET Aspire templates include ASP.NET Core projects that are configured to use HTTPS by default. If this is the first time you're running the project, ASP.NET Core prompts you to install a localhost certificate. There are situations in which you trust/install the development certificate, but you don't close all your browser windows. +Several .NET Aspire templates include ASP.NET Core projects that are configured to use HTTPS by default. If this is the first time you're running the project, and you're using Visual Studio, you're prompted to install a localhost certificate. -## Possible solution +- There are situations in which you trust/install the development certificate, but you don't close all your browser windows. In these cases, your browser might indicate that the certificate isn't trusted. -Close all browser windows. Then attempt to resolve this issue by trusting the self-signed development certificate. To trust the certificate, run the following commands. First, remove the existing certificates: +- There are also situations where you don't trust the certificate at all. In these cases, your browser might indicate that the certificate isn't trusted. + +Additionally, there are warning messages from Kestrel written to the console that indicate that the certificate is not trusted. + +## Possible solutions + +Close all browser windows and try again. If you're still experiencing the issue, then attempt to resolve this by trusting the self-signed development certificate with the .NET CLI. To trust the certificate, run the following commands. First, remove the existing certificates. + +> [!NOTE] +> This will remove all existing development certificates on the local machine. ```dotnetcli dotnet dev-certs https --clean ``` -Next, trust the certificate: +To trust the certificate: ```dotnetcli dotnet dev-certs https --trust ``` +For more troubleshooting, see [Troubleshoot certificate problems such as certificate not trusted](/aspnet/core/security/enforcing-ssl#troubleshoot-certificate-problems-such-as-certificate-not-trusted). + ## See also - [Trust the ASP.NET Core HTTPS development certificate on Windows and macOS](/aspnet/core/security/enforcing-ssl#trust-the-aspnet-core-https-development-certificate-on-windows-and-macos) From b98b42e56cdf530f8ddcd68bcd2c181ac4a18449 Mon Sep 17 00:00:00 2001 From: David Pine Date: Wed, 15 May 2024 14:46:37 -0500 Subject: [PATCH 5/8] Add content based on new context --- docs/troubleshooting/unable-to-install-workload.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/troubleshooting/unable-to-install-workload.md b/docs/troubleshooting/unable-to-install-workload.md index 6570e999c9..f45fb93d51 100644 --- a/docs/troubleshooting/unable-to-install-workload.md +++ b/docs/troubleshooting/unable-to-install-workload.md @@ -8,15 +8,24 @@ ms.date: 05/15/2024 This article provides guidance on how to troubleshoot issues that you might encounter when installing the .NET Aspire workload. +> [!IMPORTANT] +> This article is intended to help you troubleshoot issues with installing the .NET Aspire workload, but it's not necessarily related to .NET Aspire. Instead it's more about .NET workloads. + ## Symptoms When you install the .NET Aspire workload, you might encounter an installation error. The error message might indicate that the installation failed, or that the workload couldn't be installed. The error message might also indicate that a package source is unavailable, or that a package source isn't found. +One common issue is that your SDK is aware of some workload manifest or workload pack versions that are not present in any of the feeds configured when you are trying to run the dotnet workload commands. This can happen if the SDK, during its daily check for updates, finds a new version of a workload manifest in a feed that isn't used when running `dotnet workload` commands. This discrepancy can cause errors during installation. + +A less common issue, even when using the correct feeds, is that a workload manifest may have a dependency on a workload pack that is not published on the same feed. This can also lead to errors during installation as the required pack cannot be found. + ## Possible solution Ensure that any recursive _Nuget.config_ files are configured to specify the correct package sources and NuGet feeds. For example, if you have a _Nuget.config_ file in your user profile directory, ensure that it doesn't specify a package source that is no longer available. - +If you encounter errors related to the SDK being aware of workload manifest or workload pack versions not present in your configured feeds, you may need to adjust your feeds or find the feed where the new version of the manifest or required pack is located. + +In the case where a workload manifest has a dependency on a workload pack not published on the same feed, you will need to find and add the feed where that pack is located to your NuGet configuration. ## See also From c7ec95bc6afe50d6896b8be47df6e7c8f4a0b9fd Mon Sep 17 00:00:00 2001 From: David Pine Date: Wed, 15 May 2024 14:57:43 -0500 Subject: [PATCH 6/8] Update a few words --- docs/toc.yml | 2 +- docs/troubleshooting/unable-to-install-workload.md | 5 +---- 2 files changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/toc.yml b/docs/toc.yml index 9e359a0145..341b04229f 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -209,7 +209,7 @@ items: href: troubleshooting/unable-to-install-workload.md - name: .NET Aspire GitHub repository href: https://github.com/dotnet/aspire - - name: Discord + - name: Ask questions on Discord displayName: discord,community href: https://aka.ms/aspire/discord - name: Stack Overflow — .NET Aspire diff --git a/docs/troubleshooting/unable-to-install-workload.md b/docs/troubleshooting/unable-to-install-workload.md index f45fb93d51..9988e72cd2 100644 --- a/docs/troubleshooting/unable-to-install-workload.md +++ b/docs/troubleshooting/unable-to-install-workload.md @@ -6,10 +6,7 @@ ms.date: 05/15/2024 # Troubleshoot installing the .NET Aspire workload -This article provides guidance on how to troubleshoot issues that you might encounter when installing the .NET Aspire workload. - -> [!IMPORTANT] -> This article is intended to help you troubleshoot issues with installing the .NET Aspire workload, but it's not necessarily related to .NET Aspire. Instead it's more about .NET workloads. +This article provides guidance on how to troubleshoot issues that you might encounter when installing the .NET Aspire workload from the .NET CLI. ## Symptoms From a13283d12e4067dd0382756e27324ef59bcbb893 Mon Sep 17 00:00:00 2001 From: David Pine Date: Wed, 15 May 2024 18:39:05 -0500 Subject: [PATCH 7/8] A few more bits of feedback --- docs/troubleshooting/unable-to-install-workload.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/troubleshooting/unable-to-install-workload.md b/docs/troubleshooting/unable-to-install-workload.md index 9988e72cd2..87c66b2aa4 100644 --- a/docs/troubleshooting/unable-to-install-workload.md +++ b/docs/troubleshooting/unable-to-install-workload.md @@ -10,7 +10,11 @@ This article provides guidance on how to troubleshoot issues that you might enco ## Symptoms -When you install the .NET Aspire workload, you might encounter an installation error. The error message might indicate that the installation failed, or that the workload couldn't be installed. The error message might also indicate that a package source is unavailable, or that a package source isn't found. +When you install the .NET Aspire workload, you might encounter an installation error. The error message might indicate that the installation failed, or that the workload couldn't be installed. The error message might also indicate that a package source is unavailable, or that a package source isn't found often similar to: + +```Output +Workload update failed: One or more errors ocurred: (Version X.Y.00Z of package A.B.C is not found in NuGet feeds. +``` One common issue is that your SDK is aware of some workload manifest or workload pack versions that are not present in any of the feeds configured when you are trying to run the dotnet workload commands. This can happen if the SDK, during its daily check for updates, finds a new version of a workload manifest in a feed that isn't used when running `dotnet workload` commands. This discrepancy can cause errors during installation. @@ -24,6 +28,11 @@ If you encounter errors related to the SDK being aware of workload manifest or w In the case where a workload manifest has a dependency on a workload pack not published on the same feed, you will need to find and add the feed where that pack is located to your NuGet configuration. +> [!IMPORTANT] +> Some development environments may depend on private feeds that provide newer versions of the workload manifest or workload pack. In these situations, you may want to disable the daily SDK check for updates to avoid encountering errors during installation. +> +> To disable the daily SDK check for updates, set the `DOTNET_CLI_WORKLOAD_UPDATE_NOTIFY_DISABLE` environment variable to `true`. + ## See also - [NuGet: nuget.config reference](/nuget/reference/nuget-config-file) From 8fa05a8146f1fdbf59ca5a114cda7f257d392ff7 Mon Sep 17 00:00:00 2001 From: David Pine Date: Wed, 15 May 2024 18:41:11 -0500 Subject: [PATCH 8/8] Add link to SDK docs PR --- docs/troubleshooting/unable-to-install-workload.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/troubleshooting/unable-to-install-workload.md b/docs/troubleshooting/unable-to-install-workload.md index 87c66b2aa4..8e66ac2cec 100644 --- a/docs/troubleshooting/unable-to-install-workload.md +++ b/docs/troubleshooting/unable-to-install-workload.md @@ -35,5 +35,6 @@ In the case where a workload manifest has a dependency on a workload pack not pu ## See also -- [NuGet: nuget.config reference](/nuget/reference/nuget-config-file) +- [.NET SDK: Diagnosing issues with .NET SDK Workloads](https://github.com/dotnet/sdk/pull/40912) - [.NET CLI: dotnet workload install](/dotnet/core/tools/dotnet-workload-install) +- [NuGet: nuget.config reference](/nuget/reference/nuget-config-file)