Freigegebene Azure Core-Clientbibliothek für .NET– Version 1.35.0

Azure.Core bietet freigegebene Grundtypen, Abstraktionen und Hilfsprogramme für moderne .NET Azure SDK-Clientbibliotheken. Diese Bibliotheken folgen den Azure SDK-Entwurfsrichtlinien für .NET und können leicht anhand von Paket- und Namespacenamen identifiziert werden, beginnend mit "Azure", z. B. Azure.Storage.Blobs. Eine vollständige Liste der Clientbibliotheken, die Azure.Core verwenden, finden Sie hier.

Azure.Core ermöglicht Es Clientbibliotheken, allgemeine Funktionen konsistent verfügbar zu machen, sodass Sie, sobald Sie erfahren haben, wie Sie diese APIs in einer Clientbibliothek verwenden, wissen, wie Sie sie in anderen Clientbibliotheken verwenden können.

Quellcode | Paket (NuGet) | API-Referenzdokumentation

Erste Schritte

In der Regel müssen Sie Azure.Core nicht installieren. Es wird für Sie installiert, wenn Sie eine der Clientbibliotheken installieren, die sie verwenden. Falls Sie es explizit installieren möchten (z. B. um Eine eigene Clientbibliothek zu implementieren), finden Sie das NuGet-Paket hier.

Wichtige Begriffe

Die Standard gemeinsam genutzten Konzepten von Azure.Core (und daher Azure SDK-Bibliotheken, die Azure.Core verwenden) umfassen:

• Konfigurieren von Dienstclients, z. B. Konfigurieren von Wiederholungen, Protokollierung (ClientOptions).
• Zugreifen auf HTTP-Antwortdetails (Response, Response<T>).
• Aufrufen von Vorgängen mit langer Ausführungsdauer (Operation<T>).
• Paging und asynchrone Streams (AsyncPageable<T>).
• Ausnahmen für die konsistente Meldung von Fehlern aus Dienstanforderungen. (RequestFailedException).
• Anpassen von Anforderungen (RequestContext).
• Abstraktionen zum Darstellen von Azure SDK-Anmeldeinformationen. (TokenCredentials).

Im Folgenden finden Sie Abschnitte, in der diese gemeinsamen Konzepte ausführlicher erläutert werden.

Threadsicherheit

Wir garantieren, dass alle Client-instance Methoden threadsicher und unabhängig voneinander sind (Richtlinie). Dadurch wird sichergestellt, dass die Empfehlung, Clientinstanzen wiederzuverwenden, immer sicher ist, auch über Threads hinweg.

Zusätzliche Konzepte

Clientoptionen | Zugreifen auf die Antwort | Vorgänge | mit langer AusführungsdauerBehandeln von Fehlern | Diagnose | Spott | Clientlebensdauer

Beispiele

HINWEIS: Die Beispiele in dieser Datei gelten nur für Pakete, die den Azure SDK-Entwurfsrichtlinien entsprechen. Die Namen solcher Pakete beginnen in der Regel mit Azure.

Konfigurieren von Dienstclients mit ClientOptions

Azure SDK-Clientbibliotheken machen in der Regel einen oder mehrere Dienstclienttypen verfügbar, die die Standard Ausgangspunkte für den Aufruf entsprechender Azure-Dienste sind. Sie können diese Clienttypen leicht finden, da ihre Namen mit dem Wort Client enden. Kann beispielsweise verwendet werden, BlockBlobClient um den Blobspeicherdienst aufzurufen, und KeyClient kann für den Zugriff auf Key Vault Kryptografieschlüssel des Diensts verwendet werden.

Diese Clienttypen können instanziiert werden, indem ein einfacher Konstruktor oder dessen Überladung aufgerufen wird, die verschiedene Konfigurationsoptionen verwendet. Diese Optionen werden als Parameter übergeben, der die von Azure.Core verfügbar gemachte Klasse erweitert ClientOptions . Den Unterklassen werden in der Regel verschiedene dienstspezifische Optionen hinzugefügt, aber eine Reihe sdkweiter Optionen sind direkt auf ClientOptionsverfügbar.

