Delat Azure Core-klientbibliotek för .NET – version 1.30.0

Azure.Core tillhandahåller delade primitiver, abstraktioner och hjälpfunktioner för moderna .NET Azure SDK-klientbibliotek. Dessa bibliotek följer Riktlinjerna för Azure SDK-design för .NET och kan enkelt identifieras med paket- och namnområdesnamn som börjar med "Azure", t.ex. Azure.Storage.Blobs. En mer fullständig lista över klientbibliotek som använder Azure.Core finns här.

Med Azure.Core kan klientbibliotek exponera vanliga funktioner på ett konsekvent sätt, så att du när du lär dig hur du använder dessa API:er i ett klientbibliotek vet hur du använder dem i andra klientbibliotek.

Källkod | Paket (NuGet) | API-referensdokumentation

Komma igång

Vanligtvis behöver du inte installera Azure.Core. Det installeras åt dig när du installerar ett av klientbiblioteken med hjälp av det. Om du vill installera det explicit (till exempel för att implementera ditt eget klientbibliotek) kan du hitta NuGet-paketet här.

Viktiga begrepp

De viktigaste delade begreppen i Azure.Core (och så Azure SDK-bibliotek med Hjälp av Azure.Core) är:

• Konfigurera tjänstklienter, t.ex. konfigurera återförsök, logga (ClientOptions).
• Åtkomst till HTTP-svarsinformation (Response, Response<T>).
• Anropar långvariga åtgärder (Operation<T>).
• Växling och asynkrona strömmar (AsyncPageable<T>).
• Undantag för att rapportera fel från tjänstbegäranden på ett konsekvent sätt. (RequestFailedException).
• Anpassa begäran (RequestContext).
• Abstraktioner för att representera Azure SDK-autentiseringsuppgifter. (TokenCredentials).

Nedan hittar du avsnitt som förklarar dessa delade begrepp i detalj.

Trådsäkerhet

Vi garanterar att alla klientinstansmetoder är trådsäkra och oberoende av varandra (riktlinje). Detta säkerställer att rekommendationen att återanvända klientinstanser alltid är säker, även över trådar.

Ytterligare begrepp

Klientalternativ | Åtkomst till svaret | Långvariga åtgärder | Hantera fel | Diagnostik | Gäckande | Klientlivslängd

Exempel

OBSERVERA: Exempel i den här filen gäller endast för paket som följer Riktlinjerna för Azure SDK-design. Namnen på sådana paket börjar vanligtvis med Azure.

Konfigurera tjänstklienter med ClientOptions

Azure SDK-klientbibliotek exponerar vanligtvis en eller flera tjänstklienttyper som är de viktigaste startpunkterna för att anropa motsvarande Azure-tjänster. Du kan enkelt hitta dessa klienttyper när deras namn slutar med ordet Klient. Kan till exempel BlockBlobClient användas för att anropa bloblagringstjänsten och KeyClient kan användas för att komma åt Key Vault kryptografiska nycklar för tjänsten.

Dessa klienttyper kan instansieras genom att anropa en enkel konstruktor eller dess överlagring som tar olika konfigurationsalternativ. De här alternativen skickas som en parameter som utökar klassen som exponeras ClientOptions av Azure.Core. Olika tjänstspecifika alternativ läggs vanligtvis till i dess underklasser, men en uppsättning SDK-alternativ är tillgängliga direkt på 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);

Mer information om klientkonfiguration i klientkonfigurationsexempel

Komma åt HTTP-svarsinformation med hjälp av Response<T>

Tjänstklienter har metoder som kan användas för att anropa Azure-tjänster. Vi refererar till dessa tjänstmetoder för klientmetoder. Tjänstmetoder returnerar en delad Azure.Core-typ Response<T> (i sällsynta fall dess icke-generiska syskon, en rå Response). Den här typen ger åtkomst till både det deserialiserade resultatet av tjänstanropet och till information om HTTP-svaret som returneras från servern.

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

Mer information om svarstyper i svarsexempel

Konfigurera konsolloggning

Om du vill skapa en Azure SDK-logglyssnare som matar ut meddelanden till konsolen använder du AzureEventSourceListener.CreateConsoleLogger metoden .

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

Mer information om loggning i diagnostikexempel

Rapporteringsfel RequestFailedException

När ett tjänstanrop misslyckas Azure.RequestFailedException utlöses. Undantagstypen tillhandahåller en statusegenskap med en HTTP-statuskod och en ErrorCode-egenskap med en tjänstspecifik felkod.

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

Mer information om hur du hanterar svar i svarsexempel

Använda tjänstmetoder som returneras AsyncPageable<T>

Om ett tjänstanrop returnerar flera värden på sidor returneras Pageable<T>/AsyncPageable<T> det som ett resultat. Du kan iterera direkt AsyncPageable eller på sidor.

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

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

Mer information om sidsvar finns i Sidnumrering med Azure SDK för .NET.

Använda Long-Running åtgärder med Operation<T>

Vissa åtgärder tar lång tid att slutföra och kräver avsökning för deras status. Metoder som startar långvariga åtgärder returnerar *Operation<T> typer.

Metoden WaitForCompletionAsync är ett enkelt sätt att vänta på att åtgärden slutförs och få det resulterande värdet.

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

Mer information om långvariga åtgärder i långvariga åtgärdsexempel

Anpassa begäran med hjälp av RequestContext

Förutom allmän konfiguration av tjänstklienter via ClientOptionskan du anpassa begäranden som skickas av tjänstklienter med hjälp av protokollmetoder eller bekvämlighets-API:er som exponeras RequestContext som en parameter.

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

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

Mer om anpassning av begäran i RequestContext-exempel

Gäckande

En av de viktigaste övergripande funktionerna i våra nya klientbibliotek med Hjälp av Azure.Core är att de är utformade för att håna. Modellering aktiveras av:

• tillhandahålla en skyddad parameterlös konstruktor för klienttyper.
• göra tjänstmetoder virtuella.
• tillhandahåller API:er för att konstruera modelltyper som returneras från virtuella tjänstmetoder. Om du vill hitta de här fabriksmetoderna letar du efter typer med ModelFactory-suffixet, t.ex. . SecretModelFactory

Metoden ConfigurationClient.Get kan till exempel hånas (med Moq) på följande sätt:

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

Mer om att håna i hånexempel

Distribuerad spårning med Application Insights

Funktionen Application Insights i Azure Monitor är en utökningsbar APM-tjänst (Application Performance Management) för utvecklare och DevOps-utvecklare. Använd den för att övervaka dina liveprogram. Den identifierar automatiskt prestandaavvikelser och innehåller kraftfulla analysverktyg som hjälper dig att diagnostisera problem och förstå vad användarna faktiskt gör med din app

Om ditt program redan använder ApplicationInsights stöds automatisk insamling av Azure SDK-spårningar sedan version 2.12.0.

Om du vill konfigurera ApplicationInsights-spårning för ditt program följer du guiden Starta övervakningsprogram .

Mer information om diagnostik i diagnostikexempel.

Felsökning

Tre huvudsakliga sätt att felsöka fel är att inspektera undantag, aktivera loggning och distribuerad spårning

Nästa steg

Utforska och installera tillgängliga Azure SDK-bibliotek.

Bidra

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns på https://cla.microsoft.com.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång i alla lagringsplatser med vår CLA.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Mer information finns i Vanliga frågor och svar om uppförandekod eller kontakt opencode@microsoft.com med ytterligare frågor eller kommentarer.