Delen via

Gedeelde Azure Core-clientbibliotheek voor .NET - versie 1.30.0

  • Artikel

Azure.Core biedt gedeelde primitieven, abstracties en helpers voor moderne .NET Azure SDK-clientbibliotheken. Deze bibliotheken volgen de Azure SDK-ontwerprichtlijnen voor .NET en kunnen gemakkelijk worden geïdentificeerd aan pakket- en naamruimtennamen die beginnen met 'Azure', bijvoorbeeld Azure.Storage.Blobs. Een meer volledige lijst met clientbibliotheken die gebruikmaken van Azure.Core vindt u hier.

Met Azure.Core kunnen clientbibliotheken algemene functionaliteit op een consistente manier beschikbaar maken, zodat u weet hoe u deze API's in één clientbibliotheek kunt gebruiken in andere clientbibliotheken.

Broncode | Pakket (NuGet) | API-referentiedocumentatie

Aan de slag

Normaal gesproken hoeft u Azure.Core niet te installeren; het wordt voor u geïnstalleerd wanneer u een van de clientbibliotheken installeert die er gebruik van maken. Als u het expliciet wilt installeren (bijvoorbeeld om uw eigen clientbibliotheek te implementeren), kunt u het NuGet-pakket hier vinden.

Belangrijkste concepten

De belangrijkste gedeelde concepten van Azure.Core (en dus Azure SDK-bibliotheken met Behulp van Azure.Core) zijn:

  • Serviceclients configureren, bijvoorbeeld nieuwe pogingen configureren, logboekregistratie (ClientOptions).
  • Http-antwoorddetails openen (Response, Response<T>).
  • Langlopende bewerkingen aanroepen (Operation<T>).
  • Paging en asynchrone stromen (AsyncPageable<T>).
  • Uitzonderingen voor het rapporteren van fouten van serviceaanvragen op een consistente manier. (RequestFailedException).
  • Aanvraag aanpassen (RequestContext).
  • Abstracties voor het vertegenwoordigen van Azure SDK-referenties. (TokenCredentials).

Hieronder vindt u secties waarin deze gedeelde concepten gedetailleerder worden uitgelegd.

Veiligheid van schroefdraad

We garanderen dat alle clientexemplaarmethoden thread-veilig en onafhankelijk van elkaar zijn (richtlijn). Dit zorgt ervoor dat de aanbeveling om clientexemplaren opnieuw te gebruiken altijd veilig is, zelfs voor alle threads.

Aanvullende concepten

Clientopties | Toegang tot het antwoord | Langlopende bewerkingen | Afhandeling van fouten | Diagnostics | Spottende | Clientlevensduur

Voorbeelden

OPMERKING: Voorbeelden in dit bestand zijn alleen van toepassing op pakketten die voldoen aan de ontwerprichtlijnen voor Azure SDK. Namen van dergelijke pakketten beginnen meestal met Azure.

Serviceclients configureren met behulp van ClientOptions

Azure SDK-clientbibliotheken bieden doorgaans een of meer serviceclienttypen die de belangrijkste uitgangspunten zijn voor het aanroepen van bijbehorende Azure-services. U kunt deze clienttypen gemakkelijk vinden, omdat hun namen eindigen met het woord Client. Kan bijvoorbeeld BlockBlobClient worden gebruikt om de blobopslagservice aan te roepen en KeyClient kan worden gebruikt voor toegang tot cryptografische sleutels van Key Vault service.

Deze clienttypen kunnen worden geïnstantieerd door een eenvoudige constructor aan te roepen, of de overbelasting die verschillende configuratieopties nodig heeft. Deze opties worden doorgegeven als een parameter die de klasse uitbreidt ClientOptions die beschikbaar wordt gesteld door Azure.Core. Verschillende servicespecifieke opties worden meestal toegevoegd aan de subklassen, maar een set SDK-brede opties is rechtstreeks beschikbaar op 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);

Meer informatie over clientconfiguratie in voorbeelden van clientconfiguraties

Http-antwoorddetails openen met behulp van Response<T>

Serviceclients hebben methoden die kunnen worden gebruikt om Azure-services aan te roepen. We verwijzen naar deze servicemethoden voor clientmethoden. Servicemethoden retourneren een gedeeld Azure.Core-type Response<T> (in zeldzame gevallen is het niet-generieke type, een onbewerkt Response). Dit type biedt toegang tot zowel het gedeserialiseerde resultaat van de serviceaanroep als tot de details van het HTTP-antwoord dat van de server wordt geretourneerd.

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

Meer informatie over antwoordtypen in antwoordvoorbeelden