SecretClientOptions options = new SecretClientOptions()
{
    Retry =
    {
        Delay = TimeSpan.FromSeconds(2),
        MaxRetries = 10,
        Mode = RetryMode.Fixed
    },
    Diagnostics =
    {
        IsLoggingContentEnabled = true,
        ApplicationId = "myApplicationId"
    }
};

SecretClient client = new SecretClient(new Uri("http://example.com"), new DefaultAzureCredential(), options);

Weitere Informationen zur Clientkonfiguration finden Sie unter Clientkonfigurationsbeispiele.

Zugreifen auf HTTP-Antwortdetails mithilfe von Response<T>

Dienstclients verfügen über Methoden, die zum Aufrufen von Azure-Diensten verwendet werden können. Wir beziehen uns auf diese Clientmethoden-Dienstmethoden. Dienstmethoden geben einen freigegebenen Azure.Core-Typ Response<T> zurück (in seltenen Fällen der nicht generische gleichgeordnete Typ, ein unformatiertes Response). Dieser Typ bietet Zugriff sowohl auf das deserialisierte Ergebnis des Dienstaufrufs als auch auf die Details der vom Server zurückgegebenen HTTP-Antwort.

// create a client
var client = new SecretClient(new Uri("http://example.com"), new DefaultAzureCredential());

// call a service method, which returns Response<T>
Response<KeyVaultSecret> response = await client.GetSecretAsync("SecretName");

// Response<T> has two main accessors.
// Value property for accessing the deserialized result of the call
KeyVaultSecret secret = response.Value;

// .. and GetRawResponse method for accessing all the details of the HTTP response
Response http = response.GetRawResponse();

// for example, you can access HTTP status
int status = http.Status;

// or the headers
foreach (HttpHeader header in http.Headers)
{
    Console.WriteLine($"{header.Name} {header.Value}");
}

Weitere Informationen zu Antworttypen in Antwortbeispielen.

Einrichten der Konsolenprotokollierung

Verwenden Sie die Methode, um einen Azure SDK-Protokolllistener zu erstellen, der Nachrichten an die Konsole AzureEventSourceListener.CreateConsoleLogger ausgibt.

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

Weitere Informationen zur Anmeldung Diagnose Beispielen.

Melden von Fehlern RequestFailedException

Wenn ein Dienstaufruf fehlschlägt Azure.RequestFailedException , wird ausgelöst. Der Ausnahmetyp stellt eine Status-Eigenschaft mit einem HTTP-status Code und eine ErrorCode-Eigenschaft mit einem dienstspezifischen Fehlercode bereit.

try
{
    KeyVaultSecret secret = client.GetSecret("NonexistentSecret");
}
// handle exception with status code 404
catch (RequestFailedException e) when (e.Status == 404)
{
    // handle not found error
    Console.WriteLine("ErrorCode " + e.ErrorCode);
}

Weitere Informationen zur Behandlung von Antworten in Antwortbeispielen.

Verwenden von Dienstmethoden, die zurückgegeben werden AsyncPageable<T>

Wenn ein Dienstaufruf mehrere Werte auf Seiten zurückgibt, würde er als Ergebnis zurückgegeben Pageable<T>/AsyncPageable<T> . Sie können direkt oder in Seiten durchlaufen AsyncPageable .

// call a service method, which returns AsyncPageable<T>
AsyncPageable<SecretProperties> allSecretProperties = client.GetPropertiesOfSecretsAsync();

await foreach (SecretProperties secretProperties in allSecretProperties)
{
    Console.WriteLine(secretProperties.Name);
}

Weitere Informationen zu ausgelagerten Antworten finden Sie unter Paginierung mit dem Azure SDK für .NET.

Verwenden von Long-Running Vorgängen mit Operation<T>

Einige Vorgänge dauern lange und erfordern eine Abfrage ihrer status. Methoden, die vorgänge mit langer Ausführungszeit starten, geben Typen zurück *Operation<T> .

