Condividi tramite

Libreria client condivisa di Azure Core per .NET - versione 1.30.0

  • Articolo

Azure.Core offre primitive, astrazioni e helper condivisi per le librerie client .NET Azure SDK moderne. Queste librerie seguono le linee guida per la progettazione di Azure SDK per .NET e possono essere facilmente identificate dai nomi dei pacchetti e degli spazi dei nomi a partire da 'Azure', ad esempio Azure.Storage.Blobs. Qui è disponibile un elenco più completo delle librerie client con Azure.Core.

Azure.Core consente alle librerie client di esporre funzionalità comuni in modo coerente, in modo che una volta apprese come usare queste API in una libreria client, si saprà come usarli in altre librerie client.

Codice | sorgente Pacchetto (NuGet) | Documentazione di riferimento sulle API

Introduzione

In genere, non sarà necessario installare Azure.Core; verrà installato per l'utente quando si installa una delle librerie client che lo usano. Nel caso in cui si vuole installarlo in modo esplicito (per implementare la propria libreria client, ad esempio), è possibile trovare il pacchetto NuGet qui.

Concetti chiave

I concetti condivisi principali di Azure.Core (e quindi le librerie di Azure SDK con Azure.Core) includono:

  • Configurazione dei client del servizio, ad esempio la configurazione dei tentativi, la registrazione (ClientOptions).
  • Accesso ai dettagli della risposta HTTP (Response, Response<T>).
  • Chiamata di operazioni a esecuzione prolungata (Operation<T>).
  • Paging e flussi asincroni (AsyncPageable<T>).
  • Eccezioni per la segnalazione di errori dalle richieste di servizio in modo coerente. (RequestFailedException).
  • Personalizzazione della richiesta (RequestContext).
  • Astrazioni per rappresentare le credenziali di Azure SDK. (TokenCredentials).

Di seguito sono disponibili sezioni che illustrano questi concetti condivisi in modo più dettagliato.

Thread safety

Si garantisce che tutti i metodi di istanza client siano thread-safe e indipendenti tra loro (linee guida). Ciò garantisce che la raccomandazione di riutilizzare le istanze client sia sempre sicura, anche tra thread.

Concetti aggiuntivi

Opzioni | client Accesso alla risposta | Operazioni | a esecuzione prolungataGestione degli errori | Diagnostica | Beffardo | Durata client

Esempio

NOTA: Gli esempi in questo file si applicano solo ai pacchetti che seguono le linee guida per la progettazione di Azure SDK. I nomi di tali pacchetti iniziano in genere con Azure.

Configurazione dei client di servizio tramite ClientOptions

Le librerie client di Azure SDK in genere espongono uno o più tipi di client di servizio che rappresentano i punti di partenza principali per chiamare i servizi di Azure corrispondenti. È possibile trovare facilmente questi tipi di client come nomi finali con la parola Client. Ad esempio, BlockBlobClient può essere usato per chiamare il servizio di archiviazione BLOB e KeyClient può essere usato per accedere alle chiavi crittografiche del servizio Key Vault.

Questi tipi di client possono essere creata un'istanza chiamando un semplice costruttore o il relativo overload che accetta varie opzioni di configurazione. Queste opzioni vengono passate come parametro che estende ClientOptions la classe esposta da Azure.Core. Diverse opzioni specifiche del servizio vengono in genere aggiunte alle sottoclassi, ma un set di opzioni a livello di SDK è disponibile direttamente in 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);

Altre informazioni sulla configurazione client negli esempi di configurazione client

Accesso ai dettagli della risposta HTTP tramite Response<T>

I client di servizio dispongono di metodi che possono essere usati per chiamare i servizi di Azure. Si fa riferimento a questi metodi del servizio metodi client. I metodi di servizio restituiscono un tipo Response<T> Azure.Core condiviso (in rari casi i relativi fratelli non generici, un oggetto non elaborato Response). Questo tipo fornisce l'accesso sia al risultato deserializzato della chiamata al servizio che ai dettagli della risposta HTTP restituita dal server.

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

Altre informazioni sui tipi di risposta negli esempi di risposta

Configurazione della registrazione della console

Per creare un listener di log di Azure SDK che restituisce messaggi alla console usare AzureEventSourceListener.CreateConsoleLogger il metodo.

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

