From 3b0c2c86e714bf0b79d560f9226b140b9035ec23 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 14:44:51 +0000 Subject: [PATCH 01/30] Initial plan From 6906c897db44d339a58677d0466f0ba8162357a3 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 14:58:08 +0000 Subject: [PATCH 02/30] Restructure Azure AI Foundry integration into subfolder Co-authored-by: alistairmatthews <41286777+alistairmatthews@users.noreply.github.com> --- .../config/sidebar/integrations.topics.ts | 16 +++- .../azure-ai-foundry-client.mdx | 52 ++++++++++++ .../azure-ai-foundry-get-started.mdx | 84 +++++++++++++++++++ .../azure-ai-foundry-host.mdx} | 31 +++---- 4 files changed, 163 insertions(+), 20 deletions(-) create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-client.mdx create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started.mdx rename src/frontend/src/content/docs/integrations/cloud/azure/{azure-ai-foundry.mdx => azure-ai-foundry/azure-ai-foundry-host.mdx} (90%) diff --git a/src/frontend/config/sidebar/integrations.topics.ts b/src/frontend/config/sidebar/integrations.topics.ts index 80af1db7..2b862fc4 100644 --- a/src/frontend/config/sidebar/integrations.topics.ts +++ b/src/frontend/config/sidebar/integrations.topics.ts @@ -269,7 +269,21 @@ export const integrationTopics: StarlightSidebarTopicsUserConfig = { }, { label: 'Azure AI Foundry', - slug: 'integrations/cloud/azure/azure-ai-foundry', + collapsed: true, + items: [ + { + label: 'Get started', + slug: 'integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started', + }, + { + label: 'Hosting integration (AppHost)', + slug: 'integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host', + }, + { + label: 'Client integration', + slug: 'integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-client', + }, + ], }, { label: 'Azure AI Inference', diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-client.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-client.mdx new file mode 100644 index 00000000..53cf2bcf --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-client.mdx @@ -0,0 +1,52 @@ +--- +title: Azure AI Foundry client integration +description: Learn how to use the Aspire Azure AI Foundry client integration to connect to Azure AI Foundry services. +next: false +--- + +import { Aside, Badge, CardGrid, LinkCard } from '@astrojs/starlight/components'; +import { Image } from 'astro:assets'; +import aiFoundryIcon from '@assets/icons/azure-ai-foundry-icon.png'; + +Azure AI Foundry logo + + + +The client integration for Azure AI Foundry is provided through the [Azure AI Inference](/integrations/cloud/azure/azure-ai-inference/) integration. + +For an introduction to working with the Azure AI Foundry client integration, see [Get started with the Azure AI Foundry integrations](/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started/). + +## Using Azure AI Foundry from client applications + +To use Azure AI Foundry services from your client applications, you'll use the Azure AI Inference client integration. This integration provides a consistent way to interact with various AI models deployed in Azure AI Foundry, including chat completions, embeddings, and other AI capabilities. + +For detailed information on how to: + +- Install the Azure AI Inference client package +- Configure the client in your application +- Use chat completions and other AI features +- Handle authentication and connection strings + +See the complete [Azure AI Inference integration documentation](/integrations/cloud/azure/azure-ai-inference/). + +## Next steps + + + + + diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started.mdx new file mode 100644 index 00000000..4042d073 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started.mdx @@ -0,0 +1,84 @@ +--- +title: Get started with the Azure AI Foundry integrations +description: Learn how to set up the Aspire Azure AI Foundry Hosting and Client integrations simply. +prev: false +--- + +import { Image } from 'astro:assets'; +import InstallPackage from '@components/InstallPackage.astro'; +import { Aside, Badge, CardGrid, LinkCard } from '@astrojs/starlight/components'; +import aiFoundryIcon from '@assets/icons/azure-ai-foundry-icon.png'; + +Azure AI Foundry logo + + + +[Azure AI Foundry](https://learn.microsoft.com/ai-studio) provides a unified platform for developing, testing, and deploying AI applications. The Aspire Azure AI Foundry integration enables you to connect to Azure AI Foundry services from your applications, providing access to various AI capabilities including model deployments, prompt flow, and more. + +In this introduction, you'll see how to install and use the Aspire Azure AI Foundry integrations in a simple configuration. If you already have this knowledge, see [Azure AI Foundry Hosting integration](/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host/) for full reference details. + + + +## Set up hosting integration + +To begin, install the Aspire Azure AI Foundry Hosting integration in your Aspire AppHost project. This integration allows you to create and manage Azure AI Foundry resources from your Aspire hosting projects: + + + +Next, in the AppHost project, create an Azure AI Foundry resource and pass it to the consuming client projects: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var foundry = builder.AddAzureAIFoundry("foundry"); + +var chat = foundry.AddDeployment("chat", "Phi-4", "1", "Microsoft"); + +builder.AddProject() + .WithReference(chat) + .WaitFor(chat); + +// After adding all resources, run the app... + +builder.Build().Run(); +``` + +The preceding code adds an Azure AI Foundry resource named `foundry` with a deployment named `chat` using the Phi-4 model to the AppHost project. The `WithReference` method passes the connection information to the `ExampleProject` project. + + + + + +## Set up client integration + +The client integration for Azure AI Foundry is the [Azure AI Inference](/integrations/cloud/azure/azure-ai-inference/) integration. To use Azure AI Foundry from your client applications, install the Azure AI Inference integration in your client project. + +For more information on using the client integration, see the [Azure AI Inference integration documentation](/integrations/cloud/azure/azure-ai-inference/). + +## Next steps + + + + + diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host.mdx similarity index 90% rename from src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry.mdx rename to src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host.mdx index 41dc588c..243aaa55 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host.mdx @@ -1,11 +1,10 @@ --- -title: Azure AI Foundry integration -description: This article describes the Aspire Azure AI Foundry integration features and capabilities. +title: Azure AI Foundry hosting integration +description: Learn how to use the Aspire Azure AI Foundry hosting integration to create Azure AI Foundry resources. --- import { Aside, Badge } from '@astrojs/starlight/components'; import InstallPackage from '@components/InstallPackage.astro'; -import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; import { Image } from 'astro:assets'; import aiFoundryIcon from '@assets/icons/azure-ai-foundry-icon.png'; @@ -20,15 +19,13 @@ import aiFoundryIcon from '@assets/icons/azure-ai-foundry-icon.png'; -[Azure AI Foundry](https://learn.microsoft.com/ai-studio) provides a unified platform for developing, testing, and deploying AI applications. The Aspire Azure AI Foundry integration enables you to connect to Azure AI Foundry services from your applications, providing access to various AI capabilities including model deployments, prompt flow, and more. - -## Hosting integration - The Aspire Azure AI Foundry hosting integration models the AI Foundry project as the `AzureAIFoundryResource` type. To access this type and APIs for expressing them within your AppHost project, install the [📦 Aspire.Hosting.Azure.AIFoundry](https://www.nuget.org/packages/Aspire.Hosting.Azure.AIFoundry) NuGet package: -### Add an Azure AI Foundry resource +For an introduction to working with the Azure AI Foundry hosting integration, see [Get started with the Azure AI Foundry integrations](/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started/). + +## Add an Azure AI Foundry resource To add an Azure AI Foundry resource to your AppHost project, call the `AddAzureAIFoundry` method providing a name: @@ -48,7 +45,7 @@ The preceding code adds an Azure AI Foundry resource named `foundry` to the AppH > [!IMPORTANT] > When you call `AddAzureAIFoundry`, it implicitly calls `AddAzureProvisioning`—which adds support for generating Azure resources dynamically during app startup. The app must configure the appropriate subscription and location. For more information, see [Local provisioning: Configuration](/integrations/cloud/azure/local-provisioning/#configuration). -### Add an Azure AI Foundry deployment resource +## Add an Azure AI Foundry deployment resource To add an Azure AI Foundry deployment resource, call the `AddDeployment` method: @@ -79,7 +76,7 @@ The preceding code: > > For more information, see the [AIFoundryModel API reference](https://learn.microsoft.com/dotnet/api/aspire.hosting.azure.aifoundrymodel). -### Configure deployment properties +## Configure deployment properties You can customize deployment properties using the `WithProperties` method: @@ -94,7 +91,7 @@ var chat = foundry.AddDeployment("chat", "Phi-4", "1", "Microsoft") The preceding code sets the SKU name to `Standard` and capacity to `10` for the deployment. -### Connect to an existing Azure AI Foundry service +## Connect to an existing Azure AI Foundry service You might have an existing Azure AI Foundry service that you want to connect to. You can chain a call to annotate that your `AzureAIFoundryResource` is an existing resource: @@ -116,7 +113,7 @@ builder.AddProject() > [!IMPORTANT] > When you call `RunAsExisting`, `PublishAsExisting`, or `AsExisting` methods to work with resources that are already present in your Azure subscription, you must add certain configuration values to your AppHost to ensure that Aspire can locate them. The necessary configuration values include **SubscriptionId**, **AllowResourceGroupCreation**, **ResourceGroup**, and **Location**. If you don't set them, "Missing configuration" errors appear in the Aspire dashboard. For more information about how to set them, see [Use existing Azure resources](/integrations/cloud/azure/overview/#use-existing-azure-resources). -### Use Foundry Local for development +## Use Foundry Local for development Aspire supports the usage of Foundry Local for local development. Add the following to your AppHost project: @@ -139,7 +136,7 @@ When the AppHost starts up, the local foundry service is also started. This requ The `RunAsFoundryLocal` method configures the resource to run as an emulator. It downloads and loads the specified models locally. The method provides health checks for the local service and automatically manages the Foundry Local lifecycle. -### Assign roles to resources +## Assign roles to resources You can assign specific roles to resources that need to access the Azure AI Foundry service. Use the `WithRoleAssignments` method: @@ -153,7 +150,7 @@ builder.AddProject("api") The preceding code assigns the `CognitiveServicesUser` role to the `api` project, granting it the necessary permissions to access the Azure AI Foundry resource. -### Provisioning-generated Bicep +## Provisioning-generated Bicep If you're new to [Bicep](https://learn.microsoft.com/azure/azure-resource-manager/bicep/overview), it's a domain-specific language for defining Azure resources. With Aspire, you don't need to write Bicep by-hand, instead the provisioning APIs generate Bicep for you. When you publish your app, the generated Bicep provisions an Azure AI Foundry resource with standard defaults. @@ -243,7 +240,7 @@ resource ai_foundry_CognitiveServicesOpenAIUser 'Microsoft.Authorization/roleAss The generated Bicep is a starting point and is influenced by changes to the provisioning infrastructure in C#. Customizations to the Bicep file directly will be overwritten, so make changes through the C# provisioning APIs to ensure they're reflected in the generated files. -#### Customize provisioning infrastructure +### Customize provisioning infrastructure All Aspire Azure resources are subclasses of the `AzureProvisioningResource` type. This enables customization of the generated Bicep by providing a fluent API to configure the Azure resources—using the `ConfigureInfrastructure` API: @@ -271,7 +268,3 @@ The preceding code: - The single `CognitiveServicesAccount` resource is retrieved. - The `Sku` property is assigned to a new instance of `CognitiveServicesSku` with an `E0` name and `Enterprise` tier. - A tag is added to the Cognitive Services resource with a key of `ExampleKey` and a value of `Example value`. - -## Client integration - -The client integration for Azure AI Foundry is the [Azure AI Inference](/integrations/cloud/azure/azure-ai-inference/) integration. From 0de61f69b01184fe842c8f78148371720e06c879 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 14:59:23 +0000 Subject: [PATCH 03/30] Update integration-docs.json to point to get-started page Co-authored-by: alistairmatthews <41286777+alistairmatthews@users.noreply.github.com> --- src/frontend/src/data/integration-docs.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/frontend/src/data/integration-docs.json b/src/frontend/src/data/integration-docs.json index 29ab9d20..031f93e3 100644 --- a/src/frontend/src/data/integration-docs.json +++ b/src/frontend/src/data/integration-docs.json @@ -61,7 +61,7 @@ }, { "match": "Aspire.Hosting.Azure.AIFoundry", - "href": "/integrations/cloud/azure/azure-ai-foundry/" + "href": "/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started/" }, { "match": "Aspire.Hosting.Azure.AppConfiguration", From 8e6501b12498ba551f44bc8915d420099eb07c43 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 15:00:49 +0000 Subject: [PATCH 04/30] Fix parameter documentation for AddDeployment method Co-authored-by: alistairmatthews <41286777+alistairmatthews@users.noreply.github.com> --- .../cloud/azure/azure-ai-foundry/azure-ai-foundry-host.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host.mdx index 243aaa55..36f08d7e 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host.mdx @@ -69,7 +69,7 @@ The preceding code: - Adds an Azure AI Foundry deployment resource named `chat` with a model name of `Phi-4`. The model name must correspond to an [available model](https://learn.microsoft.com/azure/ai-foundry/foundry-models/concepts/models) in the Azure AI Foundry service. > [!NOTE] -> The `format` parameter of the `AddDeployment(...)` method specifies the model publisher or provider. Common values include: +> The fourth parameter of the `AddDeployment(...)` method specifies the model publisher or provider. Common values include: > > - `"OpenAI"` for GPT models (e.g., GPT-4o, GPT-4, GPT-3.5 Turbo) > - `"Microsoft"` for Phi models (e.g., Phi-4, Phi-3.5) From f7020384fb157b38a30b5b9e991f324db7d2c108 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 15:15:48 +0000 Subject: [PATCH 05/30] Restructure Azure AI Inference integration into subfolder Co-authored-by: alistairmatthews <41286777+alistairmatthews@users.noreply.github.com> --- .../config/sidebar/integrations.topics.ts | 16 ++- .../azure-ai-inference-client.mdx} | 47 +------- .../azure-ai-inference-get-started.mdx | 105 ++++++++++++++++++ .../azure-ai-inference-host.mdx | 53 +++++++++ src/frontend/src/data/integration-docs.json | 2 +- 5 files changed, 179 insertions(+), 44 deletions(-) rename src/frontend/src/content/docs/integrations/cloud/azure/{azure-ai-inference.mdx => azure-ai-inference/azure-ai-inference-client.mdx} (86%) create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-get-started.mdx create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-host.mdx diff --git a/src/frontend/config/sidebar/integrations.topics.ts b/src/frontend/config/sidebar/integrations.topics.ts index 2b862fc4..e8fda4f2 100644 --- a/src/frontend/config/sidebar/integrations.topics.ts +++ b/src/frontend/config/sidebar/integrations.topics.ts @@ -287,7 +287,21 @@ export const integrationTopics: StarlightSidebarTopicsUserConfig = { }, { label: 'Azure AI Inference', - slug: 'integrations/cloud/azure/azure-ai-inference', + collapsed: true, + items: [ + { + label: 'Get started', + slug: 'integrations/cloud/azure/azure-ai-inference/azure-ai-inference-get-started', + }, + { + label: 'Hosting integration (AppHost)', + slug: 'integrations/cloud/azure/azure-ai-inference/azure-ai-inference-host', + }, + { + label: 'Client integration', + slug: 'integrations/cloud/azure/azure-ai-inference/azure-ai-inference-client', + }, + ], }, { label: 'Azure AI Search', diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-inference.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-client.mdx similarity index 86% rename from src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-inference.mdx rename to src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-client.mdx index e0d2e73f..8bf770a1 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-inference.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-client.mdx @@ -1,10 +1,10 @@ --- -title: Azure AI Inference integration -description: This article describes the Aspire Azure AI Inference integration features and capabilities. +title: Azure AI Inference client integration +description: Learn how to use the Aspire Azure AI Inference client integration to connect to Azure AI Inference services. +next: false --- import { Aside, Badge } from '@astrojs/starlight/components'; -import InstallPackage from '@components/InstallPackage.astro'; import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; import { Image } from 'astro:assets'; import aiFoundryIcon from '@assets/icons/azure-ai-foundry-icon.png'; @@ -20,44 +20,6 @@ import aiFoundryIcon from '@assets/icons/azure-ai-foundry-icon.png'; -[Azure AI Inference](https://learn.microsoft.com/azure/ai-foundry/how-to/deploy-models-serverless?view=foundry-classic) provides serverless API endpoints for deploying and using AI models. The Aspire Azure AI Inference integration enables you to connect to Azure AI Inference services from your applications, making it easy to call models for chat, completions, embeddings, and more. - -## Hosting integration - -Although the Azure AI Inference library doesn't currently offer direct hosting integration, you can still integrate it into your AppHost project. Simply add a connection string to establish a reference to an existing Azure AI Foundry resource. - -### Connect to an existing Azure AI Foundry service - -If you already have an [Azure AI Foundry](https://ai.azure.com/) service, you can easily connect to it by adding a connection string to your AppHost. This approach uses a simple, string-based configuration. To establish the connection, use the `AddConnectionString` method: - -```csharp title="C# — AppHost.cs" -var builder = DistributedApplication.CreateBuilder(args); - -var aiFoundry = builder.AddConnectionString("ai-foundry"); - -builder.AddProject() - .WithReference(aiFoundry); - -// After adding all resources, run the app... -``` - -> [!NOTE] -> Connection strings are used to represent a wide range of connection information, including database connections, message brokers, endpoint URIs, and other services. In nomenclature, the term "connection string" is used to represent any kind of connection information. - -The connection string is configured in the AppHost's configuration, typically under User Secrets, under the `ConnectionStrings` section: - -```json -{ - "ConnectionStrings": { - "ai-foundry": "Endpoint=https://{endpoint}/;DeploymentId={deploymentName}" - } -} -``` - -For more information, see [Add existing Azure resources with connection strings](/integrations/cloud/azure/overview/#add-existing-azure-resources-with-connection-strings). - -## Client integration - Two kinds of clients are available in the Aspire Azure AI Inference integration: - `ChatCompletionsClient`: A client for interacting with a chat completions model. @@ -69,10 +31,11 @@ The Aspire Azure AI Inference client integration is used to work with Azure AI m +For an introduction to working with the Azure AI Inference client integration, see [Get started with the Azure AI Inference integrations](/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-get-started/). + > [!IMPORTANT] > Check the model inference tasks for both clients. Some models may only support chat completions, while others may only support embeddings. Ensure that the model you choose aligns with the client you intend to use. > This information is available in the [model catalog](https://ai.azure.com/resource/models/) and in the Quick facts section of each model's details page. - ### Add an Azure AI Inference Chat Completions client In the _Program.cs_ file of your client-consuming project, use the `AddAzureChatCompletionsClient` method on any `IHostApplicationBuilder` to register a `ChatCompletionsClient` for dependency injection (DI). diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-get-started.mdx new file mode 100644 index 00000000..f82de527 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-get-started.mdx @@ -0,0 +1,105 @@ +--- +title: Get started with the Azure AI Inference integrations +description: Learn how to set up the Aspire Azure AI Inference Hosting and Client integrations simply. +prev: false +--- + +import { Image } from 'astro:assets'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; +import { Aside, Badge, CardGrid, LinkCard } from '@astrojs/starlight/components'; +import aiFoundryIcon from '@assets/icons/azure-ai-foundry-icon.png'; + +Azure AI Inference logo + + + +[Azure AI Inference](https://learn.microsoft.com/azure/ai-foundry/how-to/deploy-models-serverless?view=foundry-classic) provides serverless API endpoints for deploying and using AI models. The Aspire Azure AI Inference integration enables you to connect to Azure AI Inference services from your applications, making it easy to call models for chat, completions, embeddings, and more. + +In this introduction, you'll see how to install and use the Aspire Azure AI Inference integrations in a simple configuration. If you already have this knowledge, see [Azure AI Inference Hosting integration](/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-host/) for full reference details. + + + +## Set up hosting integration + +Although the Azure AI Inference library doesn't currently offer direct hosting integration, you can still integrate it into your AppHost project. Simply add a connection string to establish a reference to an existing Azure AI Foundry resource. + +If you already have an [Azure AI Foundry](https://ai.azure.com/) service, you can easily connect to it by adding a connection string to your AppHost: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var aiFoundry = builder.AddConnectionString("ai-foundry"); + +builder.AddProject() + .WithReference(aiFoundry); + +// After adding all resources, run the app... + +builder.Build().Run(); +``` + +The connection string is configured in the AppHost's configuration, typically under User Secrets, under the `ConnectionStrings` section: + +```json +{ + "ConnectionStrings": { + "ai-foundry": "Endpoint=https://{endpoint}/;DeploymentId={deploymentName}" + } +} +``` + + + +## Set up client integration + +To use Azure AI Inference from your client applications, install the [📦 Aspire.Azure.AI.Inference](https://www.nuget.org/packages/Aspire.Azure.AI.Inference) NuGet package in the client-consuming project: + + + +In the _Program.cs_ file of your client-consuming project, add the Azure AI Inference Chat Completions client: + +```csharp +builder.AddAzureChatCompletionsClient(connectionName: "ai-foundry") + .AddChatClient("deploymentName"); +``` + +After adding the `IChatClient`, you can retrieve the client instance using dependency injection: + +```csharp +public class ExampleService(IChatClient chatClient) +{ + public async Task GetResponseAsync(string userMessage) + { + var response = await chatClient.CompleteAsync(userMessage); + return response.Message.Text ?? string.Empty; + } +} +``` + +For more information on using the client integration, see [Azure AI Inference Client integration](/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-client/). + +## Next steps + + + + + diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-host.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-host.mdx new file mode 100644 index 00000000..55a7dfc2 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-host.mdx @@ -0,0 +1,53 @@ +--- +title: Azure AI Inference hosting integration +description: Learn how to use the Aspire Azure AI Inference hosting integration to connect to Azure AI Inference resources. +--- + +import { Aside, Badge } from '@astrojs/starlight/components'; +import { Image } from 'astro:assets'; +import aiFoundryIcon from '@assets/icons/azure-ai-foundry-icon.png'; + +Azure AI Inference logo + + + +Although the Azure AI Inference library doesn't currently offer direct hosting integration, you can still integrate it into your AppHost project. Simply add a connection string to establish a reference to an existing Azure AI Foundry resource. + +For an introduction to working with the Azure AI Inference hosting integration, see [Get started with the Azure AI Inference integrations](/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-get-started/). + +## Connect to an existing Azure AI Foundry service + +If you already have an [Azure AI Foundry](https://ai.azure.com/) service, you can easily connect to it by adding a connection string to your AppHost. This approach uses a simple, string-based configuration. To establish the connection, use the `AddConnectionString` method: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var aiFoundry = builder.AddConnectionString("ai-foundry"); + +builder.AddProject() + .WithReference(aiFoundry); + +// After adding all resources, run the app... +``` + +> [!NOTE] +> Connection strings are used to represent a wide range of connection information, including database connections, message brokers, endpoint URIs, and other services. In nomenclature, the term "connection string" is used to represent any kind of connection information. + +The connection string is configured in the AppHost's configuration, typically under User Secrets, under the `ConnectionStrings` section: + +```json +{ + "ConnectionStrings": { + "ai-foundry": "Endpoint=https://{endpoint}/;DeploymentId={deploymentName}" + } +} +``` + +For more information, see [Add existing Azure resources with connection strings](/integrations/cloud/azure/overview/#add-existing-azure-resources-with-connection-strings). diff --git a/src/frontend/src/data/integration-docs.json b/src/frontend/src/data/integration-docs.json index 031f93e3..d1d3dbaf 100644 --- a/src/frontend/src/data/integration-docs.json +++ b/src/frontend/src/data/integration-docs.json @@ -1,7 +1,7 @@ [ { "match": "Aspire.Azure.AI.Inference", - "href": "/integrations/cloud/azure/azure-ai-inference/" + "href": "/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-get-started/" }, { "match": "Aspire.Azure.AI.OpenAI", From 08cb52fe41209da85ee4006fd4709e9d47f30c2d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 15:20:35 +0000 Subject: [PATCH 06/30] Restructure Azure AI Search integration into subfolder --- .../config/sidebar/integrations.topics.ts | 16 +- .../cloud/azure/azure-ai-search.mdx | 398 ------------------ .../azure-ai-search-client.mdx | 221 ++++++++++ .../azure-ai-search-get-started.mdx | 104 +++++ .../azure-ai-search/azure-ai-search-host.mdx | 193 +++++++++ src/frontend/src/data/integration-docs.json | 4 +- 6 files changed, 535 insertions(+), 401 deletions(-) delete mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-search.mdx create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-search/azure-ai-search-client.mdx create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-search/azure-ai-search-get-started.mdx create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-search/azure-ai-search-host.mdx diff --git a/src/frontend/config/sidebar/integrations.topics.ts b/src/frontend/config/sidebar/integrations.topics.ts index e8fda4f2..8ef057be 100644 --- a/src/frontend/config/sidebar/integrations.topics.ts +++ b/src/frontend/config/sidebar/integrations.topics.ts @@ -305,7 +305,21 @@ export const integrationTopics: StarlightSidebarTopicsUserConfig = { }, { label: 'Azure AI Search', - slug: 'integrations/cloud/azure/azure-ai-search', + collapsed: true, + items: [ + { + label: 'Get started', + slug: 'integrations/cloud/azure/azure-ai-search/azure-ai-search-get-started', + }, + { + label: 'Hosting integration (AppHost)', + slug: 'integrations/cloud/azure/azure-ai-search/azure-ai-search-host', + }, + { + label: 'Client integration', + slug: 'integrations/cloud/azure/azure-ai-search/azure-ai-search-client', + }, + ], }, { label: 'Azure OpenAI', diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-search.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-search.mdx deleted file mode 100644 index 5eba1d6d..00000000 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-search.mdx +++ /dev/null @@ -1,398 +0,0 @@ ---- -title: Azure AI Search integration -description: This article describes the Aspire Azure AI Search integration features and capabilities. ---- - -import { Aside } from '@astrojs/starlight/components'; -import InstallPackage from '@components/InstallPackage.astro'; -import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; -import { Image } from 'astro:assets'; -import searchIcon from '@assets/icons/azure-search-icon.png'; - -Azure AI Search logo - -[Azure AI Search](https://learn.microsoft.com/azure/search) is an enterprise-ready information retrieval system for your heterogeneous content that you ingest into a search index, and surface to users through queries and apps. It comes with a comprehensive set of advanced search technologies, built for high-performance applications at any scale. The Aspire Azure AI Search integration enables you to connect to Azure AI Search services from your applications. - -## Hosting integration - -The Aspire Azure AI Search hosting integration models the search service as the `AzureSearchResource` type. To access this type and APIs for expressing them within your AppHost project, install the [📦 Aspire.Hosting.Azure.Search](https://www.nuget.org/packages/Aspire.Hosting.Azure.Search) NuGet package: - - - -### Add an Azure AI Search resource - -To add an Azure AI Search resource to your AppHost project, call the `AddAzureSearch` method providing a name: - -```csharp title="C# — AppHost.cs" -var builder = DistributedApplication.CreateBuilder(args); - -var search = builder.AddAzureSearch("search"); - -builder.AddProject() - .WithReference(search); - -// After adding all resources, run the app... -``` - -The preceding code adds an Azure AI Search resource named `search` to the AppHost project. The `WithReference` method passes the connection information to the `ExampleProject` project. - - - -### Connect to an existing Azure AI Search instance - -You might have an existing Azure AI Search service that you want to connect to. You can chain a call to annotate that your `AzureSearchResource` is an existing resource: - -```csharp title="C# — AppHost.cs" -var builder = DistributedApplication.CreateBuilder(args); - -var existingSearchName = builder.AddParameter("existingSearchName"); -var existingSearchResourceGroup = builder.AddParameter("existingSearchResourceGroup"); - -var search = builder.AddAzureSearch("search") - .AsExisting(existingSearchName, existingSearchResourceGroup); - -builder.AddProject() - .WithReference(search); - -// After adding all resources, run the app... -``` - -For more information on treating Azure AI Search resources as existing resources, see [Use existing Azure resources](/integrations/cloud/azure/overview/#use-existing-azure-resources). - - - -### Provisioning-generated Bicep - -If you're new to [Bicep](https://learn.microsoft.com/azure/azure-resource-manager/bicep/overview), it's a domain-specific language for defining Azure resources. With , you don't need to write Bicep by hand; instead, the provisioning APIs generate Bicep for you. When you publish your app, the generated Bicep is output alongside the manifest file. When you add an Azure AI Search resource, Bicep is generated to provision the search service with appropriate defaults. - -```bicep title="Generated Bicep — search.bicep" -@description('The location for the resource(s) to be deployed.') -param location string = resourceGroup().location - -resource search 'Microsoft.Search/searchServices@2023-11-01' = { - name: take('search-${uniqueString(resourceGroup().id)}', 60) - location: location - properties: { - hostingMode: 'default' - disableLocalAuth: true - partitionCount: 1 - replicaCount: 1 - } - sku: { - name: 'basic' - } - tags: { - 'aspire-resource-name': 'search' - } -} - -output connectionString string = 'Endpoint=https://${search.name}.search.windows.net' - -output name string = search.name -``` - -The preceding Bicep is a module that provisions an Azure AI Search service resource. Additionally, role assignments are created for the Azure resource in a separate module: - -```bicep title="Generated Bicep — search-roles.bicep" -@description('The location for the resource(s) to be deployed.') -param location string = resourceGroup().location - -param search_outputs_name string - -param principalType string - -param principalId string - -resource search 'Microsoft.Search/searchServices@2023-11-01' existing = { - name: search_outputs_name -} - -resource search_SearchIndexDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = { - name: guid(search.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '8ebe5a00-799e-43f5-93ac-243d3dce84a7')) - properties: { - principalId: principalId - roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '8ebe5a00-799e-43f5-93ac-243d3dce84a7') - principalType: principalType - } - scope: search -} - -resource search_SearchServiceContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = { - name: guid(search.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '7ca78c08-252a-4471-8644-bb5ff32d4ba0')) - properties: { - principalId: principalId - roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '7ca78c08-252a-4471-8644-bb5ff32d4ba0') - principalType: principalType - } - scope: search -} -``` - -The generated Bicep is a starting point and is influenced by changes to the provisioning infrastructure in C#. Customizations to the Bicep file directly will be overwritten, so make changes through the C# provisioning APIs to ensure they are reflected in the generated files. - -#### Customize provisioning infrastructure - -All Aspire Azure resources are subclasses of the `AzureProvisioningResource` type. This type enables the customization of the generated Bicep by providing a fluent API to configure the Azure resources using the `ConfigureInfrastructure` API: - -```csharp title="C# — AppHost.cs" -var builder = DistributedApplication.CreateBuilder(args); - -builder.AddAzureSearch("search") - .ConfigureInfrastructure(infra => - { - var searchService = infra.GetProvisionableResources() - .OfType() - .Single(); - - searchService.PartitionCount = 6; - searchService.ReplicaCount = 3; - searchService.SearchSkuName = SearchServiceSkuName.Standard3; - searchService.Tags.Add("ExampleKey", "Example value"); - }); -``` - -The preceding code: - -- Chains a call to the `ConfigureInfrastructure` API: - - The `infra` parameter is an instance of the `AzureResourceInfrastructure` type. - - The provisionable resources are retrieved by calling the `GetProvisionableResources` method. - - The single `SearchService` resource is retrieved. - - The `PartitionCount` is set to `6`. - - The `ReplicaCount` is set to `3`. - - The `SearchSkuName` is set to `Standard3`. - - A tag is added to the Cognitive Services resource with a key of `ExampleKey` and a value of `Example value`. - -There are many more configuration options available to customize the Search resource. For more information, see [Azure.Provisioning customization](/integrations/cloud/azure/customize-resources/#azureprovisioning-customization). - -### Connection properties - -When you reference an Azure AI Search service using `WithReference`, the following connection properties are made available to the consuming project: - -| Property Name | Description | -| ------------- | ---------------------------------------------------------------------------------------------------- | -| `Uri` | The HTTPS endpoint of the Azure AI Search service in the format `https://{name}.search.windows.net`. | - - - -## Client integration - -The Aspire Azure AI Search client integration is used to connect to an Azure AI Search service using the `SearchIndexClient`. To get started with the Aspire Azure AI Search client integration, install the [📦 Aspire.Azure.Search.Documents](https://www.nuget.org/packages/Aspire.Azure.Search.Documents) NuGet package. - - - -### Add an Azure AI Search index client - -In the `Program.cs` file of your client-consuming project, call the `AddAzureSearchClient` extension method on any `IHostApplicationBuilder` to register a [SearchIndexClient class](https://learn.microsoft.com/dotnet/api/microsoft.azure.search.searchindexclient) for use via the dependency injection container. The method takes a connection name parameter. - -```csharp -builder.AddAzureSearchClient(connectionName: "search"); -``` - -> [!TIP] -> The `connectionName` parameter must match the name used when adding the Azure AI Search resource in the AppHost project. For more information, see [Add an Azure AI Search resource](#add-an-azure-ai-search-resource). - -After adding the `SearchIndexClient`, you can retrieve the client instance using dependency injection. For example, to retrieve the client instance from an example service: - -```csharp -public class ExampleService(SearchIndexClient indexClient) -{ - // Use indexClient -} -``` - -You can also retrieve a `SearchClient` which can be used for querying, by calling the `GetSearchClient` method: - -```csharp -public class ExampleService(SearchIndexClient indexClient) -{ - public async Task GetDocumentCountAsync( - string indexName, - CancellationToken cancellationToken) - { - var searchClient = indexClient.GetSearchClient(indexName); - - var documentCountResponse = await searchClient.GetDocumentCountAsync( - cancellationToken); - - return documentCountResponse.Value; - } -} -``` - -For more information, see: - -- Azure AI Search client library for .NET [samples using the `SearchIndexClient`](https://learn.microsoft.com/azure/search/samples-dotnet). -- [Dependency injection in .NET](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection) for details on dependency injection. - -### Add keyed Azure AI Search index client - -There might be situations where you want to register multiple `SearchIndexClient` instances with different connection names. To register keyed Azure AI Search clients, call the `AddKeyedAzureSearchClient` method: - -```csharp -builder.AddKeyedAzureSearchClient(name: "images"); -builder.AddKeyedAzureSearchClient(name: "documents"); -``` - -> [!IMPORTANT] -> When using keyed services, it's expected that your Azure AI Search resource configured two named connections, one for the `images` and one for the `documents`. - -Then you can retrieve the client instances using dependency injection. For example, to retrieve the clients from a service: - -```csharp -public class ExampleService( - [KeyedService("images")] SearchIndexClient imagesClient, - [KeyedService("documents")] SearchIndexClient documentsClient) -{ - // Use clients... -} -``` - -For more information, see [Keyed services in .NET](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection#keyed-services). - -### Configuration - -The Azure AI Search Documents library provides multiple options to configure the Azure AI Search connection based on the requirements and conventions of your project. Either an `Endpoint` or a `ConnectionString` is required to be supplied. - -#### Use a connection string - -A connection can be constructed from the **Keys and Endpoint** tab with the format `Endpoint={endpoint};Key={key};`. You can provide the name of the connection string when calling `builder.AddAzureSearchClient()`: - -```csharp -builder.AddAzureSearchClient("searchConnectionName"); -``` - -The connection string is retrieved from the `ConnectionStrings` configuration section. Two connection formats are supported: - -##### Account endpoint - -The recommended approach is to use an `Endpoint`, which works with the `AzureSearchSettings.Credential` property to establish a connection. If no credential is configured, the `DefaultAzureCredential` is used. - -```json -{ - "ConnectionStrings": { - "search": "https://{search_service}.search.windows.net/" - } -} -``` - -##### Connection string - -Alternatively, a connection string with key can be used, however; it's not the recommended approach: - -```json -{ - "ConnectionStrings": { - "search": "Endpoint=https://{search_service}.search.windows.net/;Key={account_key};" - } -} -``` - -### Use configuration providers - -The Azure AI Search library supports `Microsoft.Extensions.Configuration`. It loads the `AzureSearchSettings` and `SearchClientOptions` from configuration by using the `Aspire:Azure:Search:Documents` key. Example `appsettings.json` that configures some of the options: - -```json -{ - "Aspire": { - "Azure": { - "Search": { - "Documents": { - "DisableTracing": false - } - } - } - } -} -``` - -For the complete Azure AI Search Documents client integration JSON schema, see [Aspire.Azure.Search.Documents/ConfigurationSchema.json](https://github.com/dotnet/aspire/blob/main/src/Components/Aspire.Azure.Search.Documents/ConfigurationSchema.json). - -### Use named configuration - -The Azure AI Search library supports named configuration, which allows you to configure multiple instances of the same resource type with different settings. The named configuration uses the connection name as a key under the main configuration section. - -```json -{ - "Aspire": { - "Azure": { - "Search": { - "Documents": { - "search1": { - "Endpoint": "https://mysearch1.search.windows.net/", - "DisableTracing": false - }, - "search2": { - "Endpoint": "https://mysearch2.search.windows.net/", - "DisableTracing": true - } - } - } - } - } -} -``` - -In this example, the `search1` and `search2` connection names can be used when calling `AddAzureSearchClient`: - -```csharp -builder.AddAzureSearchClient("search1"); -builder.AddAzureSearchClient("search2"); -``` - -Named configuration takes precedence over the top-level configuration. If both are provided, the settings from the named configuration override the top-level settings. - -### Use inline delegates - -You can also pass the `Action configureSettings` delegate to set up some or all the options inline, for example to disable tracing from code: - -```csharp -builder.AddAzureSearchClient( - "searchConnectionName", - static settings => settings.DisableTracing = true); -``` - -You can also set up the `SearchClientOptions` using the optional `Action> configureClientBuilder` parameter of the `AddAzureSearchClient` method. For example, to set the client ID for this client: - -```csharp -builder.AddAzureSearchClient( - "searchConnectionName", - configureClientBuilder: builder => builder.ConfigureOptions( - static options => options.Diagnostics.ApplicationId = "CLIENT_ID")); -``` - -The Azure AI Search Documents integration implements a single health check that calls the `GetServiceStatisticsAsync` method on the `SearchIndexClient` to verify that the service is available. - -Aspire integrations automatically set up Logging, Tracing, and Metrics configurations, which are sometimes known as _the pillars of observability_. For more information about integration observability and telemetry, see [Aspire integrations overview](/integrations/overview/). Depending on the backing service, some integrations may only support some of these features. For example, some integrations support logging and tracing, but not metrics. Telemetry features can also be disabled using the techniques presented in the [Configuration](#configuration) section. - -### Logging - -The Azure AI Search Documents integration uses the following log categories: - -- `Azure` -- `Azure.Core` -- `Azure.Identity` - -### Tracing - -The Azure AI Search Documents integration emits tracing activities using OpenTelemetry when interacting with the search service. diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-search/azure-ai-search-client.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-search/azure-ai-search-client.mdx new file mode 100644 index 00000000..fbaa6ba2 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-search/azure-ai-search-client.mdx @@ -0,0 +1,221 @@ +--- +title: Azure AI Search client integration +description: Learn how to use the Aspire Azure AI Search client integration to connect to Azure AI Search services. +next: false +--- + +import { Aside } from '@astrojs/starlight/components'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; +import { Image } from 'astro:assets'; +import searchIcon from '@assets/icons/azure-search-icon.png'; + +Azure AI Search logo + +The Aspire Azure AI Search client integration is used to connect to an Azure AI Search service using the `SearchIndexClient`. To get started with the Aspire Azure AI Search client integration, install the [📦 Aspire.Azure.Search.Documents](https://www.nuget.org/packages/Aspire.Azure.Search.Documents) NuGet package. + + + +For an introduction to working with the Azure AI Search client integration, see [Get started with the Azure AI Search integration](/integrations/cloud/azure/azure-ai-search/azure-ai-search-get-started/). + +## Add an Azure AI Search index client + +In the `Program.cs` file of your client-consuming project, call the `AddAzureSearchClient` extension method on any `IHostApplicationBuilder` to register a [SearchIndexClient class](https://learn.microsoft.com/dotnet/api/microsoft.azure.search.searchindexclient) for use via the dependency injection container. The method takes a connection name parameter. + +```csharp +builder.AddAzureSearchClient(connectionName: "search"); +``` + +> [!TIP] +> The `connectionName` parameter must match the name used when adding the Azure AI Search resource in the AppHost project. For more information, see [Add an Azure AI Search resource](/integrations/cloud/azure/azure-ai-search/azure-ai-search-host/#add-an-azure-ai-search-resource). + +After adding the `SearchIndexClient`, you can retrieve the client instance using dependency injection. For example, to retrieve the client instance from an example service: + +```csharp +public class ExampleService(SearchIndexClient indexClient) +{ + // Use indexClient +} +``` + +You can also retrieve a `SearchClient` which can be used for querying, by calling the `GetSearchClient` method: + +```csharp +public class ExampleService(SearchIndexClient indexClient) +{ + public async Task GetDocumentCountAsync( + string indexName, + CancellationToken cancellationToken) + { + var searchClient = indexClient.GetSearchClient(indexName); + + var documentCountResponse = await searchClient.GetDocumentCountAsync( + cancellationToken); + + return documentCountResponse.Value; + } +} +``` + +For more information, see: + +- Azure AI Search client library for .NET [samples using the `SearchIndexClient`](https://learn.microsoft.com/azure/search/samples-dotnet). +- [Dependency injection in .NET](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection) for details on dependency injection. + +## Add keyed Azure AI Search index client + +There might be situations where you want to register multiple `SearchIndexClient` instances with different connection names. To register keyed Azure AI Search clients, call the `AddKeyedAzureSearchClient` method: + +```csharp +builder.AddKeyedAzureSearchClient(name: "images"); +builder.AddKeyedAzureSearchClient(name: "documents"); +``` + +> [!IMPORTANT] +> When using keyed services, it's expected that your Azure AI Search resource configured two named connections, one for the `images` and one for the `documents`. + +Then you can retrieve the client instances using dependency injection. For example, to retrieve the clients from a service: + +```csharp +public class ExampleService( + [KeyedService("images")] SearchIndexClient imagesClient, + [KeyedService("documents")] SearchIndexClient documentsClient) +{ + // Use clients... +} +``` + +For more information, see [Keyed services in .NET](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection#keyed-services). + +## Configuration + +The Azure AI Search Documents library provides multiple options to configure the Azure AI Search connection based on the requirements and conventions of your project. Either an `Endpoint` or a `ConnectionString` is required to be supplied. + +### Use a connection string + +A connection can be constructed from the **Keys and Endpoint** tab with the format `Endpoint={endpoint};Key={key};`. You can provide the name of the connection string when calling `builder.AddAzureSearchClient()`: + +```csharp +builder.AddAzureSearchClient("searchConnectionName"); +``` + +The connection string is retrieved from the `ConnectionStrings` configuration section. Two connection formats are supported: + +#### Account endpoint + +The recommended approach is to use an `Endpoint`, which works with the `AzureSearchSettings.Credential` property to establish a connection. If no credential is configured, the `DefaultAzureCredential` is used. + +```json +{ + "ConnectionStrings": { + "search": "https://{search_service}.search.windows.net/" + } +} +``` + +#### Connection string + +Alternatively, a connection string with key can be used, however; it's not the recommended approach: + +```json +{ + "ConnectionStrings": { + "search": "Endpoint=https://{search_service}.search.windows.net/;Key={account_key};" + } +} +``` + +### Use configuration providers + +The Azure AI Search library supports `Microsoft.Extensions.Configuration`. It loads the `AzureSearchSettings` and `SearchClientOptions` from configuration by using the `Aspire:Azure:Search:Documents` key. Example `appsettings.json` that configures some of the options: + +```json +{ + "Aspire": { + "Azure": { + "Search": { + "Documents": { + "DisableTracing": false + } + } + } + } +} +``` + +For the complete Azure AI Search Documents client integration JSON schema, see [Aspire.Azure.Search.Documents/ConfigurationSchema.json](https://github.com/dotnet/aspire/blob/main/src/Components/Aspire.Azure.Search.Documents/ConfigurationSchema.json). + +### Use named configuration + +The Azure AI Search library supports named configuration, which allows you to configure multiple instances of the same resource type with different settings. The named configuration uses the connection name as a key under the main configuration section. + +```json +{ + "Aspire": { + "Azure": { + "Search": { + "Documents": { + "search1": { + "Endpoint": "https://mysearch1.search.windows.net/", + "DisableTracing": false + }, + "search2": { + "Endpoint": "https://mysearch2.search.windows.net/", + "DisableTracing": true + } + } + } + } + } +} +``` + +In this example, the `search1` and `search2` connection names can be used when calling `AddAzureSearchClient`: + +```csharp +builder.AddAzureSearchClient("search1"); +builder.AddAzureSearchClient("search2"); +``` + +Named configuration takes precedence over the top-level configuration. If both are provided, the settings from the named configuration override the top-level settings. + +### Use inline delegates + +You can also pass the `Action configureSettings` delegate to set up some or all the options inline, for example to disable tracing from code: + +```csharp +builder.AddAzureSearchClient( + "searchConnectionName", + static settings => settings.DisableTracing = true); +``` + +You can also set up the `SearchClientOptions` using the optional `Action> configureClientBuilder` parameter of the `AddAzureSearchClient` method. For example, to set the client ID for this client: + +```csharp +builder.AddAzureSearchClient( + "searchConnectionName", + configureClientBuilder: builder => builder.ConfigureOptions( + static options => options.Diagnostics.ApplicationId = "CLIENT_ID")); +``` + +The Azure AI Search Documents integration implements a single health check that calls the `GetServiceStatisticsAsync` method on the `SearchIndexClient` to verify that the service is available. + +Aspire integrations automatically set up Logging, Tracing, and Metrics configurations, which are sometimes known as _the pillars of observability_. For more information about integration observability and telemetry, see [Aspire integrations overview](/integrations/overview/). Depending on the backing service, some integrations may only support some of these features. For example, some integrations support logging and tracing, but not metrics. Telemetry features can also be disabled using the techniques presented in the [Configuration](#configuration) section. + +## Logging + +The Azure AI Search Documents integration uses the following log categories: + +- `Azure` +- `Azure.Core` +- `Azure.Identity` + +## Tracing + +The Azure AI Search Documents integration emits tracing activities using OpenTelemetry when interacting with the search service. diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-search/azure-ai-search-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-search/azure-ai-search-get-started.mdx new file mode 100644 index 00000000..f8d8d3d3 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-search/azure-ai-search-get-started.mdx @@ -0,0 +1,104 @@ +--- +title: Get started with the Azure AI Search integration +description: Learn how to set up the Aspire Azure AI Search Hosting and Client integrations simply. +prev: false +--- + +import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components'; +import InstallPackage from '@components/InstallPackage.astro'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; +import { Image } from 'astro:assets'; +import searchIcon from '@assets/icons/azure-search-icon.png'; + +Azure AI Search logo + +[Azure AI Search](https://learn.microsoft.com/azure/search) is an enterprise-ready information retrieval system for your heterogeneous content that you ingest into a search index, and surface to users through queries and apps. It comes with a comprehensive set of advanced search technologies, built for high-performance applications at any scale. The Aspire Azure AI Search integration enables you to connect to Azure AI Search services from your applications. + +In this introduction, you'll see how to install and use the Aspire Azure AI Search integrations in a simple configuration. If you already have this knowledge, see [Azure AI Search Hosting integration](/integrations/cloud/azure/azure-ai-search/azure-ai-search-host/) for full reference details. + + + +## Set up hosting integration + +To begin, install the Aspire Azure AI Search Hosting integration in your Aspire AppHost project. This integration allows you to create and manage Azure AI Search resources from your Aspire hosting projects: + + + +Next, in the AppHost project, create an Azure AI Search resource and pass it to the consuming client projects: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var search = builder.AddAzureSearch("search"); + +builder.AddProject() + .WithReference(search); + +// After adding all resources, run the app... + +builder.Build().Run(); +``` + +The preceding code adds an Azure AI Search resource named `search` to the AppHost project. The `WithReference` method passes the connection information to the `ExampleProject` project. + + + + + +## Set up client integration + +To use Azure AI Search from your client applications, install the Aspire Azure AI Search client integration in your client project: + + + +In the `Program.cs` file of your client-consuming project, call the `AddAzureSearchClient` extension method to register a `SearchIndexClient` for use via the dependency injection container: + +```csharp +builder.AddAzureSearchClient(connectionName: "search"); +``` + +> [!TIP] +> The `connectionName` parameter must match the name used when adding the Azure AI Search resource in the AppHost project. + +After adding the `SearchIndexClient`, you can retrieve the client instance using dependency injection: + +```csharp +public class ExampleService(SearchIndexClient indexClient) +{ + // Use indexClient +} +``` + +For full details on using the client integration, see [Azure AI Search Client integration](/integrations/cloud/azure/azure-ai-search/azure-ai-search-client/). + +## Next steps + + + + + diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-search/azure-ai-search-host.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-search/azure-ai-search-host.mdx new file mode 100644 index 00000000..ce0e68ae --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-search/azure-ai-search-host.mdx @@ -0,0 +1,193 @@ +--- +title: Azure AI Search hosting integration +description: Learn how to use the Aspire Azure AI Search hosting integration to create Azure AI Search resources. +--- + +import { Aside } from '@astrojs/starlight/components'; +import InstallPackage from '@components/InstallPackage.astro'; +import { Image } from 'astro:assets'; +import searchIcon from '@assets/icons/azure-search-icon.png'; + +Azure AI Search logo + +The Aspire Azure AI Search hosting integration models the search service as the `AzureSearchResource` type. To access this type and APIs for expressing them within your AppHost project, install the [📦 Aspire.Hosting.Azure.Search](https://www.nuget.org/packages/Aspire.Hosting.Azure.Search) NuGet package: + + + +For an introduction to working with the Azure AI Search hosting integration, see [Get started with the Azure AI Search integration](/integrations/cloud/azure/azure-ai-search/azure-ai-search-get-started/). + +## Add an Azure AI Search resource + +To add an Azure AI Search resource to your AppHost project, call the `AddAzureSearch` method providing a name: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var search = builder.AddAzureSearch("search"); + +builder.AddProject() + .WithReference(search); + +// After adding all resources, run the app... +``` + +The preceding code adds an Azure AI Search resource named `search` to the AppHost project. The `WithReference` method passes the connection information to the `ExampleProject` project. + + + +## Connect to an existing Azure AI Search instance + +You might have an existing Azure AI Search service that you want to connect to. You can chain a call to annotate that your `AzureSearchResource` is an existing resource: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var existingSearchName = builder.AddParameter("existingSearchName"); +var existingSearchResourceGroup = builder.AddParameter("existingSearchResourceGroup"); + +var search = builder.AddAzureSearch("search") + .AsExisting(existingSearchName, existingSearchResourceGroup); + +builder.AddProject() + .WithReference(search); + +// After adding all resources, run the app... +``` + +For more information on treating Azure AI Search resources as existing resources, see [Use existing Azure resources](/integrations/cloud/azure/overview/#use-existing-azure-resources). + + + +## Provisioning-generated Bicep + +If you're new to [Bicep](https://learn.microsoft.com/azure/azure-resource-manager/bicep/overview), it's a domain-specific language for defining Azure resources. With , you don't need to write Bicep by hand; instead, the provisioning APIs generate Bicep for you. When you publish your app, the generated Bicep is output alongside the manifest file. When you add an Azure AI Search resource, Bicep is generated to provision the search service with appropriate defaults. + +```bicep title="Generated Bicep — search.bicep" +@description('The location for the resource(s) to be deployed.') +param location string = resourceGroup().location + +resource search 'Microsoft.Search/searchServices@2023-11-01' = { + name: take('search-${uniqueString(resourceGroup().id)}', 60) + location: location + properties: { + hostingMode: 'default' + disableLocalAuth: true + partitionCount: 1 + replicaCount: 1 + } + sku: { + name: 'basic' + } + tags: { + 'aspire-resource-name': 'search' + } +} + +output connectionString string = 'Endpoint=https://${search.name}.search.windows.net' + +output name string = search.name +``` + +The preceding Bicep is a module that provisions an Azure AI Search service resource. Additionally, role assignments are created for the Azure resource in a separate module: + +```bicep title="Generated Bicep — search-roles.bicep" +@description('The location for the resource(s) to be deployed.') +param location string = resourceGroup().location + +param search_outputs_name string + +param principalType string + +param principalId string + +resource search 'Microsoft.Search/searchServices@2023-11-01' existing = { + name: search_outputs_name +} + +resource search_SearchIndexDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(search.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '8ebe5a00-799e-43f5-93ac-243d3dce84a7')) + properties: { + principalId: principalId + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '8ebe5a00-799e-43f5-93ac-243d3dce84a7') + principalType: principalType + } + scope: search +} + +resource search_SearchServiceContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(search.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '7ca78c08-252a-4471-8644-bb5ff32d4ba0')) + properties: { + principalId: principalId + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '7ca78c08-252a-4471-8644-bb5ff32d4ba0') + principalType: principalType + } + scope: search +} +``` + +The generated Bicep is a starting point and is influenced by changes to the provisioning infrastructure in C#. Customizations to the Bicep file directly will be overwritten, so make changes through the C# provisioning APIs to ensure they are reflected in the generated files. + +### Customize provisioning infrastructure + +All Aspire Azure resources are subclasses of the `AzureProvisioningResource` type. This type enables the customization of the generated Bicep by providing a fluent API to configure the Azure resources using the `ConfigureInfrastructure` API: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +builder.AddAzureSearch("search") + .ConfigureInfrastructure(infra => + { + var searchService = infra.GetProvisionableResources() + .OfType() + .Single(); + + searchService.PartitionCount = 6; + searchService.ReplicaCount = 3; + searchService.SearchSkuName = SearchServiceSkuName.Standard3; + searchService.Tags.Add("ExampleKey", "Example value"); + }); +``` + +The preceding code: + +- Chains a call to the `ConfigureInfrastructure` API: + - The `infra` parameter is an instance of the `AzureResourceInfrastructure` type. + - The provisionable resources are retrieved by calling the `GetProvisionableResources` method. + - The single `SearchService` resource is retrieved. + - The `PartitionCount` is set to `6`. + - The `ReplicaCount` is set to `3`. + - The `SearchSkuName` is set to `Standard3`. + - A tag is added to the Cognitive Services resource with a key of `ExampleKey` and a value of `Example value`. + +There are many more configuration options available to customize the Search resource. For more information, see [Azure.Provisioning customization](/integrations/cloud/azure/customize-resources/#azureprovisioning-customization). + +## Connection properties + +When you reference an Azure AI Search service using `WithReference`, the following connection properties are made available to the consuming project: + +| Property Name | Description | +| ------------- | ---------------------------------------------------------------------------------------------------- | +| `Uri` | The HTTPS endpoint of the Azure AI Search service in the format `https://{name}.search.windows.net`. | + + diff --git a/src/frontend/src/data/integration-docs.json b/src/frontend/src/data/integration-docs.json index d1d3dbaf..355ed23e 100644 --- a/src/frontend/src/data/integration-docs.json +++ b/src/frontend/src/data/integration-docs.json @@ -33,7 +33,7 @@ }, { "match": "Aspire.Azure.Search.Documents", - "href": "/integrations/cloud/azure/azure-ai-search/" + "href": "/integrations/cloud/azure/azure-ai-search/azure-ai-search-get-started/" }, { "match": "Aspire.Azure.Security.KeyVault", @@ -121,7 +121,7 @@ }, { "match": "Aspire.Hosting.Azure.Search", - "href": "/integrations/cloud/azure/azure-ai-search/" + "href": "/integrations/cloud/azure/azure-ai-search/azure-ai-search-get-started/" }, { "match": "Aspire.Hosting.Azure.ServiceBus", From fccbde4ba6de9ed98182d3df180c05839d102831 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 15:24:30 +0000 Subject: [PATCH 07/30] Restructure Azure App Configuration integration into subfolder --- .../config/sidebar/integrations.topics.ts | 16 +- .../azure-app-configuration-client.mdx | 170 ++++++++++++++ .../azure-app-configuration-get-started.mdx | 97 ++++++++ .../azure-app-configuration-host.mdx} | 207 ++---------------- src/frontend/src/data/integration-docs.json | 4 +- 5 files changed, 297 insertions(+), 197 deletions(-) create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-app-configuration/azure-app-configuration-client.mdx create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-app-configuration/azure-app-configuration-get-started.mdx rename src/frontend/src/content/docs/integrations/cloud/azure/{azure-app-configuration.mdx => azure-app-configuration/azure-app-configuration-host.mdx} (57%) diff --git a/src/frontend/config/sidebar/integrations.topics.ts b/src/frontend/config/sidebar/integrations.topics.ts index 8ef057be..007deda0 100644 --- a/src/frontend/config/sidebar/integrations.topics.ts +++ b/src/frontend/config/sidebar/integrations.topics.ts @@ -329,7 +329,21 @@ export const integrationTopics: StarlightSidebarTopicsUserConfig = { }, { label: 'Azure App Configuration', - slug: 'integrations/cloud/azure/azure-app-configuration', + collapsed: true, + items: [ + { + label: 'Get started', + slug: 'integrations/cloud/azure/azure-app-configuration/azure-app-configuration-get-started', + }, + { + label: 'Hosting integration (AppHost)', + slug: 'integrations/cloud/azure/azure-app-configuration/azure-app-configuration-host', + }, + { + label: 'Client integration', + slug: 'integrations/cloud/azure/azure-app-configuration/azure-app-configuration-client', + }, + ], }, { label: 'Azure App Service', diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-app-configuration/azure-app-configuration-client.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-app-configuration/azure-app-configuration-client.mdx new file mode 100644 index 00000000..0391a0d5 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-app-configuration/azure-app-configuration-client.mdx @@ -0,0 +1,170 @@ +--- +title: Azure App Configuration Client integration +description: Learn about the Aspire Azure App Configuration client integration including feature flags, configuration, and telemetry. +--- + +import { Aside } from '@astrojs/starlight/components'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; + +To get started with the Aspire Azure App Configuration client integration, install the [📦 Aspire.Microsoft.Extensions.Configuration.AzureAppConfiguration](https://www.nuget.org/packages/Aspire.Microsoft.Extensions.Configuration.AzureAppConfiguration) NuGet package in the client-consuming project, that is, the project for the application that uses the App Configuration client. The App Configuration client integration registers an Azure configuration provider to populate the `IConfiguration` instance. + + + +In the `Program.cs` file of your client-consuming project, call the `AddAzureAppConfiguration` extension method on any `IHostApplicationBuilder` to register the required services to flow Azure App Configuration values into the `IConfiguration` instance for use via the dependency injection container. The method takes a connection name parameter. + +```csharp title="C# — Program.cs" +builder.AddAzureAppConfiguration(connectionName: "config"); +``` + +> [!TIP] +> The `connectionName` parameter must match the name used when adding the App Configuration resource in the AppHost project. In other words, when you call `AddAzureAppConfiguration` in the AppHost and provide a name of `config` that same name should be used when calling `AddAzureAppConfiguration` in the client-consuming project. For more information, see [Add an Azure App Configuration resource](/integrations/cloud/azure/azure-app-configuration/azure-app-configuration-host/#add-an-azure-app-configuration-resource). + +You can then retrieve the `IConfiguration` instance using dependency injection. For example, to retrieve the client from an example service: + +```csharp title="C# — ExampleService.cs" +public class ExampleService(IConfiguration configuration) +{ + private readonly string _someValue = configuration["SomeKey"]; +} +``` + +## Configure the Azure App Configuration provider + +The `AddAzureAppConfiguration` method accepts an optional `Action configureOptions` delegate that you use to configure the Azure App Configuration provider. This follows the same pattern as the non-Aspire `Microsoft.Extensions.Configuration.AzureAppConfiguration` package, but Aspire automatically handles the connection—you don't need to call `options.Connect`. + +```csharp title="C# — Program.cs" +builder.AddAzureAppConfiguration( + "config", + configureOptions: options => + { + // Select specific keys or labels + options.Select("MyApp:*"); + options.Select("MyApp:*", "Production"); + + // Configure refresh options + options.ConfigureRefresh(refresh => + { + refresh.Register("MyApp:Sentinel", refreshAll: true) + .SetRefreshInterval(TimeSpan.FromSeconds(30)); + }); + }); +``` + +For more information on available configuration options, see the [Azure App Configuration provider reference](https://learn.microsoft.com/azure/azure-app-configuration/reference-dotnet-provider). + +## Use feature flags + +To use feature flags, install the [📦 Microsoft.FeatureManagement](https://www.nuget.org/packages/Microsoft.FeatureManagement) NuGet package: + + + +App Configuration doesn't load feature flags by default. To load feature flags, use the `configureOptions` delegate (as shown in [Configure the Azure App Configuration provider](#configure-the-azure-app-configuration-provider)) to call `UseFeatureFlags()` when calling `builder.AddAzureAppConfiguration`. + +```csharp title="C# — Program.cs" +builder.AddAzureAppConfiguration( + "config", + configureOptions: options => options.UseFeatureFlags()); + +// Register feature management services +builder.Services.AddFeatureManagement(); +``` + +The `configureOptions` pattern is used to configure the Azure App Configuration provider. For more information, see [Azure App Configuration: .NET configuration provider](https://learn.microsoft.com/azure/azure-app-configuration/reference-dotnet-provider). You can then use `IFeatureManager` to evaluate feature flags in your app. Consider the following example ASP.NET Core Minimal API app: + +```csharp title="C# — Program.cs" +using Microsoft.Extensions.Hosting; +using Microsoft.FeatureManagement; + +var builder = WebApplication.CreateBuilder(args); + +builder.AddAzureAppConfiguration( + "config", + configureOptions: options => options.UseFeatureFlags()); + +// Register feature management services +builder.Services.AddFeatureManagement(); + +var app = builder.Build(); + +app.MapGet("/", async (IFeatureManager featureManager) => +{ + if (await featureManager.IsEnabledAsync("NewFeature")) + { + return Results.Ok("New feature is enabled!"); + } + + return Results.Ok("Using standard implementation."); +}); + +app.Run(); +``` + +For more information, see [.NET Feature Management](https://learn.microsoft.com/azure/azure-app-configuration/feature-management-dotnet-reference). + +## Configuration + +The Aspire Azure App Configuration library provides multiple options to configure the Azure App Configuration connection based on the requirements and conventions of your project. The App Config endpoint is required to be supplied, either in `AzureAppConfigurationSettings.Endpoint` or using a connection string. + +### Use a connection string + +When using a connection string from the `ConnectionStrings` configuration section, you can provide the name of the connection string when calling `builder.AddAzureAppConfiguration()`: + +```csharp title="C# — Program.cs" +builder.AddAzureAppConfiguration("config"); +``` + +Then the App Configuration endpoint is retrieved from the `ConnectionStrings` configuration section. The App Configuration store URI works with the `AzureAppConfigurationSettings.Credential` property to establish a connection. If no credential is configured, the `DefaultAzureCredential` is used. + +```json title="JSON — appsettings.json" +{ + "ConnectionStrings": { + "config": "https://{store_name}.azconfig.io" + } +} +``` + +### Use configuration providers + +The Aspire Azure App Configuration library supports `Microsoft.Extensions.Configuration`. It loads the `AzureAppConfigurationSettings` from configuration by using the `Aspire:Microsoft:Extensions:Configuration:AzureAppConfiguration` key. Example _appsettings.json_ that configures some of the options: + +```json title="JSON — appsettings.json" +{ + "Aspire": { + "Microsoft": { + "Extensions": { + "Configuration": { + "AzureAppConfiguration": { + "Endpoint": "YOUR_APPCONFIGURATION_ENDPOINT_URI" + } + } + } + } + } +} +``` + +For the complete App Configuration client integration JSON schema, see [ConfigurationSchema.json](https://github.com/dotnet/aspire/blob/main/src/Components/Aspire.Microsoft.Extensions.Configuration.AzureAppConfiguration/ConfigurationSchema.json). + +### Use inline delegates + +You can also pass the `Action configureSettings` delegate to set up some or all the options inline, for example to set App Configuration endpoint from code: + +```csharp title="C# — Program.cs" +builder.AddAzureAppConfiguration( + "config", + configureSettings: settings => settings.Endpoint = "https://YOUR_URI"); +``` + +## Logging + +The Aspire Azure App Configuration integration uses the following log categories: + +- `Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh` + +## Tracing + +The Aspire Azure App Configuration integration doesn't make use of any activity sources thus no tracing is available. + +## Metrics + +The Aspire Azure App Configuration integration currently doesn't support metrics. diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-app-configuration/azure-app-configuration-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-app-configuration/azure-app-configuration-get-started.mdx new file mode 100644 index 00000000..417e51fd --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-app-configuration/azure-app-configuration-get-started.mdx @@ -0,0 +1,97 @@ +--- +title: Get started with the Azure App Configuration integrations +description: Learn how to set up the Aspire Azure App Configuration Hosting and Client integrations simply. +prev: false +--- + +import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components'; +import InstallPackage from '@components/InstallPackage.astro'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; +import { Image } from 'astro:assets'; +import appConfigIcon from '@assets/icons/azure-appconfig-icon.png'; + +Azure App Configuration logo + +[Azure App Configuration](https://learn.microsoft.com/azure-app-configuration) provides a service to centrally manage application settings and feature flags. Modern programs, especially programs running in a cloud, generally have many components that are distributed in nature. Spreading configuration settings across these components can lead to hard-to-troubleshoot errors during an application deployment. The Aspire Azure App Configuration integration enables you to connect to existing App Configuration instances or create new instances all from your AppHost. + +In this introduction, you'll see how to install and use the Aspire Azure App Configuration integrations in a simple configuration. If you already have this knowledge, see [Azure App Configuration Hosting integration](/integrations/cloud/azure/azure-app-configuration/azure-app-configuration-host/) for full reference details. + + + +## Set up hosting integration + +To begin, install the Aspire Azure App Configuration Hosting integration in your Aspire AppHost project. This integration allows you to create and manage Azure App Configuration resources from your Aspire hosting projects: + + + +Next, in the AppHost project, create an Azure App Configuration resource and pass it to the consuming client projects: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var appConfig = builder.AddAzureAppConfiguration("config"); + +builder.AddProject("web") + .WithReference(appConfig); + +// After adding all resources, run the app... + +builder.Build().Run(); +``` + + + +## Set up client integration + +To get started with the Aspire Azure App Configuration client integration, install the [📦 Aspire.Microsoft.Extensions.Configuration.AzureAppConfiguration](https://www.nuget.org/packages/Aspire.Microsoft.Extensions.Configuration.AzureAppConfiguration) NuGet package in the client-consuming project: + + + +In the `Program.cs` file of your client-consuming project, call the `AddAzureAppConfiguration` extension method to register the required services: + +```csharp title="C# — Program.cs" +builder.AddAzureAppConfiguration(connectionName: "config"); +``` + + + +You can then retrieve the `IConfiguration` instance using dependency injection: + +```csharp title="C# — ExampleService.cs" +public class ExampleService(IConfiguration configuration) +{ + private readonly string _someValue = configuration["SomeKey"]; +} +``` + +## See also + + + + + diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-app-configuration.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-app-configuration/azure-app-configuration-host.mdx similarity index 57% rename from src/frontend/src/content/docs/integrations/cloud/azure/azure-app-configuration.mdx rename to src/frontend/src/content/docs/integrations/cloud/azure/azure-app-configuration/azure-app-configuration-host.mdx index 3cfb59d3..bcfc55e2 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-app-configuration.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-app-configuration/azure-app-configuration-host.mdx @@ -1,32 +1,16 @@ --- -title: Azure App Configuration integration -description: This article describes the Aspire Azure App Configuration integration features and capabilities. +title: Azure App Configuration Hosting integration +description: Learn about the Aspire Azure App Configuration hosting integration including provisioning, customization, and configuration. --- import { Aside } from '@astrojs/starlight/components'; import InstallPackage from '@components/InstallPackage.astro'; -import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; -import { Image } from 'astro:assets'; -import appConfigIcon from '@assets/icons/azure-appconfig-icon.png'; - -Azure App Configuration logo - -[Azure App Configuration](https://learn.microsoft.com/azure-app-configuration) provides a service to centrally manage application settings and feature flags. Modern programs, especially programs running in a cloud, generally have many components that are distributed in nature. Spreading configuration settings across these components can lead to hard-to-troubleshoot errors during an application deployment. The Aspire Azure App Configuration integration enables you to connect to existing App Configuration instances or create new instances all from your AppHost. - -## Hosting integration The Aspire Azure App Configuration hosting integration models the App Configuration resource as the `AzureAppConfigurationResource` type. To access this type and APIs for expressing them within your AppHost project, install the [📦 Aspire.Hosting.Azure.AppConfiguration](https://www.nuget.org/packages/Aspire.Hosting.Azure.AppConfiguration) NuGet package: -### Add an Azure App Configuration resource +## Add an Azure App Configuration resource To add an Azure App Configuration resource to your AppHost project, call the `AddAzureAppConfiguration` method providing a name: @@ -50,7 +34,7 @@ When you add an `AzureAppConfigurationResource` to the AppHost, it exposes other Configuration](/integrations/cloud/azure/local-provisioning/#configuration). -#### Provisioning-generated Bicep +## Provisioning-generated Bicep If you're new to [Bicep](https://learn.microsoft.com/azure/azure-resource-manager/bicep/overview), it's a domain-specific language for defining Azure resources. With Aspire, you don't need to write Bicep by-hand, instead the provisioning APIs generate Bicep for you. When you publish your app, the generated Bicep is output alongside the manifest file. When you add an Azure App Configuration resource, the following Bicep is generated: @@ -108,7 +92,7 @@ resource config_AppConfigurationDataOwner 'Microsoft.Authorization/roleAssignmen The generated Bicep is a starting point and is influenced by changes to the provisioning infrastructure in C#. Customizations to the Bicep file directly will be overwritten, so make changes through the C# provisioning APIs to ensure they're reflected in the generated files. -#### Customize provisioning infrastructure +## Customize provisioning infrastructure All Aspire Azure resources are subclasses of the `AzureProvisioningResource` type. This type enables the customization of the generated Bicep by providing a fluent API to configure the Azure resources—using the `ConfigureInfrastructure` API. For example, you can configure the `sku`, purge protection, and more. The following example demonstrates how to customize the Azure App Configuration resource: @@ -139,7 +123,7 @@ The preceding code: There are many more configuration options available to customize the Azure App Configuration resource. For more information, see [Azure.Provisioning customization](/integrations/cloud/azure/customize-resources/#azureprovisioning-customization). -### Use existing Azure App Configuration resource +## Use existing Azure App Configuration resource You might have an existing Azure App Configuration store that you want to connect to. If you want to use an existing Azure App Configuration store, you can do so by calling the `AsExisting` method. This method accepts the config store and resource group names as parameters, and uses it to connect to the existing Azure App Configuration store resource. @@ -159,7 +143,7 @@ builder.Build().Run(); For more information, see [Use existing Azure resources](/integrations/cloud/azure/overview/#use-existing-azure-resources). -### Connect to existing Azure App Configuration store +## Connect to existing Azure App Configuration store An alternative approach to using the `*AsExisting` APIs enables the addition of a connection string instead, where the AppHost uses configuration to resolve the connection information. To add a connection to an existing Azure App Configuration store, call the `AddConnectionString` method: @@ -189,7 +173,7 @@ The connection string is configured in the AppHost's configuration, typically un The dependent resource can access the injected connection string by calling the `GetConnectionString` method, and passing the connection name as the parameter, in this case `"config"`. The `GetConnectionString` API is shorthand for `IConfiguration.GetSection("ConnectionStrings")[name]`. -### Add Azure App Configuration emulator resource +## Add Azure App Configuration emulator resource Microsoft provides the Azure App Configuration emulator for developers who want a local, lightweight implementation of the Azure App Configuration service to code and test against. In Aspire, you can use this emulator by calling the `RunAsEmulator` method when you add your resource: @@ -206,11 +190,11 @@ builder.Build().Run(); The Azure App Configuration emulator isn't installed on your local computer. Instead, it's accessible to Aspire as a container. The `RunAsEmulator` method creates and starts the container when the AppHost starts using the `azure-app-configuration/app-configuration-emulator` image. -#### Configure Azure App Configuration emulator container +### Configure Azure App Configuration emulator container There are various configurations available to container resources. For example, you can configure the container's port, environment variables, its lifetime, and more. -##### Configure Azure App Configuration emulator host port +#### Configure Azure App Configuration emulator host port By default, Aspire assigns a random host port for the emulator container. If you want to use a specific port, chain calls on the container resource builder provided by the `RunAsEmulator` method as shown in the following example: @@ -228,7 +212,7 @@ var appConfig = builder.AddAzureAppConfiguration("config") The preceding code configures the emulator container's endpoint to listen on port `28000`. -##### Configure Azure App Configuration emulator with persistent lifetime +#### Configure Azure App Configuration emulator with persistent lifetime To configure the emulator container with a persistent lifetime, call the `WithLifetime` method on the emulator container resource and pass `ContainerLifetime.Persistent`: @@ -244,7 +228,7 @@ var appConfig = builder.AddAzureAppConfiguration("config") // After adding all resources, run the app... ``` -##### Configure Azure App Configuration emulator with data volume +#### Configure Azure App Configuration emulator with data volume By default, the Azure App Configuration emulator doesn't persist data between container restarts. To enable persistent storage using a Docker volume, call the `WithDataVolume` method on the emulator resource: @@ -262,7 +246,7 @@ var appConfig = builder.AddAzureAppConfiguration("config") The data volume is used to persist the emulator data outside the lifecycle of its container, ensuring configuration values survive container restarts. The data volume is mounted at the `/data` path in the emulator container and when a `name` parameter isn't provided, the name is autogenerated from the application and resource names (for example, if your application is named `myapp` and the resource is `config`, the autogenerated name will be `myapp-config`). For more information on data volumes and details on why they're preferred over [bind mounts](#configure-azure-app-configuration-emulator-with-data-bind-mount), see [Docker docs: Volumes](https://docs.docker.com/engine/storage/volumes). -##### Configure Azure App Configuration emulator with data bind mount +#### Configure Azure App Configuration emulator with data bind mount To persist emulator data to a specific directory on your host machine, call the `WithDataBindMount` method. This is useful when you want direct access to the data files on your host system: @@ -282,168 +266,3 @@ var appConfig = builder.AddAzureAppConfiguration("config") > Data [bind mounts](https://docs.docker.com/engine/storage/bind-mounts/) have limited functionality compared to [volumes](https://docs.docker.com/engine/storage/volumes/), which offer better performance, portability, and security, making them more suitable for production environments. However, bind mounts allow direct access and modification of files on the host system, ideal for development and testing where real-time changes are needed. Data bind mounts rely on the host machine's filesystem to persist the emulator data across container restarts. The data bind mount is mounted at the `../Emulator/Data` path on the host machine relative to the AppHost directory (`IDistributedApplicationBuilder.AppHostDirectory`) in the emulator container. For more information on data bind mounts, see [Docker docs: Bind mounts](https://docs.docker.com/engine/storage/bind-mounts). - -## Client integration - -To get started with the Aspire Azure App Configuration client integration, install the [📦 Aspire.Microsoft.Extensions.Configuration.AzureAppConfiguration](https://www.nuget.org/packages/Aspire.Microsoft.Extensions.Configuration.AzureAppConfiguration) NuGet package in the client-consuming project, that is, the project for the application that uses the App Configuration client. The App Configuration client integration registers an Azure configuration provider to populate the `IConfiguration` instance. - - - -In the `Program.cs` file of your client-consuming project, call the `AddAzureAppConfiguration` extension method on any `IHostApplicationBuilder` to register the required services to flow Azure App Configuration values into the `IConfiguration` instance for use via the dependency injection container. The method takes a connection name parameter. - -```csharp title="C# — Program.cs" -builder.AddAzureAppConfiguration(connectionName: "config"); -``` - -> [!TIP] -> The `connectionName` parameter must match the name used when adding the App Configuration resource in the AppHost project. In other words, when you call `AddAzureAppConfiguration` in the AppHost and provide a name of `config` that same name should be used when calling `AddAzureAppConfiguration` in the client-consuming project. For more information, see [Add an Azure App Configuration resource](#add-an-azure-app-configuration-resource). - -You can then retrieve the `IConfiguration` instance using dependency injection. For example, to retrieve the client from an example service: - -```csharp title="C# — ExampleService.cs" -public class ExampleService(IConfiguration configuration) -{ - private readonly string _someValue = configuration["SomeKey"]; -} -``` - -### Configure the Azure App Configuration provider - -The `AddAzureAppConfiguration` method accepts an optional `Action configureOptions` delegate that you use to configure the Azure App Configuration provider. This follows the same pattern as the non-Aspire `Microsoft.Extensions.Configuration.AzureAppConfiguration` package, but Aspire automatically handles the connection—you don't need to call `options.Connect`. - -```csharp title="C# — Program.cs" -builder.AddAzureAppConfiguration( - "config", - configureOptions: options => - { - // Select specific keys or labels - options.Select("MyApp:*"); - options.Select("MyApp:*", "Production"); - - // Configure refresh options - options.ConfigureRefresh(refresh => - { - refresh.Register("MyApp:Sentinel", refreshAll: true) - .SetRefreshInterval(TimeSpan.FromSeconds(30)); - }); - }); -``` - -For more information on available configuration options, see the [Azure App Configuration provider reference](https://learn.microsoft.com/azure/azure-app-configuration/reference-dotnet-provider). - -### Use feature flags - -To use feature flags, install the [📦 Microsoft.FeatureManagement](https://www.nuget.org/packages/Microsoft.FeatureManagement) NuGet package: - - - -App Configuration doesn't load feature flags by default. To load feature flags, use the `configureOptions` delegate (as shown in [Configure the Azure App Configuration provider](#configure-the-azure-app-configuration-provider)) to call `UseFeatureFlags()` when calling `builder.AddAzureAppConfiguration`. - -```csharp title="C# — Program.cs" -builder.AddAzureAppConfiguration( - "config", - configureOptions: options => options.UseFeatureFlags()); - -// Register feature management services -builder.Services.AddFeatureManagement(); -``` - -The `configureOptions` pattern is used to configure the Azure App Configuration provider. For more information, see [Azure App Configuration: .NET configuration provider](https://learn.microsoft.com/azure/azure-app-configuration/reference-dotnet-provider). You can then use `IFeatureManager` to evaluate feature flags in your app. Consider the following example ASP.NET Core Minimal API app: - -```csharp title="C# — Program.cs" -using Microsoft.Extensions.Hosting; -using Microsoft.FeatureManagement; - -var builder = WebApplication.CreateBuilder(args); - -builder.AddAzureAppConfiguration( - "config", - configureOptions: options => options.UseFeatureFlags()); - -// Register feature management services -builder.Services.AddFeatureManagement(); - -var app = builder.Build(); - -app.MapGet("/", async (IFeatureManager featureManager) => -{ - if (await featureManager.IsEnabledAsync("NewFeature")) - { - return Results.Ok("New feature is enabled!"); - } - - return Results.Ok("Using standard implementation."); -}); - -app.Run(); -``` - -For more information, see [.NET Feature Management](https://learn.microsoft.com/azure/azure-app-configuration/feature-management-dotnet-reference). - -### Configuration - -The Aspire Azure App Configuration library provides multiple options to configure the Azure App Configuration connection based on the requirements and conventions of your project. The App Config endpoint is required to be supplied, either in `AzureAppConfigurationSettings.Endpoint` or using a connection string. - -#### Use a connection string - -When using a connection string from the `ConnectionStrings` configuration section, you can provide the name of the connection string when calling `builder.AddAzureAppConfiguration()`: - -```csharp title="C# — Program.cs" -builder.AddAzureAppConfiguration("config"); -``` - -Then the App Configuration endpoint is retrieved from the `ConnectionStrings` configuration section. The App Configuration store URI works with the `AzureAppConfigurationSettings.Credential` property to establish a connection. If no credential is configured, the `DefaultAzureCredential` is used. - -```json title="JSON — appsettings.json" -{ - "ConnectionStrings": { - "config": "https://{store_name}.azconfig.io" - } -} -``` - -#### Use configuration providers - -The Aspire Azure App Configuration library supports `Microsoft.Extensions.Configuration`. It loads the `AzureAppConfigurationSettings` from configuration by using the `Aspire:Microsoft:Extensions:Configuration:AzureAppConfiguration` key. Example _appsettings.json_ that configures some of the options: - -```json title="JSON — appsettings.json" -{ - "Aspire": { - "Microsoft": { - "Extensions": { - "Configuration": { - "AzureAppConfiguration": { - "Endpoint": "YOUR_APPCONFIGURATION_ENDPOINT_URI" - } - } - } - } - } -} -``` - -For the complete App Configuration client integration JSON schema, see [ConfigurationSchema.json](https://github.com/dotnet/aspire/blob/main/src/Components/Aspire.Microsoft.Extensions.Configuration.AzureAppConfiguration/ConfigurationSchema.json). - -#### Use inline delegates - -You can also pass the `Action configureSettings` delegate to set up some or all the options inline, for example to set App Configuration endpoint from code: - -```csharp title="C# — Program.cs" -builder.AddAzureAppConfiguration( - "config", - configureSettings: settings => settings.Endpoint = "https://YOUR_URI"); -``` - -#### Logging - -The Aspire Azure App Configuration integration uses the following log categories: - -- `Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh` - -#### Tracing - -The Aspire Azure App Configuration integration doesn't make use of any activity sources thus no tracing is available. - -#### Metrics - -The Aspire Azure App Configuration integration currently doesn't support metrics. diff --git a/src/frontend/src/data/integration-docs.json b/src/frontend/src/data/integration-docs.json index 355ed23e..4ce9a7c3 100644 --- a/src/frontend/src/data/integration-docs.json +++ b/src/frontend/src/data/integration-docs.json @@ -65,7 +65,7 @@ }, { "match": "Aspire.Hosting.Azure.AppConfiguration", - "href": "/integrations/cloud/azure/azure-app-configuration/" + "href": "/integrations/cloud/azure/azure-app-configuration/azure-app-configuration-get-started/" }, { "match": "Aspire.Hosting.Azure.AppContainers", @@ -277,7 +277,7 @@ }, { "match": "Aspire.Microsoft.Extensions.Configuration.AzureAppConfiguration", - "href": "/integrations/cloud/azure/azure-app-configuration/" + "href": "/integrations/cloud/azure/azure-app-configuration/azure-app-configuration-get-started/" }, { "match": "Aspire.Milvus.Client", From c635cc2b20503c373f3219634a2183d0b2ef13c5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 15:25:56 +0000 Subject: [PATCH 08/30] Restructure Azure App Service integration into subfolder --- .../config/sidebar/integrations.topics.ts | 16 +++- .../azure-app-service-client.mdx | 12 +++ .../azure-app-service-get-started.mdx | 79 +++++++++++++++++++ .../azure-app-service-host.mdx} | 21 +---- src/frontend/src/data/integration-docs.json | 2 +- 5 files changed, 110 insertions(+), 20 deletions(-) create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-app-service/azure-app-service-client.mdx create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-app-service/azure-app-service-get-started.mdx rename src/frontend/src/content/docs/integrations/cloud/azure/{azure-app-service.mdx => azure-app-service/azure-app-service-host.mdx} (86%) diff --git a/src/frontend/config/sidebar/integrations.topics.ts b/src/frontend/config/sidebar/integrations.topics.ts index 007deda0..1f409cce 100644 --- a/src/frontend/config/sidebar/integrations.topics.ts +++ b/src/frontend/config/sidebar/integrations.topics.ts @@ -347,7 +347,21 @@ export const integrationTopics: StarlightSidebarTopicsUserConfig = { }, { label: 'Azure App Service', - slug: 'integrations/cloud/azure/azure-app-service', + collapsed: true, + items: [ + { + label: 'Get started', + slug: 'integrations/cloud/azure/azure-app-service/azure-app-service-get-started', + }, + { + label: 'Hosting integration (AppHost)', + slug: 'integrations/cloud/azure/azure-app-service/azure-app-service-host', + }, + { + label: 'Client integration', + slug: 'integrations/cloud/azure/azure-app-service/azure-app-service-client', + }, + ], }, { label: 'Azure Cache for Redis', diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-app-service/azure-app-service-client.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-app-service/azure-app-service-client.mdx new file mode 100644 index 00000000..6ce4abbe --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-app-service/azure-app-service-client.mdx @@ -0,0 +1,12 @@ +--- +title: Azure App Service Client integration +description: Learn about Azure App Service client integration. +--- + +Azure App Service is a hosting integration only. There is no separate client integration package required to run your applications on Azure App Service. + +When you use the `PublishAsAzureAppServiceWebsite` method in your AppHost, your application code runs directly on the Azure App Service platform without needing additional client libraries or configuration changes. + +Your application will continue to use the same client integrations for other services (like databases, caches, message queues) as it does during local development. The Azure App Service integration automatically handles the deployment and hosting aspects. + +For more information on configuring resources to run on Azure App Service, see [Azure App Service Hosting integration](/integrations/cloud/azure/azure-app-service/azure-app-service-host/). diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-app-service/azure-app-service-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-app-service/azure-app-service-get-started.mdx new file mode 100644 index 00000000..b8bae79f --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-app-service/azure-app-service-get-started.mdx @@ -0,0 +1,79 @@ +--- +title: Get started with the Azure App Service integration +description: Learn how to set up the Aspire Azure App Service Hosting integration simply. +prev: false +--- + +import { Aside, Badge, CardGrid, LinkCard } from '@astrojs/starlight/components'; +import InstallPackage from '@components/InstallPackage.astro'; +import { Kbd } from 'starlight-kbd/components'; +import { Image } from 'astro:assets'; +import appServiceIcon from '@assets/icons/azure-app-services.svg'; + +Azure App Service logo + + + +[Azure App Service](https://learn.microsoft.com/azure/app-service) is a fully managed platform for building, deploying, and scaling web apps. Aspire apps often run locally during development but require scalable, production-ready hosting environments for staging and production. The Aspire integration allows you to provision or reference an existing Azure App Service environment (App Service Plan) and seamlessly publish your container, executable, and project resources as Azure App Service websites. + +In this introduction, you'll see how to install and use the Aspire Azure App Service integration in a simple configuration. If you already have this knowledge, see [Azure App Service Hosting integration](/integrations/cloud/azure/azure-app-service/azure-app-service-host/) for full reference details. + + + +## Set up hosting integration + +To begin, install the Aspire Azure App Service Hosting integration in your Aspire AppHost project: + + + +Next, add an App Service environment to your AppHost project. The environment represents the hosting infrastructure (App Service Plan) where your apps will run: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var appServiceEnv = builder.AddAzureAppServiceEnvironment("app-service-env"); + +builder.AddProject("api") + .PublishAsAzureAppServiceWebsite((infra, website) => + { + // Optional: customize the Azure App Service website here + }); + +builder.Build().Run(); +``` + + + +The preceding code: + +- Creates an Azure App Service environment named `app-service-env`. +- Adds a project named `api` to the AppHost. +- Configures the project to be published as an Azure App Service website. +- Provides an optional callback to customize the website configuration. + +During local development (when running with ), the project runs locally. When you publish your app, the project is deployed as an Azure App Service website within the provisioned environment. + +## See also + + + + diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-app-service.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-app-service/azure-app-service-host.mdx similarity index 86% rename from src/frontend/src/content/docs/integrations/cloud/azure/azure-app-service.mdx rename to src/frontend/src/content/docs/integrations/cloud/azure/azure-app-service/azure-app-service-host.mdx index ea4ffad2..f5877a03 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-app-service.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-app-service/azure-app-service-host.mdx @@ -1,29 +1,14 @@ --- -title: Azure App Service integration -description: This article describes the Aspire Azure App Service integration features and capabilities. +title: Azure App Service Hosting integration +description: Learn about the Aspire Azure App Service hosting integration including provisioning, customization, and configuration. --- import { Aside, Badge } from '@astrojs/starlight/components'; import InstallPackage from '@components/InstallPackage.astro'; import { Kbd } from 'starlight-kbd/components'; -import { Image } from 'astro:assets'; -import appServiceIcon from '@assets/icons/azure-app-services.svg'; - -Azure App Service logo -[Azure App Service](https://learn.microsoft.com/azure/app-service) is a fully managed platform for building, deploying, and scaling web apps. Aspire apps often run locally during development but require scalable, production-ready hosting environments for staging and production. The Aspire integration allows you to provision or reference an existing Azure App Service environment (App Service Plan) and seamlessly publish your container, executable, and project resources as Azure App Service websites. When you add an App Service environment, the integration automatically provisions an Azure Container Registry for container-based deployments and grants fine-grained role assignments to enable secure access between Azure resources. - -## Hosting integration - The Aspire Azure App Service hosting integration models App Service resources as the `AzureAppServiceResource` type. To access this type and APIs for expressing them within your AppHost project, install the [📦 Aspire.Hosting.Azure.AppService](https://www.nuget.org/packages/Aspire.Hosting.Azure.AppService) NuGet package: @@ -142,7 +127,7 @@ When you add an Azure App Service environment, the following key resources are p The generated Bicep is a starting point and is influenced by changes to the provisioning infrastructure in C#. Customizations to the Bicep file directly are overwritten, so make changes through the C# provisioning APIs to ensure they're reflected in the generated files. -### Customize provisioning infrastructure +## Customize provisioning infrastructure All Aspire Azure resources are subclasses of the `AzureProvisioningResource` type. This type enables the customization of the generated Bicep by providing a fluent API to configure the Azure resources—using the `ConfigureInfrastructure` API. For example, you can configure the App Service Plan SKU, location, and more. The following example demonstrates how to customize the Azure App Service environment: diff --git a/src/frontend/src/data/integration-docs.json b/src/frontend/src/data/integration-docs.json index 4ce9a7c3..632f1df5 100644 --- a/src/frontend/src/data/integration-docs.json +++ b/src/frontend/src/data/integration-docs.json @@ -77,7 +77,7 @@ }, { "match": "Aspire.Hosting.Azure.AppService", - "href": "/integrations/cloud/azure/azure-app-service/" + "href": "/integrations/cloud/azure/azure-app-service/azure-app-service-get-started/" }, { "match": "Aspire.Hosting.Azure.CognitiveServices", From 2b73a7fe1b41fdc9b9881768c0c291316c5f83bd Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 15:28:06 +0000 Subject: [PATCH 09/30] Restructure Azure Cache for Redis integration into subfolder --- .../config/sidebar/integrations.topics.ts | 16 +- .../azure-cache-redis-client.mdx | 154 +++++++++++++++ .../azure-cache-redis-get-started.mdx | 99 ++++++++++ .../azure-cache-redis-host.mdx} | 187 +----------------- src/frontend/src/data/integration-docs.json | 4 +- 5 files changed, 280 insertions(+), 180 deletions(-) create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-client.mdx create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-get-started.mdx rename src/frontend/src/content/docs/integrations/cloud/azure/{azure-cache-redis.mdx => azure-cache-redis/azure-cache-redis-host.mdx} (60%) diff --git a/src/frontend/config/sidebar/integrations.topics.ts b/src/frontend/config/sidebar/integrations.topics.ts index 1f409cce..8e7a1450 100644 --- a/src/frontend/config/sidebar/integrations.topics.ts +++ b/src/frontend/config/sidebar/integrations.topics.ts @@ -365,7 +365,21 @@ export const integrationTopics: StarlightSidebarTopicsUserConfig = { }, { label: 'Azure Cache for Redis', - slug: 'integrations/cloud/azure/azure-cache-redis', + collapsed: true, + items: [ + { + label: 'Get started', + slug: 'integrations/cloud/azure/azure-cache-redis/azure-cache-redis-get-started', + }, + { + label: 'Hosting integration (AppHost)', + slug: 'integrations/cloud/azure/azure-cache-redis/azure-cache-redis-host', + }, + { + label: 'Client integration', + slug: 'integrations/cloud/azure/azure-cache-redis/azure-cache-redis-client', + }, + ], }, { label: 'Azure Container Registry', diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-client.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-client.mdx new file mode 100644 index 00000000..ca0ca803 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-client.mdx @@ -0,0 +1,154 @@ +--- +title: Azure Cache for Redis Client integration +description: Learn about the Aspire Azure Cache for Redis client integration including distributed cache, output cache, and telemetry. +--- + +import { Aside } from '@astrojs/starlight/components'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; + +The Aspire Azure Cache for Redis client integration is used to connect to an Azure Redis cache using StackExchange.Redis. To get started with the Aspire Azure Cache for Redis client integration, install the [📦 Aspire.StackExchange.Redis](https://www.nuget.org/packages/Aspire.StackExchange.Redis) NuGet package. + + + +## Add Redis client + +In the `Program.cs` file of your client-consuming project, call the `AddRedisClient` extension method to register an `IConnectionMultiplexer` for use via the dependency injection container. The method takes a connection name parameter: + +```csharp +builder.AddRedisClient(connectionName: "redis"); +``` + + + +After adding the `IConnectionMultiplexer`, you can retrieve the connection instance using dependency injection: + +```csharp +public class ExampleService(IConnectionMultiplexer redis) +{ + // Use redis... +} +``` + +For more information, see: + +- [StackExchange.Redis documentation](https://stackexchange.github.io/StackExchange.Redis/) for examples on using the `IConnectionMultiplexer`. +- [Dependency injection in .NET](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection) for details on dependency injection. + +## Add Redis distributed cache + +For caching scenarios, you can add a Redis-based distributed cache using the `AddRedisDistributedCache` method: + +```csharp +builder.AddRedisDistributedCache(connectionName: "redis"); +``` + +This registers an `IDistributedCache` implementation backed by Redis: + +```csharp +public class ExampleService(IDistributedCache cache) +{ + // Use cache... +} +``` + +## Add Redis output cache + +For output caching scenarios in ASP.NET Core, you can add a Redis-based output cache using the `AddRedisOutputCache` method: + +```csharp +builder.AddRedisOutputCache(connectionName: "redis"); +``` + +This configures Redis as the output cache store for your web application. + +## Add keyed Redis client + +There might be situations where you want to register multiple `IConnectionMultiplexer` instances with different connection names. To register keyed Redis clients, call the `AddKeyedRedisClient` method: + +```csharp +builder.AddKeyedRedisClient(name: "primary-cache"); +builder.AddKeyedRedisClient(name: "secondary-cache"); +``` + +Then you can retrieve the connection instances using dependency injection: + +```csharp +public class ExampleService( + [KeyedService("primary-cache")] IConnectionMultiplexer primaryRedis, + [KeyedService("secondary-cache")] IConnectionMultiplexer secondaryRedis) +{ + // Use redis connections... +} +``` + +For more information, see [Keyed services in .NET](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection#keyed-services). + +## Configuration + +The Aspire Azure Cache for Redis library provides multiple options to configure the Redis connection based on the requirements and conventions of your project. A `ConnectionString` is required. + +### Use a connection string + +When using a connection string from the `ConnectionStrings` configuration section, you can provide the name of the connection string when calling `AddRedisClient`: + +```csharp +builder.AddRedisClient(connectionName: "redis"); +``` + +The connection information is retrieved from the `ConnectionStrings` configuration section: + +```json +{ + "ConnectionStrings": { + "redis": "myredis.redis.cache.windows.net:6380,password=your_password,ssl=True" + } +} +``` + +### Use configuration providers + +The library supports `Microsoft.Extensions.Configuration`. It loads settings from configuration using the `Aspire:StackExchange:Redis` key: + +```json +{ + "Aspire": { + "StackExchange": { + "Redis": { + "DisableHealthChecks": true, + "DisableTracing": false + } + } + } +} +``` + +### Use inline delegates + +You can configure settings inline: + +```csharp +builder.AddRedisClient( + "redis", + settings => settings.DisableHealthChecks = true); +``` + +## Observability and telemetry + +Aspire integrations automatically set up Logging, Tracing, and Metrics configurations. + +### Logging + +The Aspire Azure Cache for Redis integration uses standard .NET logging for connection events and errors. + +### Tracing + +The Aspire Azure Cache for Redis integration will emit the following tracing activities using OpenTelemetry: + +- `StackExchange.Redis.*` + +### Metrics + +The Aspire Azure Cache for Redis integration currently doesn't expose custom metrics by default, but uses standard Redis monitoring capabilities. diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-get-started.mdx new file mode 100644 index 00000000..1a4e7d1a --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-get-started.mdx @@ -0,0 +1,99 @@ +--- +title: Get started with the Azure Cache for Redis integrations +description: Learn how to set up the Aspire Azure Cache for Redis Hosting and Client integrations simply. +prev: false +--- + +import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components'; +import InstallPackage from '@components/InstallPackage.astro'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; +import { Image } from 'astro:assets'; +import cacheRedisIcon from '@assets/icons/azure-cacheredis-icon.png'; + +Azure Cache for Redis logo + +[Azure Cache for Redis](https://learn.microsoft.com/azure/azure-cache-for-redis/cache-overview) provides an in-memory data store based on the [Redis](https://redis.io/) software. Redis improves the performance and scalability of an application that uses backend data stores heavily. It's able to process large volumes of application requests by keeping frequently accessed data in the server memory, which can be written to and read from quickly. + +In this introduction, you'll see how to install and use the Aspire Azure Cache for Redis integrations in a simple configuration. If you already have this knowledge, see [Azure Cache for Redis Hosting integration](/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-host/) for full reference details. + + + +## Set up hosting integration + +To begin, install the Aspire Azure Cache for Redis Hosting integration in your Aspire AppHost project: + + + +Next, in the AppHost project, create an Azure Cache for Redis resource and pass it to the consuming client projects: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var redis = builder.AddAzureRedis("redis"); + +builder.AddProject() + .WithReference(redis); + +// After adding all resources, run the app... + +builder.Build().Run(); +``` + + + +## Set up client integration + +To get started with the Aspire Azure Cache for Redis client integration, install the [📦 Aspire.StackExchange.Redis](https://www.nuget.org/packages/Aspire.StackExchange.Redis) NuGet package in the client-consuming project: + + + +In the `Program.cs` file of your client-consuming project, call the `AddRedisClient` extension method to register an `IConnectionMultiplexer`: + +```csharp title="C# — Program.cs" +builder.AddRedisClient(connectionName: "redis"); +``` + + + +After adding the `IConnectionMultiplexer`, you can retrieve the connection instance using dependency injection: + +```csharp title="C# — ExampleService.cs" +public class ExampleService(IConnectionMultiplexer redis) +{ + // Use redis... +} +``` + +For more information, see [StackExchange.Redis documentation](https://stackexchange.github.io/StackExchange.Redis/) for examples on using the `IConnectionMultiplexer`. + +## See also + + + + + diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-host.mdx similarity index 60% rename from src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis.mdx rename to src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-host.mdx index 5c195eda..51642a6e 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-host.mdx @@ -1,34 +1,16 @@ --- -title: Azure Cache for Redis integration -description: This article describes the Aspire Azure Cache for Redis integration features and capabilities. +title: Azure Cache for Redis Hosting integration +description: Learn about the Aspire Azure Cache for Redis hosting integration including provisioning, customization, and configuration. --- import { Aside } from '@astrojs/starlight/components'; import InstallPackage from '@components/InstallPackage.astro'; -import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; -import { Image } from 'astro:assets'; -import cacheRedisIcon from '@assets/icons/azure-cacheredis-icon.png'; - -Azure Cache for Redis logo - -[Azure Cache for Redis](https://learn.microsoft.com/azure/azure-cache-for-redis/cache-overview) provides an in-memory data store based on the [Redis](https://redis.io/) software. Redis improves the performance and scalability of an application that uses backend data stores heavily. It's able to process large volumes of application requests by keeping frequently accessed data in the server memory, which can be written to and read from quickly. Redis brings a critical low-latency and high-throughput data storage solution to modern applications. - -Azure Cache for Redis offers both the Redis open-source (OSS Redis) and a commercial product from Redis Inc. (Redis Enterprise) as a managed service. It provides secure and dedicated Redis server instances and full Redis API compatibility. Microsoft operates the service, hosted on Azure, and usable by any application within or outside of Azure. - -## Hosting integration The Aspire Azure Cache for Redis hosting integration models the Redis cache as the `AzureRedisResource` type. To access this type and APIs for expressing them within your AppHost project, install the [📦 Aspire.Hosting.Azure.Redis](https://www.nuget.org/packages/Aspire.Hosting.Azure.Redis) NuGet package: -### Add an Azure Cache for Redis resource +## Add an Azure Cache for Redis resource To add an Azure Cache for Redis resource to your AppHost project, call the `AddAzureRedis` method providing a name: @@ -53,7 +35,7 @@ The preceding code adds an Azure Redis resource named `redis` to the AppHost pro Configuration](/integrations/cloud/azure/local-provisioning/#configuration). -### Connect to an existing Azure Cache for Redis instance +## Connect to an existing Azure Cache for Redis instance You might have an existing Azure Cache for Redis service that you want to connect to. You can chain a call to annotate that your `AzureRedisCacheResource` is an existing resource: @@ -74,7 +56,7 @@ builder.AddProject() For more information on treating Azure Redis resources as existing resources, see [Use existing Azure resources](/integrations/cloud/azure/overview/#use-existing-azure-resources). -### Run Azure Cache for Redis resource as a container +## Run Azure Cache for Redis resource as a container The Azure Cache for Redis hosting integration supports running the Redis server as a local container. This is beneficial for situations where you want to run the Redis server locally for development and testing purposes, avoiding the need to provision an Azure resource or connect to an existing Azure Cache for Redis server. @@ -97,7 +79,7 @@ The preceding code configures the Redis resource to run locally in a container. > [!TIP] > The `RunAsContainer` method is useful for local development and testing. The API exposes an optional delegate that enables you to customize the underlying `RedisResource` configuration, such adding [Redis Insights](https://redis.io/insight/), [Redis Commander](https://joeferner.github.io/redis-commander/), adding a data volume or data bind mount. For more information, see the [Aspire Redis hosting integration](/integrations/caching/redis/#add-redis-resource-with-redis-insights). -### Configure the Azure Cache for Redis resource to use access key authentication +## Configure the Azure Cache for Redis resource to use access key authentication By default, the Azure Cache for Redis resource is configured to use [Microsoft Entra ID](https://learn.microsoft.com/azure/postgresql/flexible-server/concepts-azure-ad-authentication) authentication. If you want to use password authentication (not recommended), you can configure the server to use password authentication by calling the `WithAccessKeyAuthentication` method: @@ -115,7 +97,7 @@ builder.AddProject() The preceding code configures the Azure Cache for Redis resource to use access key authentication. This alters the generated Bicep to use access key authentication instead of Microsoft Entra ID authentication. In other words, the connection string will contain a password, and will be added to an Azure Key Vault secret. -### Provisioning-generated Bicep +## Provisioning-generated Bicep If you're new to [Bicep](https://learn.microsoft.com/azure/azure-resource-manager/bicep/overview), it's a domain-specific language for defining Azure resources. With Aspire, you don't need to write Bicep by-hand, instead the provisioning APIs generate Bicep for you. When you publish your app, the generated Bicep is output alongside the manifest file. When you add an Azure Cache for Redis resource, the following Bicep is generated: @@ -178,7 +160,7 @@ resource redis_contributor 'Microsoft.Cache/redis/accessPolicyAssignments@2024-1 In addition to the Azure Cache for Redis, it also provisions an access policy assignment to the application access to the cache. The generated Bicep is a starting point and is influenced by changes to the provisioning infrastructure in C#. Customizations to the Bicep file directly will be overwritten, so make changes through the C# provisioning APIs to ensure they are reflected in the generated files. -#### Customize provisioning infrastructure +## Customize provisioning infrastructure All Aspire Azure resources are subclasses of the `AzureProvisioningResource` type. This type enables the customization of the generated Bicep by providing a fluent API to configure the Azure resources using the `ConfigureInfrastructure` API: @@ -212,11 +194,11 @@ The preceding code: There are many more configuration options available to customize the Redis resource. For more information, see [Azure.Provisioning customization](/integrations/cloud/azure/customize-resources/#azureprovisioning-customization). -### Connection properties +## Connection properties When you reference Azure Redis resources using `WithReference`, the following connection properties are made available to the consuming project: -#### Azure Redis Enterprise +### Azure Redis Enterprise | Property Name | Description | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -230,152 +212,3 @@ When you reference Azure Redis resources using `WithReference`, the following co `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `cache` becomes `CACHE_URI`. - -## Client integration - -The Aspire Azure Cache for Redis client integration is used to connect to an Azure Redis cache using StackExchange.Redis. To get started with the Aspire Azure Cache for Redis client integration, install the [📦 Aspire.StackExchange.Redis](https://www.nuget.org/packages/Aspire.StackExchange.Redis) NuGet package. - - - -### Add Redis client - -In the `Program.cs` file of your client-consuming project, call the `AddRedisClient` extension method to register an `IConnectionMultiplexer` for use via the dependency injection container. The method takes a connection name parameter: - -```csharp -builder.AddRedisClient(connectionName: "redis"); -``` - - - -After adding the `IConnectionMultiplexer`, you can retrieve the connection instance using dependency injection: - -```csharp -public class ExampleService(IConnectionMultiplexer redis) -{ - // Use redis... -} -``` - -For more information, see: - -- [StackExchange.Redis documentation](https://stackexchange.github.io/StackExchange.Redis/) for examples on using the `IConnectionMultiplexer`. -- [Dependency injection in .NET](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection) for details on dependency injection. - -### Add Redis distributed cache - -For caching scenarios, you can add a Redis-based distributed cache using the `AddRedisDistributedCache` method: - -```csharp -builder.AddRedisDistributedCache(connectionName: "redis"); -``` - -This registers an `IDistributedCache` implementation backed by Redis: - -```csharp -public class ExampleService(IDistributedCache cache) -{ - // Use cache... -} -``` - -### Add Redis output cache - -For output caching scenarios in ASP.NET Core, you can add a Redis-based output cache using the `AddRedisOutputCache` method: - -```csharp -builder.AddRedisOutputCache(connectionName: "redis"); -``` - -This configures Redis as the output cache store for your web application. - -### Add keyed Redis client - -There might be situations where you want to register multiple `IConnectionMultiplexer` instances with different connection names. To register keyed Redis clients, call the `AddKeyedRedisClient` method: - -```csharp -builder.AddKeyedRedisClient(name: "primary-cache"); -builder.AddKeyedRedisClient(name: "secondary-cache"); -``` - -Then you can retrieve the connection instances using dependency injection: - -```csharp -public class ExampleService( - [KeyedService("primary-cache")] IConnectionMultiplexer primaryRedis, - [KeyedService("secondary-cache")] IConnectionMultiplexer secondaryRedis) -{ - // Use redis connections... -} -``` - -For more information, see [Keyed services in .NET](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection#keyed-services). - -### Configuration - -The Aspire Azure Cache for Redis library provides multiple options to configure the Redis connection based on the requirements and conventions of your project. A `ConnectionString` is required. - -#### Use a connection string - -When using a connection string from the `ConnectionStrings` configuration section, you can provide the name of the connection string when calling `AddRedisClient`: - -```csharp -builder.AddRedisClient(connectionName: "redis"); -``` - -The connection information is retrieved from the `ConnectionStrings` configuration section: - -```json -{ - "ConnectionStrings": { - "redis": "myredis.redis.cache.windows.net:6380,password=your_password,ssl=True" - } -} -``` - -#### Use configuration providers - -The library supports `Microsoft.Extensions.Configuration`. It loads settings from configuration using the `Aspire:StackExchange:Redis` key: - -```json -{ - "Aspire": { - "StackExchange": { - "Redis": { - "DisableHealthChecks": true, - "DisableTracing": false - } - } - } -} -``` - -#### Use inline delegates - -You can configure settings inline: - -```csharp -builder.AddRedisClient( - "redis", - settings => settings.DisableHealthChecks = true); -``` - -### Observability and telemetry - -Aspire integrations automatically set up Logging, Tracing, and Metrics configurations. - -#### Logging - -The Aspire Azure Cache for Redis integration uses standard .NET logging for connection events and errors. - -#### Tracing - -The Aspire Azure Cache for Redis integration will emit the following tracing activities using OpenTelemetry: - -- `StackExchange.Redis.*` - -#### Metrics - -The Aspire Azure Cache for Redis integration currently doesn't expose custom metrics by default, but uses standard Redis monitoring capabilities. diff --git a/src/frontend/src/data/integration-docs.json b/src/frontend/src/data/integration-docs.json index 632f1df5..17f6a64d 100644 --- a/src/frontend/src/data/integration-docs.json +++ b/src/frontend/src/data/integration-docs.json @@ -117,7 +117,7 @@ }, { "match": "Aspire.Hosting.Azure.Redis", - "href": "/integrations/cloud/azure/azure-cache-redis/" + "href": "/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-get-started/" }, { "match": "Aspire.Hosting.Azure.Search", @@ -261,7 +261,7 @@ }, { "match": "Aspire.Microsoft.Azure.StackExchangeRedis", - "href": "/integrations/cloud/azure/azure-cache-redis/" + "href": "/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-get-started/" }, { "match": "Aspire.Microsoft.Data.SqlClient", From fe652608a7d4c1d09a13111285531b2e7d4bb311 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 15:31:00 +0000 Subject: [PATCH 10/30] Restructure Azure Container Registry integration into subfolder --- .../config/sidebar/integrations.topics.ts | 16 +++- .../azure-container-registry-client.mdx | 15 ++++ .../azure-container-registry-get-started.mdx | 81 +++++++++++++++++++ .../azure-container-registry-host.mdx} | 44 ++-------- src/frontend/src/data/integration-docs.json | 2 +- 5 files changed, 118 insertions(+), 40 deletions(-) create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-container-registry/azure-container-registry-client.mdx create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-container-registry/azure-container-registry-get-started.mdx rename src/frontend/src/content/docs/integrations/cloud/azure/{azure-container-registry.mdx => azure-container-registry/azure-container-registry-host.mdx} (79%) diff --git a/src/frontend/config/sidebar/integrations.topics.ts b/src/frontend/config/sidebar/integrations.topics.ts index 8e7a1450..e05c90ff 100644 --- a/src/frontend/config/sidebar/integrations.topics.ts +++ b/src/frontend/config/sidebar/integrations.topics.ts @@ -383,7 +383,21 @@ export const integrationTopics: StarlightSidebarTopicsUserConfig = { }, { label: 'Azure Container Registry', - slug: 'integrations/cloud/azure/azure-container-registry', + collapsed: true, + items: [ + { + label: 'Get started', + slug: 'integrations/cloud/azure/azure-container-registry/azure-container-registry-get-started', + }, + { + label: 'Hosting integration (AppHost)', + slug: 'integrations/cloud/azure/azure-container-registry/azure-container-registry-host', + }, + { + label: 'Client integration', + slug: 'integrations/cloud/azure/azure-container-registry/azure-container-registry-client', + }, + ], }, { label: 'Azure Cosmos DB', diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-container-registry/azure-container-registry-client.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-container-registry/azure-container-registry-client.mdx new file mode 100644 index 00000000..8e2b469c --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-container-registry/azure-container-registry-client.mdx @@ -0,0 +1,15 @@ +--- +title: Azure Container Registry Client integration +description: This integration does not have a client component. +--- + +import { LinkCard } from '@astrojs/starlight/components'; + +Azure Container Registry is a hosting-only integration and does not provide a client integration component. + +For more information on working with Azure Container Registry in your Aspire application, see: + + diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-container-registry/azure-container-registry-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-container-registry/azure-container-registry-get-started.mdx new file mode 100644 index 00000000..3f8693ed --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-container-registry/azure-container-registry-get-started.mdx @@ -0,0 +1,81 @@ +--- +title: Get started with the Azure Container Registry integration +description: Learn how to set up the Aspire Azure Container Registry Hosting integration simply. +prev: false +--- + +import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components'; +import InstallPackage from '@components/InstallPackage.astro'; +import { Image } from 'astro:assets'; +import containerRegistryIcon from '@assets/icons/azure-container-registry-icon.svg'; + +Azure Container Registry logo + +[Azure Container Registry](https://learn.microsoft.com/azure/container-registry) is a managed Docker container registry service that simplifies the storage, management, and deployment of container images. The Aspire integration allows you to provision or reference an existing Azure Container Registry and seamlessly integrate it with your app's compute environments. + +In this introduction, you'll see how to install and use the Aspire Azure Container Registry integration in a simple configuration. If you already have this knowledge, see [Azure Container Registry Hosting integration](/integrations/cloud/azure/azure-container-registry/azure-container-registry-host/) for full reference details. + + + +## Overview + +Aspire apps often build and run container images locally but require secure registries for staging and production environments. The Azure Container Registry integration provides the following capabilities: + +- Provision or reference an existing Azure Container Registry. +- Attach the registry to any compute-environment resource (for example, Azure Container Apps, Docker, Kubernetes) to ensure proper credential flow. +- Grant fine-grained ACR role assignments to other Azure resources. + +## Supported scenarios + +The Azure Container Registry integration supports the following scenarios: + +- **Provisioning a new registry**: Automatically create a new Azure Container Registry for your app. +- **Referencing an existing registry**: Use an existing Azure Container Registry by providing its name and resource group. +- **Credential management**: Automatically flow credentials to compute environments for secure image pulls. +- **Role assignments**: Assign specific roles (for example, `AcrPush`) to enable services to push images to the registry. + +## Set up hosting integration + +To begin, install the Aspire Azure Container Registry Hosting integration in your Aspire AppHost project. This integration allows you to create and manage Azure Container Registry resources from your Aspire hosting projects: + + + +Next, in the AppHost project, create an Azure Container Registry resource and wire it to a compute environment: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +// Add (or reference) the registry +var acr = builder.AddAzureContainerRegistry("my-acr"); + +// Wire an environment to that registry +builder.AddAzureContainerAppEnvironment("env") + .WithAzureContainerRegistry(acr); + +builder.Build().Run(); +``` + +The preceding code: + +- Creates a new Azure Container Registry named `my-acr`. +- Attaches the registry to an Azure Container Apps environment named `env`. + +## Continue learning + +For more information on how the Azure Container Registry integration works, see: + + + + diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-container-registry.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-container-registry/azure-container-registry-host.mdx similarity index 79% rename from src/frontend/src/content/docs/integrations/cloud/azure/azure-container-registry.mdx rename to src/frontend/src/content/docs/integrations/cloud/azure/azure-container-registry/azure-container-registry-host.mdx index c15e2f39..33029b42 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-container-registry.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-container-registry/azure-container-registry-host.mdx @@ -1,49 +1,17 @@ --- -title: Azure Container Registry integration -description: This article describes the Aspire Azure Container Registry integration features and capabilities. +title: Azure Container Registry Hosting integration +description: Learn about the Aspire Azure Container Registry hosting integration including provisioning, customization, and configuration. --- import { Aside } from '@astrojs/starlight/components'; import LearnMore from '@components/LearnMore.astro'; import InstallPackage from '@components/InstallPackage.astro'; -import { Image } from 'astro:assets'; -import containerRegistryIcon from '@assets/icons/azure-container-registry-icon.svg'; - -Azure Container Registry logo - -[Azure Container Registry](https://learn.microsoft.com/azure/container-registry) is a managed Docker container registry service that simplifies the storage, management, and deployment of container images. The Aspire integration allows you to provision or reference an existing Azure Container Registry and seamlessly integrate it with your app's compute environments. - -## Overview - -Aspire apps often build and run container images locally but require secure registries for staging and production environments. The Azure Container Registry integration provides the following capabilities: - -- Provision or reference an existing Azure Container Registry. -- Attach the registry to any compute-environment resource (for example, Azure Container Apps, Docker, Kubernetes) to ensure proper credential flow. -- Grant fine-grained ACR role assignments to other Azure resources. - -## Supported scenarios - -The Azure Container Registry integration supports the following scenarios: - -- **Provisioning a new registry**: Automatically create a new Azure Container Registry for your app. -- **Referencing an existing registry**: Use an existing Azure Container Registry by providing its name and resource group. -- **Credential management**: Automatically flow credentials to compute environments for secure image pulls. -- **Role assignments**: Assign specific roles (for example, `AcrPush`) to enable services to push images to the registry. - -## Hosting integration The Aspire Azure Container Registry hosting integration models the container registry as the `AzureContainerRegistryResource` type. To access this type and APIs for expressing them within your AppHost project, install the [📦 Aspire.Hosting.Azure.ContainerRegistry](https://www.nuget.org/packages/Aspire.Hosting.Azure.ContainerRegistry) NuGet package: -### Provision a new container registry +## Provision a new container registry The following example demonstrates how to provision a new Azure Container Registry and attach it to a container app environment: @@ -79,7 +47,7 @@ The preceding code: Configuration](/integrations/cloud/azure/local-provisioning/#configuration). -### Reference an existing container registry +## Reference an existing container registry To reference an existing Azure Container Registry, use the `PublishAsExisting` method with the registry name and resource group: @@ -109,7 +77,7 @@ The preceding code: - Uses parameters to allow for dynamic configuration of the registry name and resource group. - Optionally grants the `AcrPush` role to a project resource named `api`, allowing it to push images to the registry. -### Key features +## Key features **Automatic credential flow** @@ -124,7 +92,7 @@ builder.AddProject("api", "../Api/Api.csproj") .WithRoleAssignments(acr, ContainerRegistryBuiltInRole.AcrPush); ``` -#### Provisioning-generated Bicep +## Provisioning-generated Bicep If you're new to [Bicep](https://learn.microsoft.com/azure/azure-resource-manager/bicep/overview), it's a domain-specific language for defining Azure resources. With , you don't need to write Bicep by-hand, instead the provisioning APIs generate Bicep for you. When you publish your app, the generated Bicep is output alongside the manifest file. When you add an Azure Container Registry resource, the following Bicep is generated: diff --git a/src/frontend/src/data/integration-docs.json b/src/frontend/src/data/integration-docs.json index 17f6a64d..f6cc0472 100644 --- a/src/frontend/src/data/integration-docs.json +++ b/src/frontend/src/data/integration-docs.json @@ -85,7 +85,7 @@ }, { "match": "Aspire.Hosting.Azure.ContainerRegistry", - "href": "/integrations/cloud/azure/azure-container-registry/" + "href": "/integrations/cloud/azure/azure-container-registry/azure-container-registry-get-started/" }, { "match": "Aspire.Hosting.Azure.CosmosDB", From 0b208e04aae422ff848b471422aaf9af941eecd4 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 15:32:44 +0000 Subject: [PATCH 11/30] Restructure Azure Cosmos DB integration into subfolder --- .../config/sidebar/integrations.topics.ts | 16 +- .../azure-cosmos-db-client.mdx | 129 +++++++++++++++ .../azure-cosmos-db-get-started.mdx | 88 ++++++++++ .../azure-cosmos-db-host.mdx} | 152 +----------------- src/frontend/src/data/integration-docs.json | 4 +- 5 files changed, 240 insertions(+), 149 deletions(-) create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-client.mdx create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-get-started.mdx rename src/frontend/src/content/docs/integrations/cloud/azure/{azure-cosmos-db.mdx => azure-cosmos-db/azure-cosmos-db-host.mdx} (74%) diff --git a/src/frontend/config/sidebar/integrations.topics.ts b/src/frontend/config/sidebar/integrations.topics.ts index e05c90ff..4378b361 100644 --- a/src/frontend/config/sidebar/integrations.topics.ts +++ b/src/frontend/config/sidebar/integrations.topics.ts @@ -401,7 +401,21 @@ export const integrationTopics: StarlightSidebarTopicsUserConfig = { }, { label: 'Azure Cosmos DB', - slug: 'integrations/cloud/azure/azure-cosmos-db', + collapsed: true, + items: [ + { + label: 'Get started', + slug: 'integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-get-started', + }, + { + label: 'Hosting integration (AppHost)', + slug: 'integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-host', + }, + { + label: 'Client integration', + slug: 'integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-client', + }, + ], }, { label: 'Azure Event Hubs', diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-client.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-client.mdx new file mode 100644 index 00000000..e1c1d635 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-client.mdx @@ -0,0 +1,129 @@ +--- +title: Azure Cosmos DB Client integration +description: Learn about the Aspire Azure Cosmos DB client integration including configuration, health checks, and telemetry. +--- + +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; + +To get started with the Aspire Microsoft Entity Framework Core Cosmos DB integration, install the [📦 Aspire.Microsoft.EntityFrameworkCore.Cosmos](https://www.nuget.org/packages/Aspire.Microsoft.EntityFrameworkCore.Cosmos) NuGet package in the client-consuming project, i.e., the project for the application that uses the Microsoft Entity Framework Core Cosmos DB client. + + + +### Add Cosmos DB context + +In the `Program.cs` file of your client-consuming project, call the `AddCosmosDbContext` extension method to register a `DbContext` for use via the dependency injection container. The method takes a connection name parameter and a database name parameter. + +```csharp +builder.AddCosmosDbContext("cosmosdb", "databaseName"); +``` + +Alternatively, the database name can be inferred from the connection when there's a single database in the connection string. In this case, you can omit the database name parameter: + +```csharp +builder.AddCosmosDbContext("cosmosdb"); +``` + +> [!TIP] +> The `connectionName` parameter must match the name used when adding the Cosmos DB resource in the AppHost project. In other words, when you call `AddAzureCosmosDB` and provide a name of `cosmosdb` that same name should be used when calling `AddCosmosDbContext`. For more information, see [Add Azure Cosmos DB resource](#add-azure-cosmos-db-resource). + +You can then retrieve the `DbContext` instance using dependency injection. For example, to retrieve the client from a service: + +```csharp +public class ExampleService(MyDbContext context) +{ + // Use context... +} +``` + +For more information on using Entity Framework Core with Azure Cosmos DB, see the [Examples for Azure Cosmos DB for NoSQL SDK for .NET](https://learn.microsoft.com/ef/core/providers/cosmos/?tabs=dotnet-core-cli). + +### Configuration + +The Aspire Microsoft Entity Framework Core Cosmos DB integration provides multiple options to configure the Azure Cosmos DB connection based on the requirements and conventions of your project. + +#### Use a connection string + +When using a connection string from the `ConnectionStrings` configuration section, you can provide the name of the connection string when calling `builder.AddCosmosDbContext`: + +```csharp title="C# — Program.cs" +builder.AddCosmosDbContext("CosmosConnection"); +``` + +And then the connection string will be retrieved from the `ConnectionStrings` configuration section: + +```json title="appsettings.json" +{ + "ConnectionStrings": { + "CosmosConnection": "AccountEndpoint=https://{account_name}.documents.azure.com:443/;AccountKey={account_key};" + } +} +``` + +For more information, see the [ConnectionString documentation](https://learn.microsoft.com/azure/cosmos-db/nosql/how-to-dotnet-get-started#connect-with-a-connection-string). + +#### Use configuration providers + +The Aspire Microsoft Entity Framework Core Cosmos DB integration supports `Microsoft.Extensions.Configuration`. It loads the `EntityFrameworkCoreCosmosSettings` from configuration files such as `appsettings.json`. Example `appsettings.json` that configures some of the options: + +```json title="appsettings.json" +{ + "Aspire": { + "Microsoft": { + "EntityFrameworkCore": { + "Cosmos": { + "DisableTracing": true + } + } + } + } +} +``` + +For the complete Cosmos DB client integration JSON schema, see [Aspire.Microsoft.EntityFrameworkCore.Cosmos/ConfigurationSchema.json](https://github.com/dotnet/aspire/blob/main/src/Components/Aspire.Microsoft.EntityFrameworkCore.Cosmos/ConfigurationSchema.json). + +#### Use inline delegates + +You can also pass the `Action configureSettings` delegate to set up some or all the `EntityFrameworkCoreCosmosSettings` options inline, for example to disable tracing from code: + +```csharp +builder.AddCosmosDbContext( + "cosmosdb", + settings => settings.DisableTracing = true); +``` + +### Client integration health checks + +The Aspire Microsoft Entity Framework Core Cosmos DB integration currently doesn't implement health checks, though this may change in future releases. + +#### Logging + +The Aspire Microsoft Entity Framework Core Cosmos DB integration uses the following log categories: + +- `Azure-Cosmos-Operation-Request-Diagnostics` +- `Microsoft.EntityFrameworkCore.ChangeTracking` +- `Microsoft.EntityFrameworkCore.Database.Command` +- `Microsoft.EntityFrameworkCore.Infrastructure` +- `Microsoft.EntityFrameworkCore.Query` + +#### Tracing + +The Aspire Microsoft Entity Framework Core Cosmos DB integration will emit the following tracing activities using OpenTelemetry: + +- `Azure.Cosmos.Operation` +- `OpenTelemetry.Instrumentation.EntityFrameworkCore` + +#### Metrics + +The Aspire Microsoft Entity Framework Core Cosmos DB integration currently supports the following metrics: + +- `Microsoft.EntityFrameworkCore` + - `ec_Microsoft_EntityFrameworkCore_active_db_contexts` + - `ec_Microsoft_EntityFrameworkCore_total_queries` + - `ec_Microsoft_EntityFrameworkCore_queries_per_second` + - `ec_Microsoft_EntityFrameworkCore_total_save_changes` + - `ec_Microsoft_EntityFrameworkCore_save_changes_per_second` + - `ec_Microsoft_EntityFrameworkCore_compiled_query_cache_hit_rate` + - `ec_Microsoft_Entity_total_execution_strategy_operation_failures` + - `ec_Microsoft_E_execution_strategy_operation_failures_per_second` + - `ec_Microsoft_EntityFramew_total_optimistic_concurrency_failures` + - `ec_Microsoft_EntityF_optimistic_concurrency_failures_per_second` diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-get-started.mdx new file mode 100644 index 00000000..db9e4734 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-get-started.mdx @@ -0,0 +1,88 @@ +--- +title: Get started with the Azure Cosmos DB integrations +description: Learn how to set up the Aspire Azure Cosmos DB Hosting and Client integrations simply. +prev: false +--- + +import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components'; +import InstallPackage from '@components/InstallPackage.astro'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; +import { Image } from 'astro:assets'; +import cosmosDbIcon from '@assets/icons/azure-cosmosdb-icon.png'; + +Azure Cosmos DB logo + +[Azure Cosmos DB](https://azure.microsoft.com/services/cosmos-db/) is a fully managed NoSQL database service for modern app development. The Aspire Azure Cosmos DB integration enables you to connect to existing Cosmos DB instances or create new instances with the Azure Cosmos DB emulator. + +In this introduction, you'll see how to install and use the Aspire Azure Cosmos DB integrations in a simple configuration. If you already have this knowledge, see [Azure Cosmos DB Hosting integration](/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-host/) and [Azure Cosmos DB Client integration](/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-client/) for full reference details. + + + +## Set up hosting integration + +To begin, install the Aspire Azure Cosmos DB Hosting integration in your Aspire AppHost project. This integration allows you to create and manage Azure Cosmos DB resources from your Aspire hosting projects: + + + +Next, in the AppHost project, create an Azure Cosmos DB resource and pass it to the consuming client projects: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var cosmos = builder.AddAzureCosmosDB("cosmos-db"); +var db = cosmos.AddCosmosDatabase("db"); + +builder.AddProject("api") + .WithReference(db); + +// After adding all resources, run the app... + +builder.Build().Run(); +``` + +The preceding code adds an Azure Cosmos DB resource named `cosmos-db` with a database named `db`. The database is then referenced by the `api` project. + +## Set up client integration + +To get started with the Aspire Microsoft Entity Framework Core Cosmos DB client integration, install the client integration package in the client-consuming project: + + + +In the `Program.cs` file of your client-consuming project, call the `AddCosmosDbContext` extension method to register a `DbContext` for use via the dependency injection container: + +```csharp title="C# — Program.cs" +builder.AddCosmosDbContext("cosmos-db"); +``` + +You can then retrieve the `DbContext` instance using dependency injection. For example, to retrieve the client from a service: + +```csharp +public class ExampleService(MyDbContext context) +{ + // Use context... +} +``` + +## Continue learning + +For more information on how the Azure Cosmos DB integrations work, see: + + + + + diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-host.mdx similarity index 74% rename from src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db.mdx rename to src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-host.mdx index e896f580..859198f9 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-host.mdx @@ -1,36 +1,20 @@ --- -title: Azure Cosmos DB integration -description: Learn how to install and configure the Aspire Azure Cosmos DB integration to connect to existing Cosmos DB instances or create new instances from Aspire with the Azure Cosmos DB emulator. +title: Azure Cosmos DB Hosting integration +description: Learn about the Aspire Azure Cosmos DB hosting integration including provisioning, customization, and configuration. --- import { Aside } from '@astrojs/starlight/components'; import InstallPackage from '@components/InstallPackage.astro'; -import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; import ThemeImage from '@components/ThemeImage.astro'; -import { Image } from 'astro:assets'; -import cosmosDbIcon from '@assets/icons/azure-cosmosdb-icon.png'; import cosmosResourceRelationships from '@assets/integrations/cloud/azure/cosmos-db/cosmos-resource-relationships.svg'; import cosmosResourceRelationshipsLight from '@assets/integrations/cloud/azure/cosmos-db/cosmos-resource-relationships-light.svg'; -Azure Cosmos DB logo - -[Azure Cosmos DB](https://azure.microsoft.com/services/cosmos-db/) is a fully managed NoSQL database service for modern app development. The Aspire Azure Cosmos DB integration enables you to connect to existing Cosmos DB instances or create new instances with the Azure Cosmos DB emulator. - -## Hosting integration - The Aspire Azure Cosmos DB hosting integration models Cosmos DB resources as the following types: -- `AzureCosmosDBResource`: Represents an Azure Cosmos DB resource. -- `AzureCosmosDBContainerResource`: Represents an Azure Cosmos DB container resource. -- `AzureCosmosDBDatabaseResource`: Represents an Azure Cosmos DB database resource. -- `AzureCosmosDBEmulatorResource`: Represents an Azure Cosmos DB emulator resource. +- \`AzureCosmosDBResource\`: Represents an Azure Cosmos DB resource. +- \`AzureCosmosDBContainerResource\`: Represents an Azure Cosmos DB container resource. +- \`AzureCosmosDBDatabaseResource\`: Represents an Azure Cosmos DB database resource. +- \`AzureCosmosDBEmulatorResource\`: Represents an Azure Cosmos DB emulator resource. To access these types and APIs, add the [📦 Aspire.Hosting.Azure.CosmosDB](https://www.nuget.org/packages/Aspire.Hosting.Azure.CosmosDB) NuGet package to your AppHost project. @@ -424,127 +408,3 @@ The Cosmos DB container resource inherits all properties from its parent Cosmos `db1` becomes `DB1_URI`. -## Client integration - -To get started with the Aspire Microsoft Entity Framework Core Cosmos DB integration, install the [📦 Aspire.Microsoft.EntityFrameworkCore.Cosmos](https://www.nuget.org/packages/Aspire.Microsoft.EntityFrameworkCore.Cosmos) NuGet package in the client-consuming project, i.e., the project for the application that uses the Microsoft Entity Framework Core Cosmos DB client. - - - -### Add Cosmos DB context - -In the `Program.cs` file of your client-consuming project, call the `AddCosmosDbContext` extension method to register a `DbContext` for use via the dependency injection container. The method takes a connection name parameter and a database name parameter. - -```csharp -builder.AddCosmosDbContext("cosmosdb", "databaseName"); -``` - -Alternatively, the database name can be inferred from the connection when there's a single database in the connection string. In this case, you can omit the database name parameter: - -```csharp -builder.AddCosmosDbContext("cosmosdb"); -``` - -> [!TIP] -> The `connectionName` parameter must match the name used when adding the Cosmos DB resource in the AppHost project. In other words, when you call `AddAzureCosmosDB` and provide a name of `cosmosdb` that same name should be used when calling `AddCosmosDbContext`. For more information, see [Add Azure Cosmos DB resource](#add-azure-cosmos-db-resource). - -You can then retrieve the `DbContext` instance using dependency injection. For example, to retrieve the client from a service: - -```csharp -public class ExampleService(MyDbContext context) -{ - // Use context... -} -``` - -For more information on using Entity Framework Core with Azure Cosmos DB, see the [Examples for Azure Cosmos DB for NoSQL SDK for .NET](https://learn.microsoft.com/ef/core/providers/cosmos/?tabs=dotnet-core-cli). - -### Configuration - -The Aspire Microsoft Entity Framework Core Cosmos DB integration provides multiple options to configure the Azure Cosmos DB connection based on the requirements and conventions of your project. - -#### Use a connection string - -When using a connection string from the `ConnectionStrings` configuration section, you can provide the name of the connection string when calling `builder.AddCosmosDbContext`: - -```csharp title="C# — Program.cs" -builder.AddCosmosDbContext("CosmosConnection"); -``` - -And then the connection string will be retrieved from the `ConnectionStrings` configuration section: - -```json title="appsettings.json" -{ - "ConnectionStrings": { - "CosmosConnection": "AccountEndpoint=https://{account_name}.documents.azure.com:443/;AccountKey={account_key};" - } -} -``` - -For more information, see the [ConnectionString documentation](https://learn.microsoft.com/azure/cosmos-db/nosql/how-to-dotnet-get-started#connect-with-a-connection-string). - -#### Use configuration providers - -The Aspire Microsoft Entity Framework Core Cosmos DB integration supports `Microsoft.Extensions.Configuration`. It loads the `EntityFrameworkCoreCosmosSettings` from configuration files such as `appsettings.json`. Example `appsettings.json` that configures some of the options: - -```json title="appsettings.json" -{ - "Aspire": { - "Microsoft": { - "EntityFrameworkCore": { - "Cosmos": { - "DisableTracing": true - } - } - } - } -} -``` - -For the complete Cosmos DB client integration JSON schema, see [Aspire.Microsoft.EntityFrameworkCore.Cosmos/ConfigurationSchema.json](https://github.com/dotnet/aspire/blob/main/src/Components/Aspire.Microsoft.EntityFrameworkCore.Cosmos/ConfigurationSchema.json). - -#### Use inline delegates - -You can also pass the `Action configureSettings` delegate to set up some or all the `EntityFrameworkCoreCosmosSettings` options inline, for example to disable tracing from code: - -```csharp -builder.AddCosmosDbContext( - "cosmosdb", - settings => settings.DisableTracing = true); -``` - -### Client integration health checks - -The Aspire Microsoft Entity Framework Core Cosmos DB integration currently doesn't implement health checks, though this may change in future releases. - -#### Logging - -The Aspire Microsoft Entity Framework Core Cosmos DB integration uses the following log categories: - -- `Azure-Cosmos-Operation-Request-Diagnostics` -- `Microsoft.EntityFrameworkCore.ChangeTracking` -- `Microsoft.EntityFrameworkCore.Database.Command` -- `Microsoft.EntityFrameworkCore.Infrastructure` -- `Microsoft.EntityFrameworkCore.Query` - -#### Tracing - -The Aspire Microsoft Entity Framework Core Cosmos DB integration will emit the following tracing activities using OpenTelemetry: - -- `Azure.Cosmos.Operation` -- `OpenTelemetry.Instrumentation.EntityFrameworkCore` - -#### Metrics - -The Aspire Microsoft Entity Framework Core Cosmos DB integration currently supports the following metrics: - -- `Microsoft.EntityFrameworkCore` - - `ec_Microsoft_EntityFrameworkCore_active_db_contexts` - - `ec_Microsoft_EntityFrameworkCore_total_queries` - - `ec_Microsoft_EntityFrameworkCore_queries_per_second` - - `ec_Microsoft_EntityFrameworkCore_total_save_changes` - - `ec_Microsoft_EntityFrameworkCore_save_changes_per_second` - - `ec_Microsoft_EntityFrameworkCore_compiled_query_cache_hit_rate` - - `ec_Microsoft_Entity_total_execution_strategy_operation_failures` - - `ec_Microsoft_E_execution_strategy_operation_failures_per_second` - - `ec_Microsoft_EntityFramew_total_optimistic_concurrency_failures` - - `ec_Microsoft_EntityF_optimistic_concurrency_failures_per_second` diff --git a/src/frontend/src/data/integration-docs.json b/src/frontend/src/data/integration-docs.json index f6cc0472..17fcca8c 100644 --- a/src/frontend/src/data/integration-docs.json +++ b/src/frontend/src/data/integration-docs.json @@ -89,7 +89,7 @@ }, { "match": "Aspire.Hosting.Azure.CosmosDB", - "href": "/integrations/cloud/azure/azure-cosmos-db/" + "href": "/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-get-started/" }, { "match": "Aspire.Hosting.Azure.EventHubs", @@ -257,7 +257,7 @@ }, { "match": "Aspire.Microsoft.Azure.Cosmos", - "href": "/integrations/cloud/azure/azure-cosmos-db/" + "href": "/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-get-started/" }, { "match": "Aspire.Microsoft.Azure.StackExchangeRedis", From 3a28c3518355bb78fc84e1a275b792345d18f6ce Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 15:33:54 +0000 Subject: [PATCH 12/30] Restructure Azure Event Hubs integration into subfolder --- .../config/sidebar/integrations.topics.ts | 16 +- .../azure-event-hubs-client.mdx | 246 ++++++++++++++++ .../azure-event-hubs-get-started.mdx | 88 ++++++ .../azure-event-hubs-host.mdx} | 268 +----------------- src/frontend/src/data/integration-docs.json | 4 +- 5 files changed, 357 insertions(+), 265 deletions(-) create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-client.mdx create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-get-started.mdx rename src/frontend/src/content/docs/integrations/cloud/azure/{azure-event-hubs.mdx => azure-event-hubs/azure-event-hubs-host.mdx} (59%) diff --git a/src/frontend/config/sidebar/integrations.topics.ts b/src/frontend/config/sidebar/integrations.topics.ts index 4378b361..7bc7894c 100644 --- a/src/frontend/config/sidebar/integrations.topics.ts +++ b/src/frontend/config/sidebar/integrations.topics.ts @@ -419,7 +419,21 @@ export const integrationTopics: StarlightSidebarTopicsUserConfig = { }, { label: 'Azure Event Hubs', - slug: 'integrations/cloud/azure/azure-event-hubs', + collapsed: true, + items: [ + { + label: 'Get started', + slug: 'integrations/cloud/azure/azure-event-hubs/azure-event-hubs-get-started', + }, + { + label: 'Hosting integration (AppHost)', + slug: 'integrations/cloud/azure/azure-event-hubs/azure-event-hubs-host', + }, + { + label: 'Client integration', + slug: 'integrations/cloud/azure/azure-event-hubs/azure-event-hubs-client', + }, + ], }, { label: 'Azure Functions', diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-client.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-client.mdx new file mode 100644 index 00000000..dbc8664d --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-client.mdx @@ -0,0 +1,246 @@ +--- +title: Azure Event Hubs Client integration +description: Learn about the Aspire Azure Event Hubs client integration including configuration, health checks, and telemetry. +--- + +import { Aside } from '@astrojs/starlight/components'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; + +To get started with the Aspire Azure Event Hubs client integration, install the [📦 Aspire.Azure.Messaging.EventHubs](https://www.nuget.org/packages/Aspire.Azure.Messaging.EventHubs) NuGet package in the client-consuming project, that is, the project for the application that uses the Event Hubs client. + + + +### Supported Event Hubs client types + +The following Event Hub clients are supported by the library, along with their corresponding options and settings classes: + +| Azure client type | Azure options class | Aspire settings class | +| -------------------------------- | --------------------------------------- | -------------------------------------------------- | +| `EventHubProducerClient` | `EventHubProducerClientOptions` | `AzureMessagingEventHubsProducerSettings` | +| `EventHubBufferedProducerClient` | `EventHubBufferedProducerClientOptions` | `AzureMessagingEventHubsBufferedProducerSettings` | +| `EventHubConsumerClient` | `EventHubConsumerClientOptions` | `AzureMessagingEventHubsConsumerSettings` | +| `EventProcessorClient` | `EventProcessorClientOptions` | `AzureMessagingEventHubsProcessorSettings` | +| PartitionReceiver Class | `PartitionReceiverOptions` | `AzureMessagingEventHubsPartitionReceiverSettings` | + +The client types are from the Azure SDK for .NET, as are the corresponding options classes. The settings classes are provided by Aspire. The settings classes are used to configure the client instances. + +### Add an Event Hubs producer client + +In the `Program.cs` file of your client-consuming project, call the `AddAzureEventHubProducerClient` extension method on any `IHostApplicationBuilder` to register an `EventHubProducerClient` for use via the dependency injection container. The method takes a connection name parameter. + +```csharp +builder.AddAzureEventHubProducerClient(connectionName: "event-hubs"); +``` + + + +After adding the `EventHubProducerClient`, you can retrieve the client instance using dependency injection. For example, to retrieve your data source object from an example service define it as a constructor parameter and ensure the `ExampleService` class is registered with the dependency injection container: + +```csharp +public class ExampleService(EventHubProducerClient client) +{ + // Use client... +} +``` + +For more information, see: + +- [Azure.Messaging.EventHubs documentation](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/eventhub/Azure.Messaging.EventHubs/README.md) for examples on using the `EventHubProducerClient`. +- [Dependency injection in .NET](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection) for details on dependency injection. + +#### Additional APIs to consider + +The client integration provides additional APIs to configure client instances. When you need to register an Event Hubs client, consider the following APIs: + +| Azure client type | Registration API | +| -------------------------------- | ---------------------------------------- | +| `EventHubProducerClient` | `AddAzureEventHubProducerClient` | +| `EventHubBufferedProducerClient` | `AddAzureEventHubBufferedProducerClient` | +| `EventHubConsumerClient` | `AddAzureEventHubConsumerClient` | +| `EventProcessorClient` | `AddAzureEventProcessorClient` | +| `PartitionReceiver` | `AddAzurePartitionReceiverClient` | + +All of the aforementioned APIs include optional parameters to configure the client instances. + +### Add keyed Event Hubs producer client + +There might be situations where you want to register multiple `EventHubProducerClient` instances with different connection names. To register keyed Event Hubs clients, call the `AddKeyedAzureEventHubProducerClient` method: + +```csharp +builder.AddKeyedAzureEventHubProducerClient(name: "messages"); +builder.AddKeyedAzureEventHubProducerClient(name: "commands"); +``` + + + +Then you can retrieve the client instances using dependency injection. For example, to retrieve the clients from a service: + +```csharp +public class ExampleService( + [KeyedService("messages")] EventHubProducerClient messagesClient, + [KeyedService("commands")] EventHubProducerClient commandsClient) +{ + // Use clients... +} +``` + +For more information, see [Keyed services in .NET](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection#keyed-services). + +#### Additional keyed APIs to consider + +The client integration provides additional APIs to configure keyed client instances. When you need to register a keyed Event Hubs client, consider the following APIs: + +| Azure client type | Registration API | +| -------------------------------- | --------------------------------------------- | +| `EventHubProducerClient` | `AddKeyedAzureEventHubProducerClient` | +| `EventHubBufferedProducerClient` | `AddKeyedAzureEventHubBufferedProducerClient` | +| `EventHubConsumerClient` | `AddKeyedAzureEventHubConsumerClient` | +| `EventProcessorClient` | `AddKeyedAzureEventProcessorClient` | +| PartitionReceiver class | `AddKeyedAzurePartitionReceiverClient` | + +All of the aforementioned APIs include optional parameters to configure the client instances. + +### Configuration + +The Aspire Azure Event Hubs library provides multiple options to configure the Azure Event Hubs connection based on the requirements and conventions of your project. Either a `FullyQualifiedNamespace` or a `ConnectionString` is required to be supplied. + +#### Use a connection string + +When using a connection string from the `ConnectionStrings` configuration section, provide the name of the connection string when calling `builder.AddAzureEventHubProducerClient()` and other supported Event Hubs clients. In this example, the connection string does not include the `EntityPath` property, so the `EventHubName` property must be set in the settings callback: + +```csharp +builder.AddAzureEventHubProducerClient( + "event-hubs", + static settings => + { + settings.EventHubName = "MyHub"; + }); +``` + +And then the connection information will be retrieved from the `ConnectionStrings` configuration section. Two connection formats are supported: + +##### Fully Qualified Namespace (FQN) + +The recommended approach is to use a fully qualified namespace, which works with the `Credential` property to establish a connection. If no credential is configured, the `DefaultAzureCredential` is used. + +```json +{ + "ConnectionStrings": { + "event-hubs": "{your_namespace}.servicebus.windows.net" + } +} +``` + +#### Connection string + +Alternatively, use a connection string: + +```json +{ + "ConnectionStrings": { + "event-hubs": "Endpoint=sb://mynamespace.servicebus.windows.net/;SharedAccessKeyName=accesskeyname;SharedAccessKey=accesskey;EntityPath=MyHub" + } +} +``` + +### Use configuration providers + +The Aspire Azure Event Hubs library supports `Microsoft.Extensions.Configuration`. It loads the `AzureMessagingEventHubsSettings` and the associated Options, e.g. `EventProcessorClientOptions`, from configuration by using the `Aspire:Azure:Messaging:EventHubs:` key prefix, followed by the name of the specific client in use. For example, consider the `appsettings.json` that configures some of the options for an `EventProcessorClient`: + +```json +{ + "Aspire": { + "Azure": { + "Messaging": { + "EventHubs": { + "EventProcessorClient": { + "EventHubName": "MyHub", + "ClientOptions": { + "Identifier": "PROCESSOR_ID" + } + } + } + } + } + } +} +``` + +For the complete Azure Event Hubs client integration JSON schema, see [Aspire.Azure.Messaging.EventHubs/ConfigurationSchema.json](https://github.com/dotnet/aspire/blob/main/src/Components/Aspire.Azure.Messaging.EventHubs/ConfigurationSchema.json). + +### Use named configuration + +The Aspire Azure Event Hubs library supports named configuration, which allows you to configure multiple instances of the same client type with different settings. The named configuration uses the connection name as a key under the specific client configuration section. + +```json +{ + "Aspire": { + "Azure": { + "Messaging": { + "EventHubs": { + "EventProcessorClient": { + "processor1": { + "EventHubName": "MyHub1", + "ClientOptions": { + "Identifier": "PROCESSOR_1" + } + }, + "processor2": { + "EventHubName": "MyHub2", + "ClientOptions": { + "Identifier": "PROCESSOR_2" + } + } + } + } + } + } + } +} +``` + +In this example, the `processor1` and `processor2` connection names can be used when calling `AddAzureEventProcessorClient`: + +```csharp +builder.AddAzureEventProcessorClient("processor1"); +builder.AddAzureEventProcessorClient("processor2"); +``` + +Named configuration takes precedence over the top-level configuration. If both are provided, the settings from the named configuration override the top-level settings. + +You can also setup the Options type using the optional `Action> configureClientBuilder` parameter of the `AddAzureEventProcessorClient` method. For example, to set the processor's client ID for this client: + +```csharp +builder.AddAzureEventProcessorClient( + "event-hubs", + configureClientBuilder: clientBuilder => clientBuilder.ConfigureOptions( + options => options.Identifier = "PROCESSOR_ID")); +``` + +### Observability and telemetry + +Aspire integrations automatically set up Logging, Tracing, and Metrics configurations, which are sometimes known as _the pillars of observability_. Depending on the backing service, some integrations may only support some of these features. For example, some integrations support logging and tracing, but not metrics. Telemetry features can also be disabled using the techniques presented in the [Configuration](#configuration) section. + +### Logging + +The Aspire Azure Event Hubs integration uses the following log categories: + +- `Azure.Core` +- `Azure.Identity` + +### Tracing + +The Aspire Azure Event Hubs integration will emit the following tracing activities using OpenTelemetry: + +- `Azure.Messaging.EventHubs.*` + +### Metrics + +The Aspire Azure Event Hubs integration currently doesn't support metrics by default due to limitations with the Azure SDK for .NET. If that changes in the future, this section will be updated to reflect those changes. diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-get-started.mdx new file mode 100644 index 00000000..0d40aec0 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-get-started.mdx @@ -0,0 +1,88 @@ +--- +title: Get started with the Azure Event Hubs integrations +description: Learn how to set up the Aspire Azure Event Hubs Hosting and Client integrations simply. +prev: false +--- + +import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components'; +import InstallPackage from '@components/InstallPackage.astro'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; +import { Image } from 'astro:assets'; +import eventHubsIcon from '@assets/icons/azure-eventhubs-icon.png'; + +Azure Event Hubs logo + +[Azure Event Hubs](https://learn.microsoft.com/event-hubs/event-hubs-about) is a native data-streaming service in the cloud that can stream millions of events per second, with low latency, from any source to any destination. The Aspire Azure Event Hubs integration enables you to connect to Azure Event Hubs instances from your applications. + +In this introduction, you'll see how to install and use the Aspire Azure Event Hubs integrations in a simple configuration. If you already have this knowledge, see [Azure Event Hubs Hosting integration](/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-host/) and [Azure Event Hubs Client integration](/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-client/) for full reference details. + + + +## Set up hosting integration + +To begin, install the Aspire Azure Event Hubs Hosting integration in your Aspire AppHost project. This integration allows you to create and manage Azure Event Hubs resources from your Aspire hosting projects: + + + +Next, in the AppHost project, create an Azure Event Hubs resource and pass it to the consuming client projects: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var eventHubs = builder.AddAzureEventHubs("event-hubs"); +eventHubs.AddHub("messages"); + +builder.AddProject() + .WithReference(eventHubs); + +// After adding all resources, run the app... + +builder.Build().Run(); +``` + +The preceding code adds an Azure Event Hubs resource named `event-hubs` and an Event Hub named `messages` to the AppHost project. The `WithReference` method passes the connection information to the `ExampleService` project. + +## Set up client integration + +To get started with the Aspire Azure Event Hubs client integration, install the client integration package in the client-consuming project: + + + +In the `Program.cs` file of your client-consuming project, call the `AddAzureEventHubProducerClient` extension method to register an `EventHubProducerClient` for use via the dependency injection container: + +```csharp title="C# — Program.cs" +builder.AddAzureEventHubProducerClient(connectionName: "event-hubs"); +``` + +You can then retrieve the client instance using dependency injection. For example, to retrieve your client from an example service: + +```csharp +public class ExampleService(EventHubProducerClient client) +{ + // Use client... +} +``` + +## Continue learning + +For more information on how the Azure Event Hubs integrations work, see: + + + + + diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-event-hubs.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-host.mdx similarity index 59% rename from src/frontend/src/content/docs/integrations/cloud/azure/azure-event-hubs.mdx rename to src/frontend/src/content/docs/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-host.mdx index b414ed8f..37ebff13 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-event-hubs.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-host.mdx @@ -1,33 +1,17 @@ --- -title: Azure Event Hubs integration -description: This article describes the Aspire Azure Event Hubs integration features and capabilities. +title: Azure Event Hubs Hosting integration +description: Learn about the Aspire Azure Event Hubs hosting integration including provisioning, customization, and configuration. --- import { Aside } from '@astrojs/starlight/components'; import InstallPackage from '@components/InstallPackage.astro'; -import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; -import { Image } from 'astro:assets'; -import eventHubsIcon from '@assets/icons/azure-eventhubs-icon.png'; - -Azure Event Hubs logo - -[Azure Event Hubs](https://learn.microsoft.com/event-hubs/event-hubs-about) is a native data-streaming service in the cloud that can stream millions of events per second, with low latency, from any source to any destination. The Aspire Azure Event Hubs integration enables you to connect to Azure Event Hubs instances from your applications. - -## Hosting integration The Aspire Azure Event Hubs hosting integration models the various Event Hub resources as the following types: -- `AzureEventHubsResource`: Represents a top-level Azure Event Hubs resource, used for representing collections of hubs and the connection information to the underlying Azure resource. -- `AzureEventHubResource`: Represents a single Event Hub resource. -- `AzureEventHubsEmulatorResource`: Represents an Azure Event Hubs emulator as a container resource. -- `AzureEventHubConsumerGroupResource`: Represents a consumer group within an Event Hub resource. +- \`AzureEventHubsResource\`: Represents a top-level Azure Event Hubs resource, used for representing collections of hubs and the connection information to the underlying Azure resource. +- \`AzureEventHubResource\`: Represents a single Event Hub resource. +- \`AzureEventHubsEmulatorResource\`: Represents an Azure Event Hubs emulator as a container resource. +- \`AzureEventHubConsumerGroupResource\`: Represents a consumer group within an Event Hub resource. To access these types and APIs for expressing them within your [AppHost](/get-started/app-host/) project, install the [📦 Aspire.Hosting.Azure.EventHubs](https://www.nuget.org/packages/Aspire.Hosting.Azure.EventHubs) NuGet package: @@ -407,243 +391,3 @@ The Event Hub consumer group resource inherits all properties from its parent Ev `eh1` becomes `EH1_URI`. -## Client integration - -To get started with the Aspire Azure Event Hubs client integration, install the [📦 Aspire.Azure.Messaging.EventHubs](https://www.nuget.org/packages/Aspire.Azure.Messaging.EventHubs) NuGet package in the client-consuming project, that is, the project for the application that uses the Event Hubs client. - - - -### Supported Event Hubs client types - -The following Event Hub clients are supported by the library, along with their corresponding options and settings classes: - -| Azure client type | Azure options class | Aspire settings class | -| -------------------------------- | --------------------------------------- | -------------------------------------------------- | -| `EventHubProducerClient` | `EventHubProducerClientOptions` | `AzureMessagingEventHubsProducerSettings` | -| `EventHubBufferedProducerClient` | `EventHubBufferedProducerClientOptions` | `AzureMessagingEventHubsBufferedProducerSettings` | -| `EventHubConsumerClient` | `EventHubConsumerClientOptions` | `AzureMessagingEventHubsConsumerSettings` | -| `EventProcessorClient` | `EventProcessorClientOptions` | `AzureMessagingEventHubsProcessorSettings` | -| PartitionReceiver Class | `PartitionReceiverOptions` | `AzureMessagingEventHubsPartitionReceiverSettings` | - -The client types are from the Azure SDK for .NET, as are the corresponding options classes. The settings classes are provided by Aspire. The settings classes are used to configure the client instances. - -### Add an Event Hubs producer client - -In the `Program.cs` file of your client-consuming project, call the `AddAzureEventHubProducerClient` extension method on any `IHostApplicationBuilder` to register an `EventHubProducerClient` for use via the dependency injection container. The method takes a connection name parameter. - -```csharp -builder.AddAzureEventHubProducerClient(connectionName: "event-hubs"); -``` - - - -After adding the `EventHubProducerClient`, you can retrieve the client instance using dependency injection. For example, to retrieve your data source object from an example service define it as a constructor parameter and ensure the `ExampleService` class is registered with the dependency injection container: - -```csharp -public class ExampleService(EventHubProducerClient client) -{ - // Use client... -} -``` - -For more information, see: - -- [Azure.Messaging.EventHubs documentation](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/eventhub/Azure.Messaging.EventHubs/README.md) for examples on using the `EventHubProducerClient`. -- [Dependency injection in .NET](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection) for details on dependency injection. - -#### Additional APIs to consider - -The client integration provides additional APIs to configure client instances. When you need to register an Event Hubs client, consider the following APIs: - -| Azure client type | Registration API | -| -------------------------------- | ---------------------------------------- | -| `EventHubProducerClient` | `AddAzureEventHubProducerClient` | -| `EventHubBufferedProducerClient` | `AddAzureEventHubBufferedProducerClient` | -| `EventHubConsumerClient` | `AddAzureEventHubConsumerClient` | -| `EventProcessorClient` | `AddAzureEventProcessorClient` | -| `PartitionReceiver` | `AddAzurePartitionReceiverClient` | - -All of the aforementioned APIs include optional parameters to configure the client instances. - -### Add keyed Event Hubs producer client - -There might be situations where you want to register multiple `EventHubProducerClient` instances with different connection names. To register keyed Event Hubs clients, call the `AddKeyedAzureEventHubProducerClient` method: - -```csharp -builder.AddKeyedAzureEventHubProducerClient(name: "messages"); -builder.AddKeyedAzureEventHubProducerClient(name: "commands"); -``` - - - -Then you can retrieve the client instances using dependency injection. For example, to retrieve the clients from a service: - -```csharp -public class ExampleService( - [KeyedService("messages")] EventHubProducerClient messagesClient, - [KeyedService("commands")] EventHubProducerClient commandsClient) -{ - // Use clients... -} -``` - -For more information, see [Keyed services in .NET](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection#keyed-services). - -#### Additional keyed APIs to consider - -The client integration provides additional APIs to configure keyed client instances. When you need to register a keyed Event Hubs client, consider the following APIs: - -| Azure client type | Registration API | -| -------------------------------- | --------------------------------------------- | -| `EventHubProducerClient` | `AddKeyedAzureEventHubProducerClient` | -| `EventHubBufferedProducerClient` | `AddKeyedAzureEventHubBufferedProducerClient` | -| `EventHubConsumerClient` | `AddKeyedAzureEventHubConsumerClient` | -| `EventProcessorClient` | `AddKeyedAzureEventProcessorClient` | -| PartitionReceiver class | `AddKeyedAzurePartitionReceiverClient` | - -All of the aforementioned APIs include optional parameters to configure the client instances. - -### Configuration - -The Aspire Azure Event Hubs library provides multiple options to configure the Azure Event Hubs connection based on the requirements and conventions of your project. Either a `FullyQualifiedNamespace` or a `ConnectionString` is required to be supplied. - -#### Use a connection string - -When using a connection string from the `ConnectionStrings` configuration section, provide the name of the connection string when calling `builder.AddAzureEventHubProducerClient()` and other supported Event Hubs clients. In this example, the connection string does not include the `EntityPath` property, so the `EventHubName` property must be set in the settings callback: - -```csharp -builder.AddAzureEventHubProducerClient( - "event-hubs", - static settings => - { - settings.EventHubName = "MyHub"; - }); -``` - -And then the connection information will be retrieved from the `ConnectionStrings` configuration section. Two connection formats are supported: - -##### Fully Qualified Namespace (FQN) - -The recommended approach is to use a fully qualified namespace, which works with the `Credential` property to establish a connection. If no credential is configured, the `DefaultAzureCredential` is used. - -```json -{ - "ConnectionStrings": { - "event-hubs": "{your_namespace}.servicebus.windows.net" - } -} -``` - -#### Connection string - -Alternatively, use a connection string: - -```json -{ - "ConnectionStrings": { - "event-hubs": "Endpoint=sb://mynamespace.servicebus.windows.net/;SharedAccessKeyName=accesskeyname;SharedAccessKey=accesskey;EntityPath=MyHub" - } -} -``` - -### Use configuration providers - -The Aspire Azure Event Hubs library supports `Microsoft.Extensions.Configuration`. It loads the `AzureMessagingEventHubsSettings` and the associated Options, e.g. `EventProcessorClientOptions`, from configuration by using the `Aspire:Azure:Messaging:EventHubs:` key prefix, followed by the name of the specific client in use. For example, consider the `appsettings.json` that configures some of the options for an `EventProcessorClient`: - -```json -{ - "Aspire": { - "Azure": { - "Messaging": { - "EventHubs": { - "EventProcessorClient": { - "EventHubName": "MyHub", - "ClientOptions": { - "Identifier": "PROCESSOR_ID" - } - } - } - } - } - } -} -``` - -For the complete Azure Event Hubs client integration JSON schema, see [Aspire.Azure.Messaging.EventHubs/ConfigurationSchema.json](https://github.com/dotnet/aspire/blob/main/src/Components/Aspire.Azure.Messaging.EventHubs/ConfigurationSchema.json). - -### Use named configuration - -The Aspire Azure Event Hubs library supports named configuration, which allows you to configure multiple instances of the same client type with different settings. The named configuration uses the connection name as a key under the specific client configuration section. - -```json -{ - "Aspire": { - "Azure": { - "Messaging": { - "EventHubs": { - "EventProcessorClient": { - "processor1": { - "EventHubName": "MyHub1", - "ClientOptions": { - "Identifier": "PROCESSOR_1" - } - }, - "processor2": { - "EventHubName": "MyHub2", - "ClientOptions": { - "Identifier": "PROCESSOR_2" - } - } - } - } - } - } - } -} -``` - -In this example, the `processor1` and `processor2` connection names can be used when calling `AddAzureEventProcessorClient`: - -```csharp -builder.AddAzureEventProcessorClient("processor1"); -builder.AddAzureEventProcessorClient("processor2"); -``` - -Named configuration takes precedence over the top-level configuration. If both are provided, the settings from the named configuration override the top-level settings. - -You can also setup the Options type using the optional `Action> configureClientBuilder` parameter of the `AddAzureEventProcessorClient` method. For example, to set the processor's client ID for this client: - -```csharp -builder.AddAzureEventProcessorClient( - "event-hubs", - configureClientBuilder: clientBuilder => clientBuilder.ConfigureOptions( - options => options.Identifier = "PROCESSOR_ID")); -``` - -### Observability and telemetry - -Aspire integrations automatically set up Logging, Tracing, and Metrics configurations, which are sometimes known as _the pillars of observability_. Depending on the backing service, some integrations may only support some of these features. For example, some integrations support logging and tracing, but not metrics. Telemetry features can also be disabled using the techniques presented in the [Configuration](#configuration) section. - -### Logging - -The Aspire Azure Event Hubs integration uses the following log categories: - -- `Azure.Core` -- `Azure.Identity` - -### Tracing - -The Aspire Azure Event Hubs integration will emit the following tracing activities using OpenTelemetry: - -- `Azure.Messaging.EventHubs.*` - -### Metrics - -The Aspire Azure Event Hubs integration currently doesn't support metrics by default due to limitations with the Azure SDK for .NET. If that changes in the future, this section will be updated to reflect those changes. diff --git a/src/frontend/src/data/integration-docs.json b/src/frontend/src/data/integration-docs.json index 17fcca8c..1ab14c85 100644 --- a/src/frontend/src/data/integration-docs.json +++ b/src/frontend/src/data/integration-docs.json @@ -13,7 +13,7 @@ }, { "match": "Aspire.Azure.Messaging.EventHubs", - "href": "/integrations/cloud/azure/azure-event-hubs/" + "href": "/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-get-started/" }, { "match": "Aspire.Azure.Messaging.ServiceBus", @@ -93,7 +93,7 @@ }, { "match": "Aspire.Hosting.Azure.EventHubs", - "href": "/integrations/cloud/azure/azure-event-hubs/" + "href": "/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-get-started/" }, { "match": "Aspire.Hosting.Azure.Functions", From 2ae9d838dfffc74a405de75d5a8f1fd72622c760 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 15:35:15 +0000 Subject: [PATCH 13/30] Restructure Azure Functions integration into subfolder --- .../config/sidebar/integrations.topics.ts | 16 ++- .../azure-functions-client.mdx | 15 +++ .../azure-functions-get-started.mdx | 110 ++++++++++++++++++ .../azure-functions-host.mdx} | 65 ++--------- src/frontend/src/data/integration-docs.json | 2 +- 5 files changed, 150 insertions(+), 58 deletions(-) create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-functions/azure-functions-client.mdx create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-functions/azure-functions-get-started.mdx rename src/frontend/src/content/docs/integrations/cloud/azure/{azure-functions.mdx => azure-functions/azure-functions-host.mdx} (67%) diff --git a/src/frontend/config/sidebar/integrations.topics.ts b/src/frontend/config/sidebar/integrations.topics.ts index 7bc7894c..0828359f 100644 --- a/src/frontend/config/sidebar/integrations.topics.ts +++ b/src/frontend/config/sidebar/integrations.topics.ts @@ -437,7 +437,21 @@ export const integrationTopics: StarlightSidebarTopicsUserConfig = { }, { label: 'Azure Functions', - slug: 'integrations/cloud/azure/azure-functions', + collapsed: true, + items: [ + { + label: 'Get started', + slug: 'integrations/cloud/azure/azure-functions/azure-functions-get-started', + }, + { + label: 'Hosting integration (AppHost)', + slug: 'integrations/cloud/azure/azure-functions/azure-functions-host', + }, + { + label: 'Client integration', + slug: 'integrations/cloud/azure/azure-functions/azure-functions-client', + }, + ], }, { label: 'Azure Key Vault', diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-functions/azure-functions-client.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-functions/azure-functions-client.mdx new file mode 100644 index 00000000..1c65e900 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-functions/azure-functions-client.mdx @@ -0,0 +1,15 @@ +--- +title: Azure Functions Client integration +description: This integration does not have a client component. +--- + +import { LinkCard } from '@astrojs/starlight/components'; + +Azure Functions is a hosting-only integration and does not provide a client integration component. + +For more information on working with Azure Functions in your Aspire application, see: + + diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-functions/azure-functions-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-functions/azure-functions-get-started.mdx new file mode 100644 index 00000000..6aa5ce84 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-functions/azure-functions-get-started.mdx @@ -0,0 +1,110 @@ +--- +title: Get started with the Azure Functions integration +description: Learn how to set up the Aspire Azure Functions Hosting integration simply. +prev: false +--- + +import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components'; +import InstallPackage from '@components/InstallPackage.astro'; +import Pivot from '@components/Pivot.astro'; +import PivotSelector from '@components/PivotSelector.astro'; +import { Image } from 'astro:assets'; +import functionsIcon from '@assets/icons/azure-functionapps-icon.png'; + + + +Azure Functions logo + +[Azure Functions](https://learn.microsoft.com/azure-functions) is a serverless compute service that lets you run event-triggered code without having to explicitly provision or manage infrastructure. The Aspire Azure Functions integration enables you to model Azure Functions projects as part of your distributed application. + +In this introduction, you'll see how to install and use the Aspire Azure Functions integration in a simple configuration. If you already have this knowledge, see [Azure Functions Hosting integration](/integrations/cloud/azure/azure-functions/azure-functions-host/) for full reference details. + + + +It's expected that you've installed the required Azure tooling: + + +- [Configure Visual Studio for Azure development with .NET](https://learn.microsoft.com/dotnet/azure/configure-visual-studio) + + +- [Configure Visual Studio Code for Azure development with .NET](https://learn.microsoft.com/dotnet/azure/configure-vs-code) + + +- [Install the Azure Functions Core Tools](https://learn.microsoft.com/azure/azure-functions/functions-run-local?tabs=isolated-process&pivots=programming-language-csharp#install-the-azure-functions-core-tools) + + +## Supported scenarios + +The Aspire Azure Functions integration has several key supported scenarios. + +### Supported triggers + +The following table lists the supported triggers for Azure Functions in the Aspire integration: + +| Trigger | Attribute | Details | +|--|--|--| +| Azure Event Hubs trigger | `EventHubTrigger` | [📦 Aspire.Hosting.Azure.EventHubs](https://www.nuget.org/packages/Aspire.Hosting.Azure.EventHubs) | +| Azure Service Bus trigger | `ServiceBusTrigger` | [📦 Aspire.Hosting.Azure.ServiceBus](https://www.nuget.org/packages/Aspire.Hosting.Azure.ServiceBus) | +| Azure Storage Blobs trigger | `BlobTrigger` | [📦 Aspire.Hosting.Azure.Storage](https://www.nuget.org/packages/Aspire.Hosting.Azure.Storage) | +| Azure Storage Queues trigger | `QueueTrigger` | [📦 Aspire.Hosting.Azure.Storage](https://www.nuget.org/packages/Aspire.Hosting.Azure.Storage) | +| Azure CosmosDB trigger | `CosmosDbTrigger` | [📦 Aspire.Hosting.Azure.CosmosDB](https://www.nuget.org/packages/Aspire.Hosting.Azure.CosmosDB) | +| HTTP trigger | `HttpTrigger` | Supported without any additional resource dependencies. | +| Timer trigger | `TimerTrigger` | Supported without any additional resource dependencies—relies on implicit host storage. | + +> [!IMPORTANT] +> Other Azure Functions triggers and bindings aren't currently supported in the Aspire Azure Functions integration. + +For more information about the Azure Functions integration with Aspire, see [Azure Functions and Aspire integration](https://learn.microsoft.com/azure/azure-functions/dotnet-aspire-integration). + +## Set up hosting integration + +To begin, install the Aspire Azure Functions Hosting integration in your Aspire AppHost project: + + + +Next, in the AppHost project, add an Azure Functions resource: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var functions = builder.AddAzureFunctionsProject("functions") + .WithExternalHttpEndpoints(); + +builder.AddProject() + .WithReference(functions) + .WaitFor(functions); + +// After adding all resources, run the app... + +builder.Build().Run(); +``` + +The preceding code adds an Azure Functions project resource named `functions` and makes it available to other projects in your distributed application. + +## Continue learning + +For more information on how the Azure Functions integration works, see: + + + + diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-functions.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-functions/azure-functions-host.mdx similarity index 67% rename from src/frontend/src/content/docs/integrations/cloud/azure/azure-functions.mdx rename to src/frontend/src/content/docs/integrations/cloud/azure/azure-functions/azure-functions-host.mdx index 169a19ac..9f206a99 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-functions.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-functions/azure-functions-host.mdx @@ -1,6 +1,6 @@ --- -title: Azure Functions integration -description: This article describes the Aspire Azure Functions integration features and capabilities. +title: Azure Functions Hosting integration +description: Learn about the Aspire Azure Functions hosting integration including configuration and deployment. --- import { Aside } from '@astrojs/starlight/components'; @@ -8,7 +8,6 @@ import InstallPackage from '@components/InstallPackage.astro'; import Pivot from '@components/Pivot.astro'; import PivotSelector from '@components/PivotSelector.astro'; import { Image } from 'astro:assets'; -import functionsIcon from '@assets/icons/azure-functionapps-icon.png'; import vsAzureFunctionsOptions from '@assets/integrations/cloud/azure/functions/visual-studio-azure-functions-options.png'; -Azure Functions logo - -[Azure Functions](https://learn.microsoft.com/azure-functions) is a serverless compute service that lets you run event-triggered code without having to explicitly provision or manage infrastructure. The Aspire Azure Functions integration enables you to model Azure Functions projects as part of your distributed application. - -It's expected that you've installed the required Azure tooling: - - -- [Configure Visual Studio for Azure development with .NET](https://learn.microsoft.com/dotnet/azure/configure-visual-studio) - - -- [Configure Visual Studio Code for Azure development with .NET](https://learn.microsoft.com/dotnet/azure/configure-vs-code) - - -- [Install the Azure Functions Core Tools](https://learn.microsoft.com/azure/azure-functions/functions-run-local?tabs=isolated-process&pivots=programming-language-csharp#install-the-azure-functions-core-tools) - +## Deployment -## Supported scenarios - -The Aspire Azure Functions integration has several key supported scenarios. This section outlines the scenarios and provides details related to the implementation of each approach. - -### Supported triggers - -The following table lists the supported triggers for Azure Functions in the Aspire integration: - -| Trigger | Attribute | Details | -|--|--|--| -| Azure Event Hubs trigger | `EventHubTrigger` | [📦 Aspire.Hosting.Azure.EventHubs](https://www.nuget.org/packages/Aspire.Hosting.Azure.EventHubs) | -| Azure Service Bus trigger | `ServiceBusTrigger` | [📦 Aspire.Hosting.Azure.ServiceBus](https://www.nuget.org/packages/Aspire.Hosting.Azure.ServiceBus) | -| Azure Storage Blobs trigger | `BlobTrigger` | [📦 Aspire.Hosting.Azure.Storage](https://www.nuget.org/packages/Aspire.Hosting.Azure.Storage) | -| Azure Storage Queues trigger | `QueueTrigger` | [📦 Aspire.Hosting.Azure.Storage](https://www.nuget.org/packages/Aspire.Hosting.Azure.Storage) | -| Azure CosmosDB trigger | `CosmosDbTrigger` | [📦 Aspire.Hosting.Azure.CosmosDB](https://www.nuget.org/packages/Aspire.Hosting.Azure.CosmosDB) | -| HTTP trigger | `HttpTrigger` | Supported without any additional resource dependencies. | -| Timer trigger | `TimerTrigger` | Supported without any additional resource dependencies—relies on implicit host storage. | - -> [!IMPORTANT] -> Other Azure Functions triggers and bindings aren't currently supported in the Aspire Azure Functions integration. - -### Deployment - -Deployment to Azure Container Apps (ACA) is supported using the SDK container publish function in `Microsoft.Azure.Functions.Worker.Sdk`. When deploying to Azure Container Apps, KEDA-based auto-scaling rules will automatically be configured for your functions. +Deployment to Azure Container Apps (ACA) is supported using the SDK container publish function in \`Microsoft.Azure.Functions.Worker.Sdk\`. When deploying to Azure Container Apps, KEDA-based auto-scaling rules will automatically be configured for your functions. For more information about the Azure Functions integration with Aspire, see [Azure Functions and Aspire integration](https://learn.microsoft.com/azure/azure-functions/dotnet-aspire-integration). -#### Configure external HTTP endpoints +### Configure external HTTP endpoints -To make HTTP triggers publicly accessible, call the `WithExternalHttpEndpoints` API on the `AzureFunctionsProjectResource`. For more information, see [Add Azure Functions resource](#add-azure-functions-resource). +To make HTTP triggers publicly accessible, call the \`WithExternalHttpEndpoints\` API on the \`AzureFunctionsProjectResource\`. For more information, see [Add Azure Functions resource](#add-azure-functions-resource). ## Azure Function project constraints @@ -83,8 +38,8 @@ The Aspire Azure Functions integration has the following project constraints: - You must use a .NET 9 SDK or later. - It currently only supports .NET workers with the [isolated worker model](https://learn.microsoft.com/azure/azure-functions/dotnet-isolated-process-guide). - Requires the following NuGet packages: - - [📦 Microsoft.Azure.Functions.Worker](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker): Use the `FunctionsApplicationBuilder`. - - [📦 Microsoft.Azure.Functions.Worker.Sdk](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Sdk): Adds support for `aspire run` and `aspire deploy`. + - [📦 Microsoft.Azure.Functions.Worker](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker): Use the \`FunctionsApplicationBuilder\`. + - [📦 Microsoft.Azure.Functions.Worker.Sdk](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Sdk): Adds support for \`aspire run\` and \`aspire deploy\`. - [📦 Microsoft.Azure.Functions.Http.AspNetCore](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore): Adds HTTP trigger-supporting APIs. @@ -101,9 +56,7 @@ In Visual Studio, try checking for an update on the Azure Functions tooling. Ope -## Hosting integration - -The Aspire Azure Functions hosting integration models Azure Functions projects as the `AzureFunctionsProjectResource` type. To access this type and APIs for expressing them within your AppHost project, install the [📦 Aspire.Hosting.Azure.Functions](https://www.nuget.org/packages/Aspire.Hosting.Azure.Functions) NuGet package: +The Aspire Azure Functions hosting integration models Azure Functions projects as the \`AzureFunctionsProjectResource\` type. To access this type and APIs for expressing them within your AppHost project, install the [📦 Aspire.Hosting.Azure.Functions](https://www.nuget.org/packages/Aspire.Hosting.Azure.Functions) NuGet package: diff --git a/src/frontend/src/data/integration-docs.json b/src/frontend/src/data/integration-docs.json index 1ab14c85..bc52ae33 100644 --- a/src/frontend/src/data/integration-docs.json +++ b/src/frontend/src/data/integration-docs.json @@ -97,7 +97,7 @@ }, { "match": "Aspire.Hosting.Azure.Functions", - "href": "/integrations/cloud/azure/azure-functions/" + "href": "/integrations/cloud/azure/azure-functions/azure-functions-get-started/" }, { "match": "Aspire.Hosting.Azure.KeyVault", From c097ebecfe0770112eb61ee028460407e3cefe94 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 15:38:39 +0000 Subject: [PATCH 14/30] Restructure Azure Key Vault integration into subfolder --- .../config/sidebar/integrations.topics.ts | 16 +- .../cloud/azure/azure-key-vault.mdx | 413 ------------------ .../azure-key-vault-client.mdx | 242 ++++++++++ .../azure-key-vault-get-started.mdx | 121 +++++ .../azure-key-vault/azure-key-vault-host.mdx | 187 ++++++++ src/frontend/src/data/integration-docs.json | 4 +- 6 files changed, 567 insertions(+), 416 deletions(-) delete mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-key-vault.mdx create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-key-vault/azure-key-vault-client.mdx create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-key-vault/azure-key-vault-get-started.mdx create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-key-vault/azure-key-vault-host.mdx diff --git a/src/frontend/config/sidebar/integrations.topics.ts b/src/frontend/config/sidebar/integrations.topics.ts index 0828359f..eeb1a80a 100644 --- a/src/frontend/config/sidebar/integrations.topics.ts +++ b/src/frontend/config/sidebar/integrations.topics.ts @@ -455,7 +455,21 @@ export const integrationTopics: StarlightSidebarTopicsUserConfig = { }, { label: 'Azure Key Vault', - slug: 'integrations/cloud/azure/azure-key-vault', + collapsed: true, + items: [ + { + label: 'Get started', + slug: 'integrations/cloud/azure/azure-key-vault/azure-key-vault-get-started', + }, + { + label: 'Hosting integration (AppHost)', + slug: 'integrations/cloud/azure/azure-key-vault/azure-key-vault-host', + }, + { + label: 'Client integration', + slug: 'integrations/cloud/azure/azure-key-vault/azure-key-vault-client', + }, + ], }, { label: 'Azure PostgreSQL', diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-key-vault.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-key-vault.mdx deleted file mode 100644 index e109cce7..00000000 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-key-vault.mdx +++ /dev/null @@ -1,413 +0,0 @@ ---- -title: Azure Key Vault -description: Learn how to use the Azure Key Vault integration to securely store and access secrets, keys, and certificates. ---- - -import InstallPackage from '@components/InstallPackage.astro'; -import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; -import { Aside } from '@astrojs/starlight/components'; -import { Image } from 'astro:assets'; -import keyVaultIcon from '@assets/icons/azure-keyvault-icon.png'; - -Azure Key Vault logo - -[Azure Key Vault](https://learn.microsoft.com/azure/key-vault/general/overview) helps safeguard cryptographic keys and secrets used by cloud applications and services. The Aspire Azure Key Vault integration enables you to connect to existing Azure Key Vault instances. - -## Hosting integration - -The Azure Key Vault hosting integration models an Azure Key Vault resource as the `AzureKeyVaultResource` type. To access this type and APIs, add the [📦 Aspire.Hosting.Azure.KeyVault](https://www.nuget.org/packages/Aspire.Hosting.Azure.KeyVault) NuGet package in your AppHost project: - - - -### Add Azure Key Vault resource - -In your AppHost project, call `AddAzureKeyVault` on the builder instance to add an Azure Key Vault resource: - -```csharp title="C# — AppHost.cs" -var builder = DistributedApplication.CreateBuilder(args); - -var keyVault = builder.AddAzureKeyVault("key-vault"); - -builder.AddProject() - .WithReference(keyVault); - -// After adding all resources, run the app... -``` - -The `WithReference` method configures a connection in the `ExampleProject` named `"key-vault"`. - - - - - -### Connect to an existing Azure Key Vault instance - -You might have an existing Azure Key Vault instance that you want to connect to. You can chain a call to annotate that your resource is an existing resource: - -```csharp title="C# — AppHost.cs" -var builder = DistributedApplication.CreateBuilder(args); - -var existingKeyVaultName = builder.AddParameter("existingKeyVaultName"); -var existingKeyVaultResourceGroup = builder.AddParameter("existingKeyVaultResourceGroup"); - -var keyvault = builder.AddAzureKeyVault("key-vault") - .AsExisting(existingKeyVaultName, existingKeyVaultResourceGroup); - -builder.AddProject() - .WithReference(keyvault); -``` - - - -### Provisioning-generated Bicep - -If you're new to [Bicep](https://learn.microsoft.com/azure-resource-manager/bicep/overview), it's a domain-specific language for defining Azure resources. With Aspire, you don't need to write Bicep by-hand, instead the provisioning APIs generate Bicep for you. When you add an Azure Key Vault resource, the following Bicep is generated: - -:::code language="bicep" source="../snippets/azure/AppHost/key-vault/key-vault.bicep"::: - -```bicep title="Generated Bicep — key-vault.bicep" -@description('The location for the resource(s) to be deployed.') -param location string = resourceGroup().location - -resource key_vault 'Microsoft.KeyVault/vaults@2024-11-01' = { - name: take('keyvault-${uniqueString(resourceGroup().id)}', 24) - location: location - properties: { - tenantId: tenant().tenantId - sku: { - family: 'A' - name: 'standard' - } - enableRbacAuthorization: true - } - tags: { - 'aspire-resource-name': 'key-vault' - } -} - -output vaultUri string = key_vault.properties.vaultUri - -output name string = key_vault.name -``` - -The preceding Bicep is a module that provisions an Azure Key Vault resource. Additionally, role assignments are created for the Azure resource in a separate module: - -```bicep title="Generated Bicep — key-vault-roles.bicep" -@description('The location for the resource(s) to be deployed.') -param location string = resourceGroup().location - -param key_vault_outputs_name string - -param principalType string - -param principalId string - -resource key_vault 'Microsoft.KeyVault/vaults@2024-11-01' existing = { - name: key_vault_outputs_name -} - -resource key_vault_KeyVaultSecretsUser 'Microsoft.Authorization/roleAssignments@2022-04-01' = { - name: guid(key_vault.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4633458b-17de-408a-b874-0445c86b69e6')) - properties: { - principalId: principalId - roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4633458b-17de-408a-b874-0445c86b69e6') - principalType: principalType - } - scope: key_vault -} -``` - -The generated Bicep is a starting point and is influenced by changes to the provisioning infrastructure in C#. Customizations to the Bicep file directly will be overwritten, so make changes through the C# provisioning APIs to ensure they are reflected in the generated files. - -### Customize provisioning infrastructure - -All Aspire Azure resources are subclasses of the `AzureProvisioningResource` type. This type enables the customization of the generated Bicep by providing a fluent API to configure the Azure resources using the `ConfigureInfrastructure` API. For example: - -```csharp title="C# — AppHost.cs" -var builder = DistributedApplication.CreateBuilder(args); - -builder.AddAzureKeyVault("key-vault") - .ConfigureInfrastructure(infra => - { - var keyVault = infra.GetProvisionableResources() - .OfType() - .Single(); - - keyVault.Properties.Sku = new() - { - Family = KeyVaultSkuFamily.A, - Name = KeyVaultSkuName.Premium, - }; - keyVault.Properties.EnableRbacAuthorization = true; - keyVault.Tags.Add("ExampleKey", "Example value"); - }); -``` - -The preceding code: - -- Chains a call to the `ConfigureInfrastructure` API: - - The `infra` parameter is an instance of the `AzureResourceInfrastructure` type. - - The provisionable resources are retrieved by calling the `GetProvisionableResources` method. - - The single `KeyVaultService` resource is retrieved. - - The `Sku` property is set to a new `KeyVault.KeyVaultSku` instance. - - The `KeyVaultProperties.EnableRbacAuthorization` property is set to `true`. - - A tag is added to the resource with a key of `ExampleKey` and a value of `Example value`. - -There are many more configuration options available to customize the Key Vault resource. For more information, see [Azure.Provisioning customization](/integrations/cloud/azure/customize-resources/#azureprovisioning-customization). - -### Connection properties - -When you reference Azure Key Vault resources using `WithReference`, the following connection properties are made available to the consuming project: - -| Property Name | Description | -| ------------- | ----------------------------------------------------------------------------- | -| `Uri` | The Key Vault endpoint URI, typically `https://.vault.azure.net/` | - - - -## Client integration - -To get started with the Aspire Azure Key Vault client integration, install the [📦 Aspire.Azure.Security.KeyVault](https://www.nuget.org/packages/Aspire.Azure.Security.KeyVault) NuGet package: - - - -The client integration provides two ways to access secrets from Azure Key Vault: - -- Add secrets to app configuration, using either the `IConfiguration` or the `IOptions` pattern. -- Use a `SecretClient` to retrieve secrets on demand. - -### Add secrets to configuration - -In the `Program.cs` file of your client-consuming project, call the `AddAzureKeyVaultSecrets` extension method on the `IConfiguration` to add the secrets as part of your app's configuration. The method takes a connection name parameter: - -```csharp -builder.Configuration.AddAzureKeyVaultSecrets(connectionName: "key-vault"); -``` - - - - - -You can then retrieve a secret-based configuration value through the normal `IConfiguration` APIs, or by binding to strongly-typed classes with the options pattern. - -#### Retrieve `IConfiguration` instance - -```csharp -public class ExampleService(IConfiguration configuration) -{ - // Use configuration... - private string _secretValue = configuration["SecretKey"]; -} -``` - -#### Retrieve `IOptions` instance - -```csharp -public class ExampleService(IOptions options) -{ - // Use options... - private string _secretValue = options.Value.SecretKey; -} -``` - -Additional `AddAzureKeyVaultSecrets` API parameters are available optionally for the following scenarios: - -- `Action? configureSettings`: To set up some or all the options inline. -- `Action? configureClientOptions`: To set up the `SecretClientOptions` inline. -- `AzureKeyVaultConfigurationOptions? options`: To configure the `AzureKeyVaultConfigurationOptions` inline. - -### Add an Azure Secret client - -Alternatively, you can use the `SecretClient` directly to retrieve the secrets on demand. This requires a slightly different registration API. - -In the `Program.cs` file of your client-consuming project, call the `AddAzureKeyVaultClient` extension on the `IHostApplicationBuilder` instance to register a `SecretClient` for use via the dependency injection container: - -```csharp -builder.AddAzureKeyVaultClient(connectionName: "key-vault"); -``` - -After adding the `SecretClient` to the builder, you can get the `SecretClient` instance using dependency injection: - -```csharp -public class ExampleService(SecretClient client) -{ - // Use client... -} -``` - -### Add keyed Azure Key Vault client - -There might be situations where you want to register multiple `SecretClient` instances with different connection names. To register keyed Azure Key Vault clients, call the `AddKeyedAzureKeyVaultClient` method: - -```csharp -builder.AddKeyedAzureKeyVaultClient(name: "feature-toggles"); -builder.AddKeyedAzureKeyVaultClient(name: "admin-portal"); -``` - -Then you can retrieve the `SecretClient` instances using dependency injection: - -```csharp -public class ExampleService( - [FromKeyedServices("feature-toggles")] SecretClient featureTogglesClient, - [FromKeyedServices("admin-portal")] SecretClient adminPortalClient) -{ - // Use clients... -} -``` - -### Configuration - -The Azure Key Vault integration provides multiple options to configure the `SecretClient`. - -#### Use configuration providers - -The Azure Key Vault integration supports `Microsoft.Extensions.Configuration`. It loads the `AzureSecurityKeyVaultSettings` from `appsettings.json` or other configuration files using `Aspire:Azure:Security:KeyVault` key: - -```json -{ - "Aspire": { - "Azure": { - "Security": { - "KeyVault": { - "DisableHealthChecks": true, - "DisableTracing": false, - "ClientOptions": { - "Diagnostics": { - "ApplicationId": "myapp" - } - } - } - } - } - } -} -``` - -#### Use named configuration - -The Azure Key Vault integration supports named configuration for multiple instances: - -```json -{ - "Aspire": { - "Azure": { - "Security": { - "KeyVault": { - "vault1": { - "VaultUri": "https://myvault1.vault.azure.net/", - "DisableHealthChecks": true, - "ClientOptions": { - "Diagnostics": { - "ApplicationId": "myapp1" - } - } - }, - "vault2": { - "VaultUri": "https://myvault2.vault.azure.net/", - "DisableTracing": true, - "ClientOptions": { - "Diagnostics": { - "ApplicationId": "myapp2" - } - } - } - } - } - } - } -} -``` - -Use the connection names when calling `AddAzureKeyVaultSecrets`: - -```csharp -builder.AddAzureKeyVaultSecrets("vault1"); -builder.AddAzureKeyVaultSecrets("vault2"); -``` - -#### Use inline delegates - -You can also pass the `Action` delegate to set up options inline: - -```csharp -builder.AddAzureKeyVaultSecrets( - connectionName: "key-vault", - configureSettings: settings => settings.VaultUri = new Uri("KEY_VAULT_URI")); -``` - -You can also configure the `SecretClientOptions`: - -```csharp -builder.AddAzureKeyVaultSecrets( - connectionName: "key-vault", - configureClientOptions: options => options.DisableChallengeResourceVerification = true); -``` - -### Configuration options - -The following configurable options are exposed through the `AzureSecurityKeyVaultSettings` class: - -| Name | Description | -| --------------------- | ------------------------------------------------------------------------------------------- | -| `Credential` | The credential used to authenticate to the Azure Key Vault. | -| `DisableHealthChecks` | A boolean value that indicates whether the Key Vault health check is disabled or not. | -| `DisableTracing` | A boolean value that indicates whether the OpenTelemetry tracing is disabled or not. | -| `VaultUri` | A URI to the vault on which the client operates. Appears as "DNS Name" in the Azure portal. | - -### Client integration health checks - -By default, Aspire integrations enable health checks for all services. The Azure Key Vault integration includes the following health checks: - -- Adds the `AzureKeyVaultSecretsHealthCheck` health check, which attempts to connect to and query the Key Vault -- Integrates with the `/health` HTTP endpoint, which specifies all registered health checks must pass for app to be considered ready to accept traffic - -### Observability and telemetry - -#### Logging - -The Azure Key Vault integration uses the following log categories: - -- `Azure.Core` -- `Azure.Identity` - -#### Tracing - -The Azure Key Vault integration emits the following tracing activities using OpenTelemetry: - -- `Azure.Security.KeyVault.Secrets.SecretClient` - -#### Metrics - -The Azure Key Vault integration currently doesn't support metrics by default due to limitations with the Azure SDK. diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-key-vault/azure-key-vault-client.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-key-vault/azure-key-vault-client.mdx new file mode 100644 index 00000000..2191ca82 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-key-vault/azure-key-vault-client.mdx @@ -0,0 +1,242 @@ +--- +title: Azure Key Vault client integration +description: Learn how to use the Aspire Azure Key Vault client integration to connect to Azure Key Vault services. +next: false +--- + +import { Aside } from '@astrojs/starlight/components'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; +import { Image } from 'astro:assets'; +import keyVaultIcon from '@assets/icons/azure-keyvault-icon.png'; + +Azure Key Vault logo + +The Aspire Azure Key Vault client integration is used to connect to an Azure Key Vault service. To get started with the Aspire Azure Key Vault client integration, install the [📦 Aspire.Azure.Security.KeyVault](https://www.nuget.org/packages/Aspire.Azure.Security.KeyVault) NuGet package: + + + +For an introduction to working with the Azure Key Vault client integration, see [Get started with the Azure Key Vault integration](/integrations/cloud/azure/azure-key-vault/azure-key-vault-get-started/). + +The client integration provides two ways to access secrets from Azure Key Vault: + +- Add secrets to app configuration, using either the `IConfiguration` or the `IOptions` pattern. +- Use a `SecretClient` to retrieve secrets on demand. + +## Add secrets to configuration + +In the `Program.cs` file of your client-consuming project, call the `AddAzureKeyVaultSecrets` extension method on the `IConfiguration` to add the secrets as part of your app's configuration. The method takes a connection name parameter: + +```csharp +builder.Configuration.AddAzureKeyVaultSecrets(connectionName: "key-vault"); +``` + + + + + +You can then retrieve a secret-based configuration value through the normal `IConfiguration` APIs, or by binding to strongly-typed classes with the options pattern. + +### Retrieve `IConfiguration` instance + +```csharp +public class ExampleService(IConfiguration configuration) +{ + // Use configuration... + private string _secretValue = configuration["SecretKey"]; +} +``` + +### Retrieve `IOptions` instance + +```csharp +public class ExampleService(IOptions options) +{ + // Use options... + private string _secretValue = options.Value.SecretKey; +} +``` + +Additional `AddAzureKeyVaultSecrets` API parameters are available optionally for the following scenarios: + +- `Action? configureSettings`: To set up some or all the options inline. +- `Action? configureClientOptions`: To set up the `SecretClientOptions` inline. +- `AzureKeyVaultConfigurationOptions? options`: To configure the `AzureKeyVaultConfigurationOptions` inline. + +## Add an Azure Secret client + +Alternatively, you can use the `SecretClient` directly to retrieve the secrets on demand. This requires a slightly different registration API. + +In the `Program.cs` file of your client-consuming project, call the `AddAzureKeyVaultClient` extension on the `IHostApplicationBuilder` instance to register a `SecretClient` for use via the dependency injection container: + +```csharp +builder.AddAzureKeyVaultClient(connectionName: "key-vault"); +``` + +After adding the `SecretClient` to the builder, you can get the `SecretClient` instance using dependency injection: + +```csharp +public class ExampleService(SecretClient client) +{ + // Use client... +} +``` + +## Add keyed Azure Key Vault client + +There might be situations where you want to register multiple `SecretClient` instances with different connection names. To register keyed Azure Key Vault clients, call the `AddKeyedAzureKeyVaultClient` method: + +```csharp +builder.AddKeyedAzureKeyVaultClient(name: "feature-toggles"); +builder.AddKeyedAzureKeyVaultClient(name: "admin-portal"); +``` + +Then you can retrieve the `SecretClient` instances using dependency injection: + +```csharp +public class ExampleService( + [FromKeyedServices("feature-toggles")] SecretClient featureTogglesClient, + [FromKeyedServices("admin-portal")] SecretClient adminPortalClient) +{ + // Use clients... +} +``` + +## Configuration + +The Azure Key Vault integration provides multiple options to configure the `SecretClient`. + +### Use configuration providers + +The Azure Key Vault integration supports `Microsoft.Extensions.Configuration`. It loads the `AzureSecurityKeyVaultSettings` from `appsettings.json` or other configuration files using `Aspire:Azure:Security:KeyVault` key: + +```json +{ + "Aspire": { + "Azure": { + "Security": { + "KeyVault": { + "DisableHealthChecks": true, + "DisableTracing": false, + "ClientOptions": { + "Diagnostics": { + "ApplicationId": "myapp" + } + } + } + } + } + } +} +``` + +### Use named configuration + +The Azure Key Vault integration supports named configuration for multiple instances: + +```json +{ + "Aspire": { + "Azure": { + "Security": { + "KeyVault": { + "vault1": { + "VaultUri": "https://myvault1.vault.azure.net/", + "DisableHealthChecks": true, + "ClientOptions": { + "Diagnostics": { + "ApplicationId": "myapp1" + } + } + }, + "vault2": { + "VaultUri": "https://myvault2.vault.azure.net/", + "DisableTracing": true, + "ClientOptions": { + "Diagnostics": { + "ApplicationId": "myapp2" + } + } + } + } + } + } + } +} +``` + +Use the connection names when calling `AddAzureKeyVaultSecrets`: + +```csharp +builder.AddAzureKeyVaultSecrets("vault1"); +builder.AddAzureKeyVaultSecrets("vault2"); +``` + +### Use inline delegates + +You can also pass the `Action` delegate to set up options inline: + +```csharp +builder.AddAzureKeyVaultSecrets( + connectionName: "key-vault", + configureSettings: settings => settings.VaultUri = new Uri("KEY_VAULT_URI")); +``` + +You can also configure the `SecretClientOptions`: + +```csharp +builder.AddAzureKeyVaultSecrets( + connectionName: "key-vault", + configureClientOptions: options => options.DisableChallengeResourceVerification = true); +``` + +## Configuration options + +The following configurable options are exposed through the `AzureSecurityKeyVaultSettings` class: + +| Name | Description | +| --------------------- | ------------------------------------------------------------------------------------------- | +| `Credential` | The credential used to authenticate to the Azure Key Vault. | +| `DisableHealthChecks` | A boolean value that indicates whether the Key Vault health check is disabled or not. | +| `DisableTracing` | A boolean value that indicates whether the OpenTelemetry tracing is disabled or not. | +| `VaultUri` | A URI to the vault on which the client operates. Appears as "DNS Name" in the Azure portal. | + +## Client integration health checks + +By default, Aspire integrations enable health checks for all services. The Azure Key Vault integration includes the following health checks: + +- Adds the `AzureKeyVaultSecretsHealthCheck` health check, which attempts to connect to and query the Key Vault +- Integrates with the `/health` HTTP endpoint, which specifies all registered health checks must pass for app to be considered ready to accept traffic + +## Observability and telemetry + +### Logging + +The Azure Key Vault integration uses the following log categories: + +- `Azure.Core` +- `Azure.Identity` + +### Tracing + +The Azure Key Vault integration emits the following tracing activities using OpenTelemetry: + +- `Azure.Security.KeyVault.Secrets.SecretClient` + +### Metrics + +The Azure Key Vault integration currently doesn't support metrics by default due to limitations with the Azure SDK. diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-key-vault/azure-key-vault-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-key-vault/azure-key-vault-get-started.mdx new file mode 100644 index 00000000..2efd065f --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-key-vault/azure-key-vault-get-started.mdx @@ -0,0 +1,121 @@ +--- +title: Get started with the Azure Key Vault integration +description: Learn how to set up the Aspire Azure Key Vault Hosting and Client integrations simply. +prev: false +--- + +import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components'; +import InstallPackage from '@components/InstallPackage.astro'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; +import { Image } from 'astro:assets'; +import keyVaultIcon from '@assets/icons/azure-keyvault-icon.png'; + +Azure Key Vault logo + +[Azure Key Vault](https://learn.microsoft.com/azure/key-vault/general/overview) helps safeguard cryptographic keys and secrets used by cloud applications and services. The Aspire Azure Key Vault integration enables you to connect to existing Azure Key Vault instances. + +In this introduction, you'll see how to install and use the Aspire Azure Key Vault integrations in a simple configuration. If you already have this knowledge, see [Azure Key Vault Hosting integration](/integrations/cloud/azure/azure-key-vault/azure-key-vault-host/) for full reference details. + + + +## Set up hosting integration + +To begin, install the Aspire Azure Key Vault Hosting integration in your Aspire AppHost project. This integration allows you to create and manage Azure Key Vault resources from your Aspire hosting projects: + + + +Next, in the AppHost project, create an Azure Key Vault resource and pass it to the consuming client projects: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var keyVault = builder.AddAzureKeyVault("key-vault"); + +builder.AddProject() + .WithReference(keyVault); + +// After adding all resources, run the app... + +builder.Build().Run(); +``` + +The preceding code adds an Azure Key Vault resource named `key-vault` to the AppHost project. The `WithReference` method passes the connection information to the `ExampleProject` project. + + + + + +## Set up client integration + +To use Azure Key Vault from your client applications, install the Aspire Azure Key Vault client integration in your client project: + + + +The client integration provides two ways to access secrets from Azure Key Vault: + +- Add secrets to app configuration, using either the `IConfiguration` or the `IOptions` pattern. +- Use a `SecretClient` to retrieve secrets on demand. + +### Add secrets to configuration + +In the `Program.cs` file of your client-consuming project, call the `AddAzureKeyVaultSecrets` extension method on the `IConfiguration` to add the secrets as part of your app's configuration: + +```csharp +builder.Configuration.AddAzureKeyVaultSecrets(connectionName: "key-vault"); +``` + +> [!TIP] +> The `connectionName` parameter must match the name used when adding the Azure Key Vault resource in the AppHost project. + +You can then retrieve a secret-based configuration value through the normal `IConfiguration` APIs, or by binding to strongly-typed classes with the options pattern. + +### Add an Azure Secret client + +Alternatively, you can use the `SecretClient` directly to retrieve the secrets on demand: + +```csharp +builder.AddAzureKeyVaultClient(connectionName: "key-vault"); +``` + +After adding the `SecretClient` to the builder, you can get the `SecretClient` instance using dependency injection: + +```csharp +public class ExampleService(SecretClient client) +{ + // Use client... +} +``` + +For full details on using the client integration, see [Azure Key Vault Client integration](/integrations/cloud/azure/azure-key-vault/azure-key-vault-client/). + +## Next steps + + + + + diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-key-vault/azure-key-vault-host.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-key-vault/azure-key-vault-host.mdx new file mode 100644 index 00000000..ef0f2010 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-key-vault/azure-key-vault-host.mdx @@ -0,0 +1,187 @@ +--- +title: Azure Key Vault hosting integration +description: Learn how to use the Aspire Azure Key Vault hosting integration to create Azure Key Vault resources. +--- + +import { Aside } from '@astrojs/starlight/components'; +import InstallPackage from '@components/InstallPackage.astro'; +import { Image } from 'astro:assets'; +import keyVaultIcon from '@assets/icons/azure-keyvault-icon.png'; + +Azure Key Vault logo + +The Aspire Azure Key Vault hosting integration models an Azure Key Vault resource as the `AzureKeyVaultResource` type. To access this type and APIs for expressing them within your AppHost project, install the [📦 Aspire.Hosting.Azure.KeyVault](https://www.nuget.org/packages/Aspire.Hosting.Azure.KeyVault) NuGet package: + + + +For an introduction to working with the Azure Key Vault hosting integration, see [Get started with the Azure Key Vault integration](/integrations/cloud/azure/azure-key-vault/azure-key-vault-get-started/). + +## Add Azure Key Vault resource + +To add an Azure Key Vault resource to your AppHost project, call the `AddAzureKeyVault` method providing a name: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var keyVault = builder.AddAzureKeyVault("key-vault"); + +builder.AddProject() + .WithReference(keyVault); + +// After adding all resources, run the app... +``` + +The `WithReference` method configures a connection in the `ExampleProject` named `"key-vault"`. + + + + + +## Connect to an existing Azure Key Vault instance + +You might have an existing Azure Key Vault instance that you want to connect to. You can chain a call to annotate that your resource is an existing resource: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var existingKeyVaultName = builder.AddParameter("existingKeyVaultName"); +var existingKeyVaultResourceGroup = builder.AddParameter("existingKeyVaultResourceGroup"); + +var keyvault = builder.AddAzureKeyVault("key-vault") + .AsExisting(existingKeyVaultName, existingKeyVaultResourceGroup); + +builder.AddProject() + .WithReference(keyvault); +``` + + + +## Provisioning-generated Bicep + +If you're new to [Bicep](https://learn.microsoft.com/azure-resource-manager/bicep/overview), it's a domain-specific language for defining Azure resources. With Aspire, you don't need to write Bicep by-hand, instead the provisioning APIs generate Bicep for you. When you add an Azure Key Vault resource, the following Bicep is generated: + +:::code language="bicep" source="../snippets/azure/AppHost/key-vault/key-vault.bicep"::: + +```bicep title="Generated Bicep — key-vault.bicep" +@description('The location for the resource(s) to be deployed.') +param location string = resourceGroup().location + +resource key_vault 'Microsoft.KeyVault/vaults@2024-11-01' = { + name: take('keyvault-${uniqueString(resourceGroup().id)}', 24) + location: location + properties: { + tenantId: tenant().tenantId + sku: { + family: 'A' + name: 'standard' + } + enableRbacAuthorization: true + } + tags: { + 'aspire-resource-name': 'key-vault' + } +} + +output vaultUri string = key_vault.properties.vaultUri + +output name string = key_vault.name +``` + +The preceding Bicep is a module that provisions an Azure Key Vault resource. Additionally, role assignments are created for the Azure resource in a separate module: + +```bicep title="Generated Bicep — key-vault-roles.bicep" +@description('The location for the resource(s) to be deployed.') +param location string = resourceGroup().location + +param key_vault_outputs_name string + +param principalType string + +param principalId string + +resource key_vault 'Microsoft.KeyVault/vaults@2024-11-01' existing = { + name: key_vault_outputs_name +} + +resource key_vault_KeyVaultSecretsUser 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(key_vault.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4633458b-17de-408a-b874-0445c86b69e6')) + properties: { + principalId: principalId + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4633458b-17de-408a-b874-0445c86b69e6') + principalType: principalType + } + scope: key_vault +} +``` + +The generated Bicep is a starting point and is influenced by changes to the provisioning infrastructure in C#. Customizations to the Bicep file directly will be overwritten, so make changes through the C# provisioning APIs to ensure they are reflected in the generated files. + +## Customize provisioning infrastructure + +All Aspire Azure resources are subclasses of the `AzureProvisioningResource` type. This type enables the customization of the generated Bicep by providing a fluent API to configure the Azure resources using the `ConfigureInfrastructure` API. For example: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +builder.AddAzureKeyVault("key-vault") + .ConfigureInfrastructure(infra => + { + var keyVault = infra.GetProvisionableResources() + .OfType() + .Single(); + + keyVault.Properties.Sku = new() + { + Family = KeyVaultSkuFamily.A, + Name = KeyVaultSkuName.Premium, + }; + keyVault.Properties.EnableRbacAuthorization = true; + keyVault.Tags.Add("ExampleKey", "Example value"); + }); +``` + +The preceding code: + +- Chains a call to the `ConfigureInfrastructure` API: + - The `infra` parameter is an instance of the `AzureResourceInfrastructure` type. + - The provisionable resources are retrieved by calling the `GetProvisionableResources` method. + - The single `KeyVaultService` resource is retrieved. + - The `Sku` property is set to a new `KeyVault.KeyVaultSku` instance. + - The `KeyVaultProperties.EnableRbacAuthorization` property is set to `true`. + - A tag is added to the resource with a key of `ExampleKey` and a value of `Example value`. + +There are many more configuration options available to customize the Key Vault resource. For more information, see [Azure.Provisioning customization](/integrations/cloud/azure/customize-resources/#azureprovisioning-customization). + +## Connection properties + +When you reference Azure Key Vault resources using `WithReference`, the following connection properties are made available to the consuming project: + +| Property Name | Description | +| ------------- | ----------------------------------------------------------------------------- | +| `Uri` | The Key Vault endpoint URI, typically `https://.vault.azure.net/` | + + diff --git a/src/frontend/src/data/integration-docs.json b/src/frontend/src/data/integration-docs.json index bc52ae33..c6c92f88 100644 --- a/src/frontend/src/data/integration-docs.json +++ b/src/frontend/src/data/integration-docs.json @@ -37,7 +37,7 @@ }, { "match": "Aspire.Azure.Security.KeyVault", - "href": "/integrations/cloud/azure/azure-key-vault/" + "href": "/integrations/cloud/azure/azure-key-vault/azure-key-vault-get-started/" }, { "match": "Aspire.Azure.Storage.Blobs", @@ -101,7 +101,7 @@ }, { "match": "Aspire.Hosting.Azure.KeyVault", - "href": "/integrations/cloud/azure/azure-key-vault/" + "href": "/integrations/cloud/azure/azure-key-vault/azure-key-vault-get-started/" }, { "match": "Aspire.Hosting.Azure.Kusto", From a13595225a843d581eae64af0ae380172bf54ff4 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 15:40:54 +0000 Subject: [PATCH 15/30] Restructure Azure OpenAI integration into subfolder --- .../config/sidebar/integrations.topics.ts | 16 +- .../integrations/cloud/azure/azure-openai.mdx | 486 ------------------ .../azure-openai/azure-openai-client.mdx | 271 ++++++++++ .../azure-openai/azure-openai-get-started.mdx | 110 ++++ .../azure/azure-openai/azure-openai-host.mdx | 231 +++++++++ src/frontend/src/data/integration-docs.json | 4 +- 6 files changed, 629 insertions(+), 489 deletions(-) delete mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-openai.mdx create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-openai/azure-openai-client.mdx create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-openai/azure-openai-get-started.mdx create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-openai/azure-openai-host.mdx diff --git a/src/frontend/config/sidebar/integrations.topics.ts b/src/frontend/config/sidebar/integrations.topics.ts index eeb1a80a..067894e0 100644 --- a/src/frontend/config/sidebar/integrations.topics.ts +++ b/src/frontend/config/sidebar/integrations.topics.ts @@ -323,7 +323,21 @@ export const integrationTopics: StarlightSidebarTopicsUserConfig = { }, { label: 'Azure OpenAI', - slug: 'integrations/cloud/azure/azure-openai', + collapsed: true, + items: [ + { + label: 'Get started', + slug: 'integrations/cloud/azure/azure-openai/azure-openai-get-started', + }, + { + label: 'Hosting integration (AppHost)', + slug: 'integrations/cloud/azure/azure-openai/azure-openai-host', + }, + { + label: 'Client integration', + slug: 'integrations/cloud/azure/azure-openai/azure-openai-client', + }, + ], }, ], }, diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-openai.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-openai.mdx deleted file mode 100644 index bc74aac9..00000000 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-openai.mdx +++ /dev/null @@ -1,486 +0,0 @@ ---- -title: Azure OpenAI integration -description: This article describes the Aspire Azure OpenAI integration features and capabilities. ---- - -import { Aside, Badge } from '@astrojs/starlight/components'; -import InstallPackage from '@components/InstallPackage.astro'; -import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; -import { Image } from 'astro:assets'; -import openaiIcon from '@assets/icons/azure-openai-icon.png'; - -Azure OpenAI logo - -[Azure OpenAI Service](https://azure.microsoft.com/products/ai-services/openai-service) provides access to OpenAI's powerful language and embedding models with the security and enterprise promise of Azure. The Aspire Azure OpenAI integration enables you to connect to Azure OpenAI services from your applications. - -## Hosting integration - -The Aspire Azure OpenAI hosting integration models the Azure OpenAI service as the `AzureOpenAIResource` type. To access this type and APIs for expressing them within your AppHost project, install the [📦 Aspire.Hosting.Azure.CognitiveServices](https://www.nuget.org/packages/Aspire.Hosting.Azure.CognitiveServices) NuGet package: - - - -### Add an Azure OpenAI resource - -To add an Azure OpenAI resource to your AppHost project, call the `AddAzureOpenAI` method providing a name: - -```csharp title="C# — AppHost.cs" -var builder = DistributedApplication.CreateBuilder(args); - -var openai = builder.AddAzureOpenAI("openai"); - -builder.AddProject() - .WithReference(openai); - -// After adding all resources, run the app... -``` - -The preceding code adds an Azure OpenAI resource named `openai` to the AppHost project. The `WithReference` method passes the connection information to the `ExampleProject` project. - - - -### Add an Azure OpenAI deployment resource - -To add an Azure OpenAI deployment resource, call the `AddDeployment` method: - -```csharp -var builder = DistributedApplication.CreateBuilder(args); - -var openai = builder.AddAzureOpenAI("openai"); - -openai.AddDeployment( - name: "preview", - modelName: "gpt-4.5-preview", - modelVersion: "2025-02-27"); - -builder.AddProject() - .WithReference(openai) - .WaitFor(openai); - -// After adding all resources, run the app... -``` - -The preceding code: - -- Adds an Azure OpenAI resource named `openai`. -- Adds an Azure OpenAI deployment resource named `preview` with a model name of `gpt-4.5-preview`. The model name must correspond to an [available model](https://learn.microsoft.com/azure/ai-services/openai/concepts/models) in the Azure OpenAI service. - -### Connect to an existing Azure OpenAI service - -You might have an existing Azure OpenAI service that you want to connect to. You can chain a call to annotate that your `AzureOpenAIResource` is an existing resource: - -```csharp -var builder = DistributedApplication.CreateBuilder(args); - -var existingOpenAIName = builder.AddParameter("existingOpenAIName"); -var existingOpenAIResourceGroup = builder.AddParameter("existingOpenAIResourceGroup"); - -var openai = builder.AddAzureOpenAI("openai") - .AsExisting(existingOpenAIName, existingOpenAIResourceGroup); - -builder.AddProject() - .WithReference(openai); - -// After adding all resources, run the app... -``` - -For more information on treating Azure OpenAI resources as existing resources, see [Use existing Azure resources](/integrations/cloud/azure/overview/#use-existing-azure-resources). - -> [!NOTE] -> Alternatively, instead of representing an Azure OpenAI resource, you can add a connection string to the AppHost. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](/integrations/cloud/azure/overview/#add-existing-azure-resources-with-connection-strings). - -### Provisioning-generated Bicep - -If you're new to [Bicep](https://learn.microsoft.com/azure/azure-resource-manager/bicep/overview), it's a domain-specific language for defining Azure resources. With Aspire, you don't need to write Bicep by-hand, instead the provisioning APIs generate Bicep for you. When you publish your app, the generated Bicep provisions an Azure OpenAI resource with standard defaults. - -```bicep title="Bicep — openai.bicep" -@description('The location for the resource(s) to be deployed.') -param location string = resourceGroup().location - -resource openai 'Microsoft.CognitiveServices/accounts@2024-10-01' = { - name: take('openai-${uniqueString(resourceGroup().id)}', 64) - location: location - kind: 'OpenAI' - properties: { - customSubDomainName: toLower(take(concat('openai', uniqueString(resourceGroup().id)), 24)) - publicNetworkAccess: 'Enabled' - disableLocalAuth: true - } - sku: { - name: 'S0' - } - tags: { - 'aspire-resource-name': 'openai' - } -} - -resource preview 'Microsoft.CognitiveServices/accounts/deployments@2024-10-01' = { - name: 'preview' - properties: { - model: { - format: 'OpenAI' - name: 'gpt-4.5-preview' - version: '2025-02-27' - } - } - sku: { - name: 'Standard' - capacity: 8 - } - parent: openai -} - -output connectionString string = 'Endpoint=${openai.properties.endpoint}' - -output name string = openai.name -``` - -The preceding Bicep is a module that provisions an Azure Cognitive Services resource. Additionally, role assignments are created for the Azure resource in a separate module: - -```bicep title="Bicep — openai-roles.bicep" -@description('The location for the resource(s) to be deployed.') -param location string = resourceGroup().location - -param openai_outputs_name string - -param principalType string - -param principalId string - -resource openai 'Microsoft.CognitiveServices/accounts@2024-10-01' existing = { - name: openai_outputs_name -} - -resource openai_CognitiveServicesOpenAIUser 'Microsoft.Authorization/roleAssignments@2022-04-01' = { - name: guid(openai.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '5e0bd9bd-7b93-4f28-af87-19fc36ad61bd')) - properties: { - principalId: principalId - roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '5e0bd9bd-7b93-4f28-af87-19fc36ad61bd') - principalType: principalType - } - scope: openai -} -``` - -The generated Bicep is a starting point and is influenced by changes to the provisioning infrastructure in C#. Customizations to the Bicep file directly will be overwritten, so make changes through the C# provisioning APIs to ensure they are reflected in the generated files. - -#### Customize provisioning infrastructure - -All Aspire Azure resources are subclasses of the `AzureProvisioningResource` type. This enables customization of the generated Bicep by providing a fluent API to configure the Azure resources—using the `ConfigureInfrastructure` API: - -```csharp title="C# — AppHost.cs" -var builder = DistributedApplication.CreateBuilder(args); - -builder.AddAzureOpenAI("openai") - .ConfigureInfrastructure(infra => - { - var resources = infra.GetProvisionableResources(); - var account = resources.OfType().Single(); - - account.Sku = new CognitiveServicesSku - { - Tier = CognitiveServicesSkuTier.Enterprise, - Name = "E0" - }; - account.Tags.Add("ExampleKey", "Example value"); - }); -``` - -The preceding code: - -- Chains a call to the `ConfigureInfrastructure` API: - - The `infra` parameter is an instance of the `AzureResourceInfrastructure type. - - The provisionable resources are retrieved by calling the `GetProvisionableResources` method. - - The single `CognitiveServicesAccount` resource is retrieved. - - The `CognitiveServicesAccount` property is assigned to a new instance of `CognitiveServices.CognitiveServicesSku` with an `E0` name and CognitiveServicesSkuTier.Enterprise` tier. - - A tag is added to the Cognitive Services resource with a key of `ExampleKey` and a value of `Example value`. - -### Connection properties - -When you reference Azure OpenAI resources using `WithReference`, the following connection properties are made available to the consuming project: - -#### Azure OpenAI resource - -The Azure OpenAI resource exposes the following connection properties: - -| Property Name | Description | -| ------------- | ----------------------------------------------------------------------------------------------------- | -| `Uri` | The endpoint URI for the Azure OpenAI resource, typically `https://.openai.azure.com/` | - -#### Azure OpenAI deployment - -The Azure OpenAI deployment resource inherits all properties from its parent Azure OpenAI resource and adds: - -| Property Name | Description | -| ------------- | ----------------------------------------------------- | -| `ModelName` | The name of the Azure OpenAI deployment, e.g., `chat` | - - - -## Client integration - -The Aspire Azure OpenAI client integration is used to connect to an Azure OpenAI service. To get started with the Aspire Azure OpenAI client integration, install the [📦 Aspire.Azure.AI.OpenAI](https://www.nuget.org/packages/Aspire.Azure.AI.OpenAI) NuGet package. - - - -### Add Azure OpenAI client - -In the `Program.cs` file of your client-consuming project, call the `AddAzureOpenAIClient` extension method to register an `AzureOpenAIClient` for use via the dependency injection container. The method takes a connection name parameter: - -```csharp -builder.AddAzureOpenAIClient(connectionName: "openai"); -``` - - - -After adding the `AzureOpenAIClient`, you can retrieve the client instance using dependency injection: - -```csharp -public class ExampleService(AzureOpenAIClient client) -{ - // Use client... -} -``` - -### Add Azure OpenAI client with registered `IChatClient` - -If you're interested in using the `IChatClient` interface, with the OpenAI client, simply chain either of the following APIs to the `AddAzureOpenAIClient` method: - -- `AddChatClient`: Registers a singleton `IChatClient` in the services provided by the `AspireOpenAIClientBuilder`. -- `AddKeyedChatClient`: Registers a keyed singleton `IChatClient` in the services provided by the `AspireOpenAIClientBuilder`. - -For example, consider the following C# code that adds an `IChatClient` to the DI container: - -```csharp -builder.AddAzureOpenAIClient(connectionName: "openai") - .AddChatClient("deploymentName"); -``` - -Similarly, you can add a keyed `IChatClient` with the following C# code: - -```csharp -builder.AddAzureOpenAIClient(connectionName: "openai") - .AddKeyedChatClient("serviceKey", "deploymentName"); -``` - -After adding the `IChatClient`, you can retrieve the client instance using dependency injection: - -```csharp -public class ExampleService(IChatClient chatClient) -{ - public async Task GetResponseAsync(string userMessage) - { - var response = await chatClient.CompleteAsync(userMessage); - return response.Message.Text ?? string.Empty; - } -} -``` - -For more information on `IChatClient` and `Microsoft.Extensions.AI`, see [Unified AI Building Blocks for .NET](https://learn.microsoft.com/dotnet/core/extensions/artificial-intelligence). - -### Configure Azure OpenAI client settings - -The Aspire Azure OpenAI library provides a set of settings to configure the Azure OpenAI client. The `AddAzureOpenAIClient` method exposes an optional `configureSettings` parameter of type `Action?`. To configure settings inline, consider the following example: - -```csharp -builder.AddAzureOpenAIClient( - connectionName: "openai", - configureSettings: settings => - { - settings.DisableTracing = true; - - var uriString = builder.Configuration["AZURE_OPENAI_ENDPOINT"] - ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set."); - - settings.Endpoint = new Uri(uriString); - }); -``` - -The preceding code sets the `AzureOpenAISettings.DisableTracing` property to `true`, and sets the `AzureOpenAISettings.Endpoint` property to the Azure OpenAI endpoint. - -### Configure Azure OpenAI client builder options - -To configure the `AzureOpenAIClientOptions` for the client, you can use the `AddAzureOpenAIClient` method. This method takes an optional `configureClientBuilder` parameter of type `Action>?`. Consider the following example: - -```csharp -builder.AddAzureOpenAIClient( - connectionName: "openai", - configureClientBuilder: clientBuilder => - { - clientBuilder.ConfigureOptions(options => - { - options.UserAgentApplicationId = "CLIENT_ID"; - }); - }); -``` - -The client builder is an instance of the `IAzureClientBuilder` type, which provides a fluent API to configure the client options. The preceding code sets the `AzureOpenAIClientOptions.UserAgentApplicationId` property to `CLIENT_ID`. - -### Add Azure OpenAI client from configuration - -Additionally, the package provides the `AddOpenAIClientFromConfiguration` extension method to register an `OpenAIClient` or `AzureOpenAIClient` instance based on the provided connection string. This method follows these rules: - -- If the `Endpoint` attribute is empty or missing, an `OpenAIClient` instance is registered using the provided key, for example, `Key={key};`. -- If the `IsAzure` attribute is `true`, an `AzureOpenAIClient` is registered; otherwise, an `OpenAIClient` is registered, for example, `Endpoint={azure_endpoint};Key={key};IsAzure=true` registers an `AzureOpenAIClient`, while `Endpoint=https://localhost:18889;Key={key}` registers an `OpenAIClient`. -- If the `Endpoint` attribute contains `".azure."`, an `AzureOpenAIClient` is registered; otherwise, an `OpenAIClient` is registered, for example, `Endpoint=https://{account}.azure.com;Key={key};`. - -Consider the following example: - -```csharp -builder.AddOpenAIClientFromConfiguration("openai"); -``` - -> [!TIP] -> A valid connection string must contain at least an `Endpoint` or a `Key`. - -Consider the following example connection strings and whether they register an `OpenAIClient` or `AzureOpenAIClient`: - -| Example connection string | Registered client type | -| ----------------------------------------------------------------------------------- | ---------------------- | -| `Endpoint=https://{account_name}.openai.azure.com/;Key={account_key}` | `AzureOpenAIClient` | -| `Endpoint=https://{account_name}.openai.azure.com/;Key={account_key};IsAzure=false` | `OpenAIClient` | -| `Endpoint=https://{account_name}.openai.azure.com/;Key={account_key};IsAzure=true` | `AzureOpenAIClient` | -| `Endpoint=https://localhost:18889;Key={account_key}` | `OpenAIClient` | - -### Add keyed Azure OpenAI clients - -There might be situations where you want to register multiple `OpenAIClient` instances with different connection names. To register keyed Azure OpenAI clients, call the `AddKeyedAzureOpenAIClient` method: - -```csharp -builder.AddKeyedAzureOpenAIClient(name: "chat"); -builder.AddKeyedAzureOpenAIClient(name: "code"); -``` - -> [!IMPORTANT] -> When using keyed services, ensure that your Azure OpenAI resource configures two named connections, one for `chat` and one for `code`. - -Then you can retrieve the client instances using dependency injection. For example, to retrieve the clients from a service: - -```csharp -public class ExampleService( - [KeyedService("chat")] OpenAIClient chatClient, - [KeyedService("code")] OpenAIClient codeClient) -{ - // Use clients... -} -``` - -For more information, see [Keyed services in .NET](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection#keyed-services). - -### Add keyed Azure OpenAI clients from configuration - -The same functionality and rules exist for keyed Azure OpenAI clients as for the nonkeyed clients. You can use the `AddKeyedOpenAIClientFromConfiguration` extension method to register an `OpenAIClient` or `AzureOpenAIClient` instance based on the provided connection string. - -Consider the following example: - -```csharp -builder.AddKeyedOpenAIClientFromConfiguration("openai"); -``` - -This method follows the same rules as detailed in the [Add Azure OpenAI client from configuration](#add-azure-openai-client-from-configuration). - -### Configuration - -The Aspire Azure OpenAI library provides multiple options to configure the Azure OpenAI connection based on the requirements and conventions of your project. Either an `Endpoint` or a `ConnectionString` must be supplied. - -#### Use a connection string - -When using a connection string from the `ConnectionStrings` configuration section, you can provide the name of the connection string when calling `AddAzureOpenAIClient`: - -```csharp -builder.AddAzureOpenAIClient(connectionName: "openai"); -``` - -The connection information is retrieved from the `ConnectionStrings` configuration section. Two connection formats are supported: - -- **Service endpoint (recommended)**: Uses the service endpoint with `DefaultAzureCredential`. - - ```json - { - "ConnectionStrings": { - "openai": "https://{account_name}.openai.azure.com/" - } - } - ``` - -- **Connection string**: Includes an API key. - - ```json - { - "ConnectionStrings": { - "openai": "Endpoint=https://{account_name}.openai.azure.com/;Key={api_key}" - } - } - ``` - -#### Use configuration providers - -The library supports `Microsoft.Extensions.Configuration`. It loads settings from configuration using the `Aspire:Azure:AI:OpenAI` key: - -```json -{ - "Aspire": { - "Azure": { - "AI": { - "OpenAI": { - "DisableTracing": false - } - } - } - } -} -``` - -#### Use inline delegates - -You can configure settings inline: - -```csharp -builder.AddAzureOpenAIClient( - "openai", - settings => settings.DisableTracing = true); -``` - -### Observability and telemetry - -Aspire integrations automatically set up Logging, Tracing, and Metrics configurations. - -#### Logging - -The Aspire Azure OpenAI integration uses the following log categories: - -- `Azure` -- `Azure.Core` -- `Azure.Identity` -- `Azure.AI.OpenAI` - -#### Tracing - -The Aspire Azure OpenAI integration will emit the following tracing activities using OpenTelemetry: - -- `Azure.AI.OpenAI.*` -- `gen_ai.system` - Generic AI system tracing -- `gen_ai.operation.name` - Operation names for AI calls - -#### Metrics - -The Aspire Azure OpenAI integration currently doesn't support metrics by default due to limitations with the Azure SDK for .NET. diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-openai/azure-openai-client.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-openai/azure-openai-client.mdx new file mode 100644 index 00000000..2117cd61 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-openai/azure-openai-client.mdx @@ -0,0 +1,271 @@ +--- +title: Azure OpenAI client integration +description: Learn how to use the Aspire Azure OpenAI client integration to connect to Azure OpenAI services. +next: false +--- + +import { Aside } from '@astrojs/starlight/components'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; +import { Image } from 'astro:assets'; +import openaiIcon from '@assets/icons/azure-openai-icon.png'; + +Azure OpenAI logo + +The Aspire Azure OpenAI client integration is used to connect to an Azure OpenAI service. To get started with the Aspire Azure OpenAI client integration, install the [📦 Aspire.Azure.AI.OpenAI](https://www.nuget.org/packages/Aspire.Azure.AI.OpenAI) NuGet package. + + + +For an introduction to working with the Azure OpenAI client integration, see [Get started with the Azure OpenAI integration](/integrations/cloud/azure/azure-openai/azure-openai-get-started/). + +## Add Azure OpenAI client + +In the `Program.cs` file of your client-consuming project, call the `AddAzureOpenAIClient` extension method to register an `AzureOpenAIClient` for use via the dependency injection container. The method takes a connection name parameter: + +```csharp +builder.AddAzureOpenAIClient(connectionName: "openai"); +``` + + + +After adding the `AzureOpenAIClient`, you can retrieve the client instance using dependency injection: + +```csharp +public class ExampleService(AzureOpenAIClient client) +{ + // Use client... +} +``` + +## Add Azure OpenAI client with registered `IChatClient` + +If you're interested in using the `IChatClient` interface, with the OpenAI client, simply chain either of the following APIs to the `AddAzureOpenAIClient` method: + +- `AddChatClient`: Registers a singleton `IChatClient` in the services provided by the `AspireOpenAIClientBuilder`. +- `AddKeyedChatClient`: Registers a keyed singleton `IChatClient` in the services provided by the `AspireOpenAIClientBuilder`. + +For example, consider the following C# code that adds an `IChatClient` to the DI container: + +```csharp +builder.AddAzureOpenAIClient(connectionName: "openai") + .AddChatClient("deploymentName"); +``` + +Similarly, you can add a keyed `IChatClient` with the following C# code: + +```csharp +builder.AddAzureOpenAIClient(connectionName: "openai") + .AddKeyedChatClient("serviceKey", "deploymentName"); +``` + +After adding the `IChatClient`, you can retrieve the client instance using dependency injection: + +```csharp +public class ExampleService(IChatClient chatClient) +{ + public async Task GetResponseAsync(string userMessage) + { + var response = await chatClient.CompleteAsync(userMessage); + return response.Message.Text ?? string.Empty; + } +} +``` + +For more information on `IChatClient` and `Microsoft.Extensions.AI`, see [Unified AI Building Blocks for .NET](https://learn.microsoft.com/dotnet/core/extensions/artificial-intelligence). + +## Configure Azure OpenAI client settings + +The Aspire Azure OpenAI library provides a set of settings to configure the Azure OpenAI client. The `AddAzureOpenAIClient` method exposes an optional `configureSettings` parameter of type `Action?`. To configure settings inline, consider the following example: + +```csharp +builder.AddAzureOpenAIClient( + connectionName: "openai", + configureSettings: settings => + { + settings.DisableTracing = true; + + var uriString = builder.Configuration["AZURE_OPENAI_ENDPOINT"] + ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set."); + + settings.Endpoint = new Uri(uriString); + }); +``` + +The preceding code sets the `AzureOpenAISettings.DisableTracing` property to `true`, and sets the `AzureOpenAISettings.Endpoint` property to the Azure OpenAI endpoint. + +## Configure Azure OpenAI client builder options + +To configure the `AzureOpenAIClientOptions` for the client, you can use the `AddAzureOpenAIClient` method. This method takes an optional `configureClientBuilder` parameter of type `Action>?`. Consider the following example: + +```csharp +builder.AddAzureOpenAIClient( + connectionName: "openai", + configureClientBuilder: clientBuilder => + { + clientBuilder.ConfigureOptions(options => + { + options.UserAgentApplicationId = "CLIENT_ID"; + }); + }); +``` + +The client builder is an instance of the `IAzureClientBuilder` type, which provides a fluent API to configure the client options. The preceding code sets the `AzureOpenAIClientOptions.UserAgentApplicationId` property to `CLIENT_ID`. + +## Add Azure OpenAI client from configuration + +Additionally, the package provides the `AddOpenAIClientFromConfiguration` extension method to register an `OpenAIClient` or `AzureOpenAIClient` instance based on the provided connection string. This method follows these rules: + +- If the `Endpoint` attribute is empty or missing, an `OpenAIClient` instance is registered using the provided key, for example, `Key={key};`. +- If the `IsAzure` attribute is `true`, an `AzureOpenAIClient` is registered; otherwise, an `OpenAIClient` is registered, for example, `Endpoint={azure_endpoint};Key={key};IsAzure=true` registers an `AzureOpenAIClient`, while `Endpoint=https://localhost:18889;Key={key}` registers an `OpenAIClient`. +- If the `Endpoint` attribute contains `".azure."`, an `AzureOpenAIClient` is registered; otherwise, an `OpenAIClient` is registered, for example, `Endpoint=https://{account}.azure.com;Key={key};`. + +Consider the following example: + +```csharp +builder.AddOpenAIClientFromConfiguration("openai"); +``` + +> [!TIP] +> A valid connection string must contain at least an `Endpoint` or a `Key`. + +Consider the following example connection strings and whether they register an `OpenAIClient` or `AzureOpenAIClient`: + +| Example connection string | Registered client type | +| ----------------------------------------------------------------------------------- | ---------------------- | +| `Endpoint=https://{account_name}.openai.azure.com/;Key={account_key}` | `AzureOpenAIClient` | +| `Endpoint=https://{account_name}.openai.azure.com/;Key={account_key};IsAzure=false` | `OpenAIClient` | +| `Endpoint=https://{account_name}.openai.azure.com/;Key={account_key};IsAzure=true` | `AzureOpenAIClient` | +| `Endpoint=https://localhost:18889;Key={account_key}` | `OpenAIClient` | + +## Add keyed Azure OpenAI clients + +There might be situations where you want to register multiple `OpenAIClient` instances with different connection names. To register keyed Azure OpenAI clients, call the `AddKeyedAzureOpenAIClient` method: + +```csharp +builder.AddKeyedAzureOpenAIClient(name: "chat"); +builder.AddKeyedAzureOpenAIClient(name: "code"); +``` + +> [!IMPORTANT] +> When using keyed services, ensure that your Azure OpenAI resource configures two named connections, one for `chat` and one for `code`. + +Then you can retrieve the client instances using dependency injection. For example, to retrieve the clients from a service: + +```csharp +public class ExampleService( + [KeyedService("chat")] OpenAIClient chatClient, + [KeyedService("code")] OpenAIClient codeClient) +{ + // Use clients... +} +``` + +For more information, see [Keyed services in .NET](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection#keyed-services). + +## Add keyed Azure OpenAI clients from configuration + +The same functionality and rules exist for keyed Azure OpenAI clients as for the nonkeyed clients. You can use the `AddKeyedOpenAIClientFromConfiguration` extension method to register an `OpenAIClient` or `AzureOpenAIClient` instance based on the provided connection string. + +Consider the following example: + +```csharp +builder.AddKeyedOpenAIClientFromConfiguration("openai"); +``` + +This method follows the same rules as detailed in the [Add Azure OpenAI client from configuration](#add-azure-openai-client-from-configuration). + +## Configuration + +The Aspire Azure OpenAI library provides multiple options to configure the Azure OpenAI connection based on the requirements and conventions of your project. Either an `Endpoint` or a `ConnectionString` must be supplied. + +### Use a connection string + +When using a connection string from the `ConnectionStrings` configuration section, you can provide the name of the connection string when calling `AddAzureOpenAIClient`: + +```csharp +builder.AddAzureOpenAIClient(connectionName: "openai"); +``` + +The connection information is retrieved from the `ConnectionStrings` configuration section. Two connection formats are supported: + +- **Service endpoint (recommended)**: Uses the service endpoint with `DefaultAzureCredential`. + + ```json + { + "ConnectionStrings": { + "openai": "https://{account_name}.openai.azure.com/" + } + } + ``` + +- **Connection string**: Includes an API key. + + ```json + { + "ConnectionStrings": { + "openai": "Endpoint=https://{account_name}.openai.azure.com/;Key={api_key}" + } + } + ``` + +### Use configuration providers + +The library supports `Microsoft.Extensions.Configuration`. It loads settings from configuration using the `Aspire:Azure:AI:OpenAI` key: + +```json +{ + "Aspire": { + "Azure": { + "AI": { + "OpenAI": { + "DisableTracing": false + } + } + } + } +} +``` + +### Use inline delegates + +You can configure settings inline: + +```csharp +builder.AddAzureOpenAIClient( + "openai", + settings => settings.DisableTracing = true); +``` + +## Observability and telemetry + +Aspire integrations automatically set up Logging, Tracing, and Metrics configurations. + +### Logging + +The Aspire Azure OpenAI integration uses the following log categories: + +- `Azure` +- `Azure.Core` +- `Azure.Identity` +- `Azure.AI.OpenAI` + +### Tracing + +The Aspire Azure OpenAI integration will emit the following tracing activities using OpenTelemetry: + +- `Azure.AI.OpenAI.*` +- `gen_ai.system` - Generic AI system tracing +- `gen_ai.operation.name` - Operation names for AI calls + +### Metrics + +The Aspire Azure OpenAI integration currently doesn't support metrics by default due to limitations with the Azure SDK for .NET. diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-openai/azure-openai-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-openai/azure-openai-get-started.mdx new file mode 100644 index 00000000..c3ca8ffe --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-openai/azure-openai-get-started.mdx @@ -0,0 +1,110 @@ +--- +title: Get started with the Azure OpenAI integration +description: Learn how to set up the Aspire Azure OpenAI Hosting and Client integrations simply. +prev: false +--- + +import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components'; +import InstallPackage from '@components/InstallPackage.astro'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; +import { Image } from 'astro:assets'; +import openaiIcon from '@assets/icons/azure-openai-icon.png'; + +Azure OpenAI logo + +[Azure OpenAI Service](https://azure.microsoft.com/products/ai-services/openai-service) provides access to OpenAI's powerful language and embedding models with the security and enterprise promise of Azure. The Aspire Azure OpenAI integration enables you to connect to Azure OpenAI services from your applications. + +In this introduction, you'll see how to install and use the Aspire Azure OpenAI integrations in a simple configuration. If you already have this knowledge, see [Azure OpenAI Hosting integration](/integrations/cloud/azure/azure-openai/azure-openai-host/) for full reference details. + + + +## Set up hosting integration + +To begin, install the Aspire Azure OpenAI Hosting integration in your Aspire AppHost project. This integration allows you to create and manage Azure OpenAI resources from your Aspire hosting projects: + + + +Next, in the AppHost project, create an Azure OpenAI resource and pass it to the consuming client projects: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var openai = builder.AddAzureOpenAI("openai"); + +openai.AddDeployment( + name: "preview", + modelName: "gpt-4.5-preview", + modelVersion: "2025-02-27"); + +builder.AddProject() + .WithReference(openai) + .WaitFor(openai); + +// After adding all resources, run the app... + +builder.Build().Run(); +``` + +The preceding code adds an Azure OpenAI resource named `openai` to the AppHost project, configures a deployment with a specific model, and passes the connection information to the `ExampleProject` project. + + + + + +## Set up client integration + +To use Azure OpenAI from your client applications, install the Aspire Azure OpenAI client integration in your client project: + + + +In the `Program.cs` file of your client-consuming project, call the `AddAzureOpenAIClient` extension method to register an `AzureOpenAIClient` for use via the dependency injection container: + +```csharp +builder.AddAzureOpenAIClient(connectionName: "openai"); +``` + +> [!TIP] +> The `connectionName` parameter must match the name used when adding the OpenAI resource in the AppHost project. + +After adding the `AzureOpenAIClient`, you can retrieve the client instance using dependency injection: + +```csharp +public class ExampleService(AzureOpenAIClient client) +{ + // Use client... +} +``` + +For full details on using the client integration, see [Azure OpenAI Client integration](/integrations/cloud/azure/azure-openai/azure-openai-client/). + +## Next steps + + + + + diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-openai/azure-openai-host.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-openai/azure-openai-host.mdx new file mode 100644 index 00000000..482ed63f --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-openai/azure-openai-host.mdx @@ -0,0 +1,231 @@ +--- +title: Azure OpenAI hosting integration +description: Learn how to use the Aspire Azure OpenAI hosting integration to create Azure OpenAI resources. +--- + +import { Aside } from '@astrojs/starlight/components'; +import InstallPackage from '@components/InstallPackage.astro'; +import { Image } from 'astro:assets'; +import openaiIcon from '@assets/icons/azure-openai-icon.png'; + +Azure OpenAI logo + +The Aspire Azure OpenAI hosting integration models the Azure OpenAI service as the `AzureOpenAIResource` type. To access this type and APIs for expressing them within your AppHost project, install the [📦 Aspire.Hosting.Azure.CognitiveServices](https://www.nuget.org/packages/Aspire.Hosting.Azure.CognitiveServices) NuGet package: + + + +For an introduction to working with the Azure OpenAI hosting integration, see [Get started with the Azure OpenAI integration](/integrations/cloud/azure/azure-openai/azure-openai-get-started/). + +## Add an Azure OpenAI resource + +To add an Azure OpenAI resource to your AppHost project, call the `AddAzureOpenAI` method providing a name: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var openai = builder.AddAzureOpenAI("openai"); + +builder.AddProject() + .WithReference(openai); + +// After adding all resources, run the app... +``` + +The preceding code adds an Azure OpenAI resource named `openai` to the AppHost project. The `WithReference` method passes the connection information to the `ExampleProject` project. + + + +## Add an Azure OpenAI deployment resource + +To add an Azure OpenAI deployment resource, call the `AddDeployment` method: + +```csharp +var builder = DistributedApplication.CreateBuilder(args); + +var openai = builder.AddAzureOpenAI("openai"); + +openai.AddDeployment( + name: "preview", + modelName: "gpt-4.5-preview", + modelVersion: "2025-02-27"); + +builder.AddProject() + .WithReference(openai) + .WaitFor(openai); + +// After adding all resources, run the app... +``` + +The preceding code: + +- Adds an Azure OpenAI resource named `openai`. +- Adds an Azure OpenAI deployment resource named `preview` with a model name of `gpt-4.5-preview`. The model name must correspond to an [available model](https://learn.microsoft.com/azure/ai-services/openai/concepts/models) in the Azure OpenAI service. + +## Connect to an existing Azure OpenAI service + +You might have an existing Azure OpenAI service that you want to connect to. You can chain a call to annotate that your `AzureOpenAIResource` is an existing resource: + +```csharp +var builder = DistributedApplication.CreateBuilder(args); + +var existingOpenAIName = builder.AddParameter("existingOpenAIName"); +var existingOpenAIResourceGroup = builder.AddParameter("existingOpenAIResourceGroup"); + +var openai = builder.AddAzureOpenAI("openai") + .AsExisting(existingOpenAIName, existingOpenAIResourceGroup); + +builder.AddProject() + .WithReference(openai); + +// After adding all resources, run the app... +``` + +For more information on treating Azure OpenAI resources as existing resources, see [Use existing Azure resources](/integrations/cloud/azure/overview/#use-existing-azure-resources). + +> [!NOTE] +> Alternatively, instead of representing an Azure OpenAI resource, you can add a connection string to the AppHost. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](/integrations/cloud/azure/overview/#add-existing-azure-resources-with-connection-strings). + +## Provisioning-generated Bicep + +If you're new to [Bicep](https://learn.microsoft.com/azure/azure-resource-manager/bicep/overview), it's a domain-specific language for defining Azure resources. With Aspire, you don't need to write Bicep by-hand, instead the provisioning APIs generate Bicep for you. When you publish your app, the generated Bicep provisions an Azure OpenAI resource with standard defaults. + +```bicep title="Bicep — openai.bicep" +@description('The location for the resource(s) to be deployed.') +param location string = resourceGroup().location + +resource openai 'Microsoft.CognitiveServices/accounts@2024-10-01' = { + name: take('openai-${uniqueString(resourceGroup().id)}', 64) + location: location + kind: 'OpenAI' + properties: { + customSubDomainName: toLower(take(concat('openai', uniqueString(resourceGroup().id)), 24)) + publicNetworkAccess: 'Enabled' + disableLocalAuth: true + } + sku: { + name: 'S0' + } + tags: { + 'aspire-resource-name': 'openai' + } +} + +resource preview 'Microsoft.CognitiveServices/accounts/deployments@2024-10-01' = { + name: 'preview' + properties: { + model: { + format: 'OpenAI' + name: 'gpt-4.5-preview' + version: '2025-02-27' + } + } + sku: { + name: 'Standard' + capacity: 8 + } + parent: openai +} + +output connectionString string = 'Endpoint=${openai.properties.endpoint}' + +output name string = openai.name +``` + +The preceding Bicep is a module that provisions an Azure Cognitive Services resource. Additionally, role assignments are created for the Azure resource in a separate module: + +```bicep title="Bicep — openai-roles.bicep" +@description('The location for the resource(s) to be deployed.') +param location string = resourceGroup().location + +param openai_outputs_name string + +param principalType string + +param principalId string + +resource openai 'Microsoft.CognitiveServices/accounts@2024-10-01' existing = { + name: openai_outputs_name +} + +resource openai_CognitiveServicesOpenAIUser 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(openai.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '5e0bd9bd-7b93-4f28-af87-19fc36ad61bd')) + properties: { + principalId: principalId + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '5e0bd9bd-7b93-4f28-af87-19fc36ad61bd') + principalType: principalType + } + scope: openai +} +``` + +The generated Bicep is a starting point and is influenced by changes to the provisioning infrastructure in C#. Customizations to the Bicep file directly will be overwritten, so make changes through the C# provisioning APIs to ensure they are reflected in the generated files. + +## Customize provisioning infrastructure + +All Aspire Azure resources are subclasses of the `AzureProvisioningResource` type. This enables customization of the generated Bicep by providing a fluent API to configure the Azure resources—using the `ConfigureInfrastructure` API: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +builder.AddAzureOpenAI("openai") + .ConfigureInfrastructure(infra => + { + var resources = infra.GetProvisionableResources(); + var account = resources.OfType().Single(); + + account.Sku = new CognitiveServicesSku + { + Tier = CognitiveServicesSkuTier.Enterprise, + Name = "E0" + }; + account.Tags.Add("ExampleKey", "Example value"); + }); +``` + +The preceding code: + +- Chains a call to the `ConfigureInfrastructure` API: + - The `infra` parameter is an instance of the `AzureResourceInfrastructure type. + - The provisionable resources are retrieved by calling the `GetProvisionableResources` method. + - The single `CognitiveServicesAccount` resource is retrieved. + - The `CognitiveServicesAccount` property is assigned to a new instance of `CognitiveServices.CognitiveServicesSku` with an `E0` name and CognitiveServicesSkuTier.Enterprise` tier. + - A tag is added to the Cognitive Services resource with a key of `ExampleKey` and a value of `Example value`. + +## Connection properties + +When you reference Azure OpenAI resources using `WithReference`, the following connection properties are made available to the consuming project: + +### Azure OpenAI resource + +The Azure OpenAI resource exposes the following connection properties: + +| Property Name | Description | +| ------------- | ----------------------------------------------------------------------------------------------------- | +| `Uri` | The endpoint URI for the Azure OpenAI resource, typically `https://.openai.azure.com/` | + +### Azure OpenAI deployment + +The Azure OpenAI deployment resource inherits all properties from its parent Azure OpenAI resource and adds: + +| Property Name | Description | +| ------------- | ----------------------------------------------------- | +| `ModelName` | The name of the Azure OpenAI deployment, e.g., `chat` | + + diff --git a/src/frontend/src/data/integration-docs.json b/src/frontend/src/data/integration-docs.json index c6c92f88..812f1ca2 100644 --- a/src/frontend/src/data/integration-docs.json +++ b/src/frontend/src/data/integration-docs.json @@ -5,7 +5,7 @@ }, { "match": "Aspire.Azure.AI.OpenAI", - "href": "/integrations/cloud/azure/azure-openai/" + "href": "/integrations/cloud/azure/azure-openai/azure-openai-get-started/" }, { "match": "Aspire.Azure.Data.Tables", @@ -81,7 +81,7 @@ }, { "match": "Aspire.Hosting.Azure.CognitiveServices", - "href": "/integrations/cloud/azure/azure-openai/" + "href": "/integrations/cloud/azure/azure-openai/azure-openai-get-started/" }, { "match": "Aspire.Hosting.Azure.ContainerRegistry", From 213c86cc2c7c386765b7e7e3a5a0112ec5f7d649 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 15:42:47 +0000 Subject: [PATCH 16/30] Restructure Azure Service Bus integration into subfolder --- .../config/sidebar/integrations.topics.ts | 16 +- .../azure-service-bus-client.mdx | 281 ++++++++++++++++++ .../azure-service-bus-get-started.mdx | 105 +++++++ .../azure-service-bus-host.mdx} | 276 +---------------- src/frontend/src/data/integration-docs.json | 4 +- 5 files changed, 409 insertions(+), 273 deletions(-) create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-service-bus/azure-service-bus-client.mdx create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-service-bus/azure-service-bus-get-started.mdx rename src/frontend/src/content/docs/integrations/cloud/azure/{azure-service-bus.mdx => azure-service-bus/azure-service-bus-host.mdx} (62%) diff --git a/src/frontend/config/sidebar/integrations.topics.ts b/src/frontend/config/sidebar/integrations.topics.ts index 067894e0..8300d441 100644 --- a/src/frontend/config/sidebar/integrations.topics.ts +++ b/src/frontend/config/sidebar/integrations.topics.ts @@ -505,7 +505,21 @@ export const integrationTopics: StarlightSidebarTopicsUserConfig = { }, { label: 'Azure Service Bus', - slug: 'integrations/cloud/azure/azure-service-bus', + collapsed: true, + items: [ + { + label: 'Get started', + slug: 'integrations/cloud/azure/azure-service-bus/azure-service-bus-get-started', + }, + { + label: 'Hosting integration (AppHost)', + slug: 'integrations/cloud/azure/azure-service-bus/azure-service-bus-host', + }, + { + label: 'Client integration', + slug: 'integrations/cloud/azure/azure-service-bus/azure-service-bus-client', + }, + ], }, { label: 'Azure SignalR Service', diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-service-bus/azure-service-bus-client.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-service-bus/azure-service-bus-client.mdx new file mode 100644 index 00000000..94111f9f --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-service-bus/azure-service-bus-client.mdx @@ -0,0 +1,281 @@ +--- +title: Azure Service Bus client integration +description: Learn how to use the Aspire Azure Service Bus client integration to connect to Azure Service Bus services. +next: false +--- + +import { Aside } from '@astrojs/starlight/components'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; +import { Image } from 'astro:assets'; +import serviceBusIcon from '@assets/icons/azure-servicebus-icon.png'; + +Azure Service Bus logo + +The Aspire Azure Service Bus client integration is used to connect to an Azure Service Bus service. To get started with the Aspire Azure Service Bus client integration, install the [📦 Aspire.Azure.Messaging.ServiceBus](https://www.nuget.org/packages/Aspire.Azure.Messaging.ServiceBus) NuGet package: + + + +For an introduction to working with the Azure Service Bus client integration, see [Get started with the Azure Service Bus integration](/integrations/cloud/azure/azure-service-bus/azure-service-bus-get-started/). + +### Add Service Bus client + +In the `Program.cs` file of your client-consuming project, call the `AddAzureServiceBusClient` extension method on any `IHostApplicationBuilder` to register a `ServiceBusClient` for use via the dependency injection container. The method takes a connection name parameter. + +```csharp +builder.AddAzureServiceBusClient(connectionName: "messaging"); +``` + +You can then retrieve the `ServiceBusClient` instance using dependency injection. For example, to retrieve the connection from an example service: + +```csharp +public class ExampleService(ServiceBusClient client) +{ + // Use client... +} +``` + +For more information on dependency injection, see [.NET dependency injection](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection). + +### Choose the correct connection name + +When you call `AddAzureServiceBusClient()`, the correct value depends on the object you passed to the client in the AppHost. + +For example, if you use this code in the AppHost: + +```csharp +var serviceBus = builder.AddAzureServiceBus("messaging"); + +var apiService = builder.AddProject("apiservice") + .WithReference(serviceBus); +``` + +Then the correct code to add the Service Bus in your client-consuming program is: + +```csharp +builder.AddAzureServiceBusClient(connectionName: "messaging"); +``` + +However, if you created and passed a Service Bus topic in the AppHost: + +```csharp +var serviceBus = builder.AddAzureServiceBus("messaging"); +var topic = serviceBus.AddServiceBusTopic("myTopic"); + +var apiService = builder.AddProject("apiservice") + .WithReference(topic); +``` + +Then the correct code to add the Service Bus topic in your client-consuming program is: + +```csharp +builder.AddAzureServiceBusClient(connectionName: "myTopic"); +``` + +For more information, see [Add Azure Service Bus resource](#add-azure-service-bus-resource) and [Add Azure Service Bus topic and subscription](#add-azure-service-bus-topic-and-subscription). + +### Add keyed Service Bus client + +There might be situations where you want to register multiple `ServiceBusClient` instances with different connection names. To register keyed Service Bus clients, call the `AddKeyedAzureServiceBusClient` method: + +```csharp +builder.AddKeyedAzureServiceBusClient(name: "mainBus"); +builder.AddKeyedAzureServiceBusClient(name: "loggingBus"); +``` + + + +Then you can retrieve the `ServiceBusClient` instances using dependency injection. For example, to retrieve the connection from an example service: + +```csharp +public class ExampleService( + [FromKeyedServices("mainBus")] ServiceBusClient mainBusClient, + [FromKeyedServices("loggingBus")] ServiceBusClient loggingBusClient) +{ + // Use clients... +} +``` + +For more information on keyed services, see [.NET dependency injection: Keyed services](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection#keyed-services). + +### Configuration + +The Aspire Azure Service Bus integration provides multiple options to configure the connection based on the requirements and conventions of your project. + +#### Use a connection string + +When using a connection string from the `ConnectionStrings` configuration section, you can provide the name of the connection string when calling the `AddAzureServiceBusClient` method: + +```csharp +builder.AddAzureServiceBusClient("messaging"); +``` + +Then the connection string is retrieved from the `ConnectionStrings` configuration section: + +```json +{ + "ConnectionStrings": { + "messaging": "Endpoint=sb://{namespace}.servicebus.windows.net/;SharedAccessKeyName={keyName};SharedAccessKey={key};" + } +} +``` + +#### Use configuration providers + +The Aspire Azure Service Bus integration supports `Microsoft.Extensions.Configuration`. It loads the `AzureMessagingServiceBusSettings` from configuration by using the `Aspire:Azure:Messaging:ServiceBus` key. The following snippet is an example of an `appsettings.json` file that configures some of the options: + +```json +{ + "Aspire": { + "Azure": { + "Messaging": { + "ServiceBus": { + "ConnectionString": "Endpoint=sb://{namespace}.servicebus.windows.net/;SharedAccessKeyName={keyName};SharedAccessKey={key};", + "DisableTracing": false + } + } + } + } +} +``` + +For the complete Service Bus client integration JSON schema, see [Aspire.Azure.Messaging.ServiceBus/ConfigurationSchema.json](https://github.com/dotnet/aspire/blob/v9.1.0/src/Components/Aspire.Azure.Messaging.ServiceBus/ConfigurationSchema.json). + +#### Use named configuration + +The Aspire Azure Service Bus integration supports named configuration, which allows you to configure multiple instances of the same resource type with different settings. The named configuration uses the connection name as a key under the main configuration section. + +```json +{ + "Aspire": { + "Azure": { + "Messaging": { + "ServiceBus": { + "bus1": { + "ConnectionString": "Endpoint=sb://namespace1.servicebus.windows.net/;SharedAccessKeyName=keyName;SharedAccessKey=key;", + "DisableTracing": false + }, + "bus2": { + "ConnectionString": "Endpoint=sb://namespace2.servicebus.windows.net/;SharedAccessKeyName=keyName;SharedAccessKey=key;", + "DisableTracing": true + } + } + } + } + } +} +``` + +In this example, the `bus1` and `bus2` connection names can be used when calling `AddAzureServiceBusClient`: + +```csharp +builder.AddAzureServiceBusClient("bus1"); +builder.AddAzureServiceBusClient("bus2"); +``` + +Named configuration takes precedence over the top-level configuration. If both are provided, the settings from the named configuration override the top-level settings. + +#### Use inline delegates + +You can also pass the `Action configureSettings` delegate to set up some or all the options inline, for example to disable tracing from code: + +```csharp +builder.AddAzureServiceBusClient( + "messaging", + static settings => settings.DisableTracing = true); +``` + +You can also set up the `ServiceBusClientOptions` using the optional `Action configureClientOptions` parameter of the `AddAzureServiceBusClient` method. For example, to set the `Identifier` user-agent header suffix for all requests issued by this client: + +```csharp +builder.AddAzureServiceBusClient( + "messaging", + configureClientOptions: + clientOptions => clientOptions.Identifier = "myapp"); +``` + +### Client integration health checks + +By default, Aspire integrations enable health checks for all services. For more information, see [Aspire integrations overview](/integrations/overview/). + +The Aspire Azure Service Bus integration: + +- Adds the health check when `DisableTracing` is `false`, which attempts to connect to the Service Bus. +- Integrates with the `/health` HTTP endpoint, which specifies all registered health checks must pass for app to be considered ready to accept traffic. + +### Observability and telemetry + +Aspire integrations automatically set up Logging, Tracing, and Metrics configurations, which are sometimes known as _the pillars of observability_. Depending on the backing service, some integrations may only support some of these features. For example, some integrations support logging and tracing, but not metrics. Telemetry features can also be disabled using the techniques presented in the [Configuration](#configuration) section. + +#### Logging + +The Aspire Azure Service Bus integration uses the following log categories: + +- `Azure.Core` +- `Azure.Identity` +- `Azure-Messaging-ServiceBus` + +In addition to getting Azure Service Bus request diagnostics for failed requests, you can configure latency thresholds to determine which successful Azure Service Bus request diagnostics will be logged. The default values are 100 ms for point operations and 500 ms for non point operations. + +```csharp +builder.AddAzureServiceBusClient( + "messaging", + configureClientOptions: + clientOptions => { + clientOptions.ServiceBusClientTelemetryOptions = new() + { + ServiceBusThresholdOptions = new() + { + PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(50), + NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(300) + } + }; + }); +``` + +#### Tracing + +The Aspire Azure Service Bus integration will emit the following tracing activities using OpenTelemetry: + +- `Message` +- `ServiceBusSender.Send` +- `ServiceBusSender.Schedule` +- `ServiceBusSender.Cancel` +- `ServiceBusReceiver.Receive` +- `ServiceBusReceiver.ReceiveDeferred` +- `ServiceBusReceiver.Peek` +- `ServiceBusReceiver.Abandon` +- `ServiceBusReceiver.Complete` +- `ServiceBusReceiver.DeadLetter` +- `ServiceBusReceiver.Defer` +- `ServiceBusReceiver.RenewMessageLock` +- `ServiceBusSessionReceiver.RenewSessionLock` +- `ServiceBusSessionReceiver.GetSessionState` +- `ServiceBusSessionReceiver.SetSessionState` +- `ServiceBusProcessor.ProcessMessage` +- `ServiceBusSessionProcessor.ProcessSessionMessage` +- `ServiceBusRuleManager.CreateRule` +- `ServiceBusRuleManager.DeleteRule` +- `ServiceBusRuleManager.GetRules` + +Azure Service Bus tracing is currently in preview, so you must set the experimental switch to ensure traces are emitted. + +```csharp +AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true); +``` + +For more information, see [Azure Service Bus: Distributed tracing and correlation through Service Bus messaging](https://learn.microsoft.com/azure/service-bus-messaging/service-bus-end-to-end-tracing). + +#### Metrics + +The Aspire Azure Service Bus integration currently doesn't support metrics by default due to limitations with the Azure SDK. diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-service-bus/azure-service-bus-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-service-bus/azure-service-bus-get-started.mdx new file mode 100644 index 00000000..336317b3 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-service-bus/azure-service-bus-get-started.mdx @@ -0,0 +1,105 @@ +--- +title: Get started with the Azure Service Bus integration +description: Learn how to set up the Aspire Azure Service Bus Hosting and Client integrations simply. +prev: false +--- + +import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components'; +import InstallPackage from '@components/InstallPackage.astro'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; +import { Image } from 'astro:assets'; +import serviceBusIcon from '@assets/icons/azure-servicebus-icon.png'; + +Azure Service Bus logo + +[Azure Service Bus](https://learn.microsoft.com/azure/service-bus-messaging) is a fully managed enterprise message broker with message queues and publish-subscribe topics. The Aspire Azure Service Bus integration enables you to connect to Azure Service Bus instances from your applications. + +In this introduction, you'll see how to install and use the Aspire Azure Service Bus integrations in a simple configuration. If you already have this knowledge, see [Azure Service Bus Hosting integration](/integrations/cloud/azure/azure-service-bus/azure-service-bus-host/) for full reference details. + + + +## Set up hosting integration + +To begin, install the Aspire Azure Service Bus Hosting integration in your Aspire AppHost project. This integration allows you to create and manage Azure Service Bus resources from your Aspire hosting projects: + + + +Next, in the AppHost project, create an Azure Service Bus resource and pass it to the consuming client projects: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var serviceBus = builder.AddAzureServiceBus("messaging"); +var queue = serviceBus.AddServiceBusQueue("queue"); + +builder.AddProject() + .WithReference(queue); + +// After adding all resources, run the app... + +builder.Build().Run(); +``` + +The preceding code adds an Azure Service Bus resource named `messaging` to the AppHost project, adds a queue to it, and passes the queue connection information to the `ExampleProject` project. + + + + + +## Set up client integration + +To use Azure Service Bus from your client applications, install the Aspire Azure Service Bus client integration in your client project: + + + +In the `Program.cs` file of your client-consuming project, call the `AddAzureServiceBusClient` extension method to register a `ServiceBusClient` for use via the dependency injection container: + +```csharp +builder.AddAzureServiceBusClient(connectionName: "queue"); +``` + +> [!TIP] +> The `connectionName` parameter must match the name used when adding the Service Bus queue (or topic) in the AppHost project. + +After adding the `ServiceBusClient`, you can retrieve the client instance using dependency injection: + +```csharp +public class ExampleService(ServiceBusClient client) +{ + // Use client... +} +``` + +For full details on using the client integration, see [Azure Service Bus Client integration](/integrations/cloud/azure/azure-service-bus/azure-service-bus-client/). + +## Next steps + + + + + diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-service-bus.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-service-bus/azure-service-bus-host.mdx similarity index 62% rename from src/frontend/src/content/docs/integrations/cloud/azure/azure-service-bus.mdx rename to src/frontend/src/content/docs/integrations/cloud/azure/azure-service-bus/azure-service-bus-host.mdx index 7ed14685..98cf1109 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-service-bus.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-service-bus/azure-service-bus-host.mdx @@ -1,11 +1,10 @@ --- -title: Azure Service Bus integration -description: Learn how to install and configure the Aspire Azure Service Bus integration to connect to Azure Service Bus instances from any application. +title: Azure Service Bus hosting integration +description: Learn how to use the Aspire Azure Service Bus hosting integration to create Azure Service Bus resources. --- import { Aside } from '@astrojs/starlight/components'; import InstallPackage from '@components/InstallPackage.astro'; -import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; import { Image } from 'astro:assets'; import serviceBusIcon from '@assets/icons/azure-servicebus-icon.png'; @@ -18,9 +17,11 @@ import serviceBusIcon from '@assets/icons/azure-servicebus-icon.png'; data-zoom-off /> -[Azure Service Bus](https://learn.microsoft.com/azure/service-bus-messaging) is a fully managed enterprise message broker with message queues and publish-subscribe topics. The Aspire Azure Service Bus integration enables you to connect to Azure Service Bus instances from your applications. +The Aspire Azure Service Bus hosting integration models Azure Service Bus resources. To access these types and APIs for expressing them within your AppHost project, install the [📦 Aspire.Hosting.Azure.ServiceBus](https://www.nuget.org/packages/Aspire.Hosting.Azure.ServiceBus) NuGet package: -## Hosting integration + + +For an introduction to working with the Azure Service Bus hosting integration, see [Get started with the Azure Service Bus integration](/integrations/cloud/azure/azure-service-bus/azure-service-bus-get-started/). [Azure Service Bus](https://azure.microsoft.com/services/service-bus/) is a fully managed enterprise message broker with message queues and publish-subscribe topics. The Aspire Azure Service Bus integration enables you to connect to Azure Service Bus instances from applications. @@ -30,10 +31,6 @@ import serviceBusIcon from '@assets/icons/azure-servicebus-icon.png'; - `AzureServiceBusEmulatorResource`: Represents an Azure Service Bus emulator resource. - `AzureServiceBusTopicResource`: Represents an Azure Service Bus topic resource. -To access these types and APIs for expressing them, add the [📦 Aspire.Hosting.Azure.ServiceBus](https://www.nuget.org/packages/Aspire.Hosting.Azure.ServiceBus) NuGet package in the AppHost project. - - - ### Add Azure Service Bus resource In your AppHost project, call `AddAzureServiceBus` to add and return an Azure Service Bus resource builder. @@ -387,264 +384,3 @@ The Service Bus subscription resource inherits all properties from its parent Se `sb1` becomes `SB1_URI`. -## Client integration - -To get started with the Aspire Azure Service Bus client integration, install the [📦 Aspire.Azure.Messaging.ServiceBus](https://www.nuget.org/packages/Aspire.Azure.Messaging.ServiceBus) NuGet package in the client-consuming project, that is, the project for the application that uses the Service Bus client. The Service Bus client integration registers a `ServiceBusClient` instance that you can use to interact with Service Bus. - - - -### Add Service Bus client - -In the `Program.cs` file of your client-consuming project, call the `AddAzureServiceBusClient` extension method on any `IHostApplicationBuilder` to register a `ServiceBusClient` for use via the dependency injection container. The method takes a connection name parameter. - -```csharp -builder.AddAzureServiceBusClient(connectionName: "messaging"); -``` - -You can then retrieve the `ServiceBusClient` instance using dependency injection. For example, to retrieve the connection from an example service: - -```csharp -public class ExampleService(ServiceBusClient client) -{ - // Use client... -} -``` - -For more information on dependency injection, see [.NET dependency injection](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection). - -### Choose the correct connection name - -When you call `AddAzureServiceBusClient()`, the correct value depends on the object you passed to the client in the AppHost. - -For example, if you use this code in the AppHost: - -```csharp -var serviceBus = builder.AddAzureServiceBus("messaging"); - -var apiService = builder.AddProject("apiservice") - .WithReference(serviceBus); -``` - -Then the correct code to add the Service Bus in your client-consuming program is: - -```csharp -builder.AddAzureServiceBusClient(connectionName: "messaging"); -``` - -However, if you created and passed a Service Bus topic in the AppHost: - -```csharp -var serviceBus = builder.AddAzureServiceBus("messaging"); -var topic = serviceBus.AddServiceBusTopic("myTopic"); - -var apiService = builder.AddProject("apiservice") - .WithReference(topic); -``` - -Then the correct code to add the Service Bus topic in your client-consuming program is: - -```csharp -builder.AddAzureServiceBusClient(connectionName: "myTopic"); -``` - -For more information, see [Add Azure Service Bus resource](#add-azure-service-bus-resource) and [Add Azure Service Bus topic and subscription](#add-azure-service-bus-topic-and-subscription). - -### Add keyed Service Bus client - -There might be situations where you want to register multiple `ServiceBusClient` instances with different connection names. To register keyed Service Bus clients, call the `AddKeyedAzureServiceBusClient` method: - -```csharp -builder.AddKeyedAzureServiceBusClient(name: "mainBus"); -builder.AddKeyedAzureServiceBusClient(name: "loggingBus"); -``` - - - -Then you can retrieve the `ServiceBusClient` instances using dependency injection. For example, to retrieve the connection from an example service: - -```csharp -public class ExampleService( - [FromKeyedServices("mainBus")] ServiceBusClient mainBusClient, - [FromKeyedServices("loggingBus")] ServiceBusClient loggingBusClient) -{ - // Use clients... -} -``` - -For more information on keyed services, see [.NET dependency injection: Keyed services](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection#keyed-services). - -### Configuration - -The Aspire Azure Service Bus integration provides multiple options to configure the connection based on the requirements and conventions of your project. - -#### Use a connection string - -When using a connection string from the `ConnectionStrings` configuration section, you can provide the name of the connection string when calling the `AddAzureServiceBusClient` method: - -```csharp -builder.AddAzureServiceBusClient("messaging"); -``` - -Then the connection string is retrieved from the `ConnectionStrings` configuration section: - -```json -{ - "ConnectionStrings": { - "messaging": "Endpoint=sb://{namespace}.servicebus.windows.net/;SharedAccessKeyName={keyName};SharedAccessKey={key};" - } -} -``` - -#### Use configuration providers - -The Aspire Azure Service Bus integration supports `Microsoft.Extensions.Configuration`. It loads the `AzureMessagingServiceBusSettings` from configuration by using the `Aspire:Azure:Messaging:ServiceBus` key. The following snippet is an example of an `appsettings.json` file that configures some of the options: - -```json -{ - "Aspire": { - "Azure": { - "Messaging": { - "ServiceBus": { - "ConnectionString": "Endpoint=sb://{namespace}.servicebus.windows.net/;SharedAccessKeyName={keyName};SharedAccessKey={key};", - "DisableTracing": false - } - } - } - } -} -``` - -For the complete Service Bus client integration JSON schema, see [Aspire.Azure.Messaging.ServiceBus/ConfigurationSchema.json](https://github.com/dotnet/aspire/blob/v9.1.0/src/Components/Aspire.Azure.Messaging.ServiceBus/ConfigurationSchema.json). - -#### Use named configuration - -The Aspire Azure Service Bus integration supports named configuration, which allows you to configure multiple instances of the same resource type with different settings. The named configuration uses the connection name as a key under the main configuration section. - -```json -{ - "Aspire": { - "Azure": { - "Messaging": { - "ServiceBus": { - "bus1": { - "ConnectionString": "Endpoint=sb://namespace1.servicebus.windows.net/;SharedAccessKeyName=keyName;SharedAccessKey=key;", - "DisableTracing": false - }, - "bus2": { - "ConnectionString": "Endpoint=sb://namespace2.servicebus.windows.net/;SharedAccessKeyName=keyName;SharedAccessKey=key;", - "DisableTracing": true - } - } - } - } - } -} -``` - -In this example, the `bus1` and `bus2` connection names can be used when calling `AddAzureServiceBusClient`: - -```csharp -builder.AddAzureServiceBusClient("bus1"); -builder.AddAzureServiceBusClient("bus2"); -``` - -Named configuration takes precedence over the top-level configuration. If both are provided, the settings from the named configuration override the top-level settings. - -#### Use inline delegates - -You can also pass the `Action configureSettings` delegate to set up some or all the options inline, for example to disable tracing from code: - -```csharp -builder.AddAzureServiceBusClient( - "messaging", - static settings => settings.DisableTracing = true); -``` - -You can also set up the `ServiceBusClientOptions` using the optional `Action configureClientOptions` parameter of the `AddAzureServiceBusClient` method. For example, to set the `Identifier` user-agent header suffix for all requests issued by this client: - -```csharp -builder.AddAzureServiceBusClient( - "messaging", - configureClientOptions: - clientOptions => clientOptions.Identifier = "myapp"); -``` - -### Client integration health checks - -By default, Aspire integrations enable health checks for all services. For more information, see [Aspire integrations overview](/integrations/overview/). - -The Aspire Azure Service Bus integration: - -- Adds the health check when `DisableTracing` is `false`, which attempts to connect to the Service Bus. -- Integrates with the `/health` HTTP endpoint, which specifies all registered health checks must pass for app to be considered ready to accept traffic. - -### Observability and telemetry - -Aspire integrations automatically set up Logging, Tracing, and Metrics configurations, which are sometimes known as _the pillars of observability_. Depending on the backing service, some integrations may only support some of these features. For example, some integrations support logging and tracing, but not metrics. Telemetry features can also be disabled using the techniques presented in the [Configuration](#configuration) section. - -#### Logging - -The Aspire Azure Service Bus integration uses the following log categories: - -- `Azure.Core` -- `Azure.Identity` -- `Azure-Messaging-ServiceBus` - -In addition to getting Azure Service Bus request diagnostics for failed requests, you can configure latency thresholds to determine which successful Azure Service Bus request diagnostics will be logged. The default values are 100 ms for point operations and 500 ms for non point operations. - -```csharp -builder.AddAzureServiceBusClient( - "messaging", - configureClientOptions: - clientOptions => { - clientOptions.ServiceBusClientTelemetryOptions = new() - { - ServiceBusThresholdOptions = new() - { - PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(50), - NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(300) - } - }; - }); -``` - -#### Tracing - -The Aspire Azure Service Bus integration will emit the following tracing activities using OpenTelemetry: - -- `Message` -- `ServiceBusSender.Send` -- `ServiceBusSender.Schedule` -- `ServiceBusSender.Cancel` -- `ServiceBusReceiver.Receive` -- `ServiceBusReceiver.ReceiveDeferred` -- `ServiceBusReceiver.Peek` -- `ServiceBusReceiver.Abandon` -- `ServiceBusReceiver.Complete` -- `ServiceBusReceiver.DeadLetter` -- `ServiceBusReceiver.Defer` -- `ServiceBusReceiver.RenewMessageLock` -- `ServiceBusSessionReceiver.RenewSessionLock` -- `ServiceBusSessionReceiver.GetSessionState` -- `ServiceBusSessionReceiver.SetSessionState` -- `ServiceBusProcessor.ProcessMessage` -- `ServiceBusSessionProcessor.ProcessSessionMessage` -- `ServiceBusRuleManager.CreateRule` -- `ServiceBusRuleManager.DeleteRule` -- `ServiceBusRuleManager.GetRules` - -Azure Service Bus tracing is currently in preview, so you must set the experimental switch to ensure traces are emitted. - -```csharp -AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true); -``` - -For more information, see [Azure Service Bus: Distributed tracing and correlation through Service Bus messaging](https://learn.microsoft.com/azure/service-bus-messaging/service-bus-end-to-end-tracing). - -#### Metrics - -The Aspire Azure Service Bus integration currently doesn't support metrics by default due to limitations with the Azure SDK. diff --git a/src/frontend/src/data/integration-docs.json b/src/frontend/src/data/integration-docs.json index 812f1ca2..cfeee44b 100644 --- a/src/frontend/src/data/integration-docs.json +++ b/src/frontend/src/data/integration-docs.json @@ -17,7 +17,7 @@ }, { "match": "Aspire.Azure.Messaging.ServiceBus", - "href": "/integrations/cloud/azure/azure-service-bus/" + "href": "/integrations/cloud/azure/azure-service-bus/azure-service-bus-get-started/" }, { "match": "Aspire.Azure.Messaging.WebPubSub", @@ -125,7 +125,7 @@ }, { "match": "Aspire.Hosting.Azure.ServiceBus", - "href": "/integrations/cloud/azure/azure-service-bus/" + "href": "/integrations/cloud/azure/azure-service-bus/azure-service-bus-get-started/" }, { "match": "Aspire.Hosting.Azure.SignalR", From 7f16543b92182c1f54cafd12250960d708cc8166 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 15:44:17 +0000 Subject: [PATCH 17/30] Restructure Azure SignalR Service integration into subfolder --- .../config/sidebar/integrations.topics.ts | 16 ++- .../azure-signalr/azure-signalr-client.mdx | 132 ++++++++++++++++++ .../azure-signalr-get-started.mdx | 109 +++++++++++++++ .../azure-signalr-host.mdx} | 123 +--------------- src/frontend/src/data/integration-docs.json | 2 +- 5 files changed, 261 insertions(+), 121 deletions(-) create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-signalr/azure-signalr-client.mdx create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-signalr/azure-signalr-get-started.mdx rename src/frontend/src/content/docs/integrations/cloud/azure/{azure-signalr.mdx => azure-signalr/azure-signalr-host.mdx} (57%) diff --git a/src/frontend/config/sidebar/integrations.topics.ts b/src/frontend/config/sidebar/integrations.topics.ts index 8300d441..37ae4d07 100644 --- a/src/frontend/config/sidebar/integrations.topics.ts +++ b/src/frontend/config/sidebar/integrations.topics.ts @@ -523,7 +523,21 @@ export const integrationTopics: StarlightSidebarTopicsUserConfig = { }, { label: 'Azure SignalR Service', - slug: 'integrations/cloud/azure/azure-signalr', + collapsed: true, + items: [ + { + label: 'Get started', + slug: 'integrations/cloud/azure/azure-signalr/azure-signalr-get-started', + }, + { + label: 'Hosting integration (AppHost)', + slug: 'integrations/cloud/azure/azure-signalr/azure-signalr-host', + }, + { + label: 'Hub host integration', + slug: 'integrations/cloud/azure/azure-signalr/azure-signalr-client', + }, + ], }, { label: 'Azure SQL Database', diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-signalr/azure-signalr-client.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-signalr/azure-signalr-client.mdx new file mode 100644 index 00000000..55f82021 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-signalr/azure-signalr-client.mdx @@ -0,0 +1,132 @@ +--- +title: Azure SignalR Service hub host integration +description: Learn how to use the Azure SignalR Service to host SignalR hubs. +next: false +--- + +import { Aside } from '@astrojs/starlight/components'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; +import ThemeImage from '@components/ThemeImage.astro'; +import { Image } from 'astro:assets'; +import signalrIcon from '@assets/icons/azure-signalr-icon.png'; +import defaultMode from '@assets/integrations/cloud/azure/signalr/default-mode.svg'; +import defaultModeLight from '@assets/integrations/cloud/azure/signalr/default-mode-light.svg'; +import serverlessMode from '@assets/integrations/cloud/azure/signalr/serverless-mode.svg'; +import serverlessModeLight from '@assets/integrations/cloud/azure/signalr/serverless-mode-light.svg'; + +Azure SignalR Service icon + +There isn't an official Aspire Azure SignalR _client integration_. However, there is limited support for similar experiences. In these scenarios, the Azure SignalR Service acts as a proxy between the server (where the `Hub` or `Hub` are hosted) and the client (where the SignalR client is hosted). The Azure SignalR Service routes traffic between the server and client, allowing for real-time communication. + +For an introduction to working with the Azure SignalR Service, see [Get started with the Azure SignalR Service integration](/integrations/cloud/azure/azure-signalr/azure-signalr-get-started/). + +> [!IMPORTANT] +> It's important to disambiguate between Aspire client integrations and the .NET SignalR client. SignalR exposes hubs—which act as a server-side concept—and SignalR clients connect to those hubs. The .NET projects that host SignalR hubs are where you integrate with Aspire. The SignalR client is a separate library that connects to those hubs, in a different project. + +There are two packages available for, each with addressing specific scenarios such as managing the client connection to Azure SignalR Service, and hooking up to the Azure SignalR Service resource. To get started, install the [📦 Microsoft.Azure.SignalR](https://www.nuget.org/packages/Microsoft.Azure.SignalR) NuGet package in the project hosting your SignalR hub. + + + +### Configure named Azure SignalR Service in Default mode + +In _Default_ mode, your consuming project needs to rely on a named Azure SignalR Service resource. Consider the following diagram that illustrates the architecture of Azure SignalR Service in _Default_ mode: + + + +For more information on _Default_ mode, see [Azure SignalR Service: Default mode](https://learn.microsoft.com/azure/azure-signalr/concept-service-mode#default-mode). + +In your SignalR hub host project, configure Azure SignalR Service by chaining calls to `.AddSignalR().AddNamedAzureSignalR("name")`: + +```csharp +var builder = WebApplication.CreateBuilder(args); + +builder.Services.AddSignalR() + .AddNamedAzureSignalR("signalr"); + +var app = builder.Build(); + +app.MapHub("/chat"); + +app.Run(); +``` + +The `AddNamedAzureSignalR` method configures the project to use the Azure SignalR Service resource named `signalr`. The connection string is read from the configuration key `ConnectionStrings:signalr`, and additional settings are loaded from the `Azure:SignalR:signalr` configuration section. + +> [!NOTE] +> If you're using the Azure SignalR emulator, you cannot use the `AddNamedAzureSignalR` method. + +### Configure Azure SignalR Service in Serverless mode + +If you're AppHost is using the Azure SignalR emulator, you'll also need to install the [📦 Microsoft.Azure.SignalR.Management](https://www.nuget.org/packages/Microsoft.Azure.SignalR.Management) NuGet package. + + + +Azure SignalR _Serverless_ mode doesn't require a hub server to be running. The Azure SignalR Service is responsible for maintaining client connections. Additionally, in this mode, you cannot use traditional SignalR Hubs, such as `Microsoft.AspNetCore.SignalR.Hub`, `Microsoft.AspNetCore.SignalR.Hub`, or `Microsoft.AspNetCore.SignalR.IHubContext`. Instead, [configure an upstream endpoint which is usually an Azure Function SignalR trigger](https://learn.microsoft.com/azure/azure-signalr/concept-upstream). Consider the following diagram that illustrates the architecture of Azure SignalR Service in _Serverless_ mode: + + + +For more information on _Serverless_ mode, see [Azure SignalR Service: Serverless mode](https://learn.microsoft.com/azure/azure-signalr/concept-service-mode#serverless-mode). + +In a project that's intended to communicate with the Azure SignalR Service, register the appropriate services by calling `AddSignalR` and then registering the `ServiceManager` using the `signalr` connection string and add a `/negotiate` endpoint: + +```csharp +var builder = WebApplication.CreateBuilder(args); + +builder.Services.AddSingleton(sp => +{ + return new ServiceManagerBuilder() + .WithOptions(options => + { + options.ConnectionString = builder.Configuration.GetConnectionString("signalr"); + }) + .BuildServiceManager(); +}); + +var app = builder.Build(); + +app.MapPost("/negotiate", async (string? userId, ServiceManager sm, CancellationToken token) => +{ + // The creation of the ServiceHubContext is expensive, so it's recommended to + // only create it once per named context / per app run if possible. + var context = await sm.CreateHubContextAsync("messages", token); + + var negotiateResponse = await context.NegotiateAsync(new NegotiationOptions + { + UserId = userId + }, token); + + // The JSON serializer options need to be set to ignore null values, otherwise the + // response will contain null values for the properties that are not set. + // The .NET SignalR client will not be able to parse the response if the null values are present. + // For more information, see https://github.com/dotnet/aspnetcore/issues/60935. + return Results.Json(negotiateResponse, new JsonSerializerOptions(JsonSerializerDefaults.Web) + { + DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull + }); +}); + +app.Run(); +``` + +The preceding code configures the Azure SignalR Service using the `ServiceManagerBuilder` class, but doesn't call `AddSignalR` or `MapHub`. These two extensions aren't required with _Serverless_ mode. The connection string is read from the configuration key `ConnectionStrings:signalr`. When using the emulator, only the HTTP endpoint is available. Within the app, you can use the `ServiceManager` instance to create a `ServiceHubContext`. The `ServiceHubContext` is used to broadcast messages and manage connections to clients. + +The `/negotiate` endpoint is required to establish a connection between the connecting client and the Azure SignalR Service. The `ServiceHubContext` is created using the `ServiceManager.CreateHubContextAsync` method, which takes the hub name as a parameter. The `NegotiateAsync` method is called to negotiate the connection with the Azure SignalR Service, which returns an access token and the URL for the client to connect to. + +For more information, see [Use Azure SignalR Management SDK](https://learn.microsoft.com/azure/azure-signalr/signalr-howto-use-management-sdk). diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-signalr/azure-signalr-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-signalr/azure-signalr-get-started.mdx new file mode 100644 index 00000000..9419b52a --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-signalr/azure-signalr-get-started.mdx @@ -0,0 +1,109 @@ +--- +title: Get started with the Azure SignalR Service integration +description: Learn how to set up the Aspire Azure SignalR Service Hosting and Hub host integrations simply. +prev: false +--- + +import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components'; +import InstallPackage from '@components/InstallPackage.astro'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; +import { Image } from 'astro:assets'; +import signalrIcon from '@assets/icons/azure-signalr-icon.png'; + +Azure SignalR Service icon + +[Azure SignalR Service](https://learn.microsoft.com/azure-signalr) is a fully managed real-time messaging service that simplifies adding real-time web functionality to applications. The Aspire Azure SignalR Service integration enables you to connect to Azure SignalR instances from your applications. + +In this introduction, you'll see how to install and use the Aspire Azure SignalR Service integrations in a simple configuration. If you already have this knowledge, see [Azure SignalR Service Hosting integration](/integrations/cloud/azure/azure-signalr/azure-signalr-host/) for full reference details. + + + +## Set up hosting integration + +To begin, install the Aspire Azure SignalR Service Hosting integration in your Aspire AppHost project. This integration allows you to create and manage Azure SignalR Service resources from your Aspire hosting projects: + + + +Next, in the AppHost project, create an Azure SignalR Service resource and pass it to the consuming projects: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var signalR = builder.AddAzureSignalR("signalr"); + +var api = builder.AddProject("api") + .WithReference(signalR) + .WaitFor(signalR); + +builder.AddProject("webapp") + .WithReference(api) + .WaitFor(api); + +// After adding all resources, run the app... + +builder.Build().Run(); +``` + +The preceding code adds an Azure SignalR Service resource named `signalr` to the AppHost project. The `api` project references the SignalR service and the `webapp` project references the API. + + + + + +## Set up hub host integration + +To use Azure SignalR Service from your hub host applications, install the SignalR package in your project: + + + +In the `Program.cs` file of your hub host project, configure Azure SignalR Service by chaining calls to `.AddSignalR().AddNamedAzureSignalR("name")`: + +```csharp +var builder = WebApplication.CreateBuilder(args); + +builder.Services.AddSignalR() + .AddNamedAzureSignalR("signalr"); + +var app = builder.Build(); + +app.MapHub("/chat"); + +app.Run(); +``` + +> [!TIP] +> The name parameter must match the name used when adding the Azure SignalR Service resource in the AppHost project. + +For full details on using the hub host integration, see [Azure SignalR Service Hub host integration](/integrations/cloud/azure/azure-signalr/azure-signalr-client/). + +## Next steps + + + + + diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-signalr.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-signalr/azure-signalr-host.mdx similarity index 57% rename from src/frontend/src/content/docs/integrations/cloud/azure/azure-signalr.mdx rename to src/frontend/src/content/docs/integrations/cloud/azure/azure-signalr/azure-signalr-host.mdx index c329d367..8b179c2b 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-signalr.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-signalr/azure-signalr-host.mdx @@ -1,18 +1,12 @@ --- -title: Azure SignalR Service integration -description: This article describes the Aspire Azure SignalR Service integration features and capabilities. +title: Azure SignalR Service hosting integration +description: Learn how to use the Aspire Azure SignalR Service hosting integration to create Azure SignalR Service resources. --- import { Aside } from '@astrojs/starlight/components'; import InstallPackage from '@components/InstallPackage.astro'; -import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; -import ThemeImage from '@components/ThemeImage.astro'; import { Image } from 'astro:assets'; import signalrIcon from '@assets/icons/azure-signalr-icon.png'; -import defaultMode from '@assets/integrations/cloud/azure/signalr/default-mode.svg'; -import defaultModeLight from '@assets/integrations/cloud/azure/signalr/default-mode-light.svg'; -import serverlessMode from '@assets/integrations/cloud/azure/signalr/serverless-mode.svg'; -import serverlessModeLight from '@assets/integrations/cloud/azure/signalr/serverless-mode-light.svg'; -[Azure SignalR Service](https://learn.microsoft.com/azure-signalr) is a fully managed real-time messaging service that simplifies adding real-time web functionality to applications. The Aspire Azure SignalR Service integration enables you to connect to Azure SignalR instances from your applications. - -## Hosting integration - The Aspire Azure SignalR Service hosting integration models Azure SignalR resources as the following types: - `AzureSignalRResource`: Represents an Azure SignalR Service resource, including connection information to the underlying Azure resource. @@ -36,6 +26,8 @@ To access the hosting types and APIs for expressing these resources in the distr +For an introduction to working with the Azure SignalR Service hosting integration, see [Get started with the Azure SignalR Service integration](/integrations/cloud/azure/azure-signalr/azure-signalr-get-started/). + ### Add an Azure SignalR Service resource To add an Azure SignalR Service resource to your AppHost project, call the `AddAzureSignalR` method: @@ -249,110 +241,3 @@ When you reference an Azure SignalR resource using `WithReference`, the followin `sr` becomes `SR_URI`. -## Hub host integration - -There isn't an official Aspire Azure SignalR _client integration_. However, there is limited support for similar experiences. In these scenarios, the Azure SignalR Service acts as a proxy between the server (where the `Hub` or `Hub` are hosted) and the client (where the SignalR client is hosted). The Azure SignalR Service routes traffic between the server and client, allowing for real-time communication. - -> [!IMPORTANT] -> It's important to disambiguate between Aspire client integrations and the .NET SignalR client. SignalR exposes hubs—which act as a server-side concept—and SignalR clients connect to those hubs. The .NET projects that host SignalR hubs are where you integrate with Aspire. The SignalR client is a separate library that connects to those hubs, in a different project. - -There are two packages available for, each with addressing specific scenarios such as managing the client connection to Azure SignalR Service, and hooking up to the Azure SignalR Service resource. To get started, install the [📦 Microsoft.Azure.SignalR](https://www.nuget.org/packages/Microsoft.Azure.SignalR) NuGet package in the project hosting your SignalR hub. - - - -### Configure named Azure SignalR Service in Default mode - -In _Default_ mode, your consuming project needs to rely on a named Azure SignalR Service resource. Consider the following diagram that illustrates the architecture of Azure SignalR Service in _Default_ mode: - - - -For more information on _Default_ mode, see [Azure SignalR Service: Default mode](https://learn.microsoft.com/azure/azure-signalr/concept-service-mode#default-mode). - -In your SignalR hub host project, configure Azure SignalR Service by chaining calls to `.AddSignalR().AddNamedAzureSignalR("name")`: - -```csharp -var builder = WebApplication.CreateBuilder(args); - -builder.Services.AddSignalR() - .AddNamedAzureSignalR("signalr"); - -var app = builder.Build(); - -app.MapHub("/chat"); - -app.Run(); -``` - -The `AddNamedAzureSignalR` method configures the project to use the Azure SignalR Service resource named `signalr`. The connection string is read from the configuration key `ConnectionStrings:signalr`, and additional settings are loaded from the `Azure:SignalR:signalr` configuration section. - -> [!NOTE] -> If you're using the Azure SignalR emulator, you cannot use the `AddNamedAzureSignalR` method. - -### Configure Azure SignalR Service in Serverless mode - -If you're AppHost is using the Azure SignalR emulator, you'll also need to install the [📦 Microsoft.Azure.SignalR.Management](https://www.nuget.org/packages/Microsoft.Azure.SignalR.Management) NuGet package. - - - -Azure SignalR _Serverless_ mode doesn't require a hub server to be running. The Azure SignalR Service is responsible for maintaining client connections. Additionally, in this mode, you cannot use traditional SignalR Hubs, such as `Microsoft.AspNetCore.SignalR.Hub`, `Microsoft.AspNetCore.SignalR.Hub`, or `Microsoft.AspNetCore.SignalR.IHubContext`. Instead, [configure an upstream endpoint which is usually an Azure Function SignalR trigger](https://learn.microsoft.com/azure/azure-signalr/concept-upstream). Consider the following diagram that illustrates the architecture of Azure SignalR Service in _Serverless_ mode: - - - -For more information on _Serverless_ mode, see [Azure SignalR Service: Serverless mode](https://learn.microsoft.com/azure/azure-signalr/concept-service-mode#serverless-mode). - -In a project that's intended to communicate with the Azure SignalR Service, register the appropriate services by calling `AddSignalR` and then registering the `ServiceManager` using the `signalr` connection string and add a `/negotiate` endpoint: - -```csharp -var builder = WebApplication.CreateBuilder(args); - -builder.Services.AddSingleton(sp => -{ - return new ServiceManagerBuilder() - .WithOptions(options => - { - options.ConnectionString = builder.Configuration.GetConnectionString("signalr"); - }) - .BuildServiceManager(); -}); - -var app = builder.Build(); - -app.MapPost("/negotiate", async (string? userId, ServiceManager sm, CancellationToken token) => -{ - // The creation of the ServiceHubContext is expensive, so it's recommended to - // only create it once per named context / per app run if possible. - var context = await sm.CreateHubContextAsync("messages", token); - - var negotiateResponse = await context.NegotiateAsync(new NegotiationOptions - { - UserId = userId - }, token); - - // The JSON serializer options need to be set to ignore null values, otherwise the - // response will contain null values for the properties that are not set. - // The .NET SignalR client will not be able to parse the response if the null values are present. - // For more information, see https://github.com/dotnet/aspnetcore/issues/60935. - return Results.Json(negotiateResponse, new JsonSerializerOptions(JsonSerializerDefaults.Web) - { - DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull - }); -}); - -app.Run(); -``` - -The preceding code configures the Azure SignalR Service using the `ServiceManagerBuilder` class, but doesn't call `AddSignalR` or `MapHub`. These two extensions aren't required with _Serverless_ mode. The connection string is read from the configuration key `ConnectionStrings:signalr`. When using the emulator, only the HTTP endpoint is available. Within the app, you can use the `ServiceManager` instance to create a `ServiceHubContext`. The `ServiceHubContext` is used to broadcast messages and manage connections to clients. - -The `/negotiate` endpoint is required to establish a connection between the connecting client and the Azure SignalR Service. The `ServiceHubContext` is created using the `ServiceManager.CreateHubContextAsync` method, which takes the hub name as a parameter. The `NegotiateAsync` method is called to negotiate the connection with the Azure SignalR Service, which returns an access token and the URL for the client to connect to. - -For more information, see [Use Azure SignalR Management SDK](https://learn.microsoft.com/azure/azure-signalr/signalr-howto-use-management-sdk). diff --git a/src/frontend/src/data/integration-docs.json b/src/frontend/src/data/integration-docs.json index cfeee44b..4b6c4173 100644 --- a/src/frontend/src/data/integration-docs.json +++ b/src/frontend/src/data/integration-docs.json @@ -129,7 +129,7 @@ }, { "match": "Aspire.Hosting.Azure.SignalR", - "href": "/integrations/cloud/azure/azure-signalr/" + "href": "/integrations/cloud/azure/azure-signalr/azure-signalr-get-started/" }, { "match": "Aspire.Hosting.Azure.Sql", From 2cd998759596adffb241130633df5a3208bba630 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 15:45:34 +0000 Subject: [PATCH 18/30] Restructure Azure SQL Database integration into subfolder --- .../config/sidebar/integrations.topics.ts | 16 +- .../azure-sql-database-client.mdx | 157 ++++++++++++++++++ .../azure-sql-database-get-started.mdx | 105 ++++++++++++ .../azure-sql-database-host.mdx} | 149 +---------------- src/frontend/src/data/integration-docs.json | 2 +- 5 files changed, 282 insertions(+), 147 deletions(-) create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database/azure-sql-database-client.mdx create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database/azure-sql-database-get-started.mdx rename src/frontend/src/content/docs/integrations/cloud/azure/{azure-sql-database.mdx => azure-sql-database/azure-sql-database-host.mdx} (56%) diff --git a/src/frontend/config/sidebar/integrations.topics.ts b/src/frontend/config/sidebar/integrations.topics.ts index 37ae4d07..39a689ef 100644 --- a/src/frontend/config/sidebar/integrations.topics.ts +++ b/src/frontend/config/sidebar/integrations.topics.ts @@ -541,7 +541,21 @@ export const integrationTopics: StarlightSidebarTopicsUserConfig = { }, { label: 'Azure SQL Database', - slug: 'integrations/cloud/azure/azure-sql-database', + collapsed: true, + items: [ + { + label: 'Get started', + slug: 'integrations/cloud/azure/azure-sql-database/azure-sql-database-get-started', + }, + { + label: 'Hosting integration (AppHost)', + slug: 'integrations/cloud/azure/azure-sql-database/azure-sql-database-host', + }, + { + label: 'Client integration', + slug: 'integrations/cloud/azure/azure-sql-database/azure-sql-database-client', + }, + ], }, { label: 'Azure Storage', diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database/azure-sql-database-client.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database/azure-sql-database-client.mdx new file mode 100644 index 00000000..6e9f4c38 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database/azure-sql-database-client.mdx @@ -0,0 +1,157 @@ +--- +title: Azure SQL Database client integration +description: Learn how to use the Aspire Azure SQL Database client integration to connect to Azure SQL Database services. +next: false +--- + +import { Aside } from '@astrojs/starlight/components'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; +import { Image } from 'astro:assets'; +import sqlServerIcon from '@assets/icons/azure-sqlserver-icon.png'; + +Azure SQL Database logo + +The Aspire Azure SQL Database client integration is used to connect to an Azure SQL database using Microsoft.Data.SqlClient. To get started with the Aspire Azure SQL Database client integration, install the [📦 Aspire.Microsoft.Data.SqlClient](https://www.nuget.org/packages/Aspire.Microsoft.Data.SqlClient) NuGet package. + + + +For an introduction to working with the Azure SQL Database client integration, see [Get started with the Azure SQL Database integration](/integrations/cloud/azure/azure-sql-database/azure-sql-database-get-started/). + +### Add SQL Server client + +In the `Program.cs` file of your client-consuming project, call the `AddSqlServerClient` extension method to register a `SqlConnection` for use via the dependency injection container. The method takes a connection name parameter: + +```csharp +builder.AddSqlServerClient(connectionName: "database"); +``` + + + +After adding the `SqlConnection`, you can retrieve the connection instance using dependency injection: + +```csharp +public class ExampleService(SqlConnection connection) +{ + // Use connection... +} +``` + +For more information, see: + +- [Microsoft.Data.SqlClient documentation](https://learn.microsoft.com/sql/connect/ado-net/introduction-microsoft-data-sqlclient-namespace) for examples on using the `SqlConnection`. +- [Dependency injection in .NET](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection) for details on dependency injection. + +### Add keyed SQL client + +There might be situations where you want to register multiple `SqlConnection` instances with different connection names. To register keyed SQL clients, call the `AddKeyedSqlServerClient` method: + +```csharp +builder.AddKeyedSqlServerClient(name: "primary-db"); +builder.AddKeyedSqlServerClient(name: "secondary-db"); +``` + +Then you can retrieve the connection instances using dependency injection: + +```csharp +public class ExampleService( + [KeyedService("primary-db")] SqlConnection primaryConnection, + [KeyedService("secondary-db")] SqlConnection secondaryConnection) +{ + // Use connections... +} +``` + +For more information, see [Keyed services in .NET](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection#keyed-services). + +### Configuration + +The Aspire Azure SQL Database library provides multiple options to configure the SQL connection based on the requirements and conventions of your project. A `ConnectionString` is required. + +#### Use a connection string + +When using a connection string from the `ConnectionStrings` configuration section, you can provide the name of the connection string when calling `AddSqlServerClient`: + +```csharp +builder.AddSqlServerClient(connectionName: "database"); +``` + +The connection information is retrieved from the `ConnectionStrings` configuration section: + +```json +{ + "ConnectionStrings": { + "database": "Server=myserver;Database=mydb;User Id=myuser;Password=mypassword;Encrypt=True" + } +} +``` + +#### Use configuration providers + +The library supports `Microsoft.Extensions.Configuration`. It loads settings from configuration using the `Aspire:Microsoft:Data:SqlClient` key: + +```json +{ + "Aspire": { + "Microsoft": { + "Data": { + "SqlClient": { + "DisableHealthChecks": true, + "DisableTracing": false, + "DisableMetrics": false + } + } + } + } +} +``` + +#### Use inline delegates + +You can configure settings inline: + +```csharp +builder.AddSqlServerClient( + "database", + settings => settings.DisableHealthChecks = true); +``` + +### Observability and telemetry + +Aspire integrations automatically set up Logging, Tracing, and Metrics configurations. + +#### Logging + +The Aspire Azure SQL Database integration uses the following log categories: + +- `Microsoft.Data.SqlClient` + +#### Tracing + +The Aspire Azure SQL Database integration will emit the following tracing activities using OpenTelemetry: + +- `Microsoft.Data.SqlClient` + +#### Metrics + +The Aspire Azure SQL Database integration will emit the following metrics using OpenTelemetry: + +- `Microsoft.Data.SqlClient` + - `db.client.connections.create_time` + - `db.client.connections.use_time` + - `db.client.connections.wait_time` + - `db.client.connections.idle.max` + - `db.client.connections.idle.min` + - `db.client.connections.max` + - `db.client.connections.pending_requests` + - `db.client.connections.timeouts` + - `db.client.connections.usage` diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database/azure-sql-database-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database/azure-sql-database-get-started.mdx new file mode 100644 index 00000000..7a0d7ff2 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database/azure-sql-database-get-started.mdx @@ -0,0 +1,105 @@ +--- +title: Get started with the Azure SQL Database integration +description: Learn how to set up the Aspire Azure SQL Database Hosting and Client integrations simply. +prev: false +--- + +import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components'; +import InstallPackage from '@components/InstallPackage.astro'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; +import { Image } from 'astro:assets'; +import sqlServerIcon from '@assets/icons/azure-sqlserver-icon.png'; + +Azure SQL Database logo + +[Azure SQL](https://azure.microsoft.com/products/azure-sql) is a family of relational database management systems that run in the Azure cloud. The database systems are Platform-as-a-Service (PaaS) products that enable database administrators to implement highly scalable and available databases without maintaining complex infrastructures themselves. The Aspire Azure SQL Server Hosting integration provides methods to create a new Azure Database server and databases from code in your Aspire AppHost project. + +In this introduction, you'll see how to install and use the Aspire Azure SQL Database integrations in a simple configuration. If you already have this knowledge, see [Azure SQL Database Hosting integration](/integrations/cloud/azure/azure-sql-database/azure-sql-database-host/) for full reference details. + + + +## Set up hosting integration + +To begin, install the Aspire Azure SQL Database Hosting integration in your Aspire AppHost project. This integration allows you to create and manage Azure SQL Database resources from your Aspire hosting projects: + + + +Next, in the AppHost project, create an Azure SQL Database resource and pass it to the consuming client projects: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var azureSql = builder.AddAzureSqlServer("azuresql") + .AddDatabase("database"); + +var myService = builder.AddProject() + .WithReference(azureSql); + +// After adding all resources, run the app... + +builder.Build().Run(); +``` + +The preceding code adds an Azure SQL server resource named `azuresql` to the AppHost project, adds a database to it, and passes the database connection information to the consuming project. + + + + + +## Set up client integration + +To use Azure SQL Database from your client applications, install the Aspire SQL Server client integration in your client project: + + + +In the `Program.cs` file of your client-consuming project, call the `AddSqlServerClient` extension method to register a `SqlConnection` for use via the dependency injection container: + +```csharp +builder.AddSqlServerClient(connectionName: "database"); +``` + +> [!TIP] +> The `connectionName` parameter must match the name used when adding the SQL database resource in the AppHost project. + +After adding the `SqlConnection`, you can retrieve the connection instance using dependency injection: + +```csharp +public class ExampleService(SqlConnection connection) +{ + // Use connection... +} +``` + +For full details on using the client integration, see [Azure SQL Database Client integration](/integrations/cloud/azure/azure-sql-database/azure-sql-database-client/). + +## Next steps + + + + + diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database/azure-sql-database-host.mdx similarity index 56% rename from src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database.mdx rename to src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database/azure-sql-database-host.mdx index 82675e5d..5d24bbc8 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database/azure-sql-database-host.mdx @@ -1,11 +1,10 @@ --- -title: Azure SQL Database integration -description: This article describes the Aspire Azure SQL Database integration features and capabilities. +title: Azure SQL Database hosting integration +description: Learn how to use the Aspire Azure SQL Database hosting integration to create Azure SQL Database resources. --- import { Aside } from '@astrojs/starlight/components'; import InstallPackage from '@components/InstallPackage.astro'; -import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; import { Image } from 'astro:assets'; import sqlServerIcon from '@assets/icons/azure-sqlserver-icon.png'; @@ -18,14 +17,12 @@ import sqlServerIcon from '@assets/icons/azure-sqlserver-icon.png'; data-zoom-off /> -[Azure SQL](https://azure.microsoft.com/products/azure-sql) is a family of relational database management systems that run in the Azure cloud. The database systems are Platform-as-a-Service (PaaS) products that enable database administrators to implement highly scalable and available databases without maintaining complex infrastructures themselves. The Aspire Azure SQL Server Hosting integration provides methods to create a new Azure Database server and databases from code in your Aspire AppHost project. In a consuming project, you can use the Aspire SQL Server client integration as you would for any other SQL Server instance. - -## Hosting integration - The Aspire Azure SQL Database hosting integration models the SQL Server as the `AzureSqlServerResource` type and SQL databases as the `AzureSqlDatabaseResource` type. To access these types and APIs for expressing them within your AppHost project, install the [📦 Aspire.Hosting.Azure.Sql](https://www.nuget.org/packages/Aspire.Hosting.Azure.Sql) NuGet package: +For an introduction to working with the Azure SQL Database hosting integration, see [Get started with the Azure SQL Database integration](/integrations/cloud/azure/azure-sql-database/azure-sql-database-get-started/). + ### Add Azure SQL server resource and database resource In your AppHost project, call `AddAzureSqlServer` to add and return an Azure SQL server resource builder. Chain a call to the returned resource builder to `AddDatabase`, to add an Azure SQL database resource: @@ -127,141 +124,3 @@ The Azure SQL database resource inherits all properties from its parent Azure SQ for the JDBC connection string like `authentication=ActiveDirectoryDefault` or `authentication=ActiveDirectoryManagedIdentity`. - -## Client integration - -The Aspire Azure SQL Database client integration is used to connect to an Azure SQL database using Microsoft.Data.SqlClient. To get started with the Aspire Azure SQL Database client integration, install the [📦 Aspire.Microsoft.Data.SqlClient](https://www.nuget.org/packages/Aspire.Microsoft.Data.SqlClient) NuGet package. - - - -### Add SQL Server client - -In the `Program.cs` file of your client-consuming project, call the `AddSqlServerClient` extension method to register a `SqlConnection` for use via the dependency injection container. The method takes a connection name parameter: - -```csharp -builder.AddSqlServerClient(connectionName: "database"); -``` - - - -After adding the `SqlConnection`, you can retrieve the connection instance using dependency injection: - -```csharp -public class ExampleService(SqlConnection connection) -{ - // Use connection... -} -``` - -For more information, see: - -- [Microsoft.Data.SqlClient documentation](https://learn.microsoft.com/sql/connect/ado-net/introduction-microsoft-data-sqlclient-namespace) for examples on using the `SqlConnection`. -- [Dependency injection in .NET](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection) for details on dependency injection. - -### Add keyed SQL client - -There might be situations where you want to register multiple `SqlConnection` instances with different connection names. To register keyed SQL clients, call the `AddKeyedSqlServerClient` method: - -```csharp -builder.AddKeyedSqlServerClient(name: "primary-db"); -builder.AddKeyedSqlServerClient(name: "secondary-db"); -``` - -Then you can retrieve the connection instances using dependency injection: - -```csharp -public class ExampleService( - [KeyedService("primary-db")] SqlConnection primaryConnection, - [KeyedService("secondary-db")] SqlConnection secondaryConnection) -{ - // Use connections... -} -``` - -For more information, see [Keyed services in .NET](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection#keyed-services). - -### Configuration - -The Aspire Azure SQL Database library provides multiple options to configure the SQL connection based on the requirements and conventions of your project. A `ConnectionString` is required. - -#### Use a connection string - -When using a connection string from the `ConnectionStrings` configuration section, you can provide the name of the connection string when calling `AddSqlServerClient`: - -```csharp -builder.AddSqlServerClient(connectionName: "database"); -``` - -The connection information is retrieved from the `ConnectionStrings` configuration section: - -```json -{ - "ConnectionStrings": { - "database": "Server=myserver;Database=mydb;User Id=myuser;Password=mypassword;Encrypt=True" - } -} -``` - -#### Use configuration providers - -The library supports `Microsoft.Extensions.Configuration`. It loads settings from configuration using the `Aspire:Microsoft:Data:SqlClient` key: - -```json -{ - "Aspire": { - "Microsoft": { - "Data": { - "SqlClient": { - "DisableHealthChecks": true, - "DisableTracing": false, - "DisableMetrics": false - } - } - } - } -} -``` - -#### Use inline delegates - -You can configure settings inline: - -```csharp -builder.AddSqlServerClient( - "database", - settings => settings.DisableHealthChecks = true); -``` - -### Observability and telemetry - -Aspire integrations automatically set up Logging, Tracing, and Metrics configurations. - -#### Logging - -The Aspire Azure SQL Database integration uses the following log categories: - -- `Microsoft.Data.SqlClient` - -#### Tracing - -The Aspire Azure SQL Database integration will emit the following tracing activities using OpenTelemetry: - -- `Microsoft.Data.SqlClient` - -#### Metrics - -The Aspire Azure SQL Database integration will emit the following metrics using OpenTelemetry: - -- `Microsoft.Data.SqlClient` - - `db.client.connections.create_time` - - `db.client.connections.use_time` - - `db.client.connections.wait_time` - - `db.client.connections.idle.max` - - `db.client.connections.idle.min` - - `db.client.connections.max` - - `db.client.connections.pending_requests` - - `db.client.connections.timeouts` - - `db.client.connections.usage` diff --git a/src/frontend/src/data/integration-docs.json b/src/frontend/src/data/integration-docs.json index 4b6c4173..d951a3de 100644 --- a/src/frontend/src/data/integration-docs.json +++ b/src/frontend/src/data/integration-docs.json @@ -133,7 +133,7 @@ }, { "match": "Aspire.Hosting.Azure.Sql", - "href": "/integrations/cloud/azure/azure-sql-database/" + "href": "/integrations/cloud/azure/azure-sql-database/azure-sql-database-get-started/" }, { "match": "Aspire.Hosting.Azure.Storage", From 8ed230687fa71147e9a02b2db64eeba862a8c637 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 15:48:40 +0000 Subject: [PATCH 19/30] Restructure Azure Blob Storage integration into subfolder --- .../config/sidebar/integrations.topics.ts | 20 +- .../azure-storage-blobs-client.mdx | 178 +++++++++++++++++ .../azure-storage-blobs-get-started.mdx | 21 ++ .../azure-storage-blobs-host.mdx} | 188 +----------------- src/frontend/src/data/integration-docs.json | 2 +- 5 files changed, 219 insertions(+), 190 deletions(-) create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-client.mdx create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-get-started.mdx rename src/frontend/src/content/docs/integrations/cloud/azure/{azure-storage-blobs.mdx => azure-storage-blobs/azure-storage-blobs-host.mdx} (67%) diff --git a/src/frontend/config/sidebar/integrations.topics.ts b/src/frontend/config/sidebar/integrations.topics.ts index 39a689ef..e56cbc8d 100644 --- a/src/frontend/config/sidebar/integrations.topics.ts +++ b/src/frontend/config/sidebar/integrations.topics.ts @@ -558,13 +558,27 @@ export const integrationTopics: StarlightSidebarTopicsUserConfig = { ], }, { - label: 'Azure Storage', + label: 'Azure Storage Blobs', collapsed: true, items: [ { - label: 'Azure Storage Blobs', - slug: 'integrations/cloud/azure/azure-storage-blobs', + label: 'Get started', + slug: 'integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-get-started', + }, + { + label: 'Hosting integration', + slug: 'integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-host', + }, + { + label: 'Client integration', + slug: 'integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-client', }, + ], + }, + { + label: 'Azure Storage', + collapsed: true, + items: [ { label: 'Azure Storage Queues', slug: 'integrations/cloud/azure/azure-storage-queues', diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-client.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-client.mdx new file mode 100644 index 00000000..f9a99259 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-client.mdx @@ -0,0 +1,178 @@ +--- +title: Azure Blob Storage - Client integration +description: Learn how to use the Azure Blob Storage client integration. +--- + +import { Aside } from '@astrojs/starlight/components'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; + +## Client integration + +To get started with the Aspire Azure Blob Storage client integration, install the [📦 Aspire.Azure.Storage.Blobs](https://www.nuget.org/packages/Aspire.Azure.Storage.Blobs) NuGet package: + + + +### Add Azure Blob Storage client + +In the `Program.cs` file of your client-consuming project, call the `AddAzureBlobServiceClient` extension method to register a `BlobServiceClient` for dependency injection. The method takes a connection name parameter: + +```csharp +builder.AddAzureBlobServiceClient("blobs"); +``` + +You can then retrieve the `BlobServiceClient` instance using dependency injection: + +```csharp +public class ExampleService(BlobServiceClient client) +{ + // Use client... +} +``` + +### Configuration + +The Azure Blob Storage integration provides multiple options to configure the `BlobServiceClient`. + +#### Use a connection string + +When using a connection string from the `ConnectionStrings` configuration section, provide the name when calling `AddAzureBlobServiceClient`: + +```csharp +builder.AddAzureBlobServiceClient("blobs"); +``` + +Two connection formats are supported: + +##### Service URI + +The recommended approach is to use a `ServiceUri`, which works with the `Credential` property. If no credential is configured, the `DefaultAzureCredential` is used: + +```json +{ + "ConnectionStrings": { + "blobs": "https://{account_name}.blob.core.windows.net/" + } +} +``` + +##### Connection string + +Alternatively, an [Azure Storage connection string](https://learn.microsoft.com/azure/storage/common/storage-configure-connection-string) can be used: + +```json +{ + "ConnectionStrings": { + "blobs": "AccountName=myaccount;AccountKey=myaccountkey" + } +} +``` + +#### Use configuration providers + +The Azure Blob Storage integration supports `Microsoft.Extensions.Configuration`. It loads the `AzureStorageBlobsSettings` and `BlobClientOptions` from configuration using the `Aspire:Azure:Storage:Blobs` key. Example `appsettings.json`: + +```json +{ + "Aspire": { + "Azure": { + "Storage": { + "Blobs": { + "DisableHealthChecks": true, + "DisableTracing": false, + "ClientOptions": { + "Diagnostics": { + "ApplicationId": "myapp" + } + } + } + } + } + } +} +``` + +#### Use named configuration + +The Azure Blob Storage integration supports named configuration for multiple instances: + +```json +{ + "Aspire": { + "Azure": { + "Storage": { + "Blobs": { + "blob1": { + "DisableHealthChecks": true, + "ClientOptions": { + "Diagnostics": { + "ApplicationId": "myapp1" + } + } + }, + "blob2": { + "DisableTracing": true, + "ClientOptions": { + "Diagnostics": { + "ApplicationId": "myapp2" + } + } + } + } + } + } + } +} +``` + +Use the connection names when calling `AddAzureBlobServiceClient`: + +```csharp +builder.AddAzureBlobServiceClient("blob1"); +builder.AddAzureBlobServiceClient("blob2"); +``` + +#### Use inline delegates + +You can also pass the `Action` delegate to set up options inline: + +```csharp +builder.AddAzureBlobServiceClient( + "blobs", + settings => settings.DisableHealthChecks = true); +``` + +You can also configure the `BlobClientOptions`: + +```csharp +builder.AddAzureBlobServiceClient( + "blobs", + configureClientBuilder: clientBuilder => + clientBuilder.ConfigureOptions( + options => options.Diagnostics.ApplicationId = "myapp")); +``` + +### Client integration health checks + +By default, Aspire integrations enable health checks for all services. The Azure Blob Storage integration: + +- Adds the health check when `DisableHealthChecks` is `false`, which attempts to connect to the Azure Blob Storage. +- Integrates with the `/health` HTTP endpoint, which specifies all registered health checks must pass for app to be considered ready to accept traffic. + +### Observability and telemetry + +#### Logging + +The Azure Blob Storage integration uses the following log categories: + +- `Azure.Core` +- `Azure.Identity` + +#### Tracing + +The Azure Blob Storage integration emits the following tracing activities using OpenTelemetry: + +- `Azure.Storage.Blobs.BlobContainerClient` + +#### Metrics + +The Azure Blob Storage integration currently doesn't support metrics by default due to limitations with the Azure SDK. diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-get-started.mdx new file mode 100644 index 00000000..2b6398d9 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-get-started.mdx @@ -0,0 +1,21 @@ +--- +title: Azure Blob Storage +description: Learn how to use the Azure Blob Storage integration, which includes both hosting and client integrations. +--- + +import { Image } from 'astro:assets'; +import storageIcon from '@assets/icons/azure-storagecontainer-icon.png'; +import IntegrationNavigationLinks from '@components/IntegrationNavigationLinks.astro'; + +Azure Blob Storage logo + +[Azure Blob Storage](https://azure.microsoft.com/services/storage/blobs/) is a service for storing large amounts of unstructured data. The Aspire Azure Blob Storage integration enables you to connect to existing Azure Storage instances or create new instances from applications with the [`mcr.microsoft.com/azure-storage/azurite` container image](https://mcr.microsoft.com/product/azure-storage/azurite/about). + + diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-blobs.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-host.mdx similarity index 67% rename from src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-blobs.mdx rename to src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-host.mdx index b7c013f5..f9b8e853 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-blobs.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-host.mdx @@ -1,26 +1,13 @@ --- -title: Azure Blob Storage -description: Learn how to use the Azure Blob Storage integration, which includes both hosting and client integrations. +title: Azure Blob Storage - Hosting integration +description: Learn how to use the Azure Blob Storage hosting integration. --- import { Aside, Steps } from '@astrojs/starlight/components'; import { Image } from 'astro:assets'; import InstallPackage from '@components/InstallPackage.astro'; -import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; -import storageIcon from '@assets/icons/azure-storagecontainer-icon.png'; import storageExplorerImage from '@assets/integrations/cloud/azure/storage/azure-storage-explorer.png'; -Azure Blob Storage logo - -[Azure Blob Storage](https://azure.microsoft.com/services/storage/blobs/) is a service for storing large amounts of unstructured data. The Aspire Azure Blob Storage integration enables you to connect to existing Azure Storage instances or create new instances from applications with the [`mcr.microsoft.com/azure-storage/azurite` container image](https://mcr.microsoft.com/product/azure-storage/azurite/about). - ## Hosting integration The Aspire [Azure Storage](https://learn.microsoft.com/azure/storage/) hosting integration models the various storage resources as the following types: @@ -232,174 +219,3 @@ The Blob Container resource inherits all properties from its parent `AzureBlobSt - -## Client integration - -To get started with the Aspire Azure Blob Storage client integration, install the [📦 Aspire.Azure.Storage.Blobs](https://www.nuget.org/packages/Aspire.Azure.Storage.Blobs) NuGet package: - - - -### Add Azure Blob Storage client - -In the `Program.cs` file of your client-consuming project, call the `AddAzureBlobServiceClient` extension method to register a `BlobServiceClient` for dependency injection. The method takes a connection name parameter: - -```csharp -builder.AddAzureBlobServiceClient("blobs"); -``` - -You can then retrieve the `BlobServiceClient` instance using dependency injection: - -```csharp -public class ExampleService(BlobServiceClient client) -{ - // Use client... -} -``` - -### Configuration - -The Azure Blob Storage integration provides multiple options to configure the `BlobServiceClient`. - -#### Use a connection string - -When using a connection string from the `ConnectionStrings` configuration section, provide the name when calling `AddAzureBlobServiceClient`: - -```csharp -builder.AddAzureBlobServiceClient("blobs"); -``` - -Two connection formats are supported: - -##### Service URI - -The recommended approach is to use a `ServiceUri`, which works with the `Credential` property. If no credential is configured, the `DefaultAzureCredential` is used: - -```json -{ - "ConnectionStrings": { - "blobs": "https://{account_name}.blob.core.windows.net/" - } -} -``` - -##### Connection string - -Alternatively, an [Azure Storage connection string](https://learn.microsoft.com/azure/storage/common/storage-configure-connection-string) can be used: - -```json -{ - "ConnectionStrings": { - "blobs": "AccountName=myaccount;AccountKey=myaccountkey" - } -} -``` - -#### Use configuration providers - -The Azure Blob Storage integration supports `Microsoft.Extensions.Configuration`. It loads the `AzureStorageBlobsSettings` and `BlobClientOptions` from configuration using the `Aspire:Azure:Storage:Blobs` key. Example `appsettings.json`: - -```json -{ - "Aspire": { - "Azure": { - "Storage": { - "Blobs": { - "DisableHealthChecks": true, - "DisableTracing": false, - "ClientOptions": { - "Diagnostics": { - "ApplicationId": "myapp" - } - } - } - } - } - } -} -``` - -#### Use named configuration - -The Azure Blob Storage integration supports named configuration for multiple instances: - -```json -{ - "Aspire": { - "Azure": { - "Storage": { - "Blobs": { - "blob1": { - "DisableHealthChecks": true, - "ClientOptions": { - "Diagnostics": { - "ApplicationId": "myapp1" - } - } - }, - "blob2": { - "DisableTracing": true, - "ClientOptions": { - "Diagnostics": { - "ApplicationId": "myapp2" - } - } - } - } - } - } - } -} -``` - -Use the connection names when calling `AddAzureBlobServiceClient`: - -```csharp -builder.AddAzureBlobServiceClient("blob1"); -builder.AddAzureBlobServiceClient("blob2"); -``` - -#### Use inline delegates - -You can also pass the `Action` delegate to set up options inline: - -```csharp -builder.AddAzureBlobServiceClient( - "blobs", - settings => settings.DisableHealthChecks = true); -``` - -You can also configure the `BlobClientOptions`: - -```csharp -builder.AddAzureBlobServiceClient( - "blobs", - configureClientBuilder: clientBuilder => - clientBuilder.ConfigureOptions( - options => options.Diagnostics.ApplicationId = "myapp")); -``` - -### Client integration health checks - -By default, Aspire integrations enable health checks for all services. The Azure Blob Storage integration: - -- Adds the health check when `DisableHealthChecks` is `false`, which attempts to connect to the Azure Blob Storage. -- Integrates with the `/health` HTTP endpoint, which specifies all registered health checks must pass for app to be considered ready to accept traffic. - -### Observability and telemetry - -#### Logging - -The Azure Blob Storage integration uses the following log categories: - -- `Azure.Core` -- `Azure.Identity` - -#### Tracing - -The Azure Blob Storage integration emits the following tracing activities using OpenTelemetry: - -- `Azure.Storage.Blobs.BlobContainerClient` - -#### Metrics - -The Azure Blob Storage integration currently doesn't support metrics by default due to limitations with the Azure SDK. diff --git a/src/frontend/src/data/integration-docs.json b/src/frontend/src/data/integration-docs.json index d951a3de..2d4a0f41 100644 --- a/src/frontend/src/data/integration-docs.json +++ b/src/frontend/src/data/integration-docs.json @@ -41,7 +41,7 @@ }, { "match": "Aspire.Azure.Storage.Blobs", - "href": "/integrations/cloud/azure/azure-storage-blobs/" + "href": "/integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-get-started/" }, { "match": "Aspire.Azure.Storage.Queues", From 23438e3125f1aa7d27ea6c273991b9dc98399d81 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 15:50:14 +0000 Subject: [PATCH 20/30] Restructure Azure Queue Storage integration into subfolder --- .../config/sidebar/integrations.topics.ts | 20 +- .../azure-storage-queues-client.mdx | 178 ++++++++++++++++ .../azure-storage-queues-get-started.mdx | 21 ++ .../azure-storage-queues-host.mdx} | 190 +----------------- src/frontend/src/data/integration-docs.json | 2 +- 5 files changed, 220 insertions(+), 191 deletions(-) create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-queues/azure-storage-queues-client.mdx create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-queues/azure-storage-queues-get-started.mdx rename src/frontend/src/content/docs/integrations/cloud/azure/{azure-storage-queues.mdx => azure-storage-queues/azure-storage-queues-host.mdx} (67%) diff --git a/src/frontend/config/sidebar/integrations.topics.ts b/src/frontend/config/sidebar/integrations.topics.ts index e56cbc8d..4052623c 100644 --- a/src/frontend/config/sidebar/integrations.topics.ts +++ b/src/frontend/config/sidebar/integrations.topics.ts @@ -576,13 +576,27 @@ export const integrationTopics: StarlightSidebarTopicsUserConfig = { ], }, { - label: 'Azure Storage', + label: 'Azure Storage Queues', collapsed: true, items: [ { - label: 'Azure Storage Queues', - slug: 'integrations/cloud/azure/azure-storage-queues', + label: 'Get started', + slug: 'integrations/cloud/azure/azure-storage-queues/azure-storage-queues-get-started', + }, + { + label: 'Hosting integration', + slug: 'integrations/cloud/azure/azure-storage-queues/azure-storage-queues-host', + }, + { + label: 'Client integration', + slug: 'integrations/cloud/azure/azure-storage-queues/azure-storage-queues-client', }, + ], + }, + { + label: 'Azure Storage', + collapsed: true, + items: [ { label: 'Azure Storage Tables', slug: 'integrations/cloud/azure/azure-storage-tables', diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-queues/azure-storage-queues-client.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-queues/azure-storage-queues-client.mdx new file mode 100644 index 00000000..5f7ce876 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-queues/azure-storage-queues-client.mdx @@ -0,0 +1,178 @@ +--- +title: Azure Queue Storage - Client integration +description: Learn how to use the Azure Queue Storage client integration. +--- + +import { Aside } from '@astrojs/starlight/components'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; + +## Client integration + +To get started with the Aspire Azure Queue Storage client integration, install the [📦 Aspire.Azure.Storage.Queues](https://www.nuget.org/packages/Aspire.Azure.Storage.Queues) NuGet package: + + + +### Add Azure Queue Storage client + +In the `Program.cs` file of your client-consuming project, call the `AddAzureQueueClient` extension method to register a `QueueServiceClient` for dependency injection. The method takes a connection name parameter: + +```csharp +builder.AddAzureQueueClient("queues"); +``` + +You can then retrieve the `QueueServiceClient` instance using dependency injection: + +```csharp +public class ExampleService(QueueServiceClient client) +{ + // Use client... +} +``` + +### Configuration + +The Azure Queue Storage integration provides multiple options to configure the `QueueServiceClient`. + +#### Use a connection string + +When using a connection string from the `ConnectionStrings` configuration section, provide the name when calling `AddAzureQueueClient`: + +```csharp +builder.AddAzureQueueClient("queues"); +``` + +Two connection formats are supported: + +##### Service URI + +The recommended approach is to use a `ServiceUri`, which works with the `Credential` property. If no credential is configured, the `DefaultAzureCredential` is used: + +```json +{ + "ConnectionStrings": { + "queues": "https://{account_name}.queue.core.windows.net/" + } +} +``` + +##### Connection string + +Alternatively, an [Azure Storage connection string](https://learn.microsoft.com/azure/storage/common/storage-configure-connection-string) can be used: + +```json +{ + "ConnectionStrings": { + "queues": "AccountName=myaccount;AccountKey=myaccountkey" + } +} +``` + +#### Use configuration providers + +The Azure Queue Storage integration supports `Microsoft.Extensions.Configuration`. It loads the `AzureStorageQueuesSettings` and `QueueClientOptions` from configuration using the `Aspire:Azure:Storage:Queues` key. Example `appsettings.json`: + +```json +{ + "Aspire": { + "Azure": { + "Storage": { + "Queues": { + "DisableHealthChecks": true, + "DisableTracing": false, + "ClientOptions": { + "Diagnostics": { + "ApplicationId": "myapp" + } + } + } + } + } + } +} +``` + +#### Use named configuration + +The Azure Queue Storage integration supports named configuration for multiple instances: + +```json +{ + "Aspire": { + "Azure": { + "Storage": { + "Queues": { + "queue1": { + "DisableHealthChecks": true, + "ClientOptions": { + "Diagnostics": { + "ApplicationId": "myapp1" + } + } + }, + "queue2": { + "DisableTracing": true, + "ClientOptions": { + "Diagnostics": { + "ApplicationId": "myapp2" + } + } + } + } + } + } + } +} +``` + +Use the connection names when calling `AddAzureQueueClient`: + +```csharp +builder.AddAzureQueueClient("queue1"); +builder.AddAzureQueueClient("queue2"); +``` + +#### Use inline delegates + +You can also pass the `Action` delegate to set up options inline: + +```csharp +builder.AddAzureQueueClient( + "queues", + settings => settings.DisableHealthChecks = true); +``` + +You can also configure the `QueueClientOptions`: + +```csharp +builder.AddAzureQueueClient( + "queues", + configureClientBuilder: clientBuilder => + clientBuilder.ConfigureOptions( + options => options.Diagnostics.ApplicationId = "myapp")); +``` + +### Client integration health checks + +By default, Aspire integrations enable health checks for all services. The Azure Queue Storage integration: + +- Adds the health check when `DisableHealthChecks` is `false`, which attempts to connect to the Azure Queue Storage. +- Integrates with the `/health` HTTP endpoint, which specifies all registered health checks must pass for app to be considered ready to accept traffic. + +### Observability and telemetry + +#### Logging + +The Azure Queue Storage integration uses the following log categories: + +- `Azure.Core` +- `Azure.Identity` + +#### Tracing + +The Azure Queue Storage integration emits the following tracing activities using OpenTelemetry: + +- `Azure.Storage.Queues.QueueClient` + +#### Metrics + +The Azure Queue Storage integration currently doesn't support metrics by default due to limitations with the Azure SDK. diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-queues/azure-storage-queues-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-queues/azure-storage-queues-get-started.mdx new file mode 100644 index 00000000..75ab0272 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-queues/azure-storage-queues-get-started.mdx @@ -0,0 +1,21 @@ +--- +title: Azure Queue Storage +description: Learn how to use the Azure Queue Storage integration, which includes both hosting and client integrations. +--- + +import { Image } from 'astro:assets'; +import queueIcon from '@assets/icons/azure-storagequeue-icon.png'; +import IntegrationNavigationLinks from '@components/IntegrationNavigationLinks.astro'; + +Azure Queue Storage logo + +[Azure Queue Storage](https://azure.microsoft.com/services/storage/queues/) is a service for storing large amounts of unstructured data. The Aspire Azure Blob Storage integration enables you to connect to existing Azure Storage instances or create new instances from applications with the [`mcr.microsoft.com/azure-storage/azurite` container image](https://mcr.microsoft.com/product/azure-storage/azurite/about). + + diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-queues.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-queues/azure-storage-queues-host.mdx similarity index 67% rename from src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-queues.mdx rename to src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-queues/azure-storage-queues-host.mdx index 07de721b..d95bb962 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-queues.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-queues/azure-storage-queues-host.mdx @@ -1,26 +1,13 @@ --- -title: Azure Queue Storage -description: Learn how to use the Azure Queue Storage integration, which includes both hosting and client integrations. +title: Azure Queue Storage - Hosting integration +description: Learn how to use the Azure Queue Storage hosting integration. --- import { Aside, Steps } from '@astrojs/starlight/components'; -import InstallPackage from '@components/InstallPackage.astro'; -import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; import { Image } from 'astro:assets'; -import queueIcon from '@assets/icons/azure-storagequeue-icon.png'; +import InstallPackage from '@components/InstallPackage.astro'; import storageExplorerImage from '@assets/integrations/cloud/azure/storage/azure-storage-explorer.png'; -Azure Queue Storage logo - -[Azure Queue Storage](https://azure.microsoft.com/services/storage/queues/) is a service for storing large amounts of unstructured data. The Aspire Azure Blob Storage integration enables you to connect to existing Azure Storage instances or create new instances from applications with the [`mcr.microsoft.com/azure-storage/azurite` container image](https://mcr.microsoft.com/product/azure-storage/azurite/about). - ## Hosting integration The Aspire [Azure Storage](https://learn.microsoft.com/azure/storage/) hosting integration models the various storage resources as the following types: @@ -229,174 +216,3 @@ The Queue resource inherits all properties from its parent `AzureQueueStorageRes - -## Client integration - -To get started with the Aspire Azure Queue Storage client integration, install the [📦 Aspire.Azure.Storage.Queues](https://www.nuget.org/packages/Aspire.Azure.Storage.Queues) NuGet package: - - - -### Add Azure Queue Storage client - -In the `Program.cs` file of your client-consuming project, call the `AddAzureQueueClient` extension method to register a `QueueServiceClient` for dependency injection. The method takes a connection name parameter: - -```csharp -builder.AddAzureQueueClient("queues"); -``` - -You can then retrieve the `QueueServiceClient` instance using dependency injection: - -```csharp -public class ExampleService(QueueServiceClient client) -{ - // Use client... -} -``` - -### Configuration - -The Azure Queue Storage integration provides multiple options to configure the `QueueServiceClient`. - -#### Use a connection string - -When using a connection string from the `ConnectionStrings` configuration section, provide the name when calling `AddAzureQueueClient`: - -```csharp -builder.AddAzureQueueClient("queues"); -``` - -Two connection formats are supported: - -##### Service URI - -The recommended approach is to use a `ServiceUri`, which works with the `Credential` property. If no credential is configured, the `DefaultAzureCredential` is used: - -```json -{ - "ConnectionStrings": { - "queues": "https://{account_name}.queue.core.windows.net/" - } -} -``` - -##### Connection string - -Alternatively, an [Azure Storage connection string](https://learn.microsoft.com/azure/storage/common/storage-configure-connection-string) can be used: - -```json -{ - "ConnectionStrings": { - "queues": "AccountName=myaccount;AccountKey=myaccountkey" - } -} -``` - -#### Use configuration providers - -The Azure Queue Storage integration supports `Microsoft.Extensions.Configuration`. It loads the `AzureStorageQueuesSettings` and `QueueClientOptions` from configuration using the `Aspire:Azure:Storage:Queues` key. Example `appsettings.json`: - -```json -{ - "Aspire": { - "Azure": { - "Storage": { - "Queues": { - "DisableHealthChecks": true, - "DisableTracing": false, - "ClientOptions": { - "Diagnostics": { - "ApplicationId": "myapp" - } - } - } - } - } - } -} -``` - -#### Use named configuration - -The Azure Queue Storage integration supports named configuration for multiple instances: - -```json -{ - "Aspire": { - "Azure": { - "Storage": { - "Queues": { - "queue1": { - "DisableHealthChecks": true, - "ClientOptions": { - "Diagnostics": { - "ApplicationId": "myapp1" - } - } - }, - "queue2": { - "DisableTracing": true, - "ClientOptions": { - "Diagnostics": { - "ApplicationId": "myapp2" - } - } - } - } - } - } - } -} -``` - -Use the connection names when calling `AddAzureQueueClient`: - -```csharp -builder.AddAzureQueueClient("queue1"); -builder.AddAzureQueueClient("queue2"); -``` - -#### Use inline delegates - -You can also pass the `Action` delegate to set up options inline: - -```csharp -builder.AddAzureQueueClient( - "queues", - settings => settings.DisableHealthChecks = true); -``` - -You can also configure the `QueueClientOptions`: - -```csharp -builder.AddAzureQueueClient( - "queues", - configureClientBuilder: clientBuilder => - clientBuilder.ConfigureOptions( - options => options.Diagnostics.ApplicationId = "myapp")); -``` - -### Client integration health checks - -By default, Aspire integrations enable health checks for all services. The Azure Queue Storage integration: - -- Adds the health check when `DisableHealthChecks` is `false`, which attempts to connect to the Azure Queue Storage. -- Integrates with the `/health` HTTP endpoint, which specifies all registered health checks must pass for app to be considered ready to accept traffic. - -### Observability and telemetry - -#### Logging - -The Azure Queue Storage integration uses the following log categories: - -- `Azure.Core` -- `Azure.Identity` - -#### Tracing - -The Azure Queue Storage integration emits the following tracing activities using OpenTelemetry: - -- `Azure.Storage.Queues.QueueClient` - -#### Metrics - -The Azure Queue Storage integration currently doesn't support metrics by default due to limitations with the Azure SDK. diff --git a/src/frontend/src/data/integration-docs.json b/src/frontend/src/data/integration-docs.json index 2d4a0f41..56d536de 100644 --- a/src/frontend/src/data/integration-docs.json +++ b/src/frontend/src/data/integration-docs.json @@ -45,7 +45,7 @@ }, { "match": "Aspire.Azure.Storage.Queues", - "href": "/integrations/cloud/azure/azure-storage-queues/" + "href": "/integrations/cloud/azure/azure-storage-queues/azure-storage-queues-get-started/" }, { "match": "Aspire.Confluent.Kafka", From e0d6d4489f99e6cfec6b9d5ce96aa6130eb5a2a8 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 15:51:47 +0000 Subject: [PATCH 21/30] Restructure Azure Table Storage integration into subfolder --- .../config/sidebar/integrations.topics.ts | 14 +- .../azure-storage-tables-client.mdx | 141 ++++++++++++++++ .../azure-storage-tables-get-started.mdx | 21 +++ .../azure-storage-tables-host.mdx} | 153 +----------------- src/frontend/src/data/integration-docs.json | 2 +- 5 files changed, 177 insertions(+), 154 deletions(-) create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-tables/azure-storage-tables-client.mdx create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-tables/azure-storage-tables-get-started.mdx rename src/frontend/src/content/docs/integrations/cloud/azure/{azure-storage-tables.mdx => azure-storage-tables/azure-storage-tables-host.mdx} (70%) diff --git a/src/frontend/config/sidebar/integrations.topics.ts b/src/frontend/config/sidebar/integrations.topics.ts index 4052623c..39436421 100644 --- a/src/frontend/config/sidebar/integrations.topics.ts +++ b/src/frontend/config/sidebar/integrations.topics.ts @@ -594,12 +594,20 @@ export const integrationTopics: StarlightSidebarTopicsUserConfig = { ], }, { - label: 'Azure Storage', + label: 'Azure Storage Tables', collapsed: true, items: [ { - label: 'Azure Storage Tables', - slug: 'integrations/cloud/azure/azure-storage-tables', + label: 'Get started', + slug: 'integrations/cloud/azure/azure-storage-tables/azure-storage-tables-get-started', + }, + { + label: 'Hosting integration', + slug: 'integrations/cloud/azure/azure-storage-tables/azure-storage-tables-host', + }, + { + label: 'Client integration', + slug: 'integrations/cloud/azure/azure-storage-tables/azure-storage-tables-client', }, ], }, diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-tables/azure-storage-tables-client.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-tables/azure-storage-tables-client.mdx new file mode 100644 index 00000000..0e4d40c9 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-tables/azure-storage-tables-client.mdx @@ -0,0 +1,141 @@ +--- +title: Azure Table Storage - Client integration +description: Learn how to use the Azure Table Storage client integration. +--- + +import { Aside } from '@astrojs/starlight/components'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; + +## Client integration + +To get started with the Aspire Azure Table Storage client integration, install the [📦 Aspire.Azure.Data.Tables](https://www.nuget.org/packages/Aspire.Azure.Data.Tables) NuGet package: + + + +### Add Azure Table Storage client + +In the `Program.cs` file of your client-consuming project, call the `AddAzureTableClient` extension method to register a `TableServiceClient` for dependency injection. The method takes a connection name parameter: + +```csharp +builder.AddAzureTableClient("tables"); +``` + +You can then retrieve the `TableServiceClient` instance using dependency injection: + +```csharp +public class ExampleService(TableServiceClient client) +{ + // Use client... +} +``` + +### Configuration + +The Azure Table Storage integration provides multiple options to configure the `TableServiceClient`. + +#### Use configuration providers + +The Azure Table Storage integration supports `Microsoft.Extensions.Configuration`. It loads the `AzureDataTablesSettings` and `TableClientOptions` from configuration using the `Aspire:Azure:Data:Tables` key. Example `appsettings.json`: + +```json +{ + "Aspire": { + "Azure": { + "Data": { + "Tables": { + "ServiceUri": "YOUR_URI", + "DisableHealthChecks": true, + "DisableTracing": false, + "ClientOptions": { + "EnableTenantDiscovery": true + } + } + } + } + } +} +``` + +#### Use named configuration + +The Azure Table Storage integration supports named configuration for multiple instances: + +```json +{ + "Aspire": { + "Azure": { + "Data": { + "Tables": { + "tables1": { + "ServiceUri": "https://myaccount1.table.core.windows.net/", + "DisableHealthChecks": true, + "ClientOptions": { + "EnableTenantDiscovery": true + } + }, + "tables2": { + "ServiceUri": "https://myaccount2.table.core.windows.net/", + "DisableTracing": true, + "ClientOptions": { + "EnableTenantDiscovery": false + } + } + } + } + } + } +} +``` + +Use the connection names when calling `AddAzureTableClient`: + +```csharp +builder.AddAzureTableClient("tables1"); +builder.AddAzureTableClient("tables2"); +``` + +#### Use inline delegates + +You can also pass the `Action` delegate to set up options inline: + +```csharp +builder.AddAzureTableClient( + "tables", + settings => settings.DisableHealthChecks = true); +``` + +You can also configure the `TableClientOptions`: + +```csharp +builder.AddAzureTableClient( + "tables", + configureClientBuilder: clientBuilder => + clientBuilder.ConfigureOptions( + options => options.EnableTenantDiscovery = true)); +``` + +### Client integration health checks + +By default, Aspire integrations enable health checks for all services. The Azure Table Storage integration: + +- Adds the health check when `DisableHealthChecks` is `false`, which attempts to connect to the Azure Table Storage. +- Integrates with the `/health` HTTP endpoint, which specifies all registered health checks must pass for app to be considered ready to accept traffic. + +### Observability and telemetry + +#### Logging + +The Azure Table Storage integration uses the following log categories: + +- `Azure.Core` +- `Azure.Identity` + +#### Tracing + +The Azure Table Storage integration emits the following tracing activities using OpenTelemetry: + +- `Azure.Data.Tables.TableServiceClient` + +#### Metrics + +The Azure Table Storage integration currently doesn't support metrics by default due to limitations with the Azure SDK. diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-tables/azure-storage-tables-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-tables/azure-storage-tables-get-started.mdx new file mode 100644 index 00000000..fec2ae16 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-tables/azure-storage-tables-get-started.mdx @@ -0,0 +1,21 @@ +--- +title: Azure Table Storage +description: Learn how to use the Azure Table Storage integration to store structured NoSQL data in Azure Storage tables. +--- + +import { Image } from 'astro:assets'; +import tableIcon from '@assets/icons/azure-table-icon.png'; +import IntegrationNavigationLinks from '@components/IntegrationNavigationLinks.astro'; + +Azure Table Storage logo + +[Azure Table Storage](https://learn.microsoft.com/azure/storage/tables/table-storage-overview) is a service for storing large amounts of unstructured data. The Aspire Azure Blob Storage integration enables you to connect to existing Azure Storage instances or create new instances from applications with the [`mcr.microsoft.com/azure-storage/azurite` container image](https://mcr.microsoft.com/product/azure-storage/azurite/about). + + diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-tables.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-tables/azure-storage-tables-host.mdx similarity index 70% rename from src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-tables.mdx rename to src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-tables/azure-storage-tables-host.mdx index 0f099997..672649ec 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-tables.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-tables/azure-storage-tables-host.mdx @@ -1,26 +1,13 @@ --- -title: Azure Table Storage -description: Learn how to use the Azure Table Storage integration to store structured NoSQL data in Azure Storage tables. +title: Azure Table Storage - Hosting integration +description: Learn how to use the Azure Table Storage hosting integration. --- -import InstallPackage from '@components/InstallPackage.astro'; -import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; import { Aside, Steps } from '@astrojs/starlight/components'; import { Image } from 'astro:assets'; -import tableIcon from '@assets/icons/azure-table-icon.png'; +import InstallPackage from '@components/InstallPackage.astro'; import storageExplorerImage from '@assets/integrations/cloud/azure/storage/azure-storage-explorer.png'; -Azure Table Storage logo - -[Azure Table Storage](https://learn.microsoft.com/azure/storage/tables/table-storage-overview) is a service for storing large amounts of unstructured data. The Aspire Azure Blob Storage integration enables you to connect to existing Azure Storage instances or create new instances from applications with the [`mcr.microsoft.com/azure-storage/azurite` container image](https://mcr.microsoft.com/product/azure-storage/azurite/about). - ## Hosting integration The Aspire [Azure Storage](https://learn.microsoft.com/azure/storage/) hosting integration models the various storage resources as the following types: @@ -220,137 +207,3 @@ The Table Storage resource exposes the following connection properties: - -## Client integration - -To get started with the Aspire Azure Table Storage client integration, install the [📦 Aspire.Azure.Data.Tables](https://www.nuget.org/packages/Aspire.Azure.Data.Tables) NuGet package: - - - -### Add Azure Table Storage client - -In the `Program.cs` file of your client-consuming project, call the `AddAzureTableClient` extension method to register a `TableServiceClient` for dependency injection. The method takes a connection name parameter: - -```csharp -builder.AddAzureTableClient("tables"); -``` - -You can then retrieve the `TableServiceClient` instance using dependency injection: - -```csharp -public class ExampleService(TableServiceClient client) -{ - // Use client... -} -``` - -### Configuration - -The Azure Table Storage integration provides multiple options to configure the `TableServiceClient`. - -#### Use configuration providers - -The Azure Table Storage integration supports `Microsoft.Extensions.Configuration`. It loads the `AzureDataTablesSettings` and `TableClientOptions` from configuration using the `Aspire:Azure:Data:Tables` key. Example `appsettings.json`: - -```json -{ - "Aspire": { - "Azure": { - "Data": { - "Tables": { - "ServiceUri": "YOUR_URI", - "DisableHealthChecks": true, - "DisableTracing": false, - "ClientOptions": { - "EnableTenantDiscovery": true - } - } - } - } - } -} -``` - -#### Use named configuration - -The Azure Table Storage integration supports named configuration for multiple instances: - -```json -{ - "Aspire": { - "Azure": { - "Data": { - "Tables": { - "tables1": { - "ServiceUri": "https://myaccount1.table.core.windows.net/", - "DisableHealthChecks": true, - "ClientOptions": { - "EnableTenantDiscovery": true - } - }, - "tables2": { - "ServiceUri": "https://myaccount2.table.core.windows.net/", - "DisableTracing": true, - "ClientOptions": { - "EnableTenantDiscovery": false - } - } - } - } - } - } -} -``` - -Use the connection names when calling `AddAzureTableClient`: - -```csharp -builder.AddAzureTableClient("tables1"); -builder.AddAzureTableClient("tables2"); -``` - -#### Use inline delegates - -You can also pass the `Action` delegate to set up options inline: - -```csharp -builder.AddAzureTableClient( - "tables", - settings => settings.DisableHealthChecks = true); -``` - -You can also configure the `TableClientOptions`: - -```csharp -builder.AddAzureTableClient( - "tables", - configureClientBuilder: clientBuilder => - clientBuilder.ConfigureOptions( - options => options.EnableTenantDiscovery = true)); -``` - -### Client integration health checks - -By default, Aspire integrations enable health checks for all services. The Azure Table Storage integration: - -- Adds the health check when `DisableHealthChecks` is `false`, which attempts to connect to the Azure Table Storage. -- Integrates with the `/health` HTTP endpoint, which specifies all registered health checks must pass for app to be considered ready to accept traffic. - -### Observability and telemetry - -#### Logging - -The Azure Table Storage integration uses the following log categories: - -- `Azure.Core` -- `Azure.Identity` - -#### Tracing - -The Azure Table Storage integration emits the following tracing activities using OpenTelemetry: - -- `Azure.Data.Tables.TableServiceClient` - -#### Metrics - -The Azure Table Storage integration currently doesn't support metrics by default due to limitations with the Azure SDK. diff --git a/src/frontend/src/data/integration-docs.json b/src/frontend/src/data/integration-docs.json index 56d536de..19e26808 100644 --- a/src/frontend/src/data/integration-docs.json +++ b/src/frontend/src/data/integration-docs.json @@ -9,7 +9,7 @@ }, { "match": "Aspire.Azure.Data.Tables", - "href": "/integrations/cloud/azure/azure-storage-tables/" + "href": "/integrations/cloud/azure/azure-storage-tables/azure-storage-tables-get-started/" }, { "match": "Aspire.Azure.Messaging.EventHubs", From 7a912f4cb6b034e07f33c383f8ac021bdeaa8989 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 15:53:26 +0000 Subject: [PATCH 22/30] Restructure Azure Web PubSub integration into subfolder --- .../config/sidebar/integrations.topics.ts | 16 +- .../azure-web-pubsub-client.mdx | 164 ++++++++++++++++ .../azure-web-pubsub-get-started.mdx | 21 +++ .../azure-web-pubsub-host.mdx} | 175 +----------------- src/frontend/src/data/integration-docs.json | 2 +- 5 files changed, 203 insertions(+), 175 deletions(-) create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-client.mdx create mode 100644 src/frontend/src/content/docs/integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-get-started.mdx rename src/frontend/src/content/docs/integrations/cloud/azure/{azure-web-pubsub.mdx => azure-web-pubsub/azure-web-pubsub-host.mdx} (61%) diff --git a/src/frontend/config/sidebar/integrations.topics.ts b/src/frontend/config/sidebar/integrations.topics.ts index 39436421..3abfced2 100644 --- a/src/frontend/config/sidebar/integrations.topics.ts +++ b/src/frontend/config/sidebar/integrations.topics.ts @@ -613,7 +613,21 @@ export const integrationTopics: StarlightSidebarTopicsUserConfig = { }, { label: 'Azure Web PubSub', - slug: 'integrations/cloud/azure/azure-web-pubsub', + collapsed: true, + items: [ + { + label: 'Get started', + slug: 'integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-get-started', + }, + { + label: 'Hosting integration', + slug: 'integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-host', + }, + { + label: 'Client integration', + slug: 'integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-client', + }, + ], }, { label: 'Azure Container App Jobs', diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-client.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-client.mdx new file mode 100644 index 00000000..3374f172 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-client.mdx @@ -0,0 +1,164 @@ +--- +title: Azure Web PubSub - Client integration +description: Learn how to use the Azure Web PubSub client integration. +--- + +import { Aside } from '@astrojs/starlight/components'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; + +## Client integration + +The Aspire Azure Web PubSub client integration is used to connect to an Azure Web PubSub service using the `WebPubSubServiceClient`. To get started with the Aspire Azure Web PubSub service client integration, install the [📦 Aspire.Azure.Messaging.WebPubSub](https://www.nuget.org/packages/Aspire.Azure.Messaging.WebPubSub) NuGet package. + + + +### Supported Web PubSub client types + +The following Web PubSub client types are supported by the library: + +| Azure client type | Azure options class | Aspire settings class | +| ------------------------ | ------------------------------- | --------------------------------- | +| `WebPubSubServiceClient` | `WebPubSubServiceClientOptions` | `AzureMessagingWebPubSubSettings` | + +### Add Web PubSub client + +In the `Program.cs` file of your client-consuming project, call the `AddAzureWebPubSubServiceClient` extension method to register a `WebPubSubServiceClient` for use via the dependency injection container. The method takes a connection name parameter: + +```csharp +builder.AddAzureWebPubSubServiceClient(connectionName: "web-pubsub"); +``` + + + +After adding the `WebPubSubServiceClient`, you can retrieve the client instance using dependency injection: + +```csharp +public class ExampleService(WebPubSubServiceClient client) +{ + // Use client... +} +``` + +For more information, see: + +- [Azure.Messaging.WebPubSub documentation](https://learn.microsoft.com/azure-web-pubsub/howto-create-serviceclient-with-net-and-azure-identity) for examples on using the `WebPubSubServiceClient`. +- [Dependency injection in .NET](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection) for details on dependency injection. + +### Add keyed Web PubSub client + +There might be situations where you want to register multiple `WebPubSubServiceClient` instances with different connection names. To register keyed Web PubSub clients, call the `AddKeyedAzureWebPubSubServiceClient` method: + +```csharp +builder.AddKeyedAzureWebPubSubServiceClient(name: "messages"); +builder.AddKeyedAzureWebPubSubServiceClient(name: "commands"); +``` + + + +Then you can retrieve the client instances using dependency injection: + +```csharp +public class ExampleService( + [KeyedService("messages")] WebPubSubServiceClient messagesClient, + [KeyedService("commands")] WebPubSubServiceClient commandsClient) +{ + // Use clients... +} +``` + +For more information, see [Keyed services in .NET](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection#keyed-services). + +### Configuration + +The Aspire Azure Web PubSub library provides multiple options to configure the Azure Web PubSub connection based on the requirements and conventions of your project. Either an `Endpoint` or a `ConnectionString` must be supplied. + +#### Use a connection string + +When using a connection string from the `ConnectionStrings` configuration section, you can provide the name of the connection string when calling `AddAzureWebPubSubServiceClient`: + +```csharp +builder.AddAzureWebPubSubServiceClient( + "web-pubsub", + settings => settings.HubName = "your_hub_name"); +``` + +The connection information is retrieved from the `ConnectionStrings` configuration section. Two connection formats are supported: + +- **Service endpoint (recommended)**: Uses the service endpoint with `DefaultAzureCredential`. + + ```json + { + "ConnectionStrings": { + "web-pubsub": "https://{account_name}.webpubsub.azure.com" + } + } + ``` + +- **Connection string**: Includes an access key. + + ```json + { + "ConnectionStrings": { + "web-pubsub": "Endpoint=https://{account_name}.webpubsub.azure.com;AccessKey={account_key}" + } + } + ``` + +#### Use configuration providers + +The library supports `Microsoft.Extensions.Configuration`. It loads settings from configuration using the `Aspire:Azure:Messaging:WebPubSub` key: + +```json +{ + "Aspire": { + "Azure": { + "Messaging": { + "WebPubSub": { + "DisableHealthChecks": true, + "HubName": "your_hub_name" + } + } + } + } +} +``` + +#### Use inline delegates + +You can configure settings inline: + +```csharp +builder.AddAzureWebPubSubServiceClient( + "web-pubsub", + settings => settings.DisableHealthChecks = true); +``` + +### Observability and telemetry + +Aspire integrations automatically set up Logging, Tracing, and Metrics configurations. + +#### Logging + +The Aspire Azure Web PubSub integration uses the following log categories: + +- `Azure` +- `Azure.Core` +- `Azure.Identity` +- `Azure.Messaging.WebPubSub` + +#### Tracing + +The Aspire Azure Web PubSub integration will emit the following tracing activities using OpenTelemetry: + +- `Azure.Messaging.WebPubSub.*` + +#### Metrics + +The Aspire Azure Web PubSub integration currently doesn't support metrics by default due to limitations with the Azure SDK for .NET. diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-get-started.mdx new file mode 100644 index 00000000..f7a25cbe --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-get-started.mdx @@ -0,0 +1,21 @@ +--- +title: Azure Web PubSub integration +description: This article describes the Aspire Azure Web PubSub integration features and capabilities. +--- + +import { Image } from 'astro:assets'; +import webPubSubIcon from '@assets/icons/azure-webpubsub-icon.png'; +import IntegrationNavigationLinks from '@components/IntegrationNavigationLinks.astro'; + +Azure Web PubSub logo + +[Azure Web PubSub](https://learn.microsoft.com/azure/azure-web-pubsub/) is a fully managed real-time messaging service that enables you to build real-time web applications using WebSockets and publish-subscribe patterns. The Aspire Azure Web PubSub integration enables you to connect to Azure Web PubSub instances from your applications. + + diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-web-pubsub.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-host.mdx similarity index 61% rename from src/frontend/src/content/docs/integrations/cloud/azure/azure-web-pubsub.mdx rename to src/frontend/src/content/docs/integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-host.mdx index cf112e63..7468d83a 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-web-pubsub.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-host.mdx @@ -1,24 +1,10 @@ --- -title: Azure Web PubSub integration -description: This article describes the Aspire Azure Web PubSub integration features and capabilities. +title: Azure Web PubSub - Hosting integration +description: Learn how to use the Azure Web PubSub hosting integration. --- import { Aside } from '@astrojs/starlight/components'; import InstallPackage from '@components/InstallPackage.astro'; -import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; -import { Image } from 'astro:assets'; -import webPubSubIcon from '@assets/icons/azure-webpubsub-icon.png'; - -Azure Web PubSub logo - -[Azure Web PubSub](https://learn.microsoft.com/azure/azure-web-pubsub/) is a fully managed real-time messaging service that enables you to build real-time web applications using WebSockets and publish-subscribe patterns. The Aspire Azure Web PubSub integration enables you to connect to Azure Web PubSub instances from your applications. ## Hosting integration @@ -244,160 +230,3 @@ When you reference an Azure Web PubSub resource using `WithReference`, the follo `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `wps1` becomes `WPS1_URI`. - -## Client integration - -The Aspire Azure Web PubSub client integration is used to connect to an Azure Web PubSub service using the `WebPubSubServiceClient`. To get started with the Aspire Azure Web PubSub service client integration, install the [📦 Aspire.Azure.Messaging.WebPubSub](https://www.nuget.org/packages/Aspire.Azure.Messaging.WebPubSub) NuGet package. - - - -### Supported Web PubSub client types - -The following Web PubSub client types are supported by the library: - -| Azure client type | Azure options class | Aspire settings class | -| ------------------------ | ------------------------------- | --------------------------------- | -| `WebPubSubServiceClient` | `WebPubSubServiceClientOptions` | `AzureMessagingWebPubSubSettings` | - -### Add Web PubSub client - -In the `Program.cs` file of your client-consuming project, call the `AddAzureWebPubSubServiceClient` extension method to register a `WebPubSubServiceClient` for use via the dependency injection container. The method takes a connection name parameter: - -```csharp -builder.AddAzureWebPubSubServiceClient(connectionName: "web-pubsub"); -``` - - - -After adding the `WebPubSubServiceClient`, you can retrieve the client instance using dependency injection: - -```csharp -public class ExampleService(WebPubSubServiceClient client) -{ - // Use client... -} -``` - -For more information, see: - -- [Azure.Messaging.WebPubSub documentation](https://learn.microsoft.com/azure-web-pubsub/howto-create-serviceclient-with-net-and-azure-identity) for examples on using the `WebPubSubServiceClient`. -- [Dependency injection in .NET](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection) for details on dependency injection. - -### Add keyed Web PubSub client - -There might be situations where you want to register multiple `WebPubSubServiceClient` instances with different connection names. To register keyed Web PubSub clients, call the `AddKeyedAzureWebPubSubServiceClient` method: - -```csharp -builder.AddKeyedAzureWebPubSubServiceClient(name: "messages"); -builder.AddKeyedAzureWebPubSubServiceClient(name: "commands"); -``` - - - -Then you can retrieve the client instances using dependency injection: - -```csharp -public class ExampleService( - [KeyedService("messages")] WebPubSubServiceClient messagesClient, - [KeyedService("commands")] WebPubSubServiceClient commandsClient) -{ - // Use clients... -} -``` - -For more information, see [Keyed services in .NET](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection#keyed-services). - -### Configuration - -The Aspire Azure Web PubSub library provides multiple options to configure the Azure Web PubSub connection based on the requirements and conventions of your project. Either an `Endpoint` or a `ConnectionString` must be supplied. - -#### Use a connection string - -When using a connection string from the `ConnectionStrings` configuration section, you can provide the name of the connection string when calling `AddAzureWebPubSubServiceClient`: - -```csharp -builder.AddAzureWebPubSubServiceClient( - "web-pubsub", - settings => settings.HubName = "your_hub_name"); -``` - -The connection information is retrieved from the `ConnectionStrings` configuration section. Two connection formats are supported: - -- **Service endpoint (recommended)**: Uses the service endpoint with `DefaultAzureCredential`. - - ```json - { - "ConnectionStrings": { - "web-pubsub": "https://{account_name}.webpubsub.azure.com" - } - } - ``` - -- **Connection string**: Includes an access key. - - ```json - { - "ConnectionStrings": { - "web-pubsub": "Endpoint=https://{account_name}.webpubsub.azure.com;AccessKey={account_key}" - } - } - ``` - -#### Use configuration providers - -The library supports `Microsoft.Extensions.Configuration`. It loads settings from configuration using the `Aspire:Azure:Messaging:WebPubSub` key: - -```json -{ - "Aspire": { - "Azure": { - "Messaging": { - "WebPubSub": { - "DisableHealthChecks": true, - "HubName": "your_hub_name" - } - } - } - } -} -``` - -#### Use inline delegates - -You can configure settings inline: - -```csharp -builder.AddAzureWebPubSubServiceClient( - "web-pubsub", - settings => settings.DisableHealthChecks = true); -``` - -### Observability and telemetry - -Aspire integrations automatically set up Logging, Tracing, and Metrics configurations. - -#### Logging - -The Aspire Azure Web PubSub integration uses the following log categories: - -- `Azure` -- `Azure.Core` -- `Azure.Identity` -- `Azure.Messaging.WebPubSub` - -#### Tracing - -The Aspire Azure Web PubSub integration will emit the following tracing activities using OpenTelemetry: - -- `Azure.Messaging.WebPubSub.*` - -#### Metrics - -The Aspire Azure Web PubSub integration currently doesn't support metrics by default due to limitations with the Azure SDK for .NET. diff --git a/src/frontend/src/data/integration-docs.json b/src/frontend/src/data/integration-docs.json index 19e26808..6d14e31b 100644 --- a/src/frontend/src/data/integration-docs.json +++ b/src/frontend/src/data/integration-docs.json @@ -21,7 +21,7 @@ }, { "match": "Aspire.Azure.Messaging.WebPubSub", - "href": "/integrations/cloud/azure/azure-web-pubsub/" + "href": "/integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-get-started/" }, { "match": "Aspire.Azure.Npgsql", From 8b62be1c813845400259ad681adbc8d68ce9d006 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 10 Feb 2026 11:43:59 +0000 Subject: [PATCH 23/30] Fix capitalization: use lowercase for 'hosting and client integrations' Co-authored-by: alistairmatthews <41286777+alistairmatthews@users.noreply.github.com> --- .../azure/azure-ai-foundry/azure-ai-foundry-get-started.mdx | 2 +- .../azure/azure-ai-inference/azure-ai-inference-get-started.mdx | 2 +- .../cloud/azure/azure-ai-search/azure-ai-search-get-started.mdx | 2 +- .../azure-app-configuration-get-started.mdx | 2 +- .../azure/azure-cache-redis/azure-cache-redis-get-started.mdx | 2 +- .../cloud/azure/azure-cosmos-db/azure-cosmos-db-get-started.mdx | 2 +- .../azure/azure-event-hubs/azure-event-hubs-get-started.mdx | 2 +- .../cloud/azure/azure-key-vault/azure-key-vault-get-started.mdx | 2 +- .../cloud/azure/azure-openai/azure-openai-get-started.mdx | 2 +- .../azure/azure-service-bus/azure-service-bus-get-started.mdx | 2 +- .../azure/azure-sql-database/azure-sql-database-get-started.mdx | 2 +- 11 files changed, 11 insertions(+), 11 deletions(-) diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started.mdx index 4042d073..50276ee9 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started.mdx @@ -1,6 +1,6 @@ --- title: Get started with the Azure AI Foundry integrations -description: Learn how to set up the Aspire Azure AI Foundry Hosting and Client integrations simply. +description: Learn how to set up the Aspire Azure AI Foundry hosting and client integrations simply. prev: false --- diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-get-started.mdx index f82de527..117d8ed6 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-get-started.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-get-started.mdx @@ -1,6 +1,6 @@ --- title: Get started with the Azure AI Inference integrations -description: Learn how to set up the Aspire Azure AI Inference Hosting and Client integrations simply. +description: Learn how to set up the Aspire Azure AI Inference hosting and client integrations simply. prev: false --- diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-search/azure-ai-search-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-search/azure-ai-search-get-started.mdx index f8d8d3d3..5aa856fa 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-search/azure-ai-search-get-started.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-search/azure-ai-search-get-started.mdx @@ -1,6 +1,6 @@ --- title: Get started with the Azure AI Search integration -description: Learn how to set up the Aspire Azure AI Search Hosting and Client integrations simply. +description: Learn how to set up the Aspire Azure AI Search hosting and client integrations simply. prev: false --- diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-app-configuration/azure-app-configuration-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-app-configuration/azure-app-configuration-get-started.mdx index 417e51fd..74931c9f 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-app-configuration/azure-app-configuration-get-started.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-app-configuration/azure-app-configuration-get-started.mdx @@ -1,6 +1,6 @@ --- title: Get started with the Azure App Configuration integrations -description: Learn how to set up the Aspire Azure App Configuration Hosting and Client integrations simply. +description: Learn how to set up the Aspire Azure App Configuration hosting and client integrations simply. prev: false --- diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-get-started.mdx index 1a4e7d1a..968211ba 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-get-started.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-get-started.mdx @@ -1,6 +1,6 @@ --- title: Get started with the Azure Cache for Redis integrations -description: Learn how to set up the Aspire Azure Cache for Redis Hosting and Client integrations simply. +description: Learn how to set up the Aspire Azure Cache for Redis hosting and client integrations simply. prev: false --- diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-get-started.mdx index db9e4734..c02d0c02 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-get-started.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-get-started.mdx @@ -1,6 +1,6 @@ --- title: Get started with the Azure Cosmos DB integrations -description: Learn how to set up the Aspire Azure Cosmos DB Hosting and Client integrations simply. +description: Learn how to set up the Aspire Azure Cosmos DB hosting and client integrations simply. prev: false --- diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-get-started.mdx index 0d40aec0..36e17f29 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-get-started.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-get-started.mdx @@ -1,6 +1,6 @@ --- title: Get started with the Azure Event Hubs integrations -description: Learn how to set up the Aspire Azure Event Hubs Hosting and Client integrations simply. +description: Learn how to set up the Aspire Azure Event Hubs hosting and client integrations simply. prev: false --- diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-key-vault/azure-key-vault-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-key-vault/azure-key-vault-get-started.mdx index 2efd065f..7713b6cc 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-key-vault/azure-key-vault-get-started.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-key-vault/azure-key-vault-get-started.mdx @@ -1,6 +1,6 @@ --- title: Get started with the Azure Key Vault integration -description: Learn how to set up the Aspire Azure Key Vault Hosting and Client integrations simply. +description: Learn how to set up the Aspire Azure Key Vault hosting and client integrations simply. prev: false --- diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-openai/azure-openai-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-openai/azure-openai-get-started.mdx index c3ca8ffe..f3e444e5 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-openai/azure-openai-get-started.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-openai/azure-openai-get-started.mdx @@ -1,6 +1,6 @@ --- title: Get started with the Azure OpenAI integration -description: Learn how to set up the Aspire Azure OpenAI Hosting and Client integrations simply. +description: Learn how to set up the Aspire Azure OpenAI hosting and client integrations simply. prev: false --- diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-service-bus/azure-service-bus-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-service-bus/azure-service-bus-get-started.mdx index 336317b3..4d4afdf5 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-service-bus/azure-service-bus-get-started.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-service-bus/azure-service-bus-get-started.mdx @@ -1,6 +1,6 @@ --- title: Get started with the Azure Service Bus integration -description: Learn how to set up the Aspire Azure Service Bus Hosting and Client integrations simply. +description: Learn how to set up the Aspire Azure Service Bus hosting and client integrations simply. prev: false --- diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database/azure-sql-database-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database/azure-sql-database-get-started.mdx index 7a0d7ff2..37bbe37a 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database/azure-sql-database-get-started.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database/azure-sql-database-get-started.mdx @@ -1,6 +1,6 @@ --- title: Get started with the Azure SQL Database integration -description: Learn how to set up the Aspire Azure SQL Database Hosting and Client integrations simply. +description: Learn how to set up the Aspire Azure SQL Database hosting and client integrations simply. prev: false --- From 372fdcf3c27b8fa671ea0452af286f3d97821bfe Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 10 Feb 2026 15:12:19 +0000 Subject: [PATCH 24/30] Update obsolete methods, fix duplicate code block identifiers, and add preview badges - Replace AddAzureRedis with AddAzureManagedRedis in cache-redis files - Replace AddAzureQueueClient with AddAzureQueueServiceClient in storage-queues - Replace AddAzureTableClient with AddAzureTableServiceClient in storage-tables - Fix duplicate 'csharp csharp' identifiers in cosmos-db-host.mdx - Add preview badge to Azure OpenAI get-started and client docs Co-authored-by: alistairmatthews <41286777+alistairmatthews@users.noreply.github.com> --- .../azure-cache-redis-get-started.mdx | 4 ++-- .../azure-cache-redis-host.mdx | 12 ++++++------ .../azure-cosmos-db/azure-cosmos-db-host.mdx | 6 +++--- .../azure/azure-openai/azure-openai-client.mdx | 4 +++- .../azure-openai/azure-openai-get-started.mdx | 4 +++- .../azure-storage-queues-client.mdx | 18 +++++++++--------- .../azure-storage-tables-client.mdx | 14 +++++++------- 7 files changed, 33 insertions(+), 29 deletions(-) diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-get-started.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-get-started.mdx index 968211ba..a0066b8b 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-get-started.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-get-started.mdx @@ -38,7 +38,7 @@ Next, in the AppHost project, create an Azure Cache for Redis resource and pass ```csharp title="C# — AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); -var redis = builder.AddAzureRedis("redis"); +var redis = builder.AddAzureManagedRedis("redis"); builder.AddProject() .WithReference(redis); @@ -49,7 +49,7 @@ builder.Build().Run(); ```