Add Azure integrations overview (#2285)

* Add initial bits for Azure overview. Fixes #2238 * Fix build warnings * Minor edit pass on provisioning article * Move a few things based on peer feedback * Rewrite in progress * Added a few more words, and rephrased a few things * Let's go * Apply suggestions from code review Co-authored-by: Eric Erhardt <[email protected]> * Adjust title and fix uid * Major changes, merge of Bicep article, and edit pass * Move the missing bits * Add missing topic links * Adjust TOC, edit pass, and disabiguate terms * More redirects and fixes for MD and links * Move a few more bits and fix a few more links * Fix redirect * Styling adjustment, bump to ul * Add more links * More links and details * Demote tip * Add alert about local provisioning. Edit pass * Add a few more shared snippets * Fix snippets * Apply suggestions from code review --------- Co-authored-by: Eric Erhardt <[email protected]>
dotnet · Dec 14, 2024 · 0ec04e7 · 0ec04e7
1 parent bd7f261
commit 0ec04e7
Show file tree

Hide file tree

Showing 51 changed files with 639 additions and 283 deletions.
diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json
@@ -275,6 +275,14 @@
     {
       "source_path_from_root": "/docs/whats-new/dotnet-aspire-9-release-candidate-1.md",
       "redirect_url": "/dotnet/aspire/whats-new/dotnet-aspire-9"
+    },
+    {
+      "source_path_from_root": "/docs/deployment/azure/custom-bicep-templates.md",
+      "redirect_url": "/dotnet/aspire/azure/integrations-overview"
+    },
+    {
+      "source_path_from_root": "/docs/deployment/azure/local-provisioning.md",
+      "redirect_url": "/dotnet/aspire/azure/local-provisioning"      
     }
   ]
 }
diff --git a/.vscode/details.code-snippets b/.vscode/details.code-snippets
diff --git a/.vscode/shared.code-snippets b/.vscode/shared.code-snippets
@@ -0,0 +1,53 @@
+{
+	"Details and summary HTML": {
+		"scope": "markdown",
+		"prefix": "details",
+		"body": [
+			"<!-- markdownlint-disable MD033 -->",
+			"<br/>",
+			"<details>",
+			"<summary id=\"$1\"><strong>Toggle $2.</strong></summary>",
+			"<p aria-labelledby=\"$1\">",
+			"",
+			"$3",
+			"",
+			"</p>",
+			"</details>",
+			"<!-- markdownlint-enable MD033 -->",
+			"$0"
+		],
+		"description": "Details and summary HTML"
+	},
+	"Inline NuGet package reference": {
+		"scope": "markdown",
+		"prefix": "inline nuget",
+		"body": [
+			"[📦 $1](https://www.nuget.org/packages/$1) NuGet package$0"
+		],
+		"description": "Add an inline NuGet package reference"
+	},
+	"Install NuGet package": {
+		"scope": "markdown",
+		"prefix": "intall nuget",
+		"body": [
+			"### [.NET CLI](#tab/dotnet-cli)",
+			"",
+			"```dotnetcli",
+			"dotnet add package $1",
+			"```",
+			"",
+			"### [PackageReference](#tab/package-reference)",
+			"",
+			"```xml",
+			"<PackageReference Include=\"$1\"",
+			"                  Version=\"*\" />",
+			"```",
+			"",
+			"---",
+			"",
+			"For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-package) or [Manage package dependencies in .NET applications](/dotnet/core/tools/dependencies).",
+			"$0"
+		],
+		"description": "Install NuGet package"
+	},
+}
diff --git a/docs/azure/integrations-overview.md b/docs/azure/integrations-overview.md
diff --git a/docs/deployment/azure/local-provisioning.md → docs/azure/local-provisioning.md b/docs/deployment/azure/local-provisioning.md → docs/azure/local-provisioning.md
@@ -1,22 +1,24 @@
 ---
 title: Local Azure provisioning
 description: Learn how to use Azure resources in your local development environment.
