diff --git a/docs/azureai/azureai-openai-component.md b/docs/azureai/azureai-openai-component.md index 1e411aa527..69a0569852 100644 --- a/docs/azureai/azureai-openai-component.md +++ b/docs/azureai/azureai-openai-component.md @@ -2,7 +2,7 @@ title: .NET Aspire Azure AI OpenAI component description: Learn how to use the .NET Aspire Azure AI OpenAI component. ms.topic: how-to -ms.date: 03/13/2024 +ms.date: 04/04/2024 --- # .NET Aspire Azure AI OpenAI component @@ -54,7 +54,22 @@ public class ExampleService(OpenAIClient client) ## App host usage -[!INCLUDE [azure-component-nuget](../includes/azure-component-nuget.md)] +To add Azure AI hosting support to your , install the [Aspire.Hosting.Azure.CognitiveServices](https://www.nuget.org/packages/Aspire.Hosting.Azure.CognitiveServices) NuGet package. + +### [.NET CLI](#tab/dotnet-cli) + +```dotnetcli +dotnet add package Aspire.Hosting.Azure.CognitiveServices --prerelease +``` + +### [PackageReference](#tab/package-reference) + +```xml + +``` + +--- In your app host project, register an Azure AI OpenAI resource using the following methods, such as : diff --git a/docs/azureai/azureai-search-document-component.md b/docs/azureai/azureai-search-document-component.md index 6a90264932..3af738968e 100644 --- a/docs/azureai/azureai-search-document-component.md +++ b/docs/azureai/azureai-search-document-component.md @@ -2,7 +2,7 @@ title: NET Aspire Azure AI Search Documents component description: Learn how to use the NET Aspire Azure AI Search Documents component. ms.topic: how-to -ms.date: 03/11/2024 +ms.date: 04/04/2024 --- # NET Aspire Azure AI Search Documents component @@ -75,7 +75,22 @@ For more information, see the [Azure AI Search client library for .NET](https:// ## App host usage -[!INCLUDE [azure-component-nuget](../includes/azure-component-nuget.md)] +To add Azure Cosmos DB hosting support to your , install the [Aspire.Hosting.Azure.CosmosDB](https://www.nuget.org/packages/Aspire.Hosting.Azure.CosmosDB) NuGet package. + +### [.NET CLI](#tab/dotnet-cli) + +```dotnetcli +dotnet add package Aspire.Hosting.Azure.CosmosDB --prerelease +``` + +### [PackageReference](#tab/package-reference) + +```xml + +``` + +--- In the _Program.cs_ file of `AppHost`, add an Azure Search service and consume the connection using the following methods: diff --git a/docs/database/azure-cosmos-db-component.md b/docs/database/azure-cosmos-db-component.md index 4324a8d28f..47f394e14b 100644 --- a/docs/database/azure-cosmos-db-component.md +++ b/docs/database/azure-cosmos-db-component.md @@ -2,7 +2,7 @@ title: .NET Aspire Azure Cosmos DB component description: This article describes the .NET Aspire Azure Cosmos DB component features and capabilities. ms.topic: how-to -ms.date: 03/13/2024 +ms.date: 04/04/2024 --- # .NET Aspire Azure Cosmos DB component @@ -51,7 +51,22 @@ For more information on using the , se ## App host usage -[!INCLUDE [azure-component-nuget](../includes/azure-component-nuget.md)] +To add Azure Cosmos DB hosting support to your , install the [Aspire.Hosting.Azure.CosmosDB](https://www.nuget.org/packages/Aspire.Hosting.Azure.CosmosDB) NuGet package. + +### [.NET CLI](#tab/dotnet-cli) + +```dotnetcli +dotnet add package Aspire.Hosting.Azure.CosmosDB --prerelease +``` + +### [PackageReference](#tab/package-reference) + +```xml + +``` + +--- In your app host project, register the .NET Aspire Azure Cosmos DB component and consume the service using the following methods: diff --git a/docs/database/azure-cosmos-db-entity-framework-component.md b/docs/database/azure-cosmos-db-entity-framework-component.md index 04ad4fa126..7803d9dd74 100644 --- a/docs/database/azure-cosmos-db-entity-framework-component.md +++ b/docs/database/azure-cosmos-db-entity-framework-component.md @@ -2,7 +2,7 @@ title: .NET Aspire Microsoft Entity Framework Core Cosmos DB component description: This article describes the .NET Aspire Microsoft Entity Framework Core Cosmos DB component features and capabilities. ms.topic: how-to -ms.date: 01/22/2024 +ms.date: 04/04/2024 --- # .NET Aspire Microsoft Entity Framework Core Cosmos DB component @@ -51,7 +51,22 @@ For more information on using Entity Framework Core with Azure Cosmos DB, see th ## App host usage -[!INCLUDE [azure-component-nuget](../includes/azure-component-nuget.md)] +To add Azure Cosmos DB hosting support to your , install the [Aspire.Hosting.Azure.CosmosDB](https://www.nuget.org/packages/Aspire.Hosting.Azure.CosmosDB) NuGet package. + +### [.NET CLI](#tab/dotnet-cli) + +```dotnetcli +dotnet add package Aspire.Hosting.Azure.CosmosDB --prerelease +``` + +### [PackageReference](#tab/package-reference) + +```xml + +``` + +--- In your app host project, register the .NET Aspire Microsoft Entity Framework Core Cosmos DB component and consume the service using the following methods: diff --git a/docs/includes/azure-component-nuget.md b/docs/includes/azure-component-nuget.md deleted file mode 100644 index 389725cffc..0000000000 --- a/docs/includes/azure-component-nuget.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -ms.date: 01/22/2024 -ms.topic: include ---- - -The .NET Aspire Azure hosting APIs are available in the `Aspire.Hosting.Azure` NuGet package. These APIs provide Azure-specific resources used within the App Host. To add Azure resources to your , install the [Aspire.Hosting.Azure](https://www.nuget.org/packages/Aspire.Hosting.Azure) NuGet package. - -### [.NET CLI](#tab/dotnet-cli) - -```dotnetcli -dotnet add package Aspire.Hosting.Azure --prerelease -``` - -### [PackageReference](#tab/package-reference) - -```xml - -``` - ---- diff --git a/docs/index.yml b/docs/index.yml index 5121b6bca9..ba78d4fb91 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -118,6 +118,9 @@ conceptualContent: - itemType: tutorial text: Implement Messaging with .NET Aspire url: messaging/messaging-components.md + - itemType: overview + text: Azure Event Hubs + url: messaging/azure-event-hubs-component.md - itemType: overview text: Azure Service Bus url: messaging/azure-service-bus-component.md diff --git a/docs/messaging/azure-event-hubs-component.md b/docs/messaging/azure-event-hubs-component.md new file mode 100644 index 0000000000..ba8b427d5d --- /dev/null +++ b/docs/messaging/azure-event-hubs-component.md @@ -0,0 +1,213 @@ +--- +title: .NET Aspire Azure Event Hubs component +description: This article describes the .NET Aspire Azure Event Hubs component features and capabilities. +ms.topic: how-to +ms.date: 04/04/2024 +--- + +# .NET Aspire Azure Event Hubs component + +In this article, you learn how to use the .NET Aspire Azure Event Hubs component. The `Aspire.Azure.Messaging.EventHubs` library offers options for registering an , an , an or a in the DI container for connecting to [Azure Event Hubs](/azure/event-hubs). + +## Prerequisites + +- Azure subscription: [create one for free](https://azure.microsoft.com/free/). +- Azure Event Hubs namespace: for more information, see [add an Event Hubs namespace](/azure/event-hubs/event-hubs-create). Alternatively, you can use a connection string, which isn't recommended in production environments. + +## Get started + +To get started with the .NET Aspire Azure Event Hubs component, install the [Aspire.Azure.Messaging.EventHubs](https://www.nuget.org/packages/Aspire.Azure.Messaging.EventHubs) NuGet package. + +### [.NET CLI](#tab/dotnet-cli) + +```dotnetcli +dotnet add package Aspire.Azure.Messaging.EventHubs --prerelease +``` + +### [PackageReference](#tab/package-reference) + +```xml + +``` + +--- + +For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-package) or [Manage package dependencies in .NET applications](/dotnet/core/tools/dependencies). + +## Supported clients with options classes + +The following clients are supported by the library, along with their corresponding options and settings classes: + +| Client type | Options class | Settings class | +|--------------------------|---------------------------------|----------------------------------------------------| +| `EventHubProducerClient` | `EventHubProducerClientOptions` | `AzureMessagingEventHubsProducerSettings` | +| `EventHubConsumerClient` | `EventHubConsumerClientOptions` | `AzureMessagingEventHubsConsumerSettings` | +| `EventProcessorClient` | `EventProcessorClientOptions` | `AzureMessagingEventHubsProcessorSettings` | +| `PartitionReceiver` | `PartitionReceiverOptions` | `AzureMessagingEventHubsPartitionReceiverSettings` | + +## Example usage + +The following example assumes that you have an Azure Event Hubs namespace and an Event Hub created and wish to configure an `EventHubProducerClient` to send events to the Event Hub. The `EventHubConsumerClient`, `EventProcessorClient`, and `PartitionReceiver`are configured in a similar manner. + +In the _Program.cs_ file of your component-consuming project, call the `AddAzureEventHubProducerClient` extension to register a `EventHubProducerClient` for use via the dependency injection container. + +```csharp +builder.AddAzureEventHubProducerClient("eventHubsConnectionName"); +``` + +You can then retrieve the `EventHubProducerClient` instance using dependency injection. For example, to retrieve the client from a service: + +```csharp +public class ExampleService(EventHubProducerClient client) +{ + // Use client... +} +``` + +For more information, see the [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`. + +## App host usage + +To add Azure Event Hub hosting support to your , install the [Aspire.Hosting.Azure.EventHubs](https://www.nuget.org/packages/Aspire.Hosting.Azure.EventHubs) NuGet package. + +### [.NET CLI](#tab/dotnet-cli) + +```dotnetcli +dotnet add package Aspire.Hosting.Azure.EventHubs --prerelease +``` + +### [PackageReference](#tab/package-reference) + +```xml + +``` + +--- + +In your app host project, add an Event Hubs connection and an Event Hub resource and consume the connection using the following methods: + +```csharp +var eventHubs = builder.AddAzureEventHubs("eventHubsConnectionName") + .AddEventHub("MyHub");; + +var ExampleService = builder.AddProject() + .WithReference(eventHubs); +``` + +The `AddAzureEventHubs` method will read connection information from the AppHost's configuration (for example, from "user secrets") under the `ConnectionStrings:eventHubsConnectionName` config key. The `WithReference` method passes that connection information into a connection string named `eventHubsConnectionName` in the `ExampleService` project. + +> [!IMPORTANT] +> Even though we are creating an Event Hub using the `AddEventHub` at the same time as the namespace, as of .NET Aspire version `preview-5`, the connection string will not include the `EntityPath` property, so the `EventHubName` property must be set in the settings callback for the preferred client. Future versions of Aspire will include the `EntityPath` property in the connection string and will not require the `EventHubName` property to be set in this scenario. + +In the _Program.cs_ file of `ExampleService`, the connection can be consumed using by calling of the supported Event Hubs client extension methods: + +```csharp +builder.AddAzureEventProcessorClient( + "eventHubsConnectionName", + static settings => + { + settings.EventHubName = "MyHub"; + }); +``` + +## Configuration + +The .NET 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 `Namespace` or a `ConnectionString` is a 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( + "eventHubsConnectionName", + 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 `AzureMessagingEventHubsSettings.Credential` property to establish a connection. If no credential is configured, the [DefaultAzureCredential](https://learn.microsoft.com/dotnet/api/azure.identity.defaultazurecredential) is used. + +```json +{ + "ConnectionStrings": { + "eventHubsConnectionName": "{your_namespace}.servicebus.windows.net" + } +} +``` + +#### Connection string + +Alternatively, use a connection string: + +```json +{ + "ConnectionStrings": { + "eventHubsConnectionName": "Endpoint=sb://mynamespace.servicebus.windows.net/;SharedAccessKeyName=accesskeyname;SharedAccessKey=accesskey;EntityPath=MyHub" + } +} +``` + +### Use configuration providers + +The .NET Aspire Azure Event Hubs library supports [Microsoft.Extensions.Configuration](https://learn.microsoft.com/dotnet/api/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" + } + } + } + } + } + } +} +``` + +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( + "eventHubsConnectionName", + configureClientBuilder: clientBuilder => clientBuilder.ConfigureOptions( + options => options.Identifier = "PROCESSOR_ID")); +``` + +[!INCLUDE [component-observability-and-telemetry](../includes/component-observability-and-telemetry.md)] + +### Logging + +The .NET Aspire Azure Event Hubs component uses the following log categories: + +- `Azure.Core` +- `Azure.Identity` + +### Tracing + +The .NET Aspire Azure Event Hubs component will emit the following tracing activities using OpenTelemetry: + +- "Azure.Messaging.EventHubs.*" + +### Metrics + +The .NET Aspire Azure Event Hubs component 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. + +## See also + +- [Azure Event Hubs](/azure/event-hubs/) +- [.NET Aspire components](../fundamentals/components-overview.md) +- [.NET Aspire GitHub repo](https://github.com/dotnet/aspire) diff --git a/docs/messaging/azure-service-bus-component.md b/docs/messaging/azure-service-bus-component.md index 7f1e99ae43..9650da5ba7 100644 --- a/docs/messaging/azure-service-bus-component.md +++ b/docs/messaging/azure-service-bus-component.md @@ -2,7 +2,7 @@ title: .NET Aspire Azure Service Bus component description: This article describes the .NET Aspire Azure Service Bus component features and capabilities ms.topic: how-to -ms.date: 01/22/2024 +ms.date: 04/04/2024 --- # .NET Aspire Azure Service Bus component @@ -57,7 +57,22 @@ public class ExampleService(ServiceBusClient client) ## App host usage -[!INCLUDE [azure-component-nuget](../includes/azure-component-nuget.md)] +To add Azure Service Bus hosting support to your , install the [Aspire.Hosting.Azure.ServiceBus](https://www.nuget.org/packages/Aspire.Hosting.Azure.ServiceBus) NuGet package. + +### [.NET CLI](#tab/dotnet-cli) + +```dotnetcli +dotnet add package Aspire.Hosting.Azure.ServiceBus --prerelease +``` + +### [PackageReference](#tab/package-reference) + +```xml + +``` + +--- In your app host project, register the Service Bus component and consume the service using the following methods: @@ -157,13 +172,6 @@ The following configurable options are exposed through the , install the [Aspire.Hosting.Azure.KeyVault](https://www.nuget.org/packages/Aspire.Hosting.Azure.KeyVault) NuGet package. + +### [.NET CLI](#tab/dotnet-cli) + +```dotnetcli +dotnet add package Aspire.Hosting.Azure.KeyVault --prerelease +``` + +### [PackageReference](#tab/package-reference) + +```xml + +``` + +--- In your app host project, register the Azure Key Vault component and consume the service using the following methods: diff --git a/docs/storage/azure-storage-blobs-component.md b/docs/storage/azure-storage-blobs-component.md index e162f829f7..8a24744fb6 100644 --- a/docs/storage/azure-storage-blobs-component.md +++ b/docs/storage/azure-storage-blobs-component.md @@ -2,7 +2,7 @@ title: .NET Aspire Azure Blob Storage component description: This article describes the .NET Aspire Azure Blob Storage component features and capabilities. ms.topic: how-to -ms.date: 03/13/2024 +ms.date: 04/04/2024 --- # .NET Aspire Azure Blob Storage component @@ -49,7 +49,22 @@ public class ExampleService(BlobServiceClient client) ## App host usage -[!INCLUDE [azure-component-nuget](../includes/azure-component-nuget.md)] +To add Azure Storage hosting support to your , install the [Aspire.Hosting.Azure.Storage](https://www.nuget.org/packages/Aspire.Hosting.Azure.Storage) NuGet package. + +### [.NET CLI](#tab/dotnet-cli) + +```dotnetcli +dotnet add package Aspire.Hosting.Azure.Storage --prerelease +``` + +### [PackageReference](#tab/package-reference) + +```xml + +``` + +--- In your app host project, register the Azure Blob Storage component and consume the service using the following methods, such as : diff --git a/docs/storage/azure-storage-components.md b/docs/storage/azure-storage-components.md index 08b0d000f8..b0c9b3b748 100644 --- a/docs/storage/azure-storage-components.md +++ b/docs/storage/azure-storage-components.md @@ -1,7 +1,7 @@ --- title: Connect an ASP.NET Core app to .NET Aspire storage components description: Learn how to connect an ASP.NET Core app to .NET Aspire storage components. -ms.date: 01/22/2024 +ms.date: 04/04/2024 ms.topic: tutorial zone_pivot_groups: azure-storage-mechanism ms.custom: devx-track-extended-azdevcli @@ -270,7 +270,22 @@ For more information about creating forms in Blazor, see [ASP.NET Core Blazor fo The _AspireStorage.AppHost_ project is the orchestrator for your app. It's responsible for connecting and configuring the different projects and services of your app. The orchestrator should be set as the startup project. -[!INCLUDE [azure-component-nuget](../includes/azure-component-nuget.md)] +To add Azure Storage hosting support to your , install the [Aspire.Hosting.Azure.Storage](https://www.nuget.org/packages/Aspire.Hosting.Azure.Storage) NuGet package. + +### [.NET CLI](#tab/dotnet-cli) + +```dotnetcli +dotnet add package Aspire.Hosting.Azure.Storage --prerelease +``` + +### [PackageReference](#tab/package-reference) + +```xml + +``` + +--- Replace the contents of the _Program.cs_ file in the _AspireStorage.AppHost_ project with the following code: diff --git a/docs/storage/azure-storage-queues-component.md b/docs/storage/azure-storage-queues-component.md index 22bf3a3878..a54d42ace8 100644 --- a/docs/storage/azure-storage-queues-component.md +++ b/docs/storage/azure-storage-queues-component.md @@ -2,7 +2,7 @@ title: .NET Aspire Azure Queue Storage component description: This article describes the .NET Aspire Azure Queue Storage component features and capabilities ms.topic: how-to -ms.date: 03/13/2024 +ms.date: 04/04/2024 --- # .NET Aspire Azure Queue Storage component @@ -49,7 +49,22 @@ public class ExampleService(QueueServiceClient client) ## App host usage -[!INCLUDE [azure-component-nuget](../includes/azure-component-nuget.md)] +To add Azure Storage hosting support to your , install the [Aspire.Hosting.Azure.Storage](https://www.nuget.org/packages/Aspire.Hosting.Azure.Storage) NuGet package. + +### [.NET CLI](#tab/dotnet-cli) + +```dotnetcli +dotnet add package Aspire.Hosting.Azure.Storage --prerelease +``` + +### [PackageReference](#tab/package-reference) + +```xml + +``` + +--- In your app host project, add a Storage Queue connection and consume the connection using the following methods, such as : diff --git a/docs/storage/azure-storage-tables-component.md b/docs/storage/azure-storage-tables-component.md index cf4f529f1b..a99bbf4c60 100644 --- a/docs/storage/azure-storage-tables-component.md +++ b/docs/storage/azure-storage-tables-component.md @@ -1,7 +1,7 @@ --- title: .NET Aspire Azure Data Tables component description: This article describes the .NET Aspire Azure Data Tables component features and capabilities. -ms.date: 01/22/2024 +ms.date: 04/04/2024 ms.topic: how-to --- @@ -57,7 +57,22 @@ public class ExampleService(TableServiceClient client) ## App host usage -[!INCLUDE [azure-component-nuget](../includes/azure-component-nuget.md)] +To add Azure Storage hosting support to your , install the [Aspire.Hosting.Azure.Storage](https://www.nuget.org/packages/Aspire.Hosting.Azure.Storage) NuGet package. + +### [.NET CLI](#tab/dotnet-cli) + +```dotnetcli +dotnet add package Aspire.Hosting.Azure.Storage --prerelease +``` + +### [PackageReference](#tab/package-reference) + +```xml + +``` + +--- In your app host project, register the Azure Table Storage component and consume the service using the following methods: diff --git a/docs/toc.yml b/docs/toc.yml index 62826e9854..056dbec90c 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -116,6 +116,8 @@ items: items: - name: Tutorial - Messaging using .NET Aspire components href: messaging/messaging-components.md + - name: Azure Event Hubs component + href: messaging/azure-event-hubs-component.md - name: Azure Service Bus component href: messaging/azure-service-bus-component.md - name: RabbitMQ service broker component