.NET Aspire Azure Cosmos DB-Integration
In diesem Artikel erfahren Sie, wie Sie die .NET AspireAzure Cosmos DB Integration verwenden. Die Aspire.Microsoft.Azure.Cosmos-Bibliothek wird verwendet, um eine CosmosClient als Singleton im DI-Container zu registrieren, wodurch eine Verbindung zu AzureAzure Cosmos DBermöglicht wird. Es ermöglicht auch entsprechende Gesundheitsprüfungen, Protokollierung und Telemetrie.
Loslegen
Um mit der .NET AspireAzure Cosmos DB-Integration zu beginnen, installieren Sie die 📦Aspire. Microsoft.Azure. Cosmos NuGet-Paket im client-verbrauchenden Projekt, d. h. das Projekt für die Anwendung, die die Azure Cosmos DBclientverwendet.
dotnet add package Aspire.Microsoft.Azure.Cosmos
Weitere Informationen finden Sie unter dotnet add package oder Verwaltung von Paketabhängigkeiten in .NET-Anwendungen.
Beispielverwendung
Rufen Sie in der datei Program.cs Ihres client-verbrauchenden Projekts die AddAzureCosmosClient-Erweiterung auf, um eine Microsoft.Azure.Cosmos.CosmosClient für die Verwendung über den Container zum Einfügen von Abhängigkeiten zu registrieren.
builder.AddAzureCosmosClient("cosmosConnectionName");
Anschließend können Sie die CosmosClient-Instanz mithilfe der Dependency Injection abrufen. So rufen Sie beispielsweise die client von einem Dienst ab:
public class ExampleService(CosmosClient client)
{
// Use client...
}
Weitere Informationen zur Verwendung des CosmosClientfinden Sie in den Examples for Azure Cosmos DB for NoSQL SDK for .NET.
Nutzung des App-Hosts
Um AzureAzure Cosmos DB Hostingunterstützung zu Ihrer IDistributedApplicationBuilderhinzuzufügen, installieren Sie das 📦Aspire.Hosting.Azure.CosmosDB NuGet-Paket im App-Host Projekt. Dies ist hilfreich, wenn Sie Aspire ein neues Azure Cosmos DB Konto für Sie bereitstellen möchten oder wenn Sie den Azure Cosmos DB Emulator verwenden möchten. Wenn Sie ein bereits bereitgestelltes AzureAzure Cosmos DB Konto verwenden möchten, müssen Sie es dem App-Hostprojekt nicht hinzufügen.
dotnet add package Aspire.Hosting.Azure.CosmosDB
Registrieren Sie in Ihrem App-Hostprojekt die .NET AspireAzure Cosmos DB Integration, und nutzen Sie den Dienst mithilfe der folgenden Methoden:
var builder = DistributedApplication.CreateBuilder(args);
var cosmos = builder.AddAzureCosmosDB("myNewCosmosAccountName");
var cosmosdb = cosmos.AddDatabase("myCosmosDatabaseName");
var exampleProject = builder.AddProject<Projects.ExampleProject>()
.WithReference(cosmosdb);
Tipp
Um den AzureAzure Cosmos DB Emulator zu verwenden, verketten Sie einen Aufruf der AddAzureCosmosDB-Methode.
cosmosdb.RunAsEmulator();
Das Starten des Cosmos DB Emulators kann einige Zeit in Anspruch nehmen. Verwenden Sie WaitFor, um die Codeausführung Ihres .NET Projekts zu verzögern, bis der Emulator ausgeführt wird und bereit ist, um Anfragen zu bedienen.
var exampleProject = builder.AddProject<Projects.ExampleProject>()
.WithReference(cosmosdb)
.WaitFor(cosmosdb);
Konfiguration
Die .NET AspireAzure Cosmos DB bibliothek bietet mehrere Optionen zum Konfigurieren der CosmosClient Verbindung basierend auf den Anforderungen und Konventionen Ihres Projekts.
Verwenden Sie eine Verbindungszeichenfolge
Wenn Sie eine Verbindungszeichenfolge aus dem Konfigurationsabschnitt ConnectionStrings verwenden, können Sie beim Aufrufen von builder.AddAzureCosmosClientden Namen der Verbindungszeichenfolge angeben:
builder.AddAzureCosmosClient("cosmosConnectionName");
Anschließend wird die Verbindungszeichenfolge aus dem Konfigurationsabschnitt ConnectionStrings abgerufen:
{
"ConnectionStrings": {
"cosmosConnectionName": "https://{account_name}.documents.azure.com:443/"
}
}
Der empfohlene Verbindungsansatz besteht darin, einen Kontoendpunkt zu verwenden, der mit der MicrosoftAzureCosmosSettings.Credential-Eigenschaft funktioniert, um eine Verbindung herzustellen. Wenn keine Anmeldeinformationen konfiguriert sind, wird die DefaultAzureCredential verwendet:
{
"ConnectionStrings": {
"cosmosConnectionName": "https://{account_name}.documents.azure.com:443/"
}
}
Alternativ kann eine AzureAzure Cosmos DB Verbindungszeichenfolge verwendet werden:
{
"ConnectionStrings": {
"cosmosConnectionName": "AccountEndpoint=https://{account_name}.documents.azure.com:443/;AccountKey={account_key};"
}
}
Konfigurationsanbieter verwenden
Die .NET AspireAzure Cosmos DB-Integration unterstützt Microsoft.Extensions.Configuration. Es lädt die MicrosoftAzureCosmosSettings aus appsettings.json oder den anderen Konfigurationsdateien mithilfe des Aspire:Microsoft:Azure:Cosmos Schlüssels. Beispiel appsettings.json, das einige der Optionen konfiguriert:
{
"Aspire": {
"Microsoft": {
"Azure": {
"Cosmos": {
"DisableTracing": false,
}
}
}
}
}
Inline-Delegaten verwenden
Sie können auch den Action<MicrosoftAzureCosmosSettings > Delegat übergeben, um einige oder alle Optionen inline einzurichten, z. B. zum Deaktivieren der Ablaufverfolgung aus Code:
builder.AddAzureCosmosClient(
"cosmosConnectionName",
static settings => settings.DisableTracing = true);
Sie können die Microsoft.Azure.Cosmos.CosmosClientOptions auch mithilfe des optionalen Parameters Action<CosmosClientOptions> configureClientOptions der AddAzureCosmosClient-Methode einrichten. Um beispielsweise das Benutzer-Agent-Header-Suffix CosmosClientOptions.ApplicationName für alle Anfragen durch diese clientfestzulegen:
builder.AddAzureCosmosClient(
"cosmosConnectionName",
configureClientOptions:
clientOptions => clientOptions.ApplicationName = "myapp");
Gesundheitschecks
Standardmäßig ermöglichen .NET-.NET Aspire-Integrationen Gesundheitschecks für alle Dienste -. Weitere Informationen finden Sie unter .NET.NET Aspire Integrationsübersicht.
Die .NET AspireAzure Cosmos DB Integration implementiert derzeit keine Gesundheitsprüfungen, dies könnte sich jedoch in zukünftigen Versionen ändern.
Observability und Telemetrie
.NET .NET Aspire-Integrationen richten automatisch Protokollierungs-, Ablaufverfolgungs- und Metrikkonfigurationen ein, die manchmal als die Säulen der Beobachtbarkeitbezeichnet werden. Weitere Informationen zur Integrations-Observability und Telemetrie finden Sie unter .NET.NET Aspire Integrationsübersicht. Abhängig vom unterstützenden Dienst unterstützen einige Integrationen möglicherweise nur einige dieser Funktionen. Beispielsweise unterstützen einige Integrationen Protokollierung und Ablaufverfolgung, aber keine Metriken. Telemetrie-Features können auch mithilfe der Techniken deaktiviert werden, die im Abschnitt Configuration dargestellt sind.
Protokollierung
Die .NET AspireAzure Cosmos DB-Integration verwendet die folgenden Protokollkategorien:
- Azure-Kosmos-Operation-Request-Diagnostics
Zusätzlich zum Abrufen von Azure Cosmos DB Anforderungsdiagnosen für fehlerhafte Anforderungen können Sie Latenzschwellenwerte konfigurieren, um zu bestimmen, welche der erfolgreichen Azure Cosmos DB Anforderungsdiagnosen protokolliert werden. Die Standardwerte sind 100 ms für Punktvorgänge und 500 ms für Vorgänge ohne Punkt.
builder.AddAzureCosmosClient(
"cosmosConnectionName",
configureClientOptions:
clientOptions => {
clientOptions.CosmosClientTelemetryOptions = new()
{
CosmosThresholdOptions = new()
{
PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(50),
NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(300)
}
};
});
Nachverfolgung
Die .NET AspireAzure Cosmos DB Integration gibt die folgenden Protokollierungsaktivitäten mithilfe von OpenTelemetryaus.
- Azure. Cosmos.Operation
Azure Azure Cosmos DB Ablaufverfolgung befindet sich derzeit in der Vorschau, daher müssen Sie den experimentellen Schalter festlegen, um sicherzustellen, dass Ablaufverfolgungen ausgegeben werden. Erfahren Sie mehr über die Nachverfolgung in AzureAzure Cosmos DB.
AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);
Metriken
Die .NET AspireAzure Cosmos DB-Integration unterstützt derzeit Metriken aufgrund von Einschränkungen mit dem Azure SDK nicht standardmäßig.
