Udostępniona biblioteka klienta platformy Azure dla platformy .NET — wersja 1.30.0

Platforma Azure.Core udostępnia udostępnione elementy pierwotne, abstrakcje i pomocniki dla nowoczesnych bibliotek klienckich zestawu Azure SDK platformy .NET. Te biblioteki są zgodne z wytycznymi dotyczącymi projektowania zestawu Azure SDK dla platformy .NET i można je łatwo zidentyfikować przy użyciu nazw pakietów i przestrzeni nazw rozpoczynających się od "Azure", np. Azure.Storage.Blobs. Bardziej kompletną listę bibliotek klienckich korzystających z platformy Azure.Core można znaleźć tutaj.

Platforma Azure.Core umożliwia bibliotekom klienckim uwidacznianie typowych funkcji w spójny sposób, dzięki czemu gdy dowiesz się, jak używać tych interfejsów API w jednej bibliotece klienta, wiesz, jak ich używać w innych bibliotekach klienckich.

Kod | źródłowy Pakiet (NuGet) | Dokumentacja referencyjna interfejsu API

Wprowadzenie

Zazwyczaj nie trzeba instalować platformy Azure.Core; Zostanie on zainstalowany podczas instalowania jednej z bibliotek klienckich przy jej użyciu. Jeśli chcesz ją jawnie zainstalować (na przykład w celu zaimplementowania własnej biblioteki klienta), pakiet NuGet można znaleźć tutaj.

Kluczowe pojęcia

Główne wspólne pojęcia platformy Azure.Core (a więc biblioteki zestawu Azure SDK korzystające z platformy Azure.Core) obejmują:

• Konfigurowanie klientów usługi, np. konfigurowanie ponownych prób, rejestrowanie (ClientOptions).
• Uzyskiwanie dostępu do szczegółów odpowiedzi HTTP (Response, Response<T>).
• Wywoływanie długotrwałych operacji (Operation<T>).
• Stronicowanie i strumienie asynchroniczne (AsyncPageable<T>).
• Wyjątki dotyczące zgłaszania błędów z żądań obsługi w spójny sposób. (RequestFailedException).
• Dostosowywanie żądania (RequestContext).
• Abstrakcje do reprezentowania poświadczeń zestawu Azure SDK. (TokenCredentials).

Poniżej znajdziesz sekcje objaśniające te wspólne pojęcia bardziej szczegółowo.

Bezpieczeństwo wątkowe

Gwarantujemy, że wszystkie metody wystąpienia klienta są bezpieczne wątkowo i niezależne od siebie (wytyczne). Dzięki temu zalecenie ponownego obsługi wystąpień klienta jest zawsze bezpieczne, nawet w wątkach.

Dodatkowe pojęcia

Opcje | klienta Uzyskiwanie dostępu do odpowiedzi | Długotrwałe operacje | Obsługa błędów | Diagnostyka | Szyderczy | Okres istnienia klienta

Przykłady

UWAGA: Przykłady w tym pliku dotyczą tylko pakietów, które są zgodne z wytycznymi dotyczącymi projektowania zestawu Azure SDK. Nazwy takich pakietów zwykle zaczynają się od Azure.

Konfigurowanie klientów usługi przy użyciu polecenia ClientOptions

Biblioteki klienta zestawu Azure SDK zwykle uwidaczniają jeden lub więcej typów klientów usług , które są głównymi punktami wyjścia do wywoływania odpowiednich usług platformy Azure. Można łatwo znaleźć te typy klientów, ponieważ ich nazwy kończą się wyrazem Klient. Na przykład BlockBlobClient może służyć do wywoływania usługi blob Storage i KeyClient może służyć do uzyskiwania dostępu do kluczy kryptograficznych usługi Key Vault.

Te typy klientów można utworzyć, wywołując prosty konstruktor lub jego przeciążenie, które przyjmuje różne opcje konfiguracji. Te opcje są przekazywane jako parametr, który rozszerza ClientOptions klasę uwidacznianą przez platformę Azure.Core. Różne opcje specyficzne dla usługi są zwykle dodawane do jej podklas, ale zestaw opcji dla całego zestawu SDK jest dostępny bezpośrednio w systemie ClientOptions.

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

Więcej informacji na temat konfiguracji klienta w przykładach konfiguracji klienta

Uzyskiwanie dostępu do szczegółów odpowiedzi HTTP przy użyciu polecenia Response<T>

Klienci usług mają metody, których można użyć do wywoływania usług platformy Azure. Odwołujemy się do tych metod usługi metod klienta. Metody usługi zwracają udostępniony typ Response<T> Azure.Core (w rzadkich przypadkach jego nieogólne elementy równorzędne, nieprzetworzone Response). Ten typ zapewnia dostęp zarówno do deserializowanego wyniku wywołania usługi, jak i do szczegółów odpowiedzi HTTP zwróconej z serwera.

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