-ms.date: 10/31/2024
+ms.date: 12/13/2024
+uid: dotnet/aspire/local-azure-provisioning
 ---
 
 # Local Azure provisioning
 
-.NET Aspire simplifies local cloud-native app development with its compelling app host model. This model allows you to run your app locally with the same configuration and services as in Azure.
+.NET Aspire simplifies local cloud-native app development with its compelling app host model. This model allows you to run your app locally with the same configuration and services as in Azure. In this article you learn how to provision Azure resources from your local development environment through the [.NET Aspire app host](xref:dotnet/aspire/app-host).
 
-In this article you learn how to provision Azure resources from your local development environment through the [.NET Aspire app host](../../fundamentals/app-host-overview.md). All of this is possible with the help of the `Azure.Provisioning.*` libraries, which provide a set of APIs to provision Azure resources. These packages are transitive dependencies of the .NET Aspire Azure hosting libraries you use in your app host, so you don't need to install them separately.
+> [!NOTE]
+> To be clear, resources are provisioned in Azure, but the provisioning process is initiated from your local development environment. To optimize your local development experience, consider using emulator or containers when available. For more information, see [Typical developer experience](integrations-overview.md#typical-developer-experience).
 
 ## Requirements
 
 This article assumes that you have an Azure account and subscription. If you don't have an Azure account, you can create a free one at [Azure Free Account](https://azure.microsoft.com/free/). For provisioning functionality to work correctly, you'll need to be authenticated with Azure. Ensure that you have the [Azure Developer CLI](/cli/azure/install-azure-cli) installed. Additionally, you'll need to provide some configuration values so that the provisioning logic can create resources on your behalf.
 
 ## App host provisioning APIs
 
-The app host provides a set of APIs to express Azure resources. These APIs are available as extension methods in .NET Aspire Azure hosting libraries, extending the `IDistributedApplicationBuilder` interface. When you add Azure resources to your app host, they'll add the appropriate provisioning functionality implicitly. In other words, you don't need to call any provisioning APIs directly.
+The app host provides a set of APIs to express Azure resources. These APIs are available as extension methods in .NET Aspire Azure hosting libraries, extending the <xref:Aspire.Hosting.IDistributedApplicationBuilder> interface. When you add Azure resources to your app host, they'll add the appropriate provisioning functionality implicitly. In other words, you don't need to call any provisioning APIs directly.
 
 When the app host starts, the following provisioning logic is executed:
 
@@ -30,7 +32,7 @@ When the app host starts, the following provisioning logic is executed:
 
 The app host automatically manages provisioning of Azure resources. The first time the app host runs, it provisions the resources specified in the app host. Subsequent runs don't provision the resources again unless the app host configuration changes.
 
-If you've already provisioned Azure resources outside of the app host and want to use them, you can provide the connection string with the `AddConnectionString` API as shown in the following Azure Key Vault example:
+If you've already provisioned Azure resources outside of the app host and want to use them, you can provide the connection string with the <xref:Aspire.Hosting.ParameterResourceBuilderExtensions.AddConnectionString*> API as shown in the following Azure Key Vault example:
 
 ```csharp
 // Service registration
@@ -43,44 +45,20 @@ builder.AddProject<Projects.ExampleProject>()
        .WithReference(secrets)
 ```
 
-The preceding code snippet shows how to add an Azure Key Vault to the app host. The `AddAzureKeyVault` API is used to add the Azure Key Vault to the app host. The `AddConnectionString` API is used to provide the connection string to the app host.
+The preceding code snippet shows how to add an Azure Key Vault to the app host. The <xref:Aspire.Hosting.AzureKeyVaultResourceExtensions.AddAzureKeyVault*> API is used to add the Azure Key Vault to the app host. The `AddConnectionString` API is used to provide the connection string to the app host.
 
-Alternatively, for some Azure resources, you can opt-in to running them as an emulator with the `RunAsEmulator` API. This API is available for Azure Cosmos DB and Azure Storage. For example, to run Azure Cosmos DB as an emulator, you can use the following code snippet:
+Alternatively, for some Azure resources, you can opt-in to running them as an emulator with the `RunAsEmulator` API. This API is available for [Azure Cosmos DB](../database/azure-cosmos-db-integration.md) and [Azure Storage](../storage/azure-storage-integrations.md) integrations. For example, to run Azure Cosmos DB as an emulator, you can use the following code snippet:
 
 ```csharp
 var cosmos = builder.AddAzureCosmosDB("cosmos")
                     .RunAsEmulator();
 ```
 
-The `RunAsEmulator` API configures an Azure Cosmos DB resource to be emulated using the Azure Cosmos DB emulator with the NoSQL API.
+The <xref:Aspire.Hosting.AzureCosmosExtensions.RunAsEmulator*> API configures an Azure Cosmos DB resource to be emulated using the Azure Cosmos DB emulator with the NoSQL API.
 
 ### .NET Aspire Azure hosting integrations
 
-If you're using Azure resources in your app host, you're using one or more of the .NET Aspire Azure hosting integrations. These hosting libraries provide extension methods to the `IDistributedApplicationBuilder` interface to add Azure resources to your app host.
-
-### Azure provisioning integrations
-
-The following Azure provisioning libraries are available:
-
-- [📦 Azure.Provisioning.AppConfiguration](https://www.nuget.org/packages/Azure.Provisioning.AppConfiguration)
-- [📦 Azure.Provisioning.ApplicationInsights](https://www.nuget.org/packages/Azure.Provisioning.ApplicationInsights)
-- [📦 Azure.Provisioning.CognitiveServices](https://www.nuget.org/packages/Azure.Provisioning.CognitiveServices)
-- [📦 Azure.Provisioning.CosmosDB](https://www.nuget.org/packages/Azure.Provisioning.CosmosDB)
-- [📦 Azure.Provisioning.EventHubs](https://www.nuget.org/packages/Azure.Provisioning.EventHubs)
-- [📦 Azure.Provisioning.KeyVault](https://www.nuget.org/packages/Azure.Provisioning.KeyVault)
-- [📦 Azure.Provisioning.OperationalInsights](https://www.nuget.org/packages/Azure.Provisioning.OperationalInsights)
-- [📦 Azure.Provisioning.PostgreSql](https://www.nuget.org/packages/Azure.Provisioning.PostgreSql)
-- [📦 Azure.Provisioning.Redis](https://www.nuget.org/packages/Azure.Provisioning.Redis)
-- [📦 Azure.Provisioning.Resources](https://www.nuget.org/packages/Azure.Provisioning.Resources)
-- [📦 Azure.Provisioning.Search](https://www.nuget.org/packages/Azure.Provisioning.Search)
-- [📦 Azure.Provisioning.ServiceBus](https://www.nuget.org/packages/Azure.Provisioning.ServiceBus)
-- [📦 Azure.Provisioning.SignalR](https://www.nuget.org/packages/Azure.Provisioning.SignalR)
-- [📦 Azure.Provisioning.Sql](https://www.nuget.org/packages/Azure.Provisioning.Sql)
-- [📦 Azure.Provisioning.Storage](https://www.nuget.org/packages/Azure.Provisioning.Storage)
-- [📦 Azure.Provisioning](https://www.nuget.org/packages/Azure.Provisioning)
-
-> [!TIP]
-> You shouldn't need to install these packages manually in your projects, as they're transitive dependencies of the corresponding .NET Aspire Azure hosting libraries.
+If you're using Azure resources in your app host, you're using one or more of the [.NET Aspire Azure hosting integrations](integrations-overview.md). These hosting libraries provide extension methods to the <xref:Aspire.Hosting.IDistributedApplicationBuilder> interface to add Azure resources to your app host.
 
 ## Configuration
 
@@ -113,7 +91,7 @@ After you've configured the necessary values, you can start provisioning Azure r
 
 The .NET Aspire app host uses a credential store for Azure resource authentication and authorization. Depending on your subscription, the correct credential store may be needed for multi-tenant provisioning scenarios.
 
-With the [Aspire.Hosting.Azure](https://nuget.org/packages/Aspire.Hosting.Azure) NuGet package installed, and if your app host depends on Azure resources, the default Azure credential store relies on the <xref:Azure.Identity.DefaultAzureCredential>. To change this behavior, you can set the credential store value in the _:::no-loc text="appsettings.json":::_ file, as shown in the following example:
+With the [📦 Aspire.Hosting.Azure](https://nuget.org/packages/Aspire.Hosting.Azure) NuGet package installed, and if your app host depends on Azure resources, the default Azure credential store relies on the <xref:Azure.Identity.DefaultAzureCredential>. To change this behavior, you can set the credential store value in the _:::no-loc text="appsettings.json":::_ file, as shown in the following example:
 
 ```json
 {
@@ -132,6 +110,9 @@ As with all [configuration-based settings](/dotnet/core/extensions/configuration
 - `AzureDeveloperCli`: Delegates to the <xref:Azure.Identity.AzureDeveloperCliCredential>.
 - `InteractiveBrowser`: Delegates to the <xref:Azure.Identity.InteractiveBrowserCredential>.
 
+> [!TIP]
+> For more information about the Azure SDK authentication and authorization, see [Credential chains in the Azure Identity library for .NET](/dotnet/azure/sdk/authentication/credential-chains?tabs=dac#defaultazurecredential-overview).
+
 ### Tooling support
 
 In Visual Studio, you can use Connected Services to configure the default Azure provisioning settings. Select the app host project, right-click on the **Connected Services** node, and select **Azure Resource Provisioning Settings**:
@@ -144,7 +125,7 @@ This will open a dialog where you can configure the Azure provisioning settings,
 
 ### Missing configuration value hints
 
-When the `Azure` configuration section is missing, has missing values, or is invalid, the [.NET Aspire dashboard](../../fundamentals/dashboard/overview.md) provides useful hints. For example, consider an app host that's missing the `SubscriptionId` configuration value that's attempting to use an Azure Key Vault resource. The **Resources** page indicates the **State** as **Missing subscription configuration**:
+When the `Azure` configuration section is missing, has missing values, or is invalid, the [.NET Aspire dashboard](../fundamentals/dashboard/overview.md) provides useful hints. For example, consider an app host that's missing the `SubscriptionId` configuration value that's attempting to use an Azure Key Vault resource. The **Resources** page indicates the **State** as **Missing subscription configuration**:
 
 :::image type="content" source="media/resources-kv-missing-subscription.png" alt-text=".NET Aspire dashboard: Missing subscription configuration.":::
 

diff --git a/...ia/azure-provisioning-settings-dialog.png → ...ia/azure-provisioning-settings-dialog.png b/...ia/azure-provisioning-settings-dialog.png → ...ia/azure-provisioning-settings-dialog.png
diff --git a/.../azure-resource-provisioning-settings.png → .../azure-resource-provisioning-settings.png b/.../azure-resource-provisioning-settings.png → .../azure-resource-provisioning-settings.png
diff --git a/.../console-logs-kv-missing-subscription.png → .../console-logs-kv-missing-subscription.png b/.../console-logs-kv-missing-subscription.png → .../console-logs-kv-missing-subscription.png
diff --git a/...dia/resources-kv-missing-subscription.png → ...dia/resources-kv-missing-subscription.png b/...dia/resources-kv-missing-subscription.png → ...dia/resources-kv-missing-subscription.png
diff --git a/.../snippets/AppHost.Bicep/AppHost.Bicep.sln → docs/azure/snippets/AppHost.Bicep.sln b/.../snippets/AppHost.Bicep/AppHost.Bicep.sln → docs/azure/snippets/AppHost.Bicep.sln
@@ -2,29 +2,29 @@ Microsoft Visual Studio Solution File, Format Version 12.00
 # Visual Studio Version 17
 VisualStudioVersion = 17.11.34929.205
 MinimumVisualStudioVersion = 10.0.40219.1
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "AppHost.Bicep", "AppHost.Bicep.csproj", "{9D692CBB-E892-4CA9-B900-BEA71FF0F37D}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "AppHost.Bicep", "AppHost.Bicep\AppHost.Bicep.csproj", "{9D692CBB-E892-4CA9-B900-BEA71FF0F37D}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "WebHook.Api", "..\WebHook.Api\WebHook.Api.csproj", "{5472D255-76E4-4000-B053-D8231FDB9905}"
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "WebHook.Api", "WebHook.Api\WebHook.Api.csproj", "{5472D255-76E4-4000-B053-D8231FDB9905}"
 EndProject
 Global
-	GlobalSection(ExtensibilityGlobals) = postSolution
-		SolutionGuid = {1FECE22C-F99C-4BEF-BE41-5BC5D0B5FCF2}
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|Any CPU = Debug|Any CPU
+		Release|Any CPU = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(ProjectConfigurationPlatforms) = postSolution
-		{5472D255-76E4-4000-B053-D8231FDB9905}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{5472D255-76E4-4000-B053-D8231FDB9905}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{5472D255-76E4-4000-B053-D8231FDB9905}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{5472D255-76E4-4000-B053-D8231FDB9905}.Release|Any CPU.Build.0 = Release|Any CPU
 		{9D692CBB-E892-4CA9-B900-BEA71FF0F37D}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{9D692CBB-E892-4CA9-B900-BEA71FF0F37D}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{9D692CBB-E892-4CA9-B900-BEA71FF0F37D}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{9D692CBB-E892-4CA9-B900-BEA71FF0F37D}.Release|Any CPU.Build.0 = Release|Any CPU
-	EndGlobalSection
-	GlobalSection(SolutionConfigurationPlatforms) = preSolution
-		Debug|Any CPU = Debug|Any CPU
-		Release|Any CPU = Release|Any CPU
+		{5472D255-76E4-4000-B053-D8231FDB9905}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{5472D255-76E4-4000-B053-D8231FDB9905}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{5472D255-76E4-4000-B053-D8231FDB9905}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{5472D255-76E4-4000-B053-D8231FDB9905}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
 	EndGlobalSection
+	GlobalSection(ExtensibilityGlobals) = postSolution
+		SolutionGuid = {1FECE22C-F99C-4BEF-BE41-5BC5D0B5FCF2}
+	EndGlobalSection
 EndGlobal
diff --git a/...ippets/AppHost.Bicep/AppHost.Bicep.csproj → ...ippets/AppHost.Bicep/AppHost.Bicep.csproj b/...ippets/AppHost.Bicep/AppHost.Bicep.csproj → ...ippets/AppHost.Bicep/AppHost.Bicep.csproj
diff --git a/...pHost.Bicep/Program.GetOutputReference.cs → ...pHost.Bicep/Program.GetOutputReference.cs b/...pHost.Bicep/Program.GetOutputReference.cs → ...pHost.Bicep/Program.GetOutputReference.cs
diff --git a/...pets/AppHost.Bicep/Program.InlineBicep.cs → ...pets/AppHost.Bicep/Program.InlineBicep.cs b/...pets/AppHost.Bicep/Program.InlineBicep.cs → ...pets/AppHost.Bicep/Program.InlineBicep.cs
diff --git a/...ts/AppHost.Bicep/Program.PassParameter.cs → ...ts/AppHost.Bicep/Program.PassParameter.cs b/...ts/AppHost.Bicep/Program.PassParameter.cs → ...ts/AppHost.Bicep/Program.PassParameter.cs
diff --git a/...s/AppHost.Bicep/Program.ReferenceBicep.cs → ...s/AppHost.Bicep/Program.ReferenceBicep.cs b/...s/AppHost.Bicep/Program.ReferenceBicep.cs → ...s/AppHost.Bicep/Program.ReferenceBicep.cs
diff --git a/...t/azure/snippets/AppHost.Bicep/Program.cs → docs/azure/snippets/AppHost.Bicep/Program.cs b/...t/azure/snippets/AppHost.Bicep/Program.cs → docs/azure/snippets/AppHost.Bicep/Program.cs
diff --git a/...Host.Bicep/Properties/launchSettings.json → ...Host.Bicep/Properties/launchSettings.json b/...Host.Bicep/Properties/launchSettings.json → ...Host.Bicep/Properties/launchSettings.json
diff --git a/...ppHost.Bicep/appsettings.Development.json → ...ppHost.Bicep/appsettings.Development.json b/...ppHost.Bicep/appsettings.Development.json → ...ppHost.Bicep/appsettings.Development.json
diff --git a/...e/snippets/AppHost.Bicep/appsettings.json → ...e/snippets/AppHost.Bicep/appsettings.json b/...e/snippets/AppHost.Bicep/appsettings.json → ...e/snippets/AppHost.Bicep/appsettings.json
diff --git a/...ure/snippets/AppHost.Bicep/cosmosdb.bicep → ...ure/snippets/AppHost.Bicep/cosmosdb.bicep b/...ure/snippets/AppHost.Bicep/cosmosdb.bicep → ...ure/snippets/AppHost.Bicep/cosmosdb.bicep
diff --git a/...ts/AppHost.Bicep/event-grid-webhook.bicep → ...ts/AppHost.Bicep/event-grid-webhook.bicep b/...ts/AppHost.Bicep/event-grid-webhook.bicep → ...ts/AppHost.Bicep/event-grid-webhook.bicep
diff --git a/.../snippets/AppHost.Bicep/storage-out.bicep → .../snippets/AppHost.Bicep/storage-out.bicep b/.../snippets/AppHost.Bicep/storage-out.bicep → .../snippets/AppHost.Bicep/storage-out.bicep
diff --git a/...zure/snippets/AppHost.Bicep/storage.bicep → ...zure/snippets/AppHost.Bicep/storage.bicep b/...zure/snippets/AppHost.Bicep/storage.bicep → ...zure/snippets/AppHost.Bicep/storage.bicep
diff --git a/...ent/azure/snippets/WebHook.Api/Program.cs → docs/azure/snippets/WebHook.Api/Program.cs b/...ent/azure/snippets/WebHook.Api/Program.cs → docs/azure/snippets/WebHook.Api/Program.cs
diff --git a/...ebHook.Api/Properties/launchSettings.json → ...ebHook.Api/Properties/launchSettings.json b/...ebHook.Api/Properties/launchSettings.json → ...ebHook.Api/Properties/launchSettings.json
diff --git a/...e/snippets/WebHook.Api/WebHook.Api.csproj → ...e/snippets/WebHook.Api/WebHook.Api.csproj b/...e/snippets/WebHook.Api/WebHook.Api.csproj → ...e/snippets/WebHook.Api/WebHook.Api.csproj
diff --git a/...ure/snippets/WebHook.Api/WebHook.Api.http → ...ure/snippets/WebHook.Api/WebHook.Api.http b/...ure/snippets/WebHook.Api/WebHook.Api.http → ...ure/snippets/WebHook.Api/WebHook.Api.http
diff --git a/.../WebHook.Api/appsettings.Development.json → .../WebHook.Api/appsettings.Development.json b/.../WebHook.Api/appsettings.Development.json → .../WebHook.Api/appsettings.Development.json
diff --git a/...ure/snippets/WebHook.Api/appsettings.json → ...ure/snippets/WebHook.Api/appsettings.json b/...ure/snippets/WebHook.Api/appsettings.json → ...ure/snippets/WebHook.Api/appsettings.json