Compartir a través de

Biblioteca cliente compartida de Azure Core para .NET: versión 1.35.0

  • Artículo

Azure.Core proporciona primitivos compartidos, abstracciones y asistentes para bibliotecas cliente modernas del SDK de Azure de .NET. Estas bibliotecas siguen las directrices de diseño del SDK de Azure para .NET y se pueden identificar fácilmente mediante nombres de paquetes y espacios de nombres a partir de "Azure", por ejemplo, Azure.Storage.Blobs. Puede encontrar una lista más completa de bibliotecas cliente con Azure.Core aquí.

Azure.Core permite a las bibliotecas cliente exponer funcionalidades comunes de forma coherente, de modo que, una vez que aprenda a usar estas API en una biblioteca cliente, sabrá cómo usarlas en otras bibliotecas cliente.

Código | fuentePaquete (NuGet) | Documentación de referencia de API

Introducción

Normalmente, no es necesario instalar Azure.Core; se instalará automáticamente cuando instale una de las bibliotecas cliente que la use. En caso de que quiera instalarlo explícitamente (para implementar su propia biblioteca cliente, por ejemplo), puede encontrar el paquete NuGet aquí.

Conceptos clave

Los conceptos compartidos principales de Azure.Core (y, por tanto, las bibliotecas del SDK de Azure mediante Azure.Core) incluyen:

  • Configuración de clientes de servicio, por ejemplo, configuración de reintentos, registro (ClientOptions).
  • Acceso a los detalles de respuesta HTTP (Response, Response<T>).
  • Llamar a operaciones de larga duración (Operation<T>).
  • Paginación y secuencias asincrónicas (AsyncPageable<T>).
  • Excepciones para notificar errores de solicitudes de servicio de forma coherente. (RequestFailedException).
  • Personalización de solicitudes (RequestContext).
  • Abstracciones para representar las credenciales del SDK de Azure. (TokenCredentials).

A continuación, encontrará secciones que explican estos conceptos compartidos con más detalle.

Seguridad para subprocesos

Garantizamos que todos los métodos de instancia de cliente son seguros para subprocesos e independientes entre sí (instrucciones). Esto garantiza que la recomendación de reutilizar instancias de cliente siempre es segura, incluso entre subprocesos.

Conceptos adicionales

Opciones | de clienteAcceso a la respuesta | Operaciones | de larga duraciónControl de errores | Diagnóstico | Burla | Duración del cliente

Ejemplos

NOTA: Los ejemplos de este archivo solo se aplican a los paquetes que siguen las directrices de diseño del SDK de Azure. Los nombres de estos paquetes suelen comenzar con Azure.

Configuración de clientes de servicio mediante ClientOptions

Las bibliotecas cliente del SDK de Azure suelen exponer uno o varios tipos de cliente de servicio que son los principales puntos de partida para llamar a los servicios de Azure correspondientes. Puede encontrar fácilmente estos tipos de cliente a medida que sus nombres terminan con la palabra Client. Por ejemplo, BlockBlobClient se puede usar para llamar al servicio blob Storage y KeyClient se puede usar para acceder a Key Vault claves criptográficas del servicio.

Se pueden crear instancias de estos tipos de cliente mediante una llamada a un constructor simple o su sobrecarga que toma varias opciones de configuración. Estas opciones se pasan como un parámetro que extiende la ClientOptions clase expuesta por Azure.Core. Normalmente se agregan varias opciones específicas del servicio a sus subclases, pero hay un conjunto de opciones para todo el SDK disponibles directamente en 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);

Más información sobre la configuración de cliente en los ejemplos de configuración de cliente.

Acceso a los detalles de respuesta HTTP mediante Response<T>

Los clientes de servicio tienen métodos que se pueden usar para llamar a servicios de Azure. Nos referimos a estos métodos de servicio de métodos de cliente. Los métodos de servicio devuelven un tipo Response<T> compartido de Azure.Core (en raras ocasiones, su elemento relacionado no genérico, un sin formato Response). Este tipo proporciona acceso al resultado deserializado de la llamada de servicio y a los detalles de la respuesta HTTP devuelta desde el servidor.

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

Más información sobre los tipos de respuesta en los ejemplos de respuesta.

Configuración del registro de la consola

Para crear un agente de escucha de registro del SDK de Azure que genere mensajes en la consola use el AzureEventSourceListener.CreateConsoleLogger método .

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

Más información sobre el registro en ejemplos de diagnóstico.

Informes de errores RequestFailedException

Cuando se produce un error Azure.RequestFailedException en una llamada de servicio, se produciría una excepción. El tipo de excepción proporciona una propiedad Status con un código de estado HTTP y una propiedad ErrorCode con un código de error específico del servicio.

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

Más información sobre cómo controlar las respuestas en los ejemplos de respuesta.

Consumo de métodos de servicio que devuelven AsyncPageable<T>

Si una llamada de servicio devuelve varios valores en páginas, se devolverá Pageable<T>/AsyncPageable<T> como resultado. Puede iterar AsyncPageable directamente o en páginas.

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

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

Para más información sobre las respuestas paginadas, consulte Paginación con el SDK de Azure para .NET.

Consumo de operaciones de Long-Running mediante Operation<T>

Algunas operaciones tardan mucho tiempo en completarse y requieren sondeos para su estado. Métodos que inician tipos de valor devuelto *Operation<T> de operaciones de ejecución prolongada.

El WaitForCompletionAsync método es una manera sencilla de esperar la finalización de la operación y obtener el valor resultante.

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

Obtenga más información sobre las operaciones de larga duración en ejemplos de operaciones de larga duración.

Personalización de solicitudes mediante RequestContext

Además de la configuración general de los clientes de servicio a través ClientOptionsde , es posible personalizar las solicitudes enviadas por los clientes de servicio mediante métodos de protocolo o API de conveniencia que se exponen RequestContext como parámetro.

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

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

Más información sobre la personalización de solicitudes en ejemplos de RequestContext.

Simulación

Una de las características transversales más importantes de nuestras nuevas bibliotecas cliente con Azure.Core es que están diseñadas para simular. La simulación está habilitada por:

  • proporcionar un constructor sin parámetros protegido en los tipos de cliente.
  • hacer que los métodos de servicio sean virtuales.
  • proporcionar API para construir tipos de modelo devueltos a partir de métodos de servicio virtual. Para buscar estos métodos de fábrica, busque tipos con el sufijo ModelFactory , por ejemplo, SecretModelFactory.

Por ejemplo, el método ConfigurationClient.Get se puede simular (con Moq) como se indica a continuación:

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

Obtenga más información sobre la simulación en Pruebas unitarias y simulación con el SDK de Azure para .NET.

Seguimiento distribuido con Application Insights

Application Insights es una característica de Azure Monitor que es un servicio de Application Performance Management (APM) extensible para desarrolladores y profesionales de DevOps. Úselo para supervisar las aplicaciones en directo. Detectará automáticamente anomalías de rendimiento e incluirá herramientas de análisis eficaces que le ayudarán a diagnosticar problemas y a comprender qué hacen realmente los usuarios con la aplicación.

Si la aplicación ya usa ApplicationInsights, se admite la recopilación automática de seguimientos del SDK de Azure desde la versión 2.12.0.

Para configurar el seguimiento de ApplicationInsights para la aplicación, siga la guía Start Monitoring Application (Iniciar la aplicación de supervisión).

Más información sobre los diagnósticos en los ejemplos de diagnóstico.

Solución de problemas

Tres formas principales de solucionar errores son inspeccionar excepciones, habilitar el registro y el seguimiento distribuido

Pasos siguientes

Explore e instale las bibliotecas disponibles del SDK de Azure.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo tendrá que hacerlo una vez en todos los repositorios mediante nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impresiones