diff --git a/src/frontend/config/redirects.mjs b/src/frontend/config/redirects.mjs index 68f40826..89216b39 100644 --- a/src/frontend/config/redirects.mjs +++ b/src/frontend/config/redirects.mjs @@ -23,4 +23,23 @@ export const redirects = { '/integrations/databases/efcore/postgresql/': '/integrations/databases/efcore/postgres/postgresql-get-started/', '/integrations/databases/efcore/azure-postgresql/': '/integrations/databases/efcore/azure-postgresql/azure-postgresql-get-started/', '/integrations/databases/efcore/azure-sql/': '/integrations/databases/efcore/azure-sql/azure-sql-get-started/', + '/integrations/cloud/azure/azure-ai-foundry/': '/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started/', + '/integrations/cloud/azure/azure-ai-inference/': '/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-get-started/', + '/integrations/cloud/azure/azure-ai-search/': '/integrations/cloud/azure/azure-ai-search/azure-ai-search-get-started/', + '/integrations/cloud/azure/azure-app-configuration/': '/integrations/cloud/azure/azure-app-configuration/azure-app-configuration-get-started/', + '/integrations/cloud/azure/azure-app-service/': '/integrations/cloud/azure/azure-app-service/azure-app-service-get-started/', + '/integrations/cloud/azure/azure-cache-redis/': '/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-get-started/', + '/integrations/cloud/azure/azure-container-registry/': '/integrations/cloud/azure/azure-container-registry/azure-container-registry-get-started/', + '/integrations/cloud/azure/azure-cosmos-db/': '/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-get-started/', + '/integrations/cloud/azure/azure-event-hubs/': '/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-get-started/', + '/integrations/cloud/azure/azure-functions/': '/integrations/cloud/azure/azure-functions/azure-functions-get-started/', + '/integrations/cloud/azure/azure-key-vault/': '/integrations/cloud/azure/azure-key-vault/azure-key-vault-get-started/', + '/integrations/cloud/azure/azure-openai/': '/integrations/cloud/azure/azure-openai/azure-openai-get-started/', + '/integrations/cloud/azure/azure-service-bus/': '/integrations/cloud/azure/azure-service-bus/azure-service-bus-get-started/', + '/integrations/cloud/azure/azure-signalr/': '/integrations/cloud/azure/azure-signalr/azure-signalr-get-started/', + '/integrations/cloud/azure/azure-sql-database/': '/integrations/cloud/azure/azure-sql-database/azure-sql-database-get-started/', + '/integrations/cloud/azure/azure-storage-blobs/': '/integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-get-started/', + '/integrations/cloud/azure/azure-storage-queues/': '/integrations/cloud/azure/azure-storage-queues/azure-storage-queues-get-started/', + '/integrations/cloud/azure/azure-storage-tables/': '/integrations/cloud/azure/azure-storage-tables/azure-storage-tables-get-started/', + '/integrations/cloud/azure/azure-web-pubsub/': '/integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-get-started/', }; diff --git a/src/frontend/config/sidebar/integrations.topics.ts b/src/frontend/config/sidebar/integrations.topics.ts index 80af1db7..3abfced2 100644 --- a/src/frontend/config/sidebar/integrations.topics.ts +++ b/src/frontend/config/sidebar/integrations.topics.ts @@ -269,53 +269,221 @@ 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', - 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', - 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', - 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', + }, + ], }, ], }, { 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', - 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', - 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', - 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', - 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', - 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', - 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', - 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', @@ -337,37 +505,129 @@ 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', - 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', - 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 Blobs', + collapsed: true, + items: [ + { + 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', + label: 'Azure Storage Queues', collapsed: true, items: [ { - label: 'Azure Storage Blobs', - slug: 'integrations/cloud/azure/azure-storage-blobs', + label: 'Get started', + slug: 'integrations/cloud/azure/azure-storage-queues/azure-storage-queues-get-started', }, { - label: 'Azure Storage Queues', - slug: 'integrations/cloud/azure/azure-storage-queues', + label: 'Hosting integration', + slug: 'integrations/cloud/azure/azure-storage-queues/azure-storage-queues-host', }, { - label: 'Azure Storage Tables', - slug: 'integrations/cloud/azure/azure-storage-tables', + label: 'Client integration', + slug: 'integrations/cloud/azure/azure-storage-queues/azure-storage-queues-client', + }, + ], + }, + { + label: 'Azure Storage Tables', + collapsed: true, + items: [ + { + 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', }, ], }, { 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/deployment/azure/azure-security-best-practices.mdx b/src/frontend/src/content/docs/deployment/azure/azure-security-best-practices.mdx index 03eaab8c..a588e2d5 100644 --- a/src/frontend/src/content/docs/deployment/azure/azure-security-best-practices.mdx +++ b/src/frontend/src/content/docs/deployment/azure/azure-security-best-practices.mdx @@ -68,7 +68,7 @@ builder.AddProject() .WithReference(keyVault); ``` -For more information, see [Aspire Azure Key Vault integration](/integrations/cloud/azure/azure-key-vault/). +For more information, see [Aspire Azure Key Vault integration](/integrations/cloud/azure/azure-key-vault/azure-key-vault-get-started/). ### Configure user-assigned managed identities @@ -110,5 +110,5 @@ For comprehensive guidance on Azure security, see [Azure security best practices ## Related content - [Deploy to Azure Container Apps using the Aspire CLI](/deployment/azure/aca-deployment-aspire-cli/) -- [Aspire Azure Key Vault integration](/integrations/cloud/azure/azure-key-vault/) +- [Aspire Azure Key Vault integration](/integrations/cloud/azure/azure-key-vault/azure-key-vault-get-started/) - [Aspire Azure user-assigned managed identity integration](/integrations/cloud/azure/user-assigned-identity/) diff --git a/src/frontend/src/content/docs/deployment/overview.mdx b/src/frontend/src/content/docs/deployment/overview.mdx index e2da4aa0..299a60b0 100644 --- a/src/frontend/src/content/docs/deployment/overview.mdx +++ b/src/frontend/src/content/docs/deployment/overview.mdx @@ -137,7 +137,7 @@ This example shows how you could explicitly map services to different compute en | [๐Ÿ“ฆ Aspire.Hosting.Docker](/integrations/compute/docker/) | Docker / Docker Compose | โœ… Yes | ๐Ÿงช Preview | Use generated Compose with your own scripts or tooling. | | [๐Ÿ“ฆ Aspire.Hosting.Kubernetes](/integrations/compute/kubernetes/) | Kubernetes | โœ… Yes | ๐Ÿงช Preview | Apply with `kubectl`, GitOps, or other controllers. | | [๐Ÿ“ฆ Aspire.Hosting.Azure.AppContainers](/integrations/cloud/azure/configure-container-apps/) | Azure Container Apps | โœ… Yes | โœ… Yes (Preview) | Deploy capability is in Preview and may change. | -| [๐Ÿ“ฆ Aspire.Hosting.Azure.AppService](/integrations/cloud/azure/azure-app-service/) | Azure App Service | โœ… Yes | โœ… Yes (Preview) | Deploy capability is in Preview and may change. | +| [๐Ÿ“ฆ Aspire.Hosting.Azure.AppService](/integrations/cloud/azure/azure-app-service/azure-app-service-get-started/) | Azure App Service | โœ… Yes | โœ… Yes (Preview) | Deploy capability is in Preview and may change. | -#### 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: -:::code language="bicep" source="../snippets/azure/AppHost/config/config.bicep"::: - ```bicep title="Generated Bicep โ€” config.bicep" @description('The location for the resource(s) to be deployed.') param location string = resourceGroup().location @@ -108,7 +90,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 +121,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 +141,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 +171,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 +188,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 +210,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 +226,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 +244,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 +264,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/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/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..861fc0cc --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-client.mdx @@ -0,0 +1,182 @@ +--- +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. + +## Properties of the Azure Cache for Redis resources + +When you use the `WithReference` method to pass an Azure Cache for Redis resource from the AppHost project to a consuming client project, several properties are available to use in the consuming project. + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Host` property of a resource called `redis` becomes `REDIS_HOST`. + +### Azure Managed Redis + +The Azure Managed Redis resource exposes the following connection properties: + +| Property Name | Description | +| ------------- | ------------------------------------------- | +| `Host` | The Redis server hostname | +| `Port` | The Redis server port (default: `10000`) | +| `Uri` | The connection URI with TLS (`rediss://`) | + +When access key authentication is enabled: + +| Property Name | Description | +| ------------- | ------------------------------------------- | +| `Password` | The access key from Key Vault | + +For example, if you reference an Azure Managed Redis resource named `redis` in your AppHost project, the following environment variables will be available in the consuming project: + +- `REDIS_HOST` +- `REDIS_PORT` +- `REDIS_URI` + +## 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..2274ad4b --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-get-started.mdx @@ -0,0 +1,119 @@ +--- +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.AddAzureManagedRedis("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"); +``` + + + +### Use injected Azure Cache for Redis properties + +In the AppHost, when you used the `WithReference` method to pass an Azure Cache for Redis resource to a consuming client project, Aspire injects several configuration properties that you can use in the consuming project. + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Host` property of a resource called `redis` becomes `REDIS_HOST`. + +Use the `GetValue()` method to obtain these environment variables in consuming projects: + +```csharp title="C# โ€” Obtain configuration properties" +string redisHost = builder.Configuration.GetValue("REDIS_HOST"); +string redisPort = builder.Configuration.GetValue("REDIS_PORT"); +string redisUri = builder.Configuration.GetValue("REDIS_URI"); +``` + + + +## Use Azure Cache for Redis resources in client code + +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 59% 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..b511e118 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,41 +1,23 @@ --- -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: +To add an Azure Cache for Redis resource to your AppHost project, call the `AddAzureManagedRedis` method providing a name: ```csharp title="C# โ€” AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); -var redis = builder.AddAzureRedis("redis"); +var redis = builder.AddAzureManagedRedis("redis"); builder.AddProject() .WithReference(redis); @@ -46,14 +28,14 @@ builder.AddProject() The preceding code adds an Azure Redis resource named `redis` to the AppHost project. The `WithReference` method passes the connection information to the `ExampleProject` project. -### 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: @@ -63,7 +45,7 @@ var builder = DistributedApplication.CreateBuilder(args); var existingRedisName = builder.AddParameter("existingRedisName"); var existingRedisResourceGroup = builder.AddParameter("existingRedisResourceGroup"); -var redis = builder.AddAzureRedis("redis") +var redis = builder.AddAzureManagedRedis("redis") .AsExisting(existingRedisName, existingRedisResourceGroup); builder.AddProject() @@ -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. @@ -83,7 +65,7 @@ To make use of the [`docker.io/library/redis`](https://hub.docker.com/_/redis/) ```csharp var builder = DistributedApplication.CreateBuilder(args); -var cache = builder.AddAzureRedis("azcache") +var cache = builder.AddAzureManagedRedis("azcache") .RunAsContainer(); builder.AddProject() @@ -97,14 +79,14 @@ 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: ```csharp var builder = DistributedApplication.CreateBuilder(args); -var cache = builder.AddAzureRedis("azcache") +var cache = builder.AddAzureManagedRedis("azcache") .WithAccessKeyAuthentication(); builder.AddProject() @@ -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/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 76% 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..61e3fcf6 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,9 +92,9 @@ 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: +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 Container Registry resource, the following Bicep is generated: ```bicep title="my-acr.module.bicep" @description('The location for the resource(s) to be deployed.') 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..a4b9ceba --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-client.mdx @@ -0,0 +1,177 @@ +--- +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](/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-host/#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). + +## Properties of the Azure Cosmos DB resources + +When you use the `WithReference` method to pass an Azure Cosmos DB resource from the AppHost project to a consuming client project, several properties are available to use in the consuming project. + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `cosmos` becomes `COSMOS_URI`. + +### Azure Cosmos DB account + +The Azure Cosmos DB account resource exposes the following connection properties: + +| Property Name | Description | +| ------------------ | ---------------------------------------------------------------- | +| `Uri` | The account endpoint URI | + +When access key authentication is enabled (via `WithAccessKeyAuthentication()`): + +| Property Name | Description | +| ------------------ | ---------------------------------------------------------------- | +| `Uri` | The account endpoint URI | +| `AccountKey` | The primary access key (retrieved from Key Vault) | +| `ConnectionString` | The full connection string (retrieved from Key Vault) | + +### Azure Cosmos DB database + +The Azure Cosmos DB database resource inherits all properties from its parent account and adds: + +| Property Name | Description | +| -------------- | --------------------- | +| `DatabaseName` | The name of the database | + +### Azure Cosmos DB container + +The Azure Cosmos DB container resource inherits all properties from its parent database and adds: + +| Property Name | Description | +| --------------- | --------------------- | +| `ContainerName` | The name of the container | + +For example, if you reference a database resource named `db` in your AppHost project, the following environment variables will be available in the consuming project: + +- `DB_URI` +- `DB_DATABASENAME` + +When access key authentication is enabled, additional environment variables are available: + +- `DB_ACCOUNTKEY` +- `DB_CONNECTIONSTRING` + +### 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..1794572d --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-get-started.mdx @@ -0,0 +1,107 @@ +--- +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"); +``` + +### Use injected Azure Cosmos DB properties + +In the AppHost, when you used the `WithReference` method to pass an Azure Cosmos DB resource to a consuming client project, Aspire injects several configuration properties that you can use in the consuming project. + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `db` becomes `DB_URI`. + +Use the `GetValue()` method to obtain these environment variables in consuming projects: + +```csharp title="C# โ€” Obtain configuration properties" +string cosmosUri = builder.Configuration.GetValue("DB_URI"); +string databaseName = builder.Configuration.GetValue("DB_DATABASENAME"); +``` + + + +## Use Azure Cosmos DB resources in client code + +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 73% 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..c720a9e5 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. @@ -40,7 +24,7 @@ To access these types and APIs, add the [๐Ÿ“ฆ Aspire.Hosting.Azure.CosmosDB](htt In your AppHost project, call `AddAzureCosmosDB` to add and return an Azure Cosmos DB resource builder: -```csharp csharp title="C# โ€” AppHost.cs" +```csharp title="C# โ€” AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); var cosmos = builder.AddAzureCosmosDB("cosmos-db"); @@ -91,7 +75,7 @@ Aspire models parent child relationships between Azure Cosmos DB resources. For To add an Azure Cosmos DB database resource, call the `AddCosmosDatabase` method on an `IResourceBuilder` instance: -```csharp csharp title="C# โ€” AppHost.cs" +```csharp title="C# โ€” AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); var cosmos = builder.AddAzureCosmosDB("cosmos-db"); @@ -106,7 +90,7 @@ An Azure Cosmos DB container is where data is stored. When you create a containe To add an Azure Cosmos DB container resource, call the `AddContainer` method on an `IResourceBuilder` instance: -```csharp csharp title="C# โ€” AppHost.cs" +```csharp title="C# โ€” AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); var cosmos = builder.AddAzureCosmosDB("cosmos-db"); @@ -282,7 +266,7 @@ The preceding code configures the Linux-based preview Cosmos DB emulator contain 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 Cosmos DB resource, the following Bicep is generated: -```bicep title="Generated Bicep โ€” cosmos.bicep +```bicep title="Generated Bicep โ€” cosmos.bicep" @description('The location for the resource(s) to be deployed.') param location string = resourceGroup().location @@ -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/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..c090b7c9 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-client.mdx @@ -0,0 +1,292 @@ +--- +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. + +## Properties of the Azure Event Hubs resources + +When you use the `WithReference` method to pass an Azure Event Hubs resource from the AppHost project to a consuming client project, several properties are available to use in the consuming project. + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `eventhubs` becomes `EVENTHUBS_URI`. + +### Azure Event Hubs namespace + +The Azure Event Hubs namespace resource exposes the following connection properties: + +| Property Name | Description | +| ------------- | --------------------------------------------------- | +| `Host` | The namespace hostname | +| `Uri` | The service endpoint URI | + +In emulator mode, additional properties are available: + +| Property Name | Description | +| ------------------ | ------------------------------------------ | +| `Host` | The local emulator host | +| `Port` | The local emulator port | +| `Uri` | The service bus URI | +| `ConnectionString` | The full connection string for the emulator | + +### Azure Event Hub + +The Azure Event Hub resource inherits all properties from its parent namespace and adds: + +| Property Name | Description | +| -------------- | --------------------- | +| `EventHubName` | The Event Hub name | + +### Azure Event Hub consumer group + +The Azure Event Hub consumer group resource inherits all properties from its parent hub and adds: + +| Property Name | Description | +| ------------------- | ------------------------ | +| `ConsumerGroupName` | The consumer group name | + +For example, if you reference an Event Hub resource named `messages` in your AppHost project, the following environment variables will be available in the consuming project: + +- `MESSAGES_HOST` +- `MESSAGES_URI` +- `MESSAGES_EVENTHUBNAME` + +### 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..91cade10 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-get-started.mdx @@ -0,0 +1,108 @@ +--- +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"); +``` + +### Use injected Azure Event Hubs properties + +In the AppHost, when you used the `WithReference` method to pass an Azure Event Hubs resource to a consuming client project, Aspire injects several configuration properties that you can use in the consuming project. + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `eventhubs` becomes `EVENTHUBS_URI`. + +Use the `GetValue()` method to obtain these environment variables in consuming projects: + +```csharp title="C# โ€” Obtain configuration properties" +string eventHubsHost = builder.Configuration.GetValue("EVENTHUBS_HOST"); +string eventHubsUri = builder.Configuration.GetValue("EVENTHUBS_URI"); +string eventHubName = builder.Configuration.GetValue("MESSAGES_EVENTHUBNAME"); +``` + + + +## Use Azure Event Hubs resources in client code + +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/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 65% 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..883de015 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,9 +38,9 @@ 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.Http.AspNetCore](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore): Adds HTTP trigger-supporting APIs. + - [๐Ÿ“ฆ 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.Extensions.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/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..977b6105 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-key-vault/azure-key-vault-client.mdx @@ -0,0 +1,260 @@ +--- +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... +} +``` + +## Properties of the Azure Key Vault resources + +When you use the `WithReference` method to pass an Azure Key Vault resource from the AppHost project to a consuming client project, several properties are available to use in the consuming project. + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `keyvault` becomes `KEYVAULT_URI`. + +### Azure Key Vault + +The Azure Key Vault resource exposes the following connection property: + +| Property Name | Description | +| ------------- | -------------------------------------------------------------------- | +| `Uri` | The vault URI (e.g., `https://{name}.vault.azure.net/`) | + +For example, if you reference an Azure Key Vault resource named `keyvault` in your AppHost project, the following environment variables will be available in the consuming project: + +- `KEYVAULT_URI` + +## 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..51b797b8 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-key-vault/azure-key-vault-get-started.mdx @@ -0,0 +1,139 @@ +--- +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"); +``` + +### Use injected Azure Key Vault properties + +In the AppHost, when you used the `WithReference` method to pass an Azure Key Vault resource to a consuming client project, Aspire injects several configuration properties that you can use in the consuming project. + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `keyvault` becomes `KEYVAULT_URI`. + +Use the `GetValue()` method to obtain these environment variables in consuming projects: + +```csharp title="C# โ€” Obtain configuration properties" +string vaultUri = builder.Configuration.GetValue("KEYVAULT_URI"); +``` + + + +## Use Azure Key Vault resources in client code + +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/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..f0e10a2d --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-openai/azure-openai-client.mdx @@ -0,0 +1,304 @@ +--- +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, Badge } 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` | + +## Properties of the Azure OpenAI resources + +When you use the `WithReference` method to pass an Azure OpenAI resource from the AppHost project to a consuming client project, several properties are available to use in the consuming project. + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `openai` becomes `OPENAI_URI`. + +### Azure OpenAI service + +The Azure OpenAI resource exposes the following connection property: + +| Property Name | Description | +| ------------- | ------------------------------- | +| `Uri` | The service endpoint URI | + +### Azure OpenAI deployment + +The Azure OpenAI deployment resource inherits the property from its parent service and adds: + +| Property Name | Description | +| ------------- | ------------------------- | +| `ModelName` | The deployment/model name | + +For example, if you reference an Azure OpenAI resource named `openai` in your AppHost project, the following environment variables will be available in the consuming project: + +- `OPENAI_URI` + +If you reference a deployment resource: + +- `{DEPLOYMENT}_URI` +- `{DEPLOYMENT}_MODELNAME` + +## 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..2dd57054 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-openai/azure-openai-get-started.mdx @@ -0,0 +1,130 @@ +--- +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, Badge, 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. + +### Use injected Azure OpenAI properties + +In the AppHost, when you used the `WithReference` method to pass an Azure OpenAI resource to a consuming client project, Aspire injects several configuration properties that you can use in the consuming project. + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `openai` becomes `OPENAI_URI`. + +Use the `GetValue()` method to obtain these environment variables in consuming projects: + +```csharp title="C# โ€” Obtain configuration properties" +string openaiUri = builder.Configuration.GetValue("OPENAI_URI"); +``` + + + +## Use Azure OpenAI client in client code + +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/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..71fc87a9 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-service-bus/azure-service-bus-client.mdx @@ -0,0 +1,335 @@ +--- +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](/integrations/cloud/azure/azure-service-bus/azure-service-bus-host/#add-azure-service-bus-resource) and [Add Azure Service Bus topic and subscription](/integrations/cloud/azure/azure-service-bus/azure-service-bus-host/#add-azure-service-bus-topic-and-subscription). + +## Properties of the Azure Service Bus resources + +When you use the `WithReference` method to pass an Azure Service Bus resource from the AppHost project to a consuming client project, several properties are available to use in the consuming project. + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `servicebus` becomes `SERVICEBUS_URI`. + +### Azure Service Bus namespace + +The Azure Service Bus namespace resource exposes the following connection properties: + +| Property Name | Description | +| ------------- | -------------------------- | +| `Host` | The namespace hostname | +| `Uri` | The service endpoint URI | + +In emulator mode, additional properties are available: + +| Property Name | Description | +| ------------------ | ------------------------------------------ | +| `Host` | The local emulator host | +| `Port` | The local emulator port | +| `Uri` | The service bus URI | +| `ConnectionString` | The full connection string for the emulator | + +### Azure Service Bus queue + +The Azure Service Bus queue resource inherits all properties from its parent namespace and adds: + +| Property Name | Description | +| ------------- | ------------------ | +| `QueueName` | The queue name | + +### Azure Service Bus topic + +The Azure Service Bus topic resource inherits all properties from its parent namespace and adds: + +| Property Name | Description | +| ------------- | ------------------ | +| `TopicName` | The topic name | + +### Azure Service Bus subscription + +The Azure Service Bus subscription resource inherits all properties from its parent topic and adds: + +| Property Name | Description | +| ------------------ | ---------------------- | +| `SubscriptionName` | The subscription name | + +For example, if you reference a queue resource named `queue` in your AppHost project, the following environment variables will be available in the consuming project: + +- `QUEUE_HOST` +- `QUEUE_URI` +- `QUEUE_QUEUENAME` + +### 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..11142caa --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-service-bus/azure-service-bus-get-started.mdx @@ -0,0 +1,125 @@ +--- +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. + +### Use injected Azure Service Bus properties + +In the AppHost, when you used the `WithReference` method to pass an Azure Service Bus resource to a consuming client project, Aspire injects several configuration properties that you can use in the consuming project. + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `queue` becomes `QUEUE_URI`. + +Use the `GetValue()` method to obtain these environment variables in consuming projects: + +```csharp title="C# โ€” Obtain configuration properties" +string serviceBusHost = builder.Configuration.GetValue("QUEUE_HOST"); +string serviceBusUri = builder.Configuration.GetValue("QUEUE_URI"); +string queueName = builder.Configuration.GetValue("QUEUE_QUEUENAME"); +``` + + + +## Use Azure Service Bus resources in client code + +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/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/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..1a1bce3d --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database/azure-sql-database-client.mdx @@ -0,0 +1,190 @@ +--- +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. + +## Properties of the Azure SQL Database resources + +When you use the `WithReference` method to pass an Azure SQL Database resource from the AppHost project to a consuming client project, several properties are available to use in the consuming project. + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Host` property of a resource called `database` becomes `DATABASE_HOST`. + +### Azure SQL Server + +The Azure SQL Server resource exposes the following connection properties: + +| Property Name | Description | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------- | +| `Host` | The server fully qualified domain name | +| `Port` | The SQL Server port (default: `1433`) | +| `Uri` | The connection URI (e.g., `mssql://{host}:1433`) | +| `JdbcConnectionString` | JDBC-format connection string (e.g., `jdbc:sqlserver://{host}:1433;encrypt=true;trustServerCertificate=false`) | + +### Azure SQL Database + +The Azure SQL Database resource inherits all properties from its parent server and adds: + +| Property Name | Description | +| -------------- | ----------------------- | +| `DatabaseName` | The name of the database | + +For example, if you reference a database resource named `database` in your AppHost project, the following environment variables will be available in the consuming project: + +- `DATABASE_HOST` +- `DATABASE_PORT` +- `DATABASE_URI` +- `DATABASE_JDBCCONNECTIONSTRING` +- `DATABASE_DATABASENAME` + +### 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..600ff249 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-sql-database/azure-sql-database-get-started.mdx @@ -0,0 +1,125 @@ +--- +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. + +### Use injected Azure SQL Database properties + +In the AppHost, when you used the `WithReference` method to pass an Azure SQL Database resource to a consuming client project, Aspire injects several configuration properties that you can use in the consuming project. + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Host` property of a resource called `database` becomes `DATABASE_HOST`. + +Use the `GetValue()` method to obtain these environment variables in consuming projects: + +```csharp title="C# โ€” Obtain configuration properties" +string sqlHost = builder.Configuration.GetValue("DATABASE_HOST"); +string sqlPort = builder.Configuration.GetValue("DATABASE_PORT"); +string databaseName = builder.Configuration.GetValue("DATABASE_DATABASENAME"); +``` + + + +## Add Azure SQL Database resources in client code + +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/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..06ac657a --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-client.mdx @@ -0,0 +1,202 @@ +--- +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... +} +``` + +## Properties of the Azure Blob Storage resources + +When you use the `WithReference` method to pass an Azure Blob Storage resource from the AppHost project to a consuming client project, several properties are available to use in the consuming project. + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `blobs` becomes `BLOBS_URI`. + +### Azure Blob Storage + +The Azure Blob Storage resource exposes the following connection properties: + +| Property Name | Description | +| ------------- | ---------------------------- | +| `Uri` | The blob service endpoint | + +In emulator mode, an additional property is available: + +| Property Name | Description | +| ------------------ | ------------------------------------------ | +| `ConnectionString` | The full connection string for the emulator | + +For example, if you reference a Blob Storage resource named `blobs` in your AppHost project, the following environment variables will be available in the consuming project: + +- `BLOBS_URI` + +### 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..1390f5dd --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-get-started.mdx @@ -0,0 +1,18 @@ +--- +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'; + +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/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..8c0b6960 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-queues/azure-storage-queues-client.mdx @@ -0,0 +1,210 @@ +--- +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 `AddAzureQueueServiceClient` extension method to register a `QueueServiceClient` for dependency injection. The method takes a connection name parameter: + +```csharp +builder.AddAzureQueueServiceClient("queues"); +``` + +You can then retrieve the `QueueServiceClient` instance using dependency injection: + +```csharp +public class ExampleService(QueueServiceClient client) +{ + // Use client... +} +``` + +## Properties of the Azure Queue Storage resources + +When you use the `WithReference` method to pass an Azure Queue Storage resource from the AppHost project to a consuming client project, several properties are available to use in the consuming project. + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `queues` becomes `QUEUES_URI`. + +### Azure Queue Storage + +The Azure Queue Storage resource exposes the following connection properties: + +| Property Name | Description | +| ------------- | ----------------------------- | +| `Uri` | The queue service endpoint | + +In emulator mode, an additional property is available: + +| Property Name | Description | +| ------------------ | ------------------------------------------ | +| `ConnectionString` | The full connection string for the emulator | + +### Azure Queue Storage queue + +The Azure Queue Storage queue resource inherits all properties from its parent storage and adds: + +| Property Name | Description | +| ------------- | ------------------ | +| `QueueName` | The queue name | + +For example, if you reference a Queue Storage resource named `queues` in your AppHost project, the following environment variables will be available in the consuming project: + +- `QUEUES_URI` + +### 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 `AddAzureQueueServiceClient`: + +```csharp +builder.AddAzureQueueServiceClient("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 `AddAzureQueueServiceClient`: + +```csharp +builder.AddAzureQueueServiceClient("queue1"); +builder.AddAzureQueueServiceClient("queue2"); +``` + +#### Use inline delegates + +You can also pass the `Action` delegate to set up options inline: + +```csharp +builder.AddAzureQueueServiceClient( + "queues", + settings => settings.DisableHealthChecks = true); +``` + +You can also configure the `QueueClientOptions`: + +```csharp +builder.AddAzureQueueServiceClient( + "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..a85b477e --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-queues/azure-storage-queues-get-started.mdx @@ -0,0 +1,18 @@ +--- +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'; + +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/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..9aa5d789 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-tables/azure-storage-tables-client.mdx @@ -0,0 +1,165 @@ +--- +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 `AddAzureTableServiceClient` extension method to register a `TableServiceClient` for dependency injection. The method takes a connection name parameter: + +```csharp +builder.AddAzureTableServiceClient("tables"); +``` + +You can then retrieve the `TableServiceClient` instance using dependency injection: + +```csharp +public class ExampleService(TableServiceClient client) +{ + // Use client... +} +``` + +## Properties of the Azure Table Storage resources + +When you use the `WithReference` method to pass an Azure Table Storage resource from the AppHost project to a consuming client project, several properties are available to use in the consuming project. + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `tables` becomes `TABLES_URI`. + +### Azure Table Storage + +The Azure Table Storage resource exposes the following connection properties: + +| Property Name | Description | +| ------------- | ----------------------------- | +| `Uri` | The table service endpoint | + +In emulator mode, an additional property is available: + +| Property Name | Description | +| ------------------ | ------------------------------------------ | +| `ConnectionString` | The full connection string for the emulator | + +For example, if you reference a Table Storage resource named `tables` in your AppHost project, the following environment variables will be available in the consuming project: + +- `TABLES_URI` + +### 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 `AddAzureTableServiceClient`: + +```csharp +builder.AddAzureTableServiceClient("tables1"); +builder.AddAzureTableServiceClient("tables2"); +``` + +#### Use inline delegates + +You can also pass the `Action` delegate to set up options inline: + +```csharp +builder.AddAzureTableServiceClient( + "tables", + settings => settings.DisableHealthChecks = true); +``` + +You can also configure the `TableClientOptions`: + +```csharp +builder.AddAzureTableServiceClient( + "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..37f7fe69 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-storage-tables/azure-storage-tables-get-started.mdx @@ -0,0 +1,18 @@ +--- +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'; + +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/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..2ef83d70 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-client.mdx @@ -0,0 +1,182 @@ +--- +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. + +## Properties of the Azure Web PubSub resources + +When you use the `WithReference` method to pass an Azure Web PubSub resource from the AppHost project to a consuming client project, several properties are available to use in the consuming project. + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `webpubsub` becomes `WEBPUBSUB_URI`. + +### Azure Web PubSub service + +The Azure Web PubSub resource exposes the following connection properties: + +| Property Name | Description | +| ------------- | --------------------------------------------------------------------- | +| `Uri` | The service endpoint URI (e.g., `https://{name}.webpubsub.azure.com`) | + +For example, if you reference an Azure Web PubSub resource named `webpubsub` in your AppHost project, the following environment variables will be available in the consuming project: + +- `WEBPUBSUB_URI` + +### 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..6cc0fb28 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-get-started.mdx @@ -0,0 +1,18 @@ +--- +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'; + +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/content/docs/integrations/cloud/azure/overview.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/overview.mdx index 7480aae9..f6db197a 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/overview.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/overview.mdx @@ -46,13 +46,13 @@ Some Azure services can be emulated to run locally. Currently, Aspire supports t | Hosting integration | Description | |--|--| -| [Azure App Configuration](/integrations/cloud/azure/azure-app-configuration/) | Call `RunAsEmulator` on the `IResourceBuilder` to configure the Azure App Configuration resource to be [emulated with the Azure App Configuration Emulator](https://learn.microsoft.com/azure/azure-app-configuration/emulator-overview). | -| [Azure Cosmos DB](/integrations/cloud/azure/azure-cosmos-db/) | Call `RunAsEmulator` on the `IResourceBuilder` to configure the Cosmos DB resource to be [emulated with the NoSQL API](https://learn.microsoft.com/azure/cosmos-db/how-to-develop-emulator). | -| [Azure AI Foundry](/integrations/cloud/azure/azure-ai-foundry/) | Call `RunAsFoundryLocal` on the `IResourceBuilder` to configure the resource to be [emulated with Foundry Local](https://learn.microsoft.com/azure/ai-foundry/foundry-local/get-started). | -| [Azure Event Hubs](/integrations/cloud/azure/azure-event-hubs/) | Call `RunAsEmulator` on the `IResourceBuilder` to configure the Event Hubs resource to be [emulated](https://learn.microsoft.com/azure/event-hubs/overview-emulator). | -| [Azure Service Bus](/integrations/cloud/azure/azure-service-bus/) | Call `RunAsEmulator` on the `IResourceBuilder` to configure the Service Bus resource to be [emulated with Service Bus emulator](https://learn.microsoft.com/azure/service-bus-messaging/overview-emulator). | -| [Azure SignalR Service](/integrations/cloud/azure/azure-signalr/) | Call `RunAsEmulator` on the `IResourceBuilder` to configure the SignalR resource to be [emulated with Azure SignalR emulator](https://learn.microsoft.com/azure/azure-signalr/signalr-howto-emulator). | -| [Azure Storage](/integrations/cloud/azure/azure-storage-blobs/) | Call `RunAsEmulator` on the `IResourceBuilder` to configure the Storage resource to be [emulated with Azurite](https://learn.microsoft.com/azure/storage/common/storage-use-azurite). | +| [Azure App Configuration](/integrations/cloud/azure/azure-app-configuration/azure-app-configuration-get-started/) | Call `RunAsEmulator` on the `IResourceBuilder` to configure the Azure App Configuration resource to be [emulated with the Azure App Configuration Emulator](https://learn.microsoft.com/azure/azure-app-configuration/emulator-overview). | +| [Azure Cosmos DB](/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-get-started/) | Call `RunAsEmulator` on the `IResourceBuilder` to configure the Cosmos DB resource to be [emulated with the NoSQL API](https://learn.microsoft.com/azure/cosmos-db/how-to-develop-emulator). | +| [Azure AI Foundry](/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started/) | Call `RunAsFoundryLocal` on the `IResourceBuilder` to configure the resource to be [emulated with Foundry Local](https://learn.microsoft.com/azure/ai-foundry/foundry-local/get-started). | +| [Azure Event Hubs](/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-get-started/) | Call `RunAsEmulator` on the `IResourceBuilder` to configure the Event Hubs resource to be [emulated](https://learn.microsoft.com/azure/event-hubs/overview-emulator). | +| [Azure Service Bus](/integrations/cloud/azure/azure-service-bus/azure-service-bus-get-started/) | Call `RunAsEmulator` on the `IResourceBuilder` to configure the Service Bus resource to be [emulated with Service Bus emulator](https://learn.microsoft.com/azure/service-bus-messaging/overview-emulator). | +| [Azure SignalR Service](/integrations/cloud/azure/azure-signalr/azure-signalr-get-started/) | Call `RunAsEmulator` on the `IResourceBuilder` to configure the SignalR resource to be [emulated with Azure SignalR emulator](https://learn.microsoft.com/azure/azure-signalr/signalr-howto-emulator). | +| [Azure Storage](/integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-get-started/) | Call `RunAsEmulator` on the `IResourceBuilder` to configure the Storage resource to be [emulated with Azurite](https://learn.microsoft.com/azure/storage/common/storage-use-azurite). | To have your Azure resources use the local emulators, chain a call the `RunAsEmulator` method on the Azure resource builder. This method configures the Azure resource to use the local emulator instead of the actual Azure service. @@ -67,9 +67,9 @@ Currently, Aspire supports the following Azure services as containers: | Hosting integration | Details | |--|--| -| [Azure Cache for Redis](/integrations/cloud/azure/azure-cache-redis/) | Call `RunAsContainer` on the `IResourceBuilder` to configure it to run locally in a container, based on the `docker.io/library/redis` image. | +| [Azure Cache for Redis](/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-get-started/) | Call `RunAsContainer` on the `IResourceBuilder` to configure it to run locally in a container, based on the `docker.io/library/redis` image. | | [Azure PostgreSQL Flexible Server](/integrations/cloud/azure/azure-postgresql/azure-postgresql-get-started/) | Call `RunAsContainer` on the `IResourceBuilder` to configure it to run locally in a container, based on the `docker.io/library/postgres` image. | -| [Azure SQL Server](/integrations/cloud/azure/azure-sql-database/) | Call `RunAsContainer` on the `IResourceBuilder` to configure it to run locally in a container, based on the `mcr.microsoft.com/mssql/server` image. | +| [Azure SQL Server](/integrations/cloud/azure/azure-sql-database/azure-sql-database-get-started/) | Call `RunAsContainer` on the `IResourceBuilder` to configure it to run locally in a container, based on the `mcr.microsoft.com/mssql/server` image. | > [!NOTE] > Like emulators, calling `RunAsContainer` on an Azure resource builder doesn't effect the [publishing manifest](/architecture/resource-publishing/). When you publish your app, the [generated Bicep file](/integrations/cloud/azure/customize-resources/) reflects the actual Azure service, not the local container. @@ -354,7 +354,7 @@ The preceding code: To configure the Azure Container App environment, see [Configure Azure Container Apps environments](/integrations/cloud/azure/configure-container-apps/). For information about publishing resources as Azure Container App Jobs, see [Azure Container App Jobs](/integrations/cloud/azure/container-app-jobs/). For more information, see [Azure.Provisioning.AppContainers.ContainerApp](https://learn.microsoft.com/dotnet/api/azure.provisioning.appcontainers.containerapp) and the `AsProvisioningParameter` API documentation. > [!TIP] -> If you're working with Azure Container Apps, you might also be interested in the [Aspire Azure Container Registry integration](/integrations/cloud/azure/azure-container-registry/). +> If you're working with Azure Container Apps, you might also be interested in the [Aspire Azure Container Registry integration](/integrations/cloud/azure/azure-container-registry/azure-container-registry-get-started/). ## See also diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/role-assignments.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/role-assignments.mdx index e76dae4d..c698542d 100644 --- a/src/frontend/src/content/docs/integrations/cloud/azure/role-assignments.mdx +++ b/src/frontend/src/content/docs/integrations/cloud/azure/role-assignments.mdx @@ -11,7 +11,7 @@ All Aspire Azure hosting integrations define Azure resources. These resources co When you add an Azure resource to the [AppHost](/get-started/app-host/), it's assigned default roles. If a resource depends on another resource, it inherits the same role assignments as the referenced resource unless explicitly overridden. -Consider a scenario where an API project resource references an [Azure Search](/integrations/cloud/azure/azure-ai-search/) resource. The API project is given the default role assignments, as shown in the following example: +Consider a scenario where an API project resource references an [Azure Search](/integrations/cloud/azure/azure-ai-search/azure-ai-search-get-started/) resource. The API project is given the default role assignments, as shown in the following example: ```csharp title="C# โ€” AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); @@ -108,7 +108,7 @@ The provisioning resource type is `Azure.Provisioning.CognitiveServices.Cognitiv - `Azure.Provisioning.CognitiveServices.CognitiveServicesBuiltInRole.CognitiveServicesUsagesReader` - `Azure.Provisioning.CognitiveServices.CognitiveServicesBuiltInRole.CognitiveServicesUser` -For more information, see [Aspire Azure OpenAI integration](/integrations/cloud/azure/azure-openai/). +For more information, see [Aspire Azure OpenAI integration](/integrations/cloud/azure/azure-openai/azure-openai-get-started/). ### Azure Cosmos DB @@ -120,7 +120,7 @@ The provisioning resource type is `Azure.Provisioning.CosmosDB.CosmosDBAccount>, For more information, see: -- [Aspire Azure Cosmos DB integration](/integrations/cloud/azure/azure-cosmos-db/). +- [Aspire Azure Cosmos DB integration](/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-get-started/). ### Azure Event Hubs @@ -132,7 +132,7 @@ The provisioning resource type is `Azure.Provisioning.EventHubs.EventHubsNamespa - `Azure.Provisioning.EventHubs.EventHubsBuiltInRole.SchemaRegistryContributor` - `Azure.Provisioning.EventHubs.EventHubsBuiltInRole.SchemaRegistryReader` -For more information, see [Aspire Azure Event Hubs integration](/integrations/cloud/azure/azure-event-hubs/). +For more information, see [Aspire Azure Event Hubs integration](/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-get-started/). ### Azure Key Vault @@ -153,7 +153,7 @@ The provisioning resource type is `Azure.Provisioning.KeyVault.KeyVaultService>, - `Azure.Provisioning.KeyVault.KeyVaultBuiltInRole.KeyVaultSecretsUser` - `Azure.Provisioning.KeyVault.KeyVaultBuiltInRole.ManagedHsmContributor` -For more information, see [Aspire Azure Key Vault integration](/integrations/cloud/azure/azure-key-vault/). +For more information, see [Aspire Azure Key Vault integration](/integrations/cloud/azure/azure-key-vault/azure-key-vault-get-started/). ### Azure AI Search @@ -163,7 +163,7 @@ The provisioning resource type is `Azure.Provisioning.Search.SearchService>, and - `Azure.Provisioning.Search.SearchBuiltInRole.SearchIndexDataReader` - `Azure.Provisioning.Search.SearchBuiltInRole.SearchServiceContributor` -For more information, see [Aspire Azure AI Search integration](/integrations/cloud/azure/azure-ai-search/). +For more information, see [Aspire Azure AI Search integration](/integrations/cloud/azure/azure-ai-search/azure-ai-search-get-started/). ### Azure Service Bus @@ -173,7 +173,7 @@ The provisioning resource type is `Azure.Provisioning.ServiceBus.ServiceBusNames - `Azure.Provisioning.ServiceBus.ServiceBusBuiltInRole.AzureServiceBusDataReceiver` - `Azure.Provisioning.ServiceBus.ServiceBusBuiltInRole.AzureServiceBusDataSender` -For more information, see [Aspire Azure Service Bus integration](/integrations/cloud/azure/azure-service-bus/). +For more information, see [Aspire Azure Service Bus integration](/integrations/cloud/azure/azure-service-bus/azure-service-bus-get-started/). ### Azure SignalR Service @@ -186,7 +186,7 @@ The provisioning resource type is `Azure.Provisioning.SignalR.SignalRService>, a - `Azure.Provisioning.SignalR.SignalRBuiltInRole.SignalRRestApiReader` - `Azure.Provisioning.SignalR.SignalRBuiltInRole.SignalRServiceOwner` -For more information, see [Aspire support for Azure SignalR Service](/integrations/cloud/azure/azure-signalr/). +For more information, see [Aspire support for Azure SignalR Service](/integrations/cloud/azure/azure-signalr/azure-signalr-get-started/). ### Azure SQL @@ -198,7 +198,7 @@ The provisioning resource type is `Azure.Provisioning.Sql.SqlServer>, and the bu - `Azure.Provisioning.Sql.SqlBuiltInRole.SqlSecurityManager` - `Azure.Provisioning.Sql.SqlBuiltInRole.SqlServerContributor` -For more information, see [Aspire Azure SQL integration](/integrations/cloud/azure/azure-sql-database/). +For more information, see [Aspire Azure SQL integration](/integrations/cloud/azure/azure-sql-database/azure-sql-database-get-started/). ### Azure Storage @@ -227,9 +227,9 @@ The provisioning resource type is `Azure.Provisioning.Storage.StorageAccount`, a For more information, see: -- [Aspire Azure Blob Storage integration](/integrations/cloud/azure/azure-storage-blobs/) -- [Aspire Azure Data Tables integration](/integrations/cloud/azure/azure-storage-queues/) -- [Aspire Azure Queue Storage integration](/integrations/cloud/azure/azure-storage-tables/) +- [Aspire Azure Blob Storage integration](/integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-get-started/) +- [Aspire Azure Data Tables integration](/integrations/cloud/azure/azure-storage-tables/azure-storage-tables-get-started/) +- [Aspire Azure Queue Storage integration](/integrations/cloud/azure/azure-storage-queues/azure-storage-queues-get-started/) ### Azure Web PubSub @@ -239,7 +239,7 @@ The provisioning resource type is `Azure.Provisioning.WebPubSub.WebPubSubService - `Azure.Provisioning.WebPubSub.WebPubSubBuiltInRole.WebPubSubServiceOwner` - `Azure.Provisioning.WebPubSub.WebPubSubBuiltInRole.WebPubSubServiceReader` -For more information, see [Aspire Azure Web PubSub integration](/integrations/cloud/azure/azure-web-pubsub/). +For more information, see [Aspire Azure Web PubSub integration](/integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-get-started/). ## See also diff --git a/src/frontend/src/content/docs/integrations/databases/efcore/azure-cosmos-db/azure-cosmos-db-host.mdx b/src/frontend/src/content/docs/integrations/databases/efcore/azure-cosmos-db/azure-cosmos-db-host.mdx index c775358f..ce32a8ad 100644 --- a/src/frontend/src/content/docs/integrations/databases/efcore/azure-cosmos-db/azure-cosmos-db-host.mdx +++ b/src/frontend/src/content/docs/integrations/databases/efcore/azure-cosmos-db/azure-cosmos-db-host.mdx @@ -37,7 +37,7 @@ For an introduction to the Azure Cosmos DB integration, see [Get started with th In your AppHost project, call `AddAzureCosmosDB` to add and return an Azure Cosmos DB resource builder: -```csharp csharp title="C# โ€” AppHost.cs" +```csharp title="C# โ€” AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); var cosmos = builder.AddAzureCosmosDB("cosmos-db"); @@ -88,7 +88,7 @@ Aspire models parent child relationships between Azure Cosmos DB resources. For To add an Azure Cosmos DB database resource, call the `AddCosmosDatabase` method on an `IResourceBuilder` instance: -```csharp csharp title="C# โ€” AppHost.cs" +```csharp title="C# โ€” AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); var cosmos = builder.AddAzureCosmosDB("cosmos-db"); @@ -103,7 +103,7 @@ An Azure Cosmos DB container is where data is stored. When you create a containe To add an Azure Cosmos DB container resource, call the `AddContainer` method on an `IResourceBuilder` instance: -```csharp csharp title="C# โ€” AppHost.cs" +```csharp title="C# โ€” AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); var cosmos = builder.AddAzureCosmosDB("cosmos-db"); diff --git a/src/frontend/src/content/docs/ja/whats-new/aspire-13-1.mdx b/src/frontend/src/content/docs/ja/whats-new/aspire-13-1.mdx index 2e88754c..48548440 100644 --- a/src/frontend/src/content/docs/ja/whats-new/aspire-13-1.mdx +++ b/src/frontend/src/content/docs/ja/whats-new/aspire-13-1.mdx @@ -515,7 +515,7 @@ builder.AddAzureFunctionsProject("myfunc", "../MyFunctions/MyFunctions.csproj"); ``` -่ฉณ็ดฐใซใคใ„ใฆใฏ [Azure Functions ็ตฑๅˆ](/ja/integrations/cloud/azure/azure-functions/) ใพใŸใฏ [Aspire ใจ Azure Functions ใฎไฝฟใ„ๆ–น](https://learn.microsoft.com/azure/azure-functions/dotnet-aspire-integration) ใ‚’ใ”ๅ‚็…งใใ ใ•ใ„ใ€‚ +่ฉณ็ดฐใซใคใ„ใฆใฏ [Azure Functions ็ตฑๅˆ](/integrations/cloud/azure/azure-functions/azure-functions-get-started/) ใพใŸใฏ [Aspire ใจ Azure Functions ใฎไฝฟใ„ๆ–น](https://learn.microsoft.com/azure/azure-functions/dotnet-aspire-integration) ใ‚’ใ”ๅ‚็…งใใ ใ•ใ„ใ€‚ ## ๐Ÿ—๏ธ ใƒ†ใƒณใƒ—ใƒฌใƒผใƒˆ diff --git a/src/frontend/src/content/docs/whats-new/aspire-13-1.mdx b/src/frontend/src/content/docs/whats-new/aspire-13-1.mdx index 3ad79a07..e0978a29 100644 --- a/src/frontend/src/content/docs/whats-new/aspire-13-1.mdx +++ b/src/frontend/src/content/docs/whats-new/aspire-13-1.mdx @@ -515,7 +515,7 @@ builder.AddAzureFunctionsProject("myfunc", "../MyFunctions/MyFunctions.csproj"); ``` -Learn more about the [Azure Functions integration](/integrations/cloud/azure/azure-functions/) or [how to use Azure Functions with Aspire](https://learn.microsoft.com/azure/azure-functions/dotnet-aspire-integration). +Learn more about the [Azure Functions integration](/integrations/cloud/azure/azure-functions/azure-functions-get-started/) or [how to use Azure Functions with Aspire](https://learn.microsoft.com/azure/azure-functions/dotnet-aspire-integration). ## ๐Ÿ—๏ธ Templates diff --git a/src/frontend/src/content/docs/whats-new/aspire-9-1.mdx b/src/frontend/src/content/docs/whats-new/aspire-9-1.mdx index 2bd18017..8590943f 100644 --- a/src/frontend/src/content/docs/whats-new/aspire-9-1.mdx +++ b/src/frontend/src/content/docs/whats-new/aspire-9-1.mdx @@ -181,9 +181,9 @@ This release also focused on improving various [Azure integrations](/integration We're excited to bring new emulators for making local development easier. The following integrations got new emulators in this release: -- [Azure Service Bus](/integrations/cloud/azure/azure-service-bus/#add-azure-service-bus-emulator-resource) -- [Azure Cosmos DB Linux-based (preview)](/integrations/cloud/azure/azure-cosmos-db/#use-linux-based-emulator-preview) -- [Azure SignalR](/integrations/cloud/azure/azure-signalr/#add-an-azure-signalr-service-emulator-resource) +- [Azure Service Bus](/integrations/cloud/azure/azure-service-bus/azure-service-bus-host/#add-azure-service-bus-emulator-resource) +- [Azure Cosmos DB Linux-based (preview)](/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-host/#use-linux-based-emulator-preview) +- [Azure SignalR](/integrations/cloud/azure/azure-signalr/azure-signalr-host/#add-an-azure-signalr-service-emulator-resource) ```csharp var serviceBus = builder.AddAzureServiceBus("servicebus") @@ -199,9 +199,9 @@ var signalr = builder.AddAzureSignalR("signalr", AzureSignalRServiceMode.Serverl These new emulators work side-by-side with the existing emulators for: -- [Azure Storage](/integrations/cloud/azure/azure-storage-blobs/) -- [Azure Event Hubs](/integrations/cloud/azure/azure-event-hubs/#add-azure-event-hubs-emulator-resource) -- [Azure Cosmos DB](/integrations/cloud/azure/azure-cosmos-db/#add-azure-cosmos-db-emulator-resource) +- [Azure Storage](/integrations/cloud/azure/azure-storage-blobs/azure-storage-blobs-get-started/) +- [Azure Event Hubs](/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-host/#add-azure-event-hubs-emulator-resource) +- [Azure Cosmos DB](/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-host/#add-azure-cosmos-db-emulator-resource) #### ๐ŸŒŒ Cosmos DB @@ -217,8 +217,8 @@ You can define a Cosmos DB database and containers in the AppHost and these reso For example API usage to add database and containers, see the following related articles: -- [Aspire Azure Cosmos DB integration](/integrations/cloud/azure/azure-cosmos-db/#add-azure-cosmos-db-database-and-container-resources) -- [Aspire Cosmos DB Entity Framework Core integration](/integrations/cloud/azure/azure-cosmos-db/#add-azure-cosmos-db-database-and-container-resources) +- [Aspire Azure Cosmos DB integration](/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-host/#add-azure-cosmos-db-database-and-container-resources) +- [Aspire Cosmos DB Entity Framework Core integration](/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-host/#add-azure-cosmos-db-database-and-container-resources) ##### โšก Support for Cosmos DB-based triggers in Azure Functions @@ -254,7 +254,7 @@ public class MyCosmosDbTrigger(ILogger logger) } ``` -For more information using Azure Functions with Aspire, see [Aspire Azure Functions integration (Preview)](/integrations/cloud/azure/azure-functions/). +For more information using Azure Functions with Aspire, see [Aspire Azure Functions integration (Preview)](/integrations/cloud/azure/azure-functions/azure-functions-get-started/). #### ๐Ÿšš Service Bus and Event Hubs @@ -262,8 +262,8 @@ Similar to Cosmos DB, the Service Bus and Event Hubs integrations now allow you For more information, see the following updated articles: -- [Aspire Azure Service Bus integration](/integrations/cloud/azure/azure-service-bus/) -- [Aspire Azure Event Hubs integration](/integrations/cloud/azure/azure-event-hubs/) +- [Aspire Azure Service Bus integration](/integrations/cloud/azure/azure-service-bus/azure-service-bus-get-started/) +- [Aspire Azure Event Hubs integration](/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-get-started/) #### โ™ป๏ธ Working with existing resources diff --git a/src/frontend/src/content/docs/whats-new/aspire-9-4.mdx b/src/frontend/src/content/docs/whats-new/aspire-9-4.mdx index f4898de7..c5f743a2 100644 --- a/src/frontend/src/content/docs/whats-new/aspire-9-4.mdx +++ b/src/frontend/src/content/docs/whats-new/aspire-9-4.mdx @@ -1081,7 +1081,7 @@ builder.Build().Run(); #### Client integration -Once you've configured the [Azure AI Foundry resource](https://aspire.dev/integrations/cloud/azure/azure-ai-foundry/) in your AppHost, consume it in your services using the [Azure AI Inference SDK](https://aspire.dev/integrations/cloud/azure/azure-ai-inference/) or [OpenAI SDK](https://aspire.dev/integrations/cloud/azure/azure-openai/) for compatible models: +Once you've configured the [Azure AI Foundry resource](https://aspire.dev/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started/) in your AppHost, consume it in your services using the [Azure AI Inference SDK](https://aspire.dev/integrations/cloud/azure/azure-ai-inference/azure-ai-inference-get-started/) or [OpenAI SDK](https://aspire.dev/integrations/cloud/azure/azure-openai/azure-openai-get-started/) for compatible models: **Using Azure AI Inference SDK:** @@ -1262,7 +1262,7 @@ This approach provides: #### ๐Ÿ” Disabled local authentication to enforce managed identity -Aspire 9.4 automatically disables local authentication for [Azure EventHubs](https://aspire.dev/integrations/cloud/azure/azure-event-hubs/) and [Azure Web PubSub](https://aspire.dev/integrations/cloud/azure/azure-web-pubsub/) resources, enforcing managed identity authentication by default. +Aspire 9.4 automatically disables local authentication for [Azure EventHubs](https://aspire.dev/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-get-started/) and [Azure Web PubSub](https://aspire.dev/integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-get-started/) resources, enforcing managed identity authentication by default. ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -1286,7 +1286,7 @@ This change automatically applies to all Azure EventHubs and Web PubSub resource ### ๐Ÿ” Azure Key Vault enhancements -Aspire 9.4 introduces significant improvements to the [Azure Key Vault integration](https://aspire.dev/integrations/cloud/azure/azure-key-vault/) with new secret management APIs that provide strongly typed access to secrets: +Aspire 9.4 introduces significant improvements to the [Azure Key Vault integration](https://aspire.dev/integrations/cloud/azure/azure-key-vault/azure-key-vault-get-started/) with new secret management APIs that provide strongly typed access to secrets: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -1374,7 +1374,7 @@ This approach provides clean separation of concerns, secure container scoping, a ### ๐Ÿ“ก OpenTelemetry tracing support for Azure App Configuration -Aspire 9.4 introduces **OpenTelemetry tracing support** for [Azure App Configuration](https://aspire.dev/integrations/cloud/azure/azure-app-configuration/), completing the observability story for this integration. The Azure App Configuration integration now automatically instruments configuration retrieval operations and refresh operations with distributed tracing. +Aspire 9.4 introduces **OpenTelemetry tracing support** for [Azure App Configuration](https://aspire.dev/integrations/cloud/azure/azure-app-configuration/azure-app-configuration-get-started/), completing the observability story for this integration. The Azure App Configuration integration now automatically instruments configuration retrieval operations and refresh operations with distributed tracing. ```csharp var builder = WebApplication.CreateBuilder(args); diff --git a/src/frontend/src/content/docs/whats-new/aspire-9-5.mdx b/src/frontend/src/content/docs/whats-new/aspire-9-5.mdx index 1934cec7..1aa4b43e 100644 --- a/src/frontend/src/content/docs/whats-new/aspire-9-5.mdx +++ b/src/frontend/src/content/docs/whats-new/aspire-9-5.mdx @@ -343,7 +343,7 @@ var embeddingModel = builder.AddGitHubModel("embeddings", GitHubModel.OpenAI.Ope For more information, see: - [Aspire GitHub Models integration (Preview)](https://aspire.dev/integrations/ai/github-models/). -- [Aspire Azure AI Foundry integration (Preview)](https://aspire.dev/integrations/cloud/azure/azure-ai-foundry/). +- [Aspire Azure AI Foundry integration (Preview)](https://aspire.dev/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-get-started/). ### Dev Tunnels hosting integration @@ -547,7 +547,7 @@ var redisEnterprise = builder.AddAzureRedisEnterprise("redis-enterprise") .WithAccessKeyAuthentication(keyVault); ``` -For more information, see [Aspire Azure Managed Redis integration](https://aspire.dev/integrations/cloud/azure/azure-cache-redis/). +For more information, see [Aspire Azure Managed Redis integration](https://aspire.dev/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-get-started/). ### Azure App Configuration emulator (preview) diff --git a/src/frontend/src/content/docs/whats-new/aspire-9.mdx b/src/frontend/src/content/docs/whats-new/aspire-9.mdx index e7c0dd08..1cda6a2c 100644 --- a/src/frontend/src/content/docs/whats-new/aspire-9.mdx +++ b/src/frontend/src/content/docs/whats-new/aspire-9.mdx @@ -385,7 +385,7 @@ In order to make Aspire applications more secure, Azure Database for PostgreSQL The following examples demonstrate how to configure your application to connect to the Azure resources using Microsoft Entra ID: - [Aspire: Azure PostgreSQL hosting integration](/integrations/cloud/azure/azure-postgresql/azure-postgresql-get-started/). -- [Aspire: Azure Redis hosting integration](/integrations/cloud/azure/azure-cache-redis/#hosting-integration). +- [Aspire: Azure Redis hosting integration](/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-host/). If you need to use password or access key authentication (not recommended), you can opt-in with the following code: @@ -652,7 +652,7 @@ Support for Azure Functions in Aspire is still in preview with support for a lim - [Azure Service Bus triggers](https://learn.microsoft.com/azure/azure-functions/functions-bindings-service-bus?pivots=programming-language-csharp) - [Azure Event Hubs triggers](https://learn.microsoft.com/azure/azure-functions/functions-bindings-event-hubs?pivots=programming-language-csharp) -For more information, see the official [Aspire Azure Functions integration (Preview)](/integrations/cloud/azure/azure-functions/). +For more information, see the official [Aspire Azure Functions integration (Preview)](/integrations/cloud/azure/azure-functions/azure-functions-get-started/). #### Customization of Azure Container Apps diff --git a/src/frontend/src/data/integration-docs.json b/src/frontend/src/data/integration-docs.json index 29ab9d20..6d14e31b 100644 --- a/src/frontend/src/data/integration-docs.json +++ b/src/frontend/src/data/integration-docs.json @@ -1,27 +1,27 @@ [ { "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", - "href": "/integrations/cloud/azure/azure-openai/" + "href": "/integrations/cloud/azure/azure-openai/azure-openai-get-started/" }, { "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", - "href": "/integrations/cloud/azure/azure-event-hubs/" + "href": "/integrations/cloud/azure/azure-event-hubs/azure-event-hubs-get-started/" }, { "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", - "href": "/integrations/cloud/azure/azure-web-pubsub/" + "href": "/integrations/cloud/azure/azure-web-pubsub/azure-web-pubsub-get-started/" }, { "match": "Aspire.Azure.Npgsql", @@ -33,19 +33,19 @@ }, { "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", - "href": "/integrations/cloud/azure/azure-key-vault/" + "href": "/integrations/cloud/azure/azure-key-vault/azure-key-vault-get-started/" }, { "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", - "href": "/integrations/cloud/azure/azure-storage-queues/" + "href": "/integrations/cloud/azure/azure-storage-queues/azure-storage-queues-get-started/" }, { "match": "Aspire.Confluent.Kafka", @@ -61,11 +61,11 @@ }, { "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", - "href": "/integrations/cloud/azure/azure-app-configuration/" + "href": "/integrations/cloud/azure/azure-app-configuration/azure-app-configuration-get-started/" }, { "match": "Aspire.Hosting.Azure.AppContainers", @@ -77,31 +77,31 @@ }, { "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", - "href": "/integrations/cloud/azure/azure-openai/" + "href": "/integrations/cloud/azure/azure-openai/azure-openai-get-started/" }, { "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", - "href": "/integrations/cloud/azure/azure-cosmos-db/" + "href": "/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-get-started/" }, { "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", - "href": "/integrations/cloud/azure/azure-functions/" + "href": "/integrations/cloud/azure/azure-functions/azure-functions-get-started/" }, { "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", @@ -117,23 +117,23 @@ }, { "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", - "href": "/integrations/cloud/azure/azure-ai-search/" + "href": "/integrations/cloud/azure/azure-ai-search/azure-ai-search-get-started/" }, { "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", - "href": "/integrations/cloud/azure/azure-signalr/" + "href": "/integrations/cloud/azure/azure-signalr/azure-signalr-get-started/" }, { "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", @@ -257,11 +257,11 @@ }, { "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", - "href": "/integrations/cloud/azure/azure-cache-redis/" + "href": "/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-get-started/" }, { "match": "Aspire.Microsoft.Data.SqlClient", @@ -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",