From 29709af8a42eb4d96bf31ec4836d6011db455bea Mon Sep 17 00:00:00 2001
From: David Pine <david.pine.7@gmail.com>
Date: Mon, 3 Jun 2024 20:26:49 -0500
Subject: [PATCH] Add troubleshooting for name in use. Fixes #681

---
 docs/index.yml                                |  3 ++
 docs/toc.yml                                  |  2 ++
 .../troubleshooting/name-is-already-in-use.md | 36 +++++++++++++++++++
 3 files changed, 41 insertions(+)
 create mode 100644 docs/troubleshooting/name-is-already-in-use.md

diff --git a/docs/index.yml b/docs/index.yml
index 5a4e0a627..454fb3a94 100644
--- a/docs/index.yml
+++ b/docs/index.yml
@@ -205,6 +205,9 @@ conceptualContent:
         - itemType: how-to-guide
           text: Untrusted localhost certificate
           url: troubleshooting/untrusted-localhost-certificate.md
+        - itemType: how-to-guide
+          text: The specified name is already in use
+          url: troubleshooting/name-is-already-in-use.md
         - itemType: reference
           text: Ask questions on Discord
           url: https://aka.ms/aspire/discord
diff --git a/docs/toc.yml b/docs/toc.yml
index e9669d81a..4337b03fe 100644
--- a/docs/toc.yml
+++ b/docs/toc.yml
@@ -233,6 +233,8 @@ items:
         href: troubleshooting/untrusted-localhost-certificate.md
       - name: Unable to install .NET Aspire workload
         href: troubleshooting/unable-to-install-workload.md
+      - name: The specified name is already in use
+        href: troubleshooting/name-is-already-in-use.md
       - name: .NET Aspire GitHub repository
         href: https://github.com/dotnet/aspire
       - name: Ask questions on Discord
diff --git a/docs/troubleshooting/name-is-already-in-use.md b/docs/troubleshooting/name-is-already-in-use.md
new file mode 100644
index 000000000..93cbc68c5
--- /dev/null
+++ b/docs/troubleshooting/name-is-already-in-use.md
@@ -0,0 +1,36 @@
+---
+title: The specified name is already in use
+description: Learn how to troubleshoot the error "The specified name is already in use" when deploying to Azure.
+ms.date: 06/03/2024
+---
+
+# The specified name is already in use
+
+When deploying to Azure initial deployments may fail with an error similar to the following:
+
+> "The specified name is already in use"
+
+This article describes several techniques to avoid this problem.
+
+## Symptoms
+
+When deploying a .NET Aspire app to Azure, the resources in the [app model](../fundamentals/app-host-overview.md#define-the-app-model) are transformed into Azure resources. Some Azure resources have globally scoped names, such as Azure App Configuration, where all instances are in the `[name].azconfig.io` global namespace.
+
+The value of `[name]` is derived from the .NET Aspire resource name, along with random characters based on the resource group name. However, the generated string may exceed the allowable length for the resource name in App Configuration. As a result, some characters are truncated to ensure compliance.
+
+When a conflict occurs in the global namespace, the resource fails to deploy because the combination of `[name]+[truncated hash]` isn't unique enough.
+
+## Possible solutions
+
+One workaround is to avoid using common names like `appconfig` or `storage` for resources. Instead, choose a more meaningful and specific name. This reduces the potential for conflict, but does not completely eliminate it. In such cases, you can use callback methods to set a specific name and avoid using the computed string altogether.
+
+Consider the following example:
+
+```csharp
+var appConfig = builder.AddAzureAppConfiguration(
+    "appConfig",
+    (resource, construct, store) =>
+{
+    store.AssignProperty(p => p.Name, "'noncalculatedname'");
+});
+```