.NET Aspire Azure Cosmos DB integrering

Artikel
12/14/2024

I den här artikeln får du lära dig hur du använder .NET AspireAzure Cosmos DB integrering. Aspire.Microsoft.Azure.Cosmos-biblioteket används för att registrera en CosmosClient som en singleton i DI-containern för att ansluta till AzureAzure Cosmos DB. Det möjliggör även motsvarande hälsokontroller, loggning och telemetri.

Sätta igång

Kom igång med .NET AspireAzure Cosmos DB-integreringen genom att installera 📦Aspire. Microsoft.Azure. Cosmos NuGet-paket i projektet client-consuming, dvs. projektet för det program som använder Azure Cosmos DBclient.

.NET CLI
PackageReference

dotnet add package Aspire.Microsoft.Azure.Cosmos

<PackageReference Include="Aspire.Microsoft.Azure.Cosmos"
                  Version="*" />

Mer information finns i dotnet add package eller Hantera paketberoenden i .NET applikationer.

Exempel på användning

I Program.cs-filen för ditt client-förbrukande projekt anropar du AddAzureCosmosClient-tillägget för att registrera en Microsoft.Azure.Cosmos.CosmosClient för användning via containern för beroendeinjektion.

builder.AddAzureCosmosClient("cosmosConnectionName");

Du kan sedan hämta CosmosClient-instansen med hjälp av beroendeinjektion. Om du till exempel vill hämta client från en tjänst:

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

För mer information om hur du använder CosmosClient, se Exempel för för Azure Cosmos DB för NoSQL SDK för .NET.

Appvärdanvändning

Om du vill lägga till AzureAzure Cosmos DB hostingstöd för din IDistributedApplicationBuilderinstallerar du 📦Aspire.Hosting.Azure.CosmosDB NuGet-paketet i projektet för appvärd . Det här är användbart om du vill Aspire etablera ett nytt Azure Cosmos DB konto åt dig, eller om du vill använda Azure Cosmos DB emulatorn. Om du vill använda ett AzureAzure Cosmos DB konto som redan har provisionerats behöver du inte lägga till det i värdprojektet för appen.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.CosmosDB

<PackageReference Include="Aspire.Hosting.Azure.CosmosDB"
                  Version="*" />

I appvärdprojektet registrerar du .NET AspireAzure Cosmos DB-integreringen och använder tjänsten med hjälp av följande metoder:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Tips

Om du vill använda AzureAzure Cosmos DB-emulatorn kedjar du ett anrop till metoden AddAzureCosmosDB.

cosmosdb.RunAsEmulator();

Det kan ta lite tid att starta Cosmos DB emulatorn. Använd WaitFor för att fördröja .NET-projektets kodkörning tills emulatorn körs och är redo att hantera begäranden.

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

Konfiguration

.NET Aspire Azure Cosmos DB-biblioteket innehåller flera alternativ för att konfigurera CosmosClient-anslutningen baserat på kraven och konventionerna i ditt projekt.

Använda en anslutningssträng

När du använder en anslutningssträng från ConnectionStrings konfigurationsavsnittet kan du ange namnet på anslutningssträngen när du anropar builder.AddAzureCosmosClient:

builder.AddAzureCosmosClient("cosmosConnectionName");

Och sedan hämtas anslutningssträngen från ConnectionStrings-konfigurationsavsnittet:

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

Den rekommenderade anslutningsmetoden är att använda en kontoslutpunkt som fungerar med egenskapen MicrosoftAzureCosmosSettings.Credential för att upprätta en anslutning. Om inga autentiseringsuppgifter har konfigurerats används DefaultAzureCredential:

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

Du kan också använda en AzureAzure Cosmos DB anslutningssträng:

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

Använda konfigurationsprovidrar

.NET Aspire Azure Cosmos DB-integreringen stöder Microsoft.Extensions.Configuration. Den läser in MicrosoftAzureCosmosSettings från appsettings.json eller andra konfigurationsfiler med hjälp av Aspire:Microsoft:Azure:Cosmos nyckel. Exempel appsettings.json som konfigurerar några av alternativen:

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

Använda inline-delegater

Du kan också skicka delegeringen Action<MicrosoftAzureCosmosSettings > för att konfigurera vissa eller alla alternativ direkt, till exempel för att inaktivera spårning i koden.

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

Du kan också konfigurera Microsoft.Azure.Cosmos.CosmosClientOptions med hjälp av den valfria Action<CosmosClientOptions> configureClientOptions parametern för metoden AddAzureCosmosClient. För att till exempel ställa in suffixet för user-agent-headern CosmosClientOptions.ApplicationName för alla begäranden som görs av denna client:

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

Hälsokontroller

Som standard aktiverar .NET.NET Aspire integreringar hälsokontroller för alla tjänster. Mer information finns i översikten över .NET.NET Aspire integreringar.

Den .NET AspireAzure Cosmos DB integreringen implementerar för närvarande inte hälsokontroller, även om detta kan ändras i framtida versioner.

Observerbarhet och telemetri

.NET .NET Aspire integreringar konfigurerar automatiskt konfigurationer för loggning, spårning och mått, som ibland kallas grundpelarna för observerbarhet. Mer information om integreringsobservabilitet och telemetri finns i översikten över .NET.NET Aspire integreringar. Beroende på säkerhetskopieringstjänsten kanske vissa integreringar bara stöder vissa av dessa funktioner. Vissa integreringar stöder till exempel loggning och spårning, men inte mått. Telemetrifunktioner kan också inaktiveras med hjälp av de tekniker som visas i avsnittet Configuration.

Skogsavverkning

.NET Aspire Azure Cosmos DB-integreringen använder följande loggkategorier:

Azure–Cosmos-Operation –Request-Diagnostics

Förutom att få Azure Cosmos DB begärandediagnostik för misslyckade begäranden kan du konfigurera tröskelvärden för svarstid för att avgöra vilken lyckad Azure Cosmos DB begärandediagnostik som ska loggas. Standardvärdena är 100 ms för punktåtgärder och 500 ms för åtgärder som inte är punktåtgärder.

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

Spårning

.NET Aspire Azure Cosmos DB-integreringen genererar följande spårningsaktiviteter med hjälp av OpenTelemetry:

Azure. Cosmos.Operation

Azure Azure Cosmos DB spårning är för närvarande i en förhandsversion, så du måste ange den experimentella inställningen för att säkerställa att spårningar genereras. Läs mer om spårning i AzureAzure Cosmos DB.

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

Mått

Den .NET AspireAzure Cosmos DB integreringen stöder för närvarande inte mått som standard på grund av begränsningar med Azure SDK.

Dela via