Bibliothèque de client partagé Azure Core pour .NET - version 1.35.0

  • Article

Azure.Core fournit des primitives, des abstractions et des assistances partagées pour les bibliothèques clientes modernes du SDK Azure .NET. Ces bibliothèques suivent les instructions de conception du Kit de développement logiciel (SDK) Azure pour .NET et peuvent être facilement identifiées par les noms de packages et d’espaces de noms commençant par « Azure », par exemple Azure.Storage.Blobs. Une liste plus complète des bibliothèques clientes utilisant Azure.Core est disponible ici.

Azure.Core permet aux bibliothèques clientes d’exposer les fonctionnalités courantes de manière cohérente, de sorte qu’une fois que vous avez appris à utiliser ces API dans une bibliothèque cliente, vous saurez comment les utiliser dans d’autres bibliothèques clientes.

| Code sourcePackage (NuGet) | Documentation de référence sur les API

Prise en main

En règle générale, vous n’avez pas besoin d’installer Azure.Core ; il sera installé pour vous lorsque vous installez l’une des bibliothèques clientes à l’aide de celle-ci. Si vous souhaitez l’installer explicitement (pour implémenter votre propre bibliothèque cliente, par exemple), vous trouverez le package NuGet ici.

Concepts clés

Les concepts partagés main d’Azure.Core (et donc les bibliothèques de SDK Azure à l’aide d’Azure.Core) sont les suivants :

  • Configuration des clients de service, par exemple la configuration des nouvelles tentatives, la journalisation (ClientOptions).
  • Accès aux détails de la réponse HTTP (Response, Response<T>).
  • Appel d’opérations de longue durée (Operation<T>).
  • Pagination et flux asynchrones (AsyncPageable<T>).
  • Exceptions pour signaler les erreurs des demandes de service de manière cohérente. (RequestFailedException).
  • Personnalisation des demandes (RequestContext).
  • Abstractions pour la représentation des informations d’identification du Kit de développement logiciel (SDK) Azure. (TokenCredentials).

Vous trouverez ci-dessous des sections expliquant ces concepts partagés plus en détail.

Sécurité des threads

Nous garantissons que toutes les méthodes de instance client sont sécurisées pour les threads et indépendantes les unes des autres (recommandations). Cela garantit que la recommandation de réutilisation des instances clientes est toujours sécurisée, même entre les threads.

Concepts supplémentaires

Options clientes | Accès à la réponse | Opérations de longue durée | Gestion des défaillances | Diagnostics | Moqueur | Durée de vie du client

Exemples

NOTE: Les exemples de ce fichier s’appliquent uniquement aux packages qui suivent les instructions de conception du Kit de développement logiciel (SDK) Azure. Les noms de tels packages commencent généralement par Azure.

Configuration des clients de service à l’aide de ClientOptions

Les bibliothèques clientes du Kit de développement logiciel (SDK) Azure exposent généralement un ou plusieurs types de clients de service qui sont les main points de départ pour appeler les services Azure correspondants. Vous pouvez facilement trouver ces types de clients, car leurs noms se terminent par le mot Client. Par exemple, BlockBlobClient peut être utilisé pour appeler le service de stockage d’objets blob et KeyClient peut être utilisé pour accéder à Key Vault clés de chiffrement du service.

Ces types de clients peuvent être instanciés en appelant un constructeur simple, ou sa surcharge qui prend différentes options de configuration. Ces options sont passées en tant que paramètre qui étend la ClientOptions classe exposée par Azure.Core. Différentes options spécifiques au service sont généralement ajoutées à ses sous-classes, mais un ensemble d’options à l’échelle du KIT de développement logiciel (SDK) est disponible directement sur 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);

Plus d’informations sur la configuration du client dans les exemples de configuration client.

Accès aux détails de la réponse HTTP à l’aide de Response<T>

Les clients de service ont des méthodes qui peuvent être utilisées pour appeler les services Azure. Nous faisons référence à ces méthodes de service de méthodes clientes. Les méthodes de service retournent un type Response<T> Azure.Core partagé (dans de rares cas, son frère non générique, un brut Response). Ce type permet d’accéder à la fois au résultat désérialisé de l’appel de service et aux détails de la réponse HTTP retournée à partir du serveur.

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

Plus d’informations sur les types de réponse dans les exemples de réponse.

Configuration de la journalisation de la console

Pour créer un écouteur de journal du Kit de développement logiciel (SDK) Azure qui génère des messages dans la console, utilisez AzureEventSourceListener.CreateConsoleLogger la méthode .

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

Plus d’informations sur la journalisation dans diagnostics exemples.

Signalement d’erreurs RequestFailedException

Lorsqu’un appel de service échoue Azure.RequestFailedException , est levée. Le type d’exception fournit une propriété Status avec un code HTTP status et une propriété ErrorCode avec un code d’erreur spécifique au service.

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

Plus d’informations sur la gestion des réponses dans les exemples de réponse.

Utilisation des méthodes de service retournées AsyncPageable<T>

Si un appel de service retourne plusieurs valeurs dans des pages, il retourne Pageable<T>/AsyncPageable<T> en conséquence. Vous pouvez itérer directement AsyncPageable ou dans des pages.

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

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

Pour plus d’informations sur les réponses paginées, consultez Pagination avec le Kit de développement logiciel (SDK) Azure pour .NET.

Utilisation des opérations Long-Running à l’aide de Operation<T>

Certaines opérations prennent beaucoup de temps et nécessitent un interrogation pour leur status. Les méthodes qui démarrent des opérations de longue durée retournent *Operation<T> des types.

La WaitForCompletionAsync méthode est un moyen simple d’attendre la fin de l’opération et d’obtenir la valeur obtenue.

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

Plus d’informations sur les opérations de longue durée dans les exemples d’opérations à long terme.

Personnalisation des demandes à l’aide de RequestContext

Outre la configuration générale des clients de service via ClientOptions, il est possible de personnaliser les demandes envoyées par les clients de service à l’aide de méthodes de protocole ou d’API pratiques qui s’exposent RequestContext en tant que paramètre.

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

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

Plus d’informations sur la personnalisation des demandes dans les exemples RequestContext.

Simulation

L’une des fonctionnalités les plus importantes de nos nouvelles bibliothèques clientes utilisant Azure.Core est qu’elles sont conçues pour la simulation. La simulation est activée par :

  • fournir un constructeur sans paramètre protégé sur les types de clients.
  • rendre les méthodes de service virtuelles.
  • fournir des API pour construire des types de modèles retournés à partir de méthodes de service virtuel. Pour rechercher ces méthodes de fabrique, recherchez les types avec le suffixe ModelFactory , par exemple SecretModelFactory.

Par exemple, la méthode ConfigurationClient.Get peut être moquée (avec Moq) comme suit :

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

Plus d’informations sur la simulation dans les tests unitaires et la simulation avec le KIT de développement logiciel (SDK) Azure pour .NET.

Suivi distribué avec Application Insights

Application Insights, fonctionnalité d’Azure Monitor, est un service extensible de gestion des performances des applications (APM) destiné aux développeurs et aux professionnels de DevOps. Utilisez-le pour superviser vos applications en temps réel. Il détecte automatiquement les anomalies de performances et inclut de puissants outils d’analyse pour vous aider à diagnostiquer les problèmes et à comprendre ce que les utilisateurs font réellement avec votre application.

Si votre application utilise déjà ApplicationInsights, la collecte automatique des traces du KIT de développement logiciel (SDK) Azure est prise en charge depuis la version 2.12.0.

Pour configurer le suivi ApplicationInsights pour votre application, suivez le guide Démarrer l’analyse de l’application .

Plus d’informations sur diagnostics dans diagnostics exemples.

Dépannage

Trois méthodes main de résolution des défaillances sont l’inspection des exceptions, l’activation dela journalisation et le suivi distribué

Étapes suivantes

Explorez et installez les bibliothèques du Kit de développement logiciel (SDK) Azure disponibles.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous n’aurez besoin de le faire qu’une seule fois sur tous les dépôts à l’aide de notre CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Impressions