Consolelogboekregistratie instellen

Gebruik de methode om een Azure SDK-logboeklistener te maken waarmee berichten worden verzonden naar de console AzureEventSourceListener.CreateConsoleLogger .

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

Meer informatie over logboekregistratie in diagnostische voorbeelden

Fouten rapporteren RequestFailedException

Wanneer een service-aanroep mislukt Azure.RequestFailedException , wordt deze gegenereerd. Het uitzonderingstype biedt een eigenschap Status met een HTTP-statuscode en een eigenschap ErrorCode met een servicespecifieke foutcode.

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

Meer informatie over het verwerken van antwoorden in antwoordvoorbeelden

Servicemethoden gebruiken die worden geretourneerd AsyncPageable<T>

Als een serviceoproep meerdere waarden op pagina's retourneert, zou deze als resultaat worden geretourneerd Pageable<T>/AsyncPageable<T> . U kunt deze rechtstreeks of in pagina's herhalen AsyncPageable .

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

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

Zie Paginering met de Azure SDK voor .NET voor meer informatie over gepagineerde antwoorden.

Gebruik van Long-Running bewerkingen met Operation<T>

Sommige bewerkingen duren lang en vereisen polling voor hun status. Methoden die langlopende bewerkingen starten, retourneren *Operation<T> typen.

De WaitForCompletionAsync methode is een eenvoudige manier om te wachten tot de bewerking is voltooid en de resulterende waarde op te halen.

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

Meer informatie over langlopende bewerkingen in voorbeelden van langlopende bewerkingen

Aanvraag aanpassen met behulp van RequestContext

Naast de algemene configuratie van serviceclients via ClientOptions, is het mogelijk om de aanvragen aan te passen die door serviceclients worden verzonden met behulp van protocolmethoden of gemaks-API's die als parameter worden weergegeven RequestContext .

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

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

Meer informatie over aanpassing van aanvragen in RequestContext-voorbeelden

Spottende

Een van de belangrijkste kruislingse functies van onze nieuwe clientbibliotheken met Behulp van Azure.Core is dat ze zijn ontworpen om te worden gesimuleerd. Mocking wordt ingeschakeld door:

  • het leveren van een beveiligde parameterloze constructor op clienttypen.
  • servicemethoden virtueel maken.
  • API's bieden voor het samenstellen van modeltypen die worden geretourneerd door virtuele servicemethoden. Als u deze factory-methoden wilt vinden, zoekt u naar typen met het achtervoegsel ModelFactory , bijvoorbeeld SecretModelFactory.

De methode ConfigurationClient.Get kan bijvoorbeeld als volgt worden gesimuleerd (met Moq):

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

Meer informatie over mocking in mocking samples

Gedistribueerde tracering met Application Insights

Application Insights, een functie van Azure Monitor, is een flexibele APM-service (Application Performance Management) voor ontwikkelaars en DevOps-professionals. Hiermee kunt u uw livetoepassingen controleren. Het detecteert automatisch prestatieafwijkingen en bevat krachtige analysehulpprogramma's om u te helpen bij het diagnosticeren van problemen en om inzicht te krijgen in wat gebruikers daadwerkelijk met uw app doen

Als uw toepassing al ApplicationInsights gebruikt, wordt het automatisch verzamelen van Azure SDK-traceringen ondersteund sinds versie 2.12.0.

Als u ApplicationInsights-tracering voor uw toepassing wilt instellen, volgt u de handleiding Toepassing voor bewaking starten .

Meer informatie over diagnostische gegevens in diagnostische voorbeelden.

Problemen oplossen

Drie belangrijke manieren om fouten op te lossen zijn het inspecteren van uitzonderingen, het inschakelen van logboekregistratie en gedistribueerde tracering

Volgende stappen

Verken en installeer beschikbare Azure SDK-bibliotheken.

Bijdragen

Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga naar https://cla.microsoft.com voor meer informatie.

Wanneer u een pull-aanvraag indient, wordt met een CLA-bot automatisch bepaald of u een CLA moet verschaffen en wordt de pull-aanvraag dienovereenkomstig opgemaakt (bijvoorbeeld met een label of commentaar). Volg gewoon de instructies van de bot. U hoeft dit maar één keer te doen voor alle opslagplaatsen met behulp van onze CLA.

Op dit project is de Microsoft Open Source Code of Conduct (Microsoft Open Source-gedragscode) van toepassing. Zie voor meer informatie de veelgestelde vragen over de gedragscode of neem contact op opencode@microsoft.com met eventuele aanvullende vragen of opmerkingen.

Weergaven