Partager via

intégration de .NET AspireAzure Cosmos DB

  • Article

Dans cet article, vous allez apprendre à utiliser l’intégration .NET AspireAzure Cosmos DB. La bibliothèque Aspire.Microsoft.Azure.Cosmos est utilisée pour inscrire un CosmosClient en tant que singleton dans le conteneur DI pour connecter à AzureAzure Cosmos DB. Il active également les vérifications d’intégrité, la journalisation et la télémétrie correspondantes.

Démarrer

Pour commencer à utiliser l’intégration .NET AspireAzure Cosmos DB, installez le package NuGet 📦Aspire.Microsoft.Azure.Cosmos dans le projet clientqui consomme, c'est-à-dire le projet de l’application qui utilise le Azure Cosmos DBclient.

dotnet add package Aspire.Microsoft.Azure.Cosmos

Pour plus d’informations, consultez dotnet add package ou Gérer les dépendances de packages dans les applications .NET.

Exemple d’utilisation

Dans le fichier Program.cs de votre projet consommant client, appelez l’extension AddAzureCosmosClient pour enregistrer un Microsoft.Azure.Cosmos.CosmosClient pour une utilisation via le conteneur d’injection de dépendances.

builder.AddAzureCosmosClient("cosmosConnectionName");

Vous pouvez ensuite récupérer l’instance CosmosClient à l’aide de l’injection de dépendances. Par exemple, pour récupérer le client à partir d’un service :

public class ExampleService(CosmosClient client)
{
    // Use client...
}

Pour plus d’informations sur l’utilisation de l'CosmosClient, consultez les exemples de pour Azure Cosmos DB pour le Kit de développement logiciel (SDK) NoSQL pour .NET.

Utilisation de l’hôte d’application

Pour ajouter prise en charge de l’hébergement à votre , installez le . Hébergement.. CosmosDB package NuGet dans le projet hôte de l’application . Cela est utile si vous souhaitez Aspire approvisionner un nouveau compte Azure Cosmos DB pour vous, ou si vous souhaitez utiliser l’émulateur Azure Cosmos DB. Si vous souhaitez utiliser un compte AzureAzure Cosmos DB déjà approvisionné, il n’est pas nécessaire de l’ajouter au projet hôte d’application.

dotnet add package Aspire.Hosting.Azure.CosmosDB

Dans votre projet hôte d’application, inscrivez l’intégration .NET AspireAzure Cosmos DB et utilisez le service à l’aide des méthodes suivantes :

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("myNewCosmosAccountName");
var cosmosdb = cosmos.AddDatabase("myCosmosDatabaseName");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(cosmosdb);

Pourboire

Pour utiliser l’émulateur AzureAzure Cosmos DB, chaînez un appel à la méthode AddAzureCosmosDB.

cosmosdb.RunAsEmulator();

Le démarrage de l’émulateur Cosmos DB peut prendre un certain temps. Utilisez WaitFor pour retarder l’exécution du code de votre projet .NET jusqu’à ce que l’émulateur soit en cours d’exécution et prêt à traiter les demandes.

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(cosmosdb)
                            .WaitFor(cosmosdb);

Configuration

La bibliothèque .NET AspireAzure Cosmos DB fournit plusieurs options pour configurer la connexion CosmosClient en fonction des exigences et des conventions de votre projet.

Utiliser une chaîne de connexion

Lorsque vous utilisez une chaîne de connexion à partir de la section de configuration ConnectionStrings, vous pouvez fournir le nom de la chaîne de connexion lors de l’appel de builder.AddAzureCosmosClient:

builder.AddAzureCosmosClient("cosmosConnectionName");

Ensuite, la chaîne de connexion est récupérée à partir de la section de configuration ConnectionStrings :

{
  "ConnectionStrings": {
    "cosmosConnectionName": "https://{account_name}.documents.azure.com:443/"
  }
}

L’approche de connexion recommandée consiste à utiliser un point de terminaison de compte, qui fonctionne avec la propriété MicrosoftAzureCosmosSettings.Credential pour établir une connexion. Si aucune information d’identification n’est configurée, la DefaultAzureCredential est utilisée :

{
    "ConnectionStrings": {
      "cosmosConnectionName": "https://{account_name}.documents.azure.com:443/"
    }
}

