Übersicht über Protokoll- und Hilfsmethoden von Azure SDK für .NET

Die Azure SDK-Clientbibliotheken stellen eine Schnittstelle zu Azure-Diensten bereit, indem Methodenaufrufe in Nachrichten übersetzt werden, die über das jeweilige Dienstprotokoll gesendet werden. Bei REST-API-Diensten bedeutet dies, dass HTTP-Anforderungen gesendet und die Antworten in Runtimetypen konvertiert werden. In diesem Artikel erfahren Sie mehr über die verschiedenen Arten von Methoden, die von den Clientbibliotheken verfügbar gemacht werden. Außerdem werden Implementierungsmuster genauer untersucht.

Grundlegendes zu Protokoll- und Hilfsmethoden

Ein Azure SDK für .NET-Clientbibliotheken kann zwei verschiedene Kategorien von Methoden verfügbar machen, um Anforderungen an einen Azure-Dienst zu stellen:

• Protokollmethoden bieten einen einfachen Wrapper für die zugrunde liegende REST-API für einen entsprechenden Azure-Dienst. Diese Methoden ordnen primitive Eingabeparameter HTTP-Anforderungswerten zu und geben ein unformatiertes HTTP-Antwortobjekt zurück.
• Hilfsmethoden bieten eine Hilfsebene über der Protokollebene auf niedrigerer Ebene, um Unterstützung für das .NET-Typsystem und andere Vorteile hinzuzufügen. Hilfsmethoden akzeptieren Primitive oder .NET-Modelltypen als Parameter und ordnen sie dem Text einer zugrunde liegenden REST-API-Anforderung zu. Diese Methoden verarbeiten auch verschiedene Details der Anforderungs- und Antwortverwaltung, damit sich Entwickler auf das Senden und Empfangen von Datenobjekten anstatt auf Probleme niedrigerer Ebene konzentrieren können.

Abhängigkeitsmuster der Azure SDK-Clientbibliothek

Protokoll- und Hilfsmethoden implementieren etwas unterschiedliche Muster basierend auf der zugrunde liegenden Paketabhängigkeitskette der jeweiligen Bibliothek. Ein Azure SDK für .NET-Clientbibliotheken hängt von einer von zwei verschiedenen grundlegenden Bibliotheken ab:

• Azure.Core bietet gemeinsam genutzte Primitive, Abstraktionen und Hilfsprogramme zum Erstellen moderner Azure SDK-Clientbibliotheken. Diese Bibliotheken folgen den Azure SDK-Entwurfsrichtlinien für .NET und verwenden Paketnamen und Namespaces, denen Azurevorangestellt ist, z. B. Azure.Storage.Blobs.
• System.ClientModel ist eine Kernbibliothek, die gemeinsam genutzte Primitive, Abstraktionen und Hilfsprogramme für .NET-Dienstclientbibliotheken bereitstellt. Die System.ClientModel-Bibliothek ist ein universelles Toolset, das darauf ausgelegt ist, Bibliotheken für verschiedene Plattformen und Dienste zu erstellen, während die Azure.Core-Bibliothek speziell für die Erstellung von Azure-Clientbibliotheken konzipiert ist.

Hinweis

Die Azure.Core-Bibliothek selbst hängt auch von System.ClientModel für verschiedene Clientbausteine ab. Im Sinne dieses Artikels liegt das Hauptunterscheidungsmerkmal der Methodenmuster darin, ob eine Clientbibliothek direkt von Azure.Core oder System.ClientModel abhängt oder über eine transitive Abhängigkeit.

In der folgenden Tabelle werden einige Anforderungs- und Antworttypen miteinander verglichen, die von Protokoll- und Hilfsmethoden in Abhängigkeit davon, ob die Bibliothek von Azure.Core oder von System.ClientModel abhängt, verwendet werden.

Thema der Anforderung oder der Antwort	Azure.Core	System.ClientModel
Anforderungstext	RequestContent	BinaryContent
Erweiterte Anforderungsoptionen	RequestContext	RequestOptions
Unformatierte HTTP-Antwort	Response	PipelineResponse
Rückgabetyp mit Ausgabemodell	Response<T>	ClientResult<T>

Die folgenden Abschnitte enthalten Implementierungsbeispiele für diese Konzepte.

Beispiele für Protokoll- und Hilfsmethoden

