integración de .NET AspireAzure Cosmos DB
En este artículo, aprenderá a usar la integración de .NET AspireAzure Cosmos DB. La biblioteca Aspire.Microsoft.Azure.Cosmos
se usa para registrar un CosmosClient como singleton en el contenedor de inyección de dependencias para conectarse a AzureAzure Cosmos DB. También habilita las comprobaciones de estado, el registro y la telemetría correspondientes.
Comenzar
Para empezar a trabajar con la integración de .NET AspireAzure Cosmos DB, instale el paquete NuGet 📦Aspire.Microsoft.Azure.Cosmos en el proyecto consumidor client, es decir, el proyecto de la aplicación que usa el Azure Cosmos DBclient.
dotnet add package Aspire.Microsoft.Azure.Cosmos
Para obtener más información, consulte dotnet add package o Administrar dependencias de paquetes en aplicaciones .NET.
Ejemplo de uso
En el archivo Program.cs de su proyecto que consume client, llame a la extensión AddAzureCosmosClient para registrar un Microsoft.Azure.Cosmos.CosmosClient para su uso a través del contenedor de inyección de dependencias.
builder.AddAzureCosmosClient("cosmosConnectionName");
A continuación, puede recuperar la instancia CosmosClient
usando la inyección de dependencias. Por ejemplo, para recuperar el client de un servicio:
public class ExampleService(CosmosClient client)
{
// Use client...
}
Para obtener más información sobre el uso de la CosmosClient, consulte los ejemplos de para Azure Cosmos DB para el SDK de NoSQL para .NET.
Uso del host de la aplicación
Para agregar compatibilidad de hospedaje para AzureAzure Cosmos DB a IDistributedApplicationBuilder, instale el paquete NuGet 📦Aspire.Hosting.Azure.CosmosDB en el proyecto host de la aplicación . Esto resulta útil si desea Aspire aprovisionar una nueva cuenta de Azure Cosmos DB para usted o si desea usar el emulador de Azure Cosmos DB. Si quiere usar una cuenta de AzureAzure Cosmos DB que ya está aprovisionada, no es necesario agregarla al proyecto host de la aplicación.
dotnet add package Aspire.Hosting.Azure.CosmosDB
En el proyecto host de la aplicación, registre la integración de .NET AspireAzure Cosmos DB y consuma el servicio mediante los métodos siguientes:
var builder = DistributedApplication.CreateBuilder(args);
var cosmos = builder.AddAzureCosmosDB("myNewCosmosAccountName");
var cosmosdb = cosmos.AddDatabase("myCosmosDatabaseName");
var exampleProject = builder.AddProject<Projects.ExampleProject>()
.WithReference(cosmosdb);
Propina
Para usar el emulador de AzureAzure Cosmos DB, encadene una llamada al método AddAzureCosmosDB.
cosmosdb.RunAsEmulator();
El inicio del emulador de Cosmos DB puede tardar algún tiempo. Use WaitFor para retrasar la ejecución del código del proyecto de .NET hasta que el emulador se esté ejecutando y listo para atender solicitudes.
var exampleProject = builder.AddProject<Projects.ExampleProject>()
.WithReference(cosmosdb)
.WaitFor(cosmosdb);
Configuración
La biblioteca .NET AspireAzure Cosmos DB proporciona varias opciones para configurar la conexión CosmosClient
en función de los requisitos y convenciones del proyecto.
Uso de una cadena de conexión
Al usar una cadena de conexión de la sección de configuración de ConnectionStrings
, puede proporcionar el nombre de la cadena de conexión al llamar a builder.AddAzureCosmosClient
:
builder.AddAzureCosmosClient("cosmosConnectionName");
Y, a continuación, la cadena de conexión se recuperará de la sección de configuración de ConnectionStrings
:
{
"ConnectionStrings": {
"cosmosConnectionName": "https://{account_name}.documents.azure.com:443/"
}
}
El enfoque de conexión recomendado es usar un punto de conexión de cuenta, que funciona con la propiedad MicrosoftAzureCosmosSettings.Credential para establecer una conexión. Si no se configura ninguna credencial, se usa el DefaultAzureCredential:
{
"ConnectionStrings": {
"cosmosConnectionName": "https://{account_name}.documents.azure.com:443/"
}
}
Como alternativa, se puede usar una cadena de conexión AzureAzure Cosmos DB:
{
"ConnectionStrings": {
"cosmosConnectionName": "AccountEndpoint=https://{account_name}.documents.azure.com:443/;AccountKey={account_key};"
}
}
Uso de proveedores de configuración
La integración de .NET AspireAzure Cosmos DB admite Microsoft.Extensions.Configuration. Carga el MicrosoftAzureCosmosSettings desde appsettings.json u otros archivos de configuración mediante la clave Aspire:Microsoft:Azure:Cosmos
. Ejemplo appsettings.json que configura algunas de las opciones:
{
"Aspire": {
"Microsoft": {
"Azure": {
"Cosmos": {
"DisableTracing": false,
}
}
}
}
}
Usa delegados insertados
También puede pasar el delegado de Action<MicrosoftAzureCosmosSettings >
para configurar algunas o todas las opciones en línea, por ejemplo, para deshabilitar el seguimiento desde el código:
builder.AddAzureCosmosClient(
"cosmosConnectionName",
static settings => settings.DisableTracing = true);
También puede configurar el Microsoft.Azure.Cosmos.CosmosClientOptions mediante el parámetro opcional Action<CosmosClientOptions> configureClientOptions
del método AddAzureCosmosClient
. Por ejemplo, para establecer el sufijo del encabezado de user-agent CosmosClientOptions.ApplicationName para todas las peticiones de este client:
builder.AddAzureCosmosClient(
"cosmosConnectionName",
configureClientOptions:
clientOptions => clientOptions.ApplicationName = "myapp");
Comprobaciones de estado
De forma predeterminada, las integraciones de .NET.NET Aspire habilitan las verificaciones de salud de para todos los servicios. Para obtener más información, consulte .NET.NET Aspire integrations overview.
Actualmente, la integración de .NET AspireAzure Cosmos DB no implementa comprobaciones de estado, aunque esto puede cambiar en futuras versiones.
Observabilidad y telemetría
.NET .NET Aspire integraciones configuran automáticamente las configuraciones de registro, seguimiento y métricas, que a veces se conocen como los pilares de la observabilidad. Para obtener más información sobre la observabilidad de integración y la telemetría, consulte información general sobre las integraciones de .NET.NET Aspire. En función del servicio de respaldo, algunas integraciones solo pueden admitir algunas de estas características. Por ejemplo, algunas integraciones admiten el registro y el seguimiento, pero no las métricas. Las características de telemetría también se pueden deshabilitar mediante las técnicas presentadas en la sección Configuración.
Registro
La integración de .NET AspireAzure Cosmos DB usa las siguientes categorías de registro:
- Azure-Cosmos-Operation-Request-Diagnostics
Además de obtener diagnósticos de solicitudes con errores Azure Cosmos DB, puede configurar umbrales de latencia para determinar qué diagnósticos de solicitudes exitosas se registrarán Azure Cosmos DB. Los valores predeterminados son 100 ms para las operaciones de punto y 500 ms para las operaciones que no son de punto.
builder.AddAzureCosmosClient(
"cosmosConnectionName",
configureClientOptions:
clientOptions => {
clientOptions.CosmosClientTelemetryOptions = new()
{
CosmosThresholdOptions = new()
{
PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(50),
NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(300)
}
};
});
Seguimiento
La integración de .NET AspireAzure Cosmos DB emitirá las siguientes actividades de seguimiento mediante OpenTelemetry:
- Azure. Cosmos.Operation
El trazado de AzureAzure Cosmos DB se encuentra actualmente en versión preliminar, por lo que debe establecer el conmutador experimental para asegurarse de que se emitan trazados. Obtenga más información sobre el seguimiento en AzureAzure Cosmos DB.
AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);
Métricas
La integración de .NET AspireAzure Cosmos DB actualmente no admite métricas de forma predeterminada debido a limitaciones con el SDK de Azure.