Więcej informacji na temat typów odpowiedzi w przykładach odpowiedzi

Konfigurowanie rejestrowania konsoli

Aby utworzyć odbiornik dziennika zestawu Azure SDK, który generuje komunikaty do konsoli przy użyciu AzureEventSourceListener.CreateConsoleLogger metody.

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

Więcej informacji na temat rejestrowania w przykładach diagnostycznych

Raportowanie błędów RequestFailedException

Gdy wywołanie usługi zakończy się niepowodzeniem Azure.RequestFailedException , zostanie rzucone. Typ wyjątku udostępnia właściwość Status z kodem stanu HTTP i właściwości ErrorCode z kodem błędu specyficznym dla usługi.

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

Więcej informacji na temat obsługi odpowiedzi w przykładach odpowiedzi

Korzystanie z metod usługi zwracanych AsyncPageable<T>

Jeśli wywołanie usługi zwraca wiele wartości na stronach, zostanie zwróconych Pageable<T>/AsyncPageable<T> w wyniku. Można iterować AsyncPageable bezpośrednio lub na stronach.

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

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

Aby uzyskać więcej informacji na temat stronicowanych odpowiedzi, zobacz Pagination with the Azure SDK for .NET (Stronicowanie przy użyciu zestawu Azure SDK dla platformy .NET).

Korzystanie z operacji Long-Running przy użyciu Operation<T>

Ukończenie niektórych operacji trwa długo i wymaga sondowania stanu. Metody rozpoczynające długotrwałe operacje zwracają *Operation<T> typy.

Metoda WaitForCompletionAsync jest łatwym sposobem oczekiwania na ukończenie operacji i uzyskania wynikowej wartości.

// 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);

Więcej informacji na temat długotrwałych operacji w przykładach długotrwałych operacji

Żądanie niestandardowe przy użyciu polecenia RequestContext

Oprócz ogólnej konfiguracji klientów usług za pośrednictwem ClientOptionsprogramu można dostosować żądania wysyłane przez klientów usług przy użyciu metod protokołu lub interfejsów API wygody, które uwidaczniają RequestContext się jako parametr.

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

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

Więcej informacji na temat dostosowywania żądania w przykładach RequestContext

pozorowanie

Jedną z najważniejszych funkcji krzyżowych naszych nowych bibliotek klienckich korzystających z platformy Azure.Core jest to, że są one przeznaczone do szyderstwa. Pozorowanie jest włączone przez:

• zapewnienie chronionego konstruktora bez parametrów w typach klientów.
• tworzenie metod usług wirtualnych.
• dostarczanie interfejsów API do konstruowania typów modeli zwracanych z metod usług wirtualnych. Aby znaleźć te metody fabryki, poszukaj typów z sufiksem ModelFactory , np. SecretModelFactory.

Na przykład metodę ConfigurationClient.Get można wyśmiewać (za pomocą moq) w następujący sposób:

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

Więcej informacji na temat pozorowania próbek

Śledzenie rozproszone za pomocą usługi Application Insights

Application Insights (funkcja usługi Azure Monitor) to rozszerzalna usługa do zrządzania wydajnością aplikacji dla deweloperów i ekspertów metodyki DevOps. Służy do monitorowania aplikacji na żywo. Automatycznie wykrywa anomalie wydajności i zawiera zaawansowane narzędzia analityczne, które ułatwiają diagnozowanie problemów i zrozumienie, co użytkownicy rzeczywiście robią z twoją aplikacją

Jeśli aplikacja korzysta już z usługi ApplicationInsights, automatyczne zbieranie śladów zestawu Azure SDK jest obsługiwane od wersji 2.12.0.

Aby skonfigurować śledzenie aplikacji ApplicationInsights dla aplikacji, postępuj zgodnie z przewodnikiem Rozpoczynanie monitorowania aplikacji .

Więcej informacji na temat diagnostyki w przykładach diagnostycznych.

Rozwiązywanie problemów

Trzy główne sposoby rozwiązywania problemów z błędami to inspekcja wyjątków, włączanie rejestrowania i rozproszone śledzenie

Następne kroki

Eksplorowanie i instalowanie dostępnych bibliotek zestawu Azure SDK.

Współtworzenie

W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź stronę https://cla.microsoft.com.

Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Należy to zrobić tylko raz we wszystkich repozytoriach przy użyciu naszego cla.

W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz Często zadawane pytania dotyczące kodeksu postępowania lub skontaktuj się z opencode@microsoft.com dodatkowymi pytaniami lub komentarzami.