Die Codierungsmuster und Typen, die von den Protokoll- und Hilfsmethoden einer Clientbibliothek verwendet werden, variieren geringfügig, je nachdem, ob die Bibliothek von Azure.Core oder System.ClientModel abhängt. Die Unterschiede beeinflussen in erster Linie die .NET-Typen, die für die Verarbeitung von Anforderungs- und Antwortdaten verwendet werden.

Bibliotheken, die von Azure.Core abhängen

Azure SDK-Clientbibliotheken, die den neuesten Entwurfsrichtlinien entsprechen, hängen von der Azure.Core-Bibliothek ab. Beispielsweise hängt die Azure.AI.ContentSafety-Bibliothek von der Azure.Core-Bibliothek ab und stellt eine ContentSafetyClient-Klasse bereit, die sowohl Protokoll- als auch Hilfsmethoden verfügbar macht.

Hilfsmethode

Der folgende Code verwendet ContentSafetyClient, um die AnalyzeText-Hilfsmethode aufzurufen:

C#

using Azure.AI.ContentSafety;
using Azure.Identity;

// Create the client
ContentSafetyClient client = new(
    new Uri("https://contentsafetyai.cognitiveservices.azure.com/"),
    new DefaultAzureCredential());

// Call the convenience method
AnalyzeTextResult result = client.AnalyzeText("What is Microsoft Azure?");

// Display the results
foreach (TextCategoriesAnalysis item in result.CategoriesAnalysis)
{
    Console.WriteLine($"{item.Category}: {item.Severity}");
}

Im vorherigen Code werden die folgenden Muster der Azure.Core-Hilfsmethode veranschaulicht:

• Verwendet einen standardmäßigen C#-Primitivtyp oder -Modelltyp als Parameter.
• Gibt einen benutzerfreundlichen C#-Typ zurück, der das Ergebnis des Vorgangs darstellt.

Protokollmethode

Der folgende Code verwendet ContentSafetyClient, um die AnalyzeText-Protokollmethode aufzurufen:

C#

using Azure;
using Azure.AI.ContentSafety;
using Azure.Core;
using Azure.Core.Serialization;
using Azure.Identity;

// Create the client
ContentSafetyClient client = new(
    new Uri("https://contentsafetyai.cognitiveservices.azure.com/"),
    new DefaultAzureCredential());

// Create the prompt
RequestContent prompt = RequestContent.Create(new
{
    text = "What is Microsoft Azure?",
});

// Call the protocol method
Response response = client.AnalyzeText(
    prompt,
    new RequestContext
    {
        ErrorOptions = ErrorOptions.NoThrow,
    });

// Any non-200 response code from Azure AI Content Safety AnalyzeText REST API isn't considered a success response.
// See REST API details at https://azure-ai-content-safety-api-docs.developer.azure-api.net/api-details#api=content-safety-service-2023-10-01&operation=TextOperations_AnalyzeText
if (response.Status != 200)
{
    throw new RequestFailedException(response);
}

// With this dynamic instance, you can use response content like a convenience model. As convenience APIs are added
// to the library, this approach helps you evolve code from protocol to convenience with minimal code changes.
dynamic content = response.Content.ToDynamicFromJson(JsonPropertyNames.CamelCase);

// Display the results
foreach (var item in content.CategoriesAnalysis)
{
    Console.WriteLine($"{item.Category}: {item.Severity}");
}

Im vorherigen Code werden die folgenden Muster der Azure.Core-Protokollmethode veranschaulicht:

1. Erstellen Sie die Anforderung mithilfe eines RequestContent Objekts für den Anforderungstext.
2. Rufen Sie die Protokollmethode mithilfe eines RequestContext Objekts zum Konfigurieren von Anforderungsoptionen auf.
3. Verarbeiten Sie die Antwort. Weitere Informationen finden Sie hier:
   • Der HTTP-Statuscode aus dem Response-Objekt zum Ermitteln von Erfolg oder Fehlschlagen.
   • Daten aus dem Inhalt des Objekts Response in einen dynamischen Typ mithilfe von ToDynamicFromJson. Weitere Informationen finden Sie unter Ankündigung der Unterstützung von Dynamic JSON in der Azure Core-Bibliothek für .NET.

Hinweis