Altre informazioni sulla registrazione negli esempi di diagnostica

Segnalazione di errori RequestFailedException

Quando una chiamata di servizio non riesce Azure.RequestFailedException viene generata. Il tipo di eccezione fornisce una proprietà Status con codice di stato HTTP e una proprietà ErrorCode con un codice di errore specifico del servizio.

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

Altre informazioni sulla gestione delle risposte negli esempi di risposta

Utilizzo dei metodi di servizio che restituiscono AsyncPageable<T>

Se una chiamata al servizio restituisce più valori nelle pagine, verrà restituita Pageable<T>/AsyncPageable<T> di conseguenza. È possibile eseguire l'iterazione AsyncPageable direttamente o nelle pagine.

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

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

Per altre informazioni sulle risposte impaginate, vedere Paginazione con Azure SDK per .NET.

Utilizzo di operazioni di Long-Running tramite Operation<T>

Alcune operazioni richiedono molto tempo per completare e richiedere il polling per il relativo stato. I metodi che iniziano le operazioni a esecuzione prolungata restituiscono *Operation<T> tipi.

Il WaitForCompletionAsync metodo è un modo semplice per attendere il completamento dell'operazione e ottenere il valore risultante.

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

Altre operazioni a esecuzione prolungata negli esempi di operazioni a esecuzione prolungata

Richiesta personalizzata tramite RequestContext

Oltre alla configurazione generale dei client di servizio tramite ClientOptions, è possibile personalizzare le richieste inviate dai client del servizio usando metodi di protocollo o API pratici che espongono RequestContext come parametro.

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

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

Altre informazioni sulla personalizzazione delle richieste negli esempi RequestContext

Comportamento fittizio

Una delle funzionalità più importanti di taglio incrociato delle nuove librerie client che usano Azure.Core è che sono progettate per la simulazione. La simulazione è abilitata da:

  • fornendo un costruttore senza parametri protetto nei tipi di client.
  • rendere virtuali i metodi di servizio.
  • fornendo API per la creazione di tipi di modello restituiti dai metodi del servizio virtuale. Per trovare questi metodi factory cercare i tipi con il suffisso ModelFactory , ad esempio SecretModelFactory.

Ad esempio, il metodo ConfigurationClient.Get può essere simulato (con Moq) come indicato di seguito:

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

Altre informazioni sulla simulazione di esempi fittizi

Traccia distribuita con Application Insights

Application Insights, una funzionalità di Monitoraggio di Azure, è un servizio di gestione delle prestazioni applicative (APM, Application Performance Management) estendibile per sviluppatori e professionisti DevOps. Può essere utilizzata per monitorare le applicazioni attive. Rileverà automaticamente le anomalie delle prestazioni e include potenti strumenti di analisi che consentono di diagnosticare i problemi e di comprendere cosa fanno effettivamente gli utenti con l'app

Se l'applicazione usa già ApplicationInsights, la raccolta automatica di tracce di Azure SDK è supportata dalla versione 2.12.0.

Per configurare il rilevamento di ApplicationInsights per l'applicazione, seguire la guida Per avviare il monitoraggio dell'applicazione .

Altre informazioni sulla diagnostica negli esempi di diagnostica.

Risoluzione dei problemi

Tre modi principali per la risoluzione dei problemi sono l'ispezione delle eccezioni, l'abilitazione della registrazione e la traccia distribuita

Passaggi successivi

Esplorare e installare le librerie di Azure SDK disponibili.

Contributo

In questo progetto sono benvenuti i contributi e i suggerimenti. Per la maggior parte dei contenuti è necessario sottoscrivere un contratto di licenza di collaborazione (CLA, Contributor License Agreement) che stabilisce che l'utente ha il diritto di concedere, e di fatto concede a Microsoft i diritti d'uso del suo contributo. Per informazioni dettagliate, vedere https://cla.microsoft.com.

Quando si invia una richiesta pull, un bot CLA determina automaticamente se è necessario specificare un contratto CLA e completare la richiesta pull in modo appropriato (ad esempio con un'etichetta e un commento). Seguire le istruzioni specificate dal bot. Questa operazione deve essere eseguita una sola volta in tutti i repository usando l'applicazione cla.

Questo progetto ha adottato il Codice di comportamento di Microsoft per l'open source. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento Open Source di Microsoft) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.

Impression