Översikt över Azure SDK för .NET-protokoll och bekvämlighetsmetoder

Azure SDK-klientbiblioteken tillhandahåller ett gränssnitt till Azure-tjänster genom att översätta metodanrop till meddelanden som skickas via respektive tjänstprotokoll. För REST API-tjänster innebär det att skicka HTTP-begäranden och konvertera svaren till körningstyper. I den här artikeln får du lära dig mer om de olika typer av metoder som exponeras av klientbiblioteken och utforska deras implementeringsmönster.

Förstå protokoll- och bekvämlighetsmetoder

Ett Azure SDK för .NET-klientbibliotek kan exponera två olika typer av metoder för att göra begäranden till en Azure-tjänst:

• Protokollmetoder ger en tunn omslutning runt det underliggande REST-API:et för en motsvarande Azure-tjänst. Dessa metoder mappar primitiva indataparametrar till HTTP-begärandevärden och returnerar ett http-svarsobjekt.
• Bekvämlighetsmetoder ger ett bekvämlighetslager över protokollskiktet på lägre nivå för att lägga till stöd för .NET-typsystemet och andra fördelar. Bekvämlighetsmetoder accepterar primitiver eller .NET-modelltyper som parametrar och mappar dem till brödtexten i en underliggande REST API-begäran. Dessa metoder hanterar också olika detaljer om hantering av begäranden och svar så att utvecklare kan fokusera på att skicka och ta emot dataobjekt, i stället för problem på lägre nivå.

Beroendemönster för Azure SDK-klientbibliotek

Protokoll- och bekvämlighetsmetoder implementerar något olika mönster baserat på den underliggande paketberoendekedjan för respektive bibliotek. Ett Azure SDK för .NET-klientbibliotek beror på ett av två olika grundläggande bibliotek:

• Azure.Core tillhandahåller delade primitiver, abstraktioner och hjälpfunktioner för att skapa moderna Azure SDK-klientbibliotek. Dessa bibliotek följer Azure SDK:s designriktlinjer för .NET och använder paketnamn och namnområden som är prefix för Azure, till exempel Azure.Storage.Blobs.
• System.ClientModel är ett kärnbibliotek som tillhandahåller delade primitiver, abstraktioner och hjälpfunktioner för .NET-tjänstklientbibliotek. Biblioteket System.ClientModel är en verktygsuppsättning för generell användning som är utformad för att hjälpa till att skapa bibliotek för olika plattformar och tjänster, medan Azure.Core biblioteket är särskilt utformat för att skapa Azure-klientbibliotek.

Kommentar

Själva Azure.Core biblioteket är System.ClientModel också beroende av för olika klientbyggstenar. I den här artikeln är den viktigaste differentiatorn för metodmönster om ett klientbibliotek är beroende av Azure.Core eller System.ClientModel direkt, snarare än via ett transitivt beroende.

I följande tabell jämförs några av de typer av begäranden och svar som används av protokoll- och bekvämlighetsmetoder, baserat på om biblioteket är Azure.Core beroende av eller System.ClientModel.

Problem med begäran eller svar	Azure.Core	System.ClientModel
Begärandetext	RequestContent	BinaryContent
Avancerade alternativ för begäranden	RequestContext	RequestOptions
Raw HTTP-svar	Response	PipelineResponse
Returtyp med utdatamodell	Response<T>	ClientResult<T>

I de kommande avsnitten finns implementeringsexempel på dessa begrepp.

Exempel på protokoll- och bekvämlighetsmetoder

De kodningsmönster och typer som används av klientbibliotekets protokoll och bekvämlighetsmetoder varierar något beroende på om biblioteket är Azure.Core beroende av eller System.ClientModel. Skillnaderna påverkar främst de .NET-typer som används för hantering av begärande- och svarsdata.

Bibliotek som är beroende av Azure.Core

Azure SDK-klientbibliotek som följer de senaste designriktlinjerna beror på Azure.Core biblioteket. Biblioteket är till exempel Azure.AI.ContentSafety beroende av Azure.Core biblioteket och tillhandahåller en ContentSafetyClient klass som exponerar både protokoll- och bekvämlighetsmetoder.

Bekvämlighetsmetod

Följande kod använder en ContentSafetyClient för att anropa AnalyzeText bekvämlighetsmetoden:

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}");
}

Föregående kod visar följande Azure.Core bekvämlighetsmetodmönster:

• Använder en vanlig C#-primitiv eller modelltyp som parameter.
• Returnerar en vänlig C#-typ som representerar resultatet av åtgärden.

Protokollmetod

Följande kod använder en ContentSafetyClient för att anropa AnalyzeText protokollmetoden:

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}");
}