Mit dem obigen Code wird das ErrorOptions.NoThrow-Verhalten konfiguriert. Diese Option verhindert, dass Statuscodes für nicht erfolgreiche Dienstantworten eine Ausnahme auslösen. Dies bedeutet, dass der App-Code den Antwortstatuscode manuell überprüfen soll.

Bibliotheken, die von System.ClientModel abhängen

Einige Clientbibliotheken, die eine Verbindung mit Nicht-Azure-Diensten herstellen, verwenden ähnliche Muster wie die Bibliotheken, die von Azure.Core abhängen. Beispielsweise stellt die OpenAI-Bibliothek einen Client bereit, der mit den OpenAI-Diensten verbunden wird. Diese Bibliotheken basieren auf einer Bibliothek namens System.ClientModel, die Muster ähnlich wie Azure.Core aufweist.

Hilfsmethode

Betrachten Sie den folgenden Code, der ChatClient verwendet, um die CompleteChat-Hilfsmethode aufzurufen:

C#

using OpenAI.Chat;

// Create the client
ChatClient client = new(
    model: "gpt-4o-mini",
    credential: Environment.GetEnvironmentVariable("OPENAI_API_KEY")!);

// Call the convenience method
ChatCompletion completion = client.CompleteChat("What is Microsoft Azure?");

// Display the results
Console.WriteLine($"[{completion.Role}]: {completion}");

Im vorherigen Code werden die folgenden Muster der System.ClientModel-Hilfsmethode veranschaulicht:

• Verwendet einen standardmäßigen C#-Primitivtyp oder -Modelltyp als Parameter.
• Gibt einen ClientResult-Typ zurück, der das Ergebnis des Vorgangs darstellt.

Protokollmethode

Der folgende Code verwendet ChatClient, um die CompleteChat-Protokollmethode aufzurufen:

C#

using OpenAI.Chat;
using System.ClientModel;
using System.ClientModel.Primitives;
using System.Text.Json;

// Create the client
ChatClient client = new(
    model: "gpt-4o-mini",
    credential: Environment.GetEnvironmentVariable("OPENAI_API_KEY")!);

// Create the request content
BinaryData input = BinaryData.FromBytes("""
    {
        "model": "gpt-4o-mini",
        "messages": [
           {
               "role": "user",
               "content": "What is Microsoft Azure?"
           }
        ]
    }
    """u8.ToArray());
using BinaryContent content = BinaryContent.Create(input);

var requestOptions = new RequestOptions();

requestOptions.AddHeader("CustomHeader", "CustomHeaderValue");
requestOptions.ErrorOptions = ClientErrorBehaviors.NoThrow;

// Call the protocol method
ClientResult result = client.CompleteChat(
    content,
    requestOptions
);

PipelineResponse response = result.GetRawResponse();

// Any non-200 response code from CompleteChat endpoint isn't considered a success response.
if (response.Status != 200)
{
    throw new ClientResultException(response);
}

using JsonDocument output = JsonDocument.Parse(response.Content);
JsonElement message = output.RootElement
    .GetProperty("choices"u8)[0]
    .GetProperty("message"u8);

