Udostępnij za pośrednictwem

integracja .NET AspireAzure Cosmos DB

  • Artykuł

Z tego artykułu dowiesz się, jak korzystać z integracji .NET AspireAzure Cosmos DB. Biblioteka Aspire.Microsoft.Azure.Cosmos służy do rejestrowania CosmosClient jako singletonu w kontenerze DI w celu połączenia z AzureAzure Cosmos DB. Umożliwia również odpowiednie kontrole kondycji, rejestrowanie i dane telemetryczne.

Rozpocznij

Aby rozpocząć pracę z integracją .NET AspireAzure Cosmos DB, zainstaluj pakiet NuGet 📦Aspire.Microsoft.Azure.Cosmos w projekcie korzystającym z client, czyli projekt aplikacji używającej Azure Cosmos DBclient.

dotnet add package Aspire.Microsoft.Azure.Cosmos

Aby uzyskać więcej informacji, zobacz dotnet add package or Manage package dependencies in .NET applications.

Przykładowe użycie

W pliku Program.cs projektu używającego clientwywołaj rozszerzenie AddAzureCosmosClient, aby zarejestrować Microsoft.Azure.Cosmos.CosmosClient do używania za pośrednictwem kontenera wstrzykiwania zależności.

builder.AddAzureCosmosClient("cosmosConnectionName");

Następnie można pobrać wystąpienie CosmosClient za pomocą wstrzykiwania zależności. Aby na przykład pobrać client z usługi:

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

Aby uzyskać więcej informacji na temat korzystania z CosmosClient, zobacz przykłady dla Azure Cosmos DB w zestawie SDK NoSQL dla .NET.

Użycie hosta aplikacji

Aby dodać obsługę hostingu AzureAzure Cosmos DB do IDistributedApplicationBuilder, zainstaluj 📦Aspire.Hosting.Azure. CosmosDB pakiet NuGet w projekcie hosta aplikacji . Jest to przydatne, jeśli chcesz Aspire aprowizować nowe konto Azure Cosmos DB lub jeśli chcesz użyć emulatora Azure Cosmos DB. Jeśli chcesz użyć już aprowizowanego konta AzureAzure Cosmos DB, nie ma potrzeby dodawania go do projektu hosta aplikacji.

dotnet add package Aspire.Hosting.Azure.CosmosDB

W projekcie hosta aplikacji zarejestruj integrację .NET AspireAzure Cosmos DB i użyj usługi przy użyciu następujących metod:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Napiwek

Aby skorzystać z emulatora AzureAzure Cosmos DB, należy wywołać metodę AddAzureCosmosDB w łańcuchu.

cosmosdb.RunAsEmulator();

Uruchomienie emulatora Cosmos DB może trochę potrwać. Użyj WaitFor, aby opóźnić wykonywanie kodu projektu .NET do momentu uruchomienia emulatora i gotowości do obsługi żądań.

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

Konfiguracja

Biblioteka .NET AspireAzure Cosmos DB udostępnia wiele opcji konfigurowania połączenia CosmosClient na podstawie wymagań i konwencji projektu.

Używanie parametrów połączenia

W przypadku używania parametrów połączenia z sekcji konfiguracji ConnectionStrings można podać nazwę parametrów połączenia podczas wywoływania builder.AddAzureCosmosClient:

builder.AddAzureCosmosClient("cosmosConnectionName");

Następnie parametry połączenia zostaną pobrane z sekcji konfiguracji ConnectionStrings:

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

Zalecaną metodą połączenia jest użycie punktu końcowego konta, który współdziała z właściwością MicrosoftAzureCosmosSettings.Credential w celu nawiązania połączenia. Jeśli nie skonfigurowano poświadczeń, zostanie użyta DefaultAzureCredential:

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

Alternatywnie można użyć parametrów połączenia AzureAzure Cosmos DB:

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

Korzystanie z dostawców konfiguracji

Integracja .NET AspireAzure Cosmos DB obsługuje Microsoft.Extensions.Configuration. Ładuje MicrosoftAzureCosmosSettings z appsettings.json lub innych plików konfiguracyjnych przy użyciu klucza Aspire:Microsoft:Azure:Cosmos. Przykład appsettings.json, który konfiguruje niektóre opcje:

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

Użyj delegatów wbudowanych

Możesz również przekazać delegata Action<MicrosoftAzureCosmosSettings >, aby skonfigurować niektóre lub wszystkie opcje wbudowane, na przykład w celu wyłączenia śledzenia z kodu:

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

Można również skonfigurować Microsoft.Azure.Cosmos.CosmosClientOptions przy użyciu opcjonalnego parametru Action<CosmosClientOptions> configureClientOptions metody AddAzureCosmosClient. Aby na przykład ustawić sufiks nagłówka user-agent CosmosClientOptions.ApplicationName dla wszystkich żądań wysyłanych przez to client:

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

Kontrole kondycji

Domyślnie integracje .NET.NET Aspire umożliwiają sprawdzanie kondycji we wszystkich usługach. Aby uzyskać więcej informacji, zobacz omówienie integracji .NET.NET Aspire.

Integracja .NET AspireAzure Cosmos DB obecnie nie implementuje kontroli kondycji, ale może to ulec zmianie w przyszłych wersjach.

Obserwowanie i telemetria

.NET .NET Aspire integracje automatycznie konfigurują ustawienia rejestrowania, śledzenia i metryk, które są czasami nazywane filarami obserwowalności. Aby uzyskać więcej informacji na temat możliwości obserwacji integracji i telemetrii, zobacz omówienie integracji .NET.NET Aspire. W zależności od usługi pomocniczej niektóre integracje mogą obsługiwać tylko niektóre z tych funkcji. Na przykład niektóre integracje obsługują rejestrowanie i śledzenie, ale nie metryki. Funkcje telemetrii można również wyłączyć przy użyciu technik przedstawionych w sekcji konfiguracji .

Logowanie

Integracja .NET AspireAzure Cosmos DB używa następujących kategorii dzienników:

  • Azure-Operacja Kosmos-Request-Diagnostics

Poza uzyskaniem diagnostyki Azure Cosmos DB dla żądań zakończonych niepowodzeniem, można skonfigurować progi opóźnienia, aby określić, które diagnostyki dotyczące pomyślnych żądań Azure Cosmos DB zostaną zarejestrowane. Wartości domyślne to 100 ms dla operacji punktów i 500 ms dla operacji innych niż punkt.

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

Śledzenie

Integracja .NET AspireAzure Cosmos DB spowoduje emitowanie następujących działań śledzenia przy użyciu OpenTelemetry:

  • Azure. Cosmos.Operation

Azure Azure Cosmos DB śledzenie jest obecnie w wersji zapoznawczej, dlatego należy ustawić przełącznik eksperymentalny, aby upewnić się, że ślady są emitowane. Dowiedz się więcej o śledzeniu w AzureAzure Cosmos DB.

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

Metryki

Integracja .NET AspireAzure Cosmos DB obecnie nie obsługuje metryk domyślnie z powodu ograniczeń SDK Azure.

Zobacz też