Föregående kod visar följande Azure.Core protokollmetodmönster:

1. Skapa begäran med hjälp av ett RequestContent objekt för begärandetexten.
2. Anropa protokollmetoden med hjälp av ett RequestContext objekt för att konfigurera alternativ för begäranden.
3. Hantera svaret genom att läsa:
   • HTTP-statuskoden från Response objektet för att fastställa lyckade eller misslyckade.
   • Data från objektets Response innehåll till en dynamisk typ med hjälp av ToDynamicFromJson. Mer information finns i Meddelande om dynamisk JSON i Azure Core-biblioteket för .NET.

Kommentar

Föregående kod konfigurerar ErrorOptions.NoThrow-beteendet . Det här alternativet förhindrar att statuskoder för tjänstsvar som inte lyckas genererar ett undantag, vilket innebär att appkoden manuellt ska hantera svarsstatuskodkontrollerna.

Bibliotek som är beroende av System.ClientModel

Vissa klientbibliotek som ansluter till icke-Azure-tjänster använder mönster som liknar de bibliotek som är beroende Azure.Coreav . Biblioteket tillhandahåller till exempel OpenAI en klient som ansluter till OpenAI-tjänsterna. Dessa bibliotek baseras på ett bibliotek med namnet System.ClientModel som har mönster som liknar Azure.Core.

Bekvämlighetsmetod

Överväg följande kod som använder en ChatClient för att anropa CompleteChat bekvämlighetsmetoden:

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}");

Föregående kod visar följande System.ClientModel bekvämlighetsmetodmönster:

• Använder en vanlig C#-primitiv eller modelltyp som parameter.
• Returnerar en ClientResult typ som representerar resultatet av åtgärden.

Protokollmetod

Följande kod använder en ChatClient för att anropa CompleteChat protokollmetoden:

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)}");

Föregående kod visar följande System.ClientModel protokollmetodmönster:

1. Skapa begäran med hjälp av ett BinaryContent objekt för begärandetexten.
2. Anropa protokollmetoden med hjälp av ett RequestOptions objekt för att konfigurera alternativ för begäranden.
3. Hantera svaret genom att läsa:
   • HTTP-statuskoden från PipelineResponse objektet för att fastställa lyckade eller misslyckade.
   • Data från PipelineResponse objektets innehåll med API System.Text.Json :er.

Kommentar

Föregående kod konfigurerar ClientErrorBehaviors.NoThrow-beteendet för RequestOptions. Det här alternativet förhindrar att statuskoder för tjänstsvar som inte lyckas genererar ett undantag, vilket innebär att appkoden manuellt ska hantera svarsstatuskodkontrollerna.

Ett System.ClientModel-baserat svar kan bearbetas som en bekvämlighetsmodell om du är beroende Azure.Coreav . Följande diff visar den här alternativa metoden, som följer samma metod som visas på fliken Protokollmetod i Bibliotek som är beroende av Azure.Core.

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}");

Hantera undantag

När ett tjänstanrop misslyckas utlöser tjänstklienten ett undantag som exponerar HTTP-statuskoden och information om tjänstsvaret, om det är tillgängligt. Ett System.ClientModel-beroende bibliotek genererar ett ClientResultException, medan ett Azure.Core-beroende bibliotek genererar en RequestFailedException.

System.ClientModel-undantag

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-undantag

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}");
}

Användningsvägledning för protokoll och bekvämlighetsmetod

Även om Azure SDK för .NET-klientbibliotek ger möjlighet att använda antingen protokoll- eller bekvämlighetsmetoder, prioriterar du användning av bekvämlighetsmetoder i de flesta scenarier. Bekvämlighetsmetoder är utformade för att förbättra utvecklingsupplevelsen och ge flexibilitet för redigering av begäranden och hantering av svar. Båda metodtyperna kan dock användas i din app efter behov. Tänk på följande kriterier när du bestämmer vilken typ av metod som ska användas.

Bekvämlighetsmetoder:

• Gör att du kan arbeta med mer användarvänliga metodparametrar och svarstyper.
• Hantera olika problem och optimeringar på låg nivå åt dig.

Protokollmetoder:

• Ge åtkomst till typer på lägre nivå, till exempel RequestContext och RequestOptions, som inte är tillgängliga via bekvämlighetsmetoder.
• Aktivera åtkomst till funktioner i underliggande REST-API:er som bekvämlighetsmetoder inte exponerar.
• Gör att du kan skapa egna bekvämlighetsmetoder runt tjänstslutpunkter som inte redan har bekvämlighetsmetoder. Den här metoden kräver att du förstår tjänstens REST API-dokumentation för att hantera begäranden och svar korrekt.

Se även

Förstå Azure Core-biblioteket för .NET