// Display the results
Console.WriteLine($@"[{message.GetProperty("role"u8)}]:
    {message.GetProperty("content"u8)}");

Im vorherigen Code werden die folgenden Muster der System.ClientModel-Protokollmethode veranschaulicht:

1. Erstellen Sie die Anforderung mithilfe eines BinaryContent Objekts für den Anforderungstext.
2. Rufen Sie die Protokollmethode mithilfe eines RequestOptions Objekts zum Konfigurieren von Anforderungsoptionen auf.
3. Verarbeiten Sie die Antwort. Weitere Informationen finden Sie hier:
   • Der HTTP-Statuscode aus dem PipelineResponse-Objekt zum Ermitteln von Erfolg oder Fehlschlagen.
   • Daten aus dem Inhalt des Objekts PipelineResponse mithilfe von System.Text.Json APIs.

Hinweis

Der vorherige Code konfiguriert das Verhalten ClientErrorBehaviors.NoThrow für RequestOptions. Diese Option verhindert, dass Statuscodes für nicht erfolgreiche Dienstantworten eine Ausnahme auslösen. Dies bedeutet, dass der App-Code den Antwortstatuscode manuell überprüfen soll.

Eine System.ClientModel-basierte Antwort kann wie ein Hilfsmodell verarbeitet werden, falls Sie eine Abhängigkeit von Azure.Core erstellen. Der folgende Diff zeigt diesen alternativen Ansatz, der denselben Ansatz verfolgt, wie der, der auf der Registerkarte Protokollmethode unter Von Azure.Core abhängige Bibliotheken beschrieben ist.

diff

PipelineResponse response = result.GetRawResponse();

- using JsonDocument output = JsonDocument.Parse(response.Content);
- JsonElement message = output.RootElement
-     .GetProperty("choices"u8)[0]
-     .GetProperty("message"u8);

- Console.WriteLine($@"[{message.GetProperty("role"u8)}]:
-     {message.GetProperty("content"u8)}");

+ dynamic output = response.Content.ToDynamicFromJson(
+     JsonPropertyNames.CamelCase);
+ var message = output.Choices[0].Message;
+ Console.WriteLine($"[{message.Role}]: {message.Content}");

Verarbeiten von Ausnahmen

Wenn ein Dienstaufruf fehlschlägt, löst der Dienstclient eine Ausnahme aus, die den HTTP-Statuscode und die Details der Dienstantwort zur Verfügung stellt (falls verfügbar). Eine von System.ClientModel abhängige Bibliothek löst eine ClientResultException aus, während eine von Azure.Core abhängige Bibliothek eine RequestFailedException auslöst.

System.ClientModel-Ausnahmen

C#

using Azure.AI.ContentSafety;
using Azure.Identity;
using Azure;

// Create the client
ContentSafetyClient client = new(
    new Uri("https://contentsafetyai.cognitiveservices.azure.com/"),
    new DefaultAzureCredential());

try
{
    // Call the convenience method
    AnalyzeTextResult result = client.AnalyzeText("What is Microsoft Azure?");

    // Display the results
    foreach (TextCategoriesAnalysis item in result.CategoriesAnalysis)
    {
        Console.WriteLine($"{item.Category}: {item.Severity}");
    }
} 
catch (RequestFailedException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

Azure.Core-Ausnahmen

C#

using OpenAI.Chat;
using System.ClientModel;

// Create the client
ChatClient client = new(
    model: "gpt-4o-mini",
    credential: Environment.GetEnvironmentVariable("OPENAI_API_KEY")!);

try
{
    // Call the convenience method
    ChatCompletion completion = client.CompleteChat("What is Microsoft Azure?");

    // Display the results
    Console.WriteLine($"[{completion.Role}]: {completion}");
}
catch (ClientResultException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

Verwendungsempfehlungen für Protokoll- und Hilfsmethoden

Obwohl das Azure SDK für .NET-Clientbibliotheken die Möglichkeit bietet, Protokoll- oder Hilfsmethoden zu verwenden, priorisieren Sie in den meisten Szenarien die Verwendung von Hilfsmethoden. Hilfsmethoden sind darauf ausgelegt, die Entwicklungserfahrung zu verbessern. Außerdem bieten sie Flexibilität bei der Erstellung von Anforderungen und der Behandlung von Antworten. Beide Methodentypen können jedoch nach Bedarf in Ihrer App verwendet werden. Berücksichtigen Sie die folgenden Kriterien, wenn Sie entscheiden, welcher Methodentyp verwendet werden soll.

Hilfsmethoden:

• Ermöglichen Ihnen die Arbeit mit benutzerfreundlicheren Methodenparametern und Antworttypen.
• Erledigen verschiedene Probleme und Optimierungen auf niedriger Ebene für Sie.

Protokollmethoden:

• Bieten Zugriff auf Typen auf niedrigerer Ebene, z. B. RequestContext und RequestOptions, die nicht über Hilfsmethoden verfügbar sind.
• Ermöglichen den Zugriff auf Features der zugrunde liegenden REST-APIs, die von Hilfsmethoden nicht verfügbar gemacht werden.
• Ermöglichen es Ihnen, eigene Hilfsmethoden für Dienstendpunkte zu erstellen, die noch nicht über Hilfsmethoden verfügen. Bei diesem Ansatz ist es erforderlich, die REST-API-Dokumentation des Diensts zu verstehen, um Anforderungen und Antworten ordnungsgemäß zu verarbeiten.

Weitere Informationen

Grundlegendes zur Azure Core-Bibliothek für .NET