Die WaitForCompletionAsync -Methode ist eine einfache Möglichkeit, auf den Abschluss des Vorgangs zu warten und den resultierenden Wert abzurufen.

// create a client
SecretClient client = new SecretClient(new Uri("http://example.com"), new DefaultAzureCredential());

// Start the operation
DeleteSecretOperation operation = await client.StartDeleteSecretAsync("SecretName");

Response<DeletedSecret> response = await operation.WaitForCompletionAsync();
DeletedSecret value = response.Value;

Console.WriteLine(value.Name);
Console.WriteLine(value.ScheduledPurgeDate);

Weitere Informationen zu Zeitintensiven Vorgängen in Beispielen für vorgänge mit langer Ausführungszeit.

Anpassen von Anforderungen mit RequestContext

Neben der allgemeinen Konfiguration von Dienstclients über ClientOptionsist es möglich, die von Dienstclients gesendeten Anforderungen mithilfe von Protokollmethoden oder Komfort-APIs anzupassen, die als Parameter verfügbar gemacht werden RequestContext .

var context = new RequestContext();
context.AddClassifier(404, isError: false);

Response response = await client.GetPetAsync("pet1", context);

Weitere Informationen zur Anforderungsanpassung finden Sie unter RequestContext-Beispiele.

Simulation

Eines der wichtigsten übergreifenden Features unserer neuen Clientbibliotheken, die Azure.Core verwenden, ist, dass sie für das Simulieren konzipiert sind. Die Simulation wird durch Folgendes aktiviert:

• Bereitstellen eines geschützten parameterlosen Konstruktors für Clienttypen.
• Virtuelle Dienstmethoden machen.
• Bereitstellen von APIs zum Erstellen von Modelltypen, die von virtuellen Dienstmethoden zurückgegeben werden. Um diese Factorymethoden zu finden, suchen Sie nach Typen mit dem ModelFactory-Suffix , z. B. SecretModelFactory.

Beispielsweise kann die ConfigurationClient.Get-Methode (mit Moq) wie folgt simuliert werden:

// Create a mock response
var mockResponse = new Mock<Response>();

// Create a mock value
var mockValue = SecretModelFactory.KeyVaultSecret(
    SecretModelFactory.SecretProperties(new Uri("http://example.com"))
);

// Create a client mock
var mock = new Mock<SecretClient>();

// Setup client method
mock.Setup(c => c.GetSecret("Name", null, default))
    .Returns(Response.FromValue(mockValue, mockResponse.Object));

// Use the client mock
SecretClient client = mock.Object;
KeyVaultSecret secret = client.GetSecret("Name");

Weitere Informationen zum Simulieren finden Sie unter Komponententests und -simulationen mit dem Azure SDK für .NET.

Verteilte Ablaufverfolgung mit Application Insights

Application Insights, ein Feature von Azure Monitor, ist ein erweiterbarer Dienst zur Verwaltung der Anwendungsleistung (Application Performance Management, APM) für Entwickler und DevOps-Profis. Überwachen Sie damit Ihre aktiven Anwendungen. Es erkennt automatisch Leistungsanomalien und enthält leistungsstarke Analysetools, die Ihnen helfen, Probleme zu diagnostizieren und zu verstehen, was Benutzer tatsächlich mit Ihrer App tun.

Wenn Ihre Anwendung bereits ApplicationInsights verwendet, wird die automatische Sammlung von Azure SDK-Ablaufverfolgungen seit Version 2.12.0unterstützt.

Befolgen Sie zum Einrichten der ApplicationInsights-Nachverfolgung für Ihre Anwendung das Handbuch Überwachung der Anwendung starten .

Weitere Informationen zu Diagnose finden Sie in Diagnose Beispielen.

Problembehandlung

Drei Standard Möglichkeiten zur Problembehandlung sind das Überprüfen von Ausnahmen, das Aktivieren der Protokollierung und die verteilte Ablaufverfolgung.

Nächste Schritte

Erkunden und installieren Sie die verfügbaren Azure SDK-Bibliotheken.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Ausführliche Informationen finden Sie unter https://cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys mit unserer CLA tun.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.