integrace .NET AspireAzure Cosmos DB

Článek
12/15/2024

V tomto článku se dozvíte, jak používat integraci .NET AspireAzure Cosmos DB. Knihovna Aspire.Microsoft.Azure.Cosmos se používá k registraci CosmosClient jako singletonu v DI kontejneru pro připojení k AzureAzure Cosmos DB. Umožňuje také odpovídající kontroly stavu, protokolování a telemetrii.

Začít

Pokud chcete začít s integrací .NET AspireAzure Cosmos DB, nainstalujte 📦Aspire.Microsoft.Azure.Cosmos do projektu využívajícího client, to znamená do projektu pro aplikaci, která využívá Azure Cosmos DBclient.

.NET rozhraní příkazového řádku
PackageReference

dotnet add package Aspire.Microsoft.Azure.Cosmos

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

Pro další informace, viz dotnet add package nebo Správa závislostí balíčků v .NET aplikacích.

Příklad využití

V souboru Program.cs projektu, který využívá client, zavolejte rozšíření AddAzureCosmosClient a zaregistrujte Microsoft.Azure.Cosmos.CosmosClient pro použití pomocí kontejneru pro injektování závislostí.

builder.AddAzureCosmosClient("cosmosConnectionName");

Potom můžete načíst instanci CosmosClient pomocí injektování závislostí. Pokud chcete například načíst client ze služby:

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

Další informace o použití CosmosClientnaleznete v části Příklady pro Azure Cosmos DB v rámci NoSQL SDK pro .NET.

Využití hostitele aplikace

Pokud chcete do IDistributedApplicationBuilderpřidat podporu hostování AzureAzure Cosmos DB, nainstalujte NuGet balíček 📦Aspire.Hosting.Azure.CosmosDB v hostitelském projektu aplikace . To je užitečné, pokud chcete Aspire zřídit nový účet Azure Cosmos DB pro vás nebo pokud chcete použít emulátor Azure Cosmos DB. Pokud chcete použít účet AzureAzure Cosmos DB, který už je zřízený, nemusíte ho přidávat do hostitelského projektu aplikace.

.NET rozhraní příkazového řádku
PackageReference

dotnet add package Aspire.Hosting.Azure.CosmosDB

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

V hostitelském projektu aplikace zaregistrujte integraci .NET AspireAzure Cosmos DB a pomocí následujících metod službu využijte:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Spropitné

Pro použití emulátoru AzureAzure Cosmos DB zřetězte volání metody AddAzureCosmosDB.

cosmosdb.RunAsEmulator();

Spuštění emulátoru Cosmos DB může nějakou dobu trvat. Pomocí WaitFor zpozdíte spuštění kódu projektu .NET, dokud emulátor neběží a připravený k obsluhování požadavků.

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

Konfigurace

Knihovna .NET AspireAzure Cosmos DB poskytuje několik možností konfigurace připojení CosmosClient na základě požadavků a konvencí projektu.

Použijte připojovací řetězec

Při použití připojovacího řetězce z oddílu konfigurace ConnectionStrings můžete při volání builder.AddAzureCosmosClientzadat název připojovacího řetězce:

builder.AddAzureCosmosClient("cosmosConnectionName");

A pak se připojovací řetězec načte z oddílu konfigurace ConnectionStrings.

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

Doporučeným přístupem připojení je použití koncového bodu účtu, který pracuje s vlastností MicrosoftAzureCosmosSettings.Credential pro navázání připojení. Pokud nejsou nakonfigurované žádné přihlašovací údaje, použije se DefaultAzureCredential:

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

Případně můžete použít připojovací řetězec AzureAzure Cosmos DB:

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

Použití zprostředkovatelů konfigurace

Integrace .NET AspireAzure Cosmos DB podporuje Microsoft.Extensions.Configuration. Načte MicrosoftAzureCosmosSettings z appsettings.json nebo jiných konfiguračních souborů pomocí klíče Aspire:Microsoft:Azure:Cosmos. Příklad appsettings.json, který konfiguruje některé z možností:

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

Použití vložených delegátů

Můžete také předat delegáta Action<MicrosoftAzureCosmosSettings > a nastavit některé nebo všechny možnosti přímo, například zakázat trasování v kódu.

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

Můžete také nastavit Microsoft.Azure.Cosmos.CosmosClientOptions pomocí volitelného parametru Action<CosmosClientOptions> configureClientOptions metody AddAzureCosmosClient. Například pro nastavení přípony hlavičky uživatelského agenta CosmosClientOptions.ApplicationName pro všechny požadavky zaslané tímto client:

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

Kontroly stavu

Integrace .NET.NET Aspire ve výchozím nastavení umožňují kontroly stavu pro všechny služby. Další informace naleznete v tématu .NET.NET Aspire přehled integrací.

Integrace .NET AspireAzure Cosmos DB v současné době neimplementuje kontroly stavu, i když se to může v budoucích verzích změnit.

Pozorovatelnost a telemetrie

.NET .NET Aspire integrace automaticky nastaví konfigurace protokolování, trasování a metriky, které se někdy označují jako pilíře pozorovatelnosti. Další informace o pozorovatelnosti a telemetrii integrace najdete v přehledu integrace .NET.NET Aspire. V závislosti na zálohovací službě můžou některé integrace podporovat pouze některé z těchto funkcí. Například některé integrace podporují protokolování a trasování, ale ne metriky. Funkce telemetrie je také možné zakázat pomocí technik uvedených v části Konfigurace.

Protokolování

Integrace .NET AspireAzure Cosmos DB používá následující kategorie protokolů:

Azure-Cosmos-Operation-Request-Diagnostics

Kromě získání diagnostiky požadavků Azure Cosmos DB pro neúspěšné požadavky můžete nakonfigurovat prahové hodnoty latence, abyste zjistili, která úspěšná diagnostika požadavků Azure Cosmos DB se zaznamenají. Výchozí hodnoty jsou 100 ms pro operace bodu a 500 ms pro operace bez bodu.

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

Trasování

Integrace .NET AspireAzure Cosmos DB pomocí OpenTelemetryvygeneruje následující aktivity trasování:

Azure. Cosmos.Operation

Azure Azure Cosmos DB trasování je aktuálně ve verzi Preview, takže je nutné nastavit experimentální přepínač, aby se zajistilo, že se trasování vygeneruje. Další informace o trasování v AzureAzure Cosmos DB.

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

Metriky

Integrace .NET AspireAzure Cosmos DB v současné době nepodporuje metriky ve výchozím nastavení kvůli omezením sady Azure SDK.

Sdílet prostřednictvím