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.