Vous pouvez également utiliser une chaîne de connexion AzureAzure Cosmos DB :

{
    "ConnectionStrings": {
    "cosmosConnectionName": "AccountEndpoint=https://{account_name}.documents.azure.com:443/;AccountKey={account_key};"
    }
}

Utiliser des fournisseurs de configuration

L’intégration .NET AspireAzure Cosmos DB prend en charge Microsoft.Extensions.Configuration. Il charge le MicrosoftAzureCosmosSettings à partir de appsettings.json ou d'autres fichiers de configuration à l'aide de la clé Aspire:Microsoft:Azure:Cosmos. Exemple appsettings.json qui configure certaines des options suivantes :

{
  "Aspire": {
    "Microsoft": {
      "Azure": {
        "Cosmos": {
          "DisableTracing": false,
        }
      }
    }
  }
}

Utiliser des délégués inline

Vous pouvez également transmettre le délégué Action<MicrosoftAzureCosmosSettings > pour configurer certaines ou toutes les options inline, par exemple pour désactiver le suivi à partir du code :

builder.AddAzureCosmosClient(
    "cosmosConnectionName",
    static settings => settings.DisableTracing = true);

Vous pouvez également configurer le Microsoft.Azure.Cosmos.CosmosClientOptions à l’aide du paramètre facultatif Action<CosmosClientOptions> configureClientOptions de la méthode AddAzureCosmosClient. Par exemple, pour définir le suffixe d'en-tête de l'agent utilisateur CosmosClientOptions.ApplicationName pour toutes les requêtes émises par ce client:

builder.AddAzureCosmosClient(
    "cosmosConnectionName",
    configureClientOptions:
        clientOptions => clientOptions.ApplicationName = "myapp");

Vérifications d’intégrité

Par défaut, les intégrations .NET.NET Aspire permettent de réaliser des vérifications d'intégrité pour tous les services. Pour plus d’informations, consultez .NET.NET Aspire vue d’ensemble des intégrations.

Actuellement, l’intégration .NET AspireAzure Cosmos DB n’implémente pas les vérifications de santé, bien que cela puisse changer dans les versions ultérieures.

Observabilité et télémétrie

.NET .NET Aspire intégrations configurent automatiquement les configurations de journalisation, de suivi et de métriques, parfois appelées les piliers de l’observabilité. Pour plus d’informations sur l’observabilité de l’intégration et la télémétrie, consultez .NET.NET Aspire vue d’ensemble des intégrations. Selon le service de stockage, certaines intégrations peuvent uniquement prendre en charge certaines de ces fonctionnalités. Par exemple, certaines intégrations prennent en charge la journalisation et le suivi, mais pas les métriques. Les fonctionnalités de télémétrie peuvent également être désactivées à l’aide des techniques présentées dans la section Configuration.

Exploitation forestière

L’intégration .NET AspireAzure Cosmos DB utilise les catégories de journaux suivantes :

  • Azure-Cosmos-Operation-Request-Diagnostics

En plus d’obtenir des diagnostics de requête Azure Cosmos DB pour les demandes ayant échoué, vous pouvez configurer des seuils de latence pour déterminer lesquels diagnostics de requête réussis Azure Cosmos DB seront enregistrés. Les valeurs par défaut sont 100 ms pour les opérations de point et 500 ms pour les opérations non point.

builder.AddAzureCosmosClient(
    "cosmosConnectionName",
    configureClientOptions:
        clientOptions => {
            clientOptions.CosmosClientTelemetryOptions = new()
            {
                CosmosThresholdOptions = new()
                {
                    PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(50),
                    NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(300)
                }
            };
        });

Traçage

L’intégration .NET AspireAzure Cosmos DB émet les activités de suivi suivantes à l’aide de OpenTelemetry:

  • Azure. Cosmos.Operation

Azure Azure Cosmos DB suivi est actuellement en préversion. Vous devez donc définir le commutateur expérimental pour vous assurer que les traces sont émises. En savoir plus sur le suivi dans AzureAzure Cosmos DB.

AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);

Métriques

L’intégration .NET AspireAzure Cosmos DB ne prend actuellement pas en charge les métriques par défaut en raison de limitations avec le KIT DE développement logiciel (SDK) Azure.

Voir aussi