Troubleshooting bits

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)

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)

docs/toc.yml

@@ -203,9 +203,13 @@ 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
+      - name: Ask questions on Discord
         displayName: discord,community
         href: https://aka.ms/aspire/discord
       - name: Stack Overflow — .NET Aspire

docs/troubleshooting/unable-to-install-workload.md

@@ -0,0 +1,40 @@
+---
+title: Troubleshoot installing the .NET Aspire workload
+description: Explore strategies for troubleshooting issues when installing the .NET Aspire workload.
+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 from the .NET CLI.
+
+## 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 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.
+
+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.
+
+> [!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
+
+- [.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)

docs/troubleshooting/untrusted-localhost-certificate.md

@@ -0,0 +1,44 @@
+---
+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/15/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, and you're using Visual Studio, you're prompted 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. In these cases, your browser might indicate that the certificate isn't trusted.
+
+- 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
+```
+
+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)
+- [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)