Sdílená klientská knihovna Azure Core pro .NET – verze 1.30.0

Azure.Core poskytuje sdílená primitiva, abstrakce a pomocné rutiny pro moderní klientské knihovny sady .NET Azure SDK. Tyto knihovny se řídí pokyny pro návrh sady Azure SDK pro .NET a dají se snadno identifikovat podle názvů balíčků a oborů názvů začínajících na Azure, například Azure.Storage.Blobs. Podrobnější seznam klientských knihoven využívajících Azure.Core najdete tady.

Azure.Core umožňuje klientským knihovnám zpřístupnit běžné funkce konzistentním způsobem, takže jakmile se naučíte používat tato rozhraní API v jedné klientské knihovně, budete vědět, jak je používat v jiných klientských knihovnách.

Zdrojový kód | Balíček (NuGet) | Referenční dokumentace k rozhraní API

Začínáme

Obvykle nebudete muset instalovat Azure.Core; nainstaluje se za vás, když instalujete některou z klientských knihoven, která ho používá. Pokud ho chcete nainstalovat explicitně (například k implementaci vlastní klientské knihovny), najdete balíček NuGet tady.

Klíčové koncepty

Mezi hlavní sdílené koncepty Azure.Core (a tedy knihovny Sady Azure SDK využívající Azure.Core) patří:

• Konfigurace klientů služeb, například konfigurace opakování, protokolování (ClientOptions).
• Přístup k podrobnostem odpovědi HTTP (Response, Response<T>).
• Volání dlouhotrvajících operací (Operation<T>).
• Stránkování a asynchronní streamy (AsyncPageable<T>).
• Výjimky pro hlášení chyb z žádostí o služby konzistentním způsobem (RequestFailedException).
• Přizpůsobení požadavku (RequestContext).
• Abstrakce pro reprezentaci přihlašovacích údajů sady Azure SDK (TokenCredentials).

Níže najdete oddíly, které tyto sdílené koncepty podrobněji vysvětlují.

Bezpečnost vlákna

Zaručujeme, že všechny metody instance klienta jsou bezpečné pro přístup z více vláken a nezávislé na sobě (pokyny). Tím se zajistí, že doporučení opakovaně používat instance klienta je vždy bezpečné, a to i napříč vlákny.

Další koncepty

Možnosti | klienta Přístup k odpovědi | Dlouhotrvající operace | Zpracování selhání | Diagnostika | Zesměšňovat | Životnost klienta

Příklady

POZNÁMKA: Ukázky v tomto souboru se vztahují pouze na balíčky, které se řídí pokyny pro návrh sady Azure SDK. Názvy takových balíčků obvykle začínají na Azure.

Konfigurace klientů služeb pomocí ClientOptions

Klientské knihovny Sady Azure SDK obvykle zpřístupňují jeden nebo více typů klientů služeb , které jsou hlavními výchozími body pro volání odpovídajících služeb Azure. Tyto typy klientů můžete snadno najít, protože jejich názvy končí slovem Klient. Můžete ho například BlockBlobClient použít k volání služby Blob Storage a KeyClient můžete ho použít pro přístup k kryptografickým klíčům Key Vault služby.

Tyto typy klientů lze vytvořit voláním jednoduchého konstruktoru nebo jeho přetížení, které přijímá různé možnosti konfigurace. Tyto možnosti se předávají jako parametr, který rozšiřuje ClientOptions třídu vystavenou službou Azure.Core. Do svých podtříd se obvykle přidávají různé možnosti specifické pro službu, ale sada možností pro celou sadu SDK je k dispozici přímo na 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);

Další informace o konfiguraci klienta v ukázkách konfigurace klienta

Přístup k podrobnostem odpovědi HTTP pomocí Response<T>

Klienti služeb mají metody, které je možné použít k volání služeb Azure. Odkazujeme na tyto metody služby klientských metod. Metody služby vrací sdílený typ Response<T> Azure.Core (ve výjimečných případech je to nezogenerní typ na stejné platformě jako nezpracovaný Response). Tento typ poskytuje přístup jak k deserializovanému výsledku volání služby, tak k podrobnostem odpovědi HTTP vrácené ze serveru.

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

Další informace o typech odpovědí v ukázkách odpovědí

Nastavení protokolování konzoly

K vytvoření naslouchacího procesu protokolů sady Azure SDK, který vypisuje zprávy do konzoly, použijte AzureEventSourceListener.CreateConsoleLogger metodu .

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

Další informace o protokolování v ukázkách diagnostiky

Hlášení chyb RequestFailedException

Když volání služby selže Azure.RequestFailedException , vyvolá se to. Typ výjimky poskytuje vlastnost Status se stavovým kódem HTTP a vlastnost ErrorCode s kódem chyby specifickým pro službu.

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

Další informace o zpracování odpovědí v ukázkách odpovědí

Využívání vracející se metody služby AsyncPageable<T>

Pokud volání služby vrátí více hodnot na stránkách, vrátí Pageable<T>/AsyncPageable<T> se jako výsledek. Iterovat AsyncPageable můžete přímo nebo na stránkách.

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

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

Další informace o stránkovaných odpovědích najdete v tématu Stránkování pomocí sady Azure SDK pro .NET.

Využívání operací Long-Running pomocí Operation<T>

Dokončení některých operací trvá dlouho a vyžadují dotazování na jejich stav. Metody, které spouští dlouhotrvající operace, vrací *Operation<T> typy.

Metoda WaitForCompletionAsync je snadný způsob, jak počkat na dokončení operace a získat výslednou hodnotu.

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

Další informace o dlouhotrvajících operacích v ukázkách dlouhotrvajících operací

Přizpůsobení žádosti pomocí RequestContext

Kromě obecné konfigurace klientů služeb prostřednictvím ClientOptionsnástroje je možné přizpůsobit požadavky odesílané klienty služby pomocí metod protokolu nebo rozhraní API pro pohodlí, která se zveřejňují RequestContext jako parametr.

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

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

Další informace o přizpůsobení požadavků v ukázkách RequestContext

Vytvoření modelu

Jednou z nejdůležitějších funkcí našich nových klientských knihoven využívajících Azure.Core je, že jsou navržené pro napodobení. Napodobování umožňuje:

• poskytnutí chráněného konstruktoru bez parametrů pro typy klientů.
• z virtuálních metod služeb.
• poskytuje rozhraní API pro vytváření typů modelů vrácených z metod virtuálních služeb. Pokud chcete tyto metody továrny najít, vyhledejte typy s příponou ModelFactory , například SecretModelFactory.

Například metodu ConfigurationClient.Get je možné napodobenou (s Moq) následujícím způsobem:

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

Další informace o napodobení ukázek

Distribuované trasování s využitím Application Insights

Application Insights je funkcí Azure Monitoru. Je to rozšiřitelná služba pro správu výkonu aplikací (APM) pro vývojáře a odborníky na DevOps. Slouží k monitorování živých aplikací. Automaticky detekuje anomálie ve výkonu a obsahuje výkonné analytické nástroje, které vám pomůžou diagnostikovat problémy a pochopit, co uživatelé s vaší aplikací skutečně dělají.

Pokud už vaše aplikace používá ApplicationInsights, podporuje se automatické shromažďování trasování sady Azure SDK od verze 2.12.0.

Pokud chcete nastavit sledování ApplicationInsights pro vaši aplikaci, postupujte podle průvodce spuštěním monitorování aplikace .

Další informace o diagnostice najdete v ukázkách diagnostiky.

Řešení potíží

Třemi hlavními způsoby řešení potíží se selháními jsou kontrola výjimek, povolení protokolování a distribuované trasování.

Další kroky

Prozkoumejte a nainstalujte dostupné knihovny Sady Azure SDK.

Přispívání

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete tady: https://cla.microsoft.com

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pomocí našeho cla to budete muset provést ve všech úložištích pouze jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování nebo kontaktujte s opencode@microsoft.com případnými dalšími dotazy nebo připomínkami.