Biblioteca de clases WebAPIService (C#)

WebAPIService es un proyecto de biblioteca de clases de ejemplo .NET 6.0 que muestra varias funcionalidades importantes que debe incluir al usar la API web de Dataverse.

Esta biblioteca demuestra:

• Administración de los límites de protección del servicio Dataverse con la biblioteca de resistencia .NET y control de errores transitorios Polly.
• Administrar un HttpClient en .NET con IHttpClientFactory.
• Usar datos de configuración para gestionar el comportamiento del cliente.
• Administrar los errores devueltos por la API web de Dataverse.
• Un patrón de reutilización de código mediante:
  • Creando clases que heredan de HttpRequestMessage y HttpResponseMessage.
  • Métodos que usan esas clases.
  • Un patrón modular para agregar nuevas capacidades según sea necesario.

Esta biblioteca no:

• Administrar la autenticación. Depende de una función pasada desde una aplicación que proporciona el token de acceso para usar. Todos los ejemplos de API web dependen de una clase App compartida que administra la autenticación mediante el Biblioteca de autenticación de Microsoft (MSAL). MSAL admite varios tipos diferentes de flujos de autenticación. Estos ejemplos usan el flujo Nombre de usuario/contraseña (ROPC) por simplicidad, pero no se recomienda este flujo. Para sus aplicaciones, debe usar uno de los otros flujos. Más información: compatibilidad con el flujo de autenticación en la Biblioteca de autenticación de Microsoft.
• Proporcionar cualquier capacidad de generación de código. Todas las clases utilizadas en las muestras están escritas a mano. Todos los datos de entidad empresarial usan el conocido Json.NET JObject Class en lugar de una clase que representa el tipo de entidad.
• Proporcionar un modelo de objetos para componer consultas de OData. Todas las consultas muestran la sintaxis de consulta de OData como parámetros de consulta.

Código

Puede encontrar el código fuente de la biblioteca de clases WebApiService y la solución Visual Studio en PowerApps-Samples/dataverse/webapi/C#-NETx/WebAPIService

Lista de clases

En se incluyen las siguientes clases.

Clase Service

La clase proporciona métodos para enviar solicitudes a Dataverse a través de un HttpClient administrado usando IHttpClientFactory.

El es el componente principal de todos los ejemplos y puede usarlo para completar cualquier operación demostrada con código de muestra. Todo lo demás que esté incluido en el o cualquiera de las muestras que lo utilizan proporciona la reutilización del código y permite las capacidades de la API web de Dataverse que se demostrará en un nivel superior.

El constructor acepta una instancia de clase Config que contiene dos propiedades requeridas: y . Todas las demás propiedades representan opciones que tienen valores predeterminados.

El constructor utiliza la inyección de dependencia para crear un que puede devolver un con nombre con las propiedades especificadas en la función . El hecho de que este cliente utilice o no cookies se basa en si el parámetro está configurado. En el constructor la directiva definida por el método estático que controla cómo se gestionan los errores transitorios y los límites de protección de servicio de Dataverse.

Métodos de servicio

La clase tiene los métodos siguientes:

Método SendAsync

Este método es el responsable final de todas las operaciones.

Este método:

• Tiene un parámetro HttpRequestMessage.
• Devuelve
• Expone la misma firma que el método HttpClient.SendAsync(HttpRequestMessage) y se puede usar de la misma manera.
• Llama a la función configurada en el método para establecer el valor de encabezado para la solicitud.
• Utiliza el método IHttpClientFactory.CreateClient para obtener el con nombre para enviar la solicitud.
• Lanza un ServiceException si la propiedad HttpResponseMessage.IsSuccessStatusCode es falsa, por lo que no es necesario comprobar el al utilizar este método.

Método SendAsyncT

Este método facilita la devolución de una clase que incluye propiedades que se encuentran en los ComplexTypes devueltos por acciones y funciones de OData en la API web de Dataverse.

• Tiene un parámetro HttpRequestMessage. Cuando se usa este método se espera, pero no se requiere, que el parámetro de solicitud sea una de las *clases de respuesta que se derivan de .
• Devuelve donde es una clase derivada de . Para obtener más información, consulte *Clases de respuesta.
• Llama al método SendAsync.
• Utiliza el método de extensión HttpResponseMessage AsT para devolver el tipo solicitado.

En el siguiente ejemplo se muestra cómo usar la función WhoAmI.

static async Task WhoAmI(Service service)
{
   var response = await service.SendAsync<WhoAmIResponse>(new WhoAmIRequest());

   Console.WriteLine($"Your user ID is {response.UserId}");
}

Método ParseError

Este método analiza el contenido de un por un fracaso de para devolver un ServiceException. El método SendAsync utiliza este método cuando la propiedad HttpResponseMessage.IsSuccessStatusCode es falsa. También se puede usar para extraer información de error de las instancias devueltas de por cuando la propiedad se establece en true. Más información: Batch

Propiedades del servicio

Service tiene una sola propiedad: .

Propiedad BaseAddress

Esta propiedad devuelve la URL base establecida en . Necesita esta URL al crear una instancia de la clase BatchRequest y para anexar a una URL relativa cada vez que se requiera una URL absoluta.

Clase Config

La clase Config contiene propiedades que controlan el comportamiento de la aplicación como se muestra en la siguiente tabla:

Clase EntityReference

La clase representa una referencia a un registro en una tabla de Dataverse. OData identifica recursos con una URL. proporciona métodos para facilitar la creación y el acceso a las propiedades de las URL.

Constructores de EntityReference

Utilice los siguientes constructores para instanciar una .

EntityReference(string entitySetName, Guid? Id)

Crea una referencia de entidad usando y .

EntityReference(URI de cadena)

Analiza una URL absoluta o relativa para crear una referencia de entidad, incluidas las URL que usan claves alternativas.

EntityReference(string setName, Dictionarystring, string? keyAttributes)

Use este constructor para instanciar una referencia de entidad usando un clave alternativa.

Propiedades de EntityReference

tiene las siguientes propiedades públicas:

Métodos EntityReference

tiene los siguientes métodos públicos: Ninguno de ellos requiere ningún parámetro.

Clases de errores

, y son clases utilizadas para deserializar errores devueltos por el servicio. No es necesario trabajar con ellos directamente.

ServiceException

ServiceException es una clase de excepción que contiene propiedades del error devuelto por el servicio. Utilice el método ParseError para obtener una instancia de esta excepción.

Extensiones

WebApiService tiene un método de extensión de un tipo de .NET.

HttpResponseMessage comoT

Esta extensión crea una instancia de dónde se deriva de HttpResponseMessage y copia las propiedades de en la clase derivada. El método SendAsyncT utiliza este método, pero también se puede utilizar por separado. Por ejemplo, cuando se utiliza la clase BatchRequest, los elementos del son tipos . Puede usar esta extensión para convertirlos a la clase derivada apropiada para facilitar el acceso a cualquier propiedad.

Mensajes

La carpeta incluye clases que heredan de HttpRequestMessage o HttpResponseMessage.

Estas clases proporcionan definiciones reutilizables de solicitudes y respuestas que corresponden a operaciones de OData que puede usar en cualquier entorno de Dataverse.

Estas clases también proporcionan ejemplos de operaciones específicas que se pueden aplicar usando y sin derivar de esos tipos.

Dentro de una aplicación, también puede crear mensajes personalizados, por ejemplo, representando una API personalizada en su entorno, utilizando el mismo patrón. Estas son clases modulares y no es necesario incluirlas en la carpeta .

Por ejemplo, el ejemplo de acciones y funciones de API web (C#) utiliza una API personalizada que no está incluida en Dataverse hasta que se instale una solución que contenga la API personalizada. La definición de las clases correspondientes para usar este mensaje se encuentra en la aplicación de muestra que lo usa:

• FunctionsAndActions/Messages/IsSystemAdminRequest.cs
• FunctionsAndActions/Messages/IsSystemAdminResponse.cs

Clases *Request

Estas clases generalmente tienen un constructor con parámetros que crea una instancia de un HttpRequestMessage con los datos necesarios para realizar la operación. Pueden tener propiedades separadas según corresponda.

El ejemplo más simple de este patrón es la clase .

namespace PowerApps.Samples.Messages
{
    /// <summary>
    /// Contains the data to perform the WhoAmI function
    /// </summary>
    public sealed class WhoAmIRequest : HttpRequestMessage
    {
        /// <summary>
        /// Initializes the WhoAmIRequest
        /// </summary>
        public WhoAmIRequest()
        {
            Method = HttpMethod.Get;
            RequestUri = new Uri(
                uriString: "WhoAmI", 
                uriKind: UriKind.Relative);
        }
    }
}

Por lo general, los nombres de estas clases se alinean con las clases en el espacio de nombres Microsoft.Xrm.Sdk.Messages del SDK de Dataverse, pero no se limitan a esas operaciones. La API web permite realizar algunas operaciones que no se pueden realizar con el SDK, por ejemplo es un mensaje que crea un registro y lo recupera. El SDK de Dataverse no proporciona esta capacidad en una sola solicitud.

Clases *Response

Cuando las clases *Request devuelven un valor, hay una clase *Response correspondiente para acceder a las propiedades devueltas. Si *Request devuelve , la operación devuelve un HttpResponseMessage, pero no hay ninguna clase derivada. Utilice el método SendAsync para enviar estas solicitudes.

Las clases *Response proporcionan propiedades con tipo que acceden a las propiedades o y las analiza para proporcionar acceso al tipo complejo devuelto por la operación.

La clase es un ejemplo. Dentro de esta clase se puede encontrar todo el código necesario para extraer las propiedades del ComplexType WhoAmIResponse.

using Newtonsoft.Json.Linq;

namespace PowerApps.Samples.Messages
{
    // This class must be instantiated by either:
    // - The Service.SendAsync<T> method
    // - The HttpResponseMessage.As<T> extension in Extensions.cs

    /// <summary>
    /// Contains the response from the WhoAmIRequest
    /// </summary>
    public sealed class WhoAmIResponse : HttpResponseMessage
    {

        // Cache the async content
        private string? _content;

        //Provides JObject for property getters
        private JObject _jObject
        {
            get
            {
                _content ??= Content.ReadAsStringAsync().GetAwaiter().GetResult();

                return JObject.Parse(_content);
            }
        }

        /// <summary>
        /// Gets the ID of the business to which the logged on user belongs.
        /// </summary>
        public Guid BusinessUnitId => (Guid)_jObject.GetValue(nameof(BusinessUnitId));

        /// <summary>
        /// Gets ID of the user who is logged on.
        /// </summary>
        public Guid UserId => (Guid)_jObject.GetValue(nameof(UserId));

        /// <summary>
        /// Gets ID of the organization that the user belongs to.
        /// </summary>
        public Guid OrganizationId => (Guid)_jObject.GetValue(nameof(OrganizationId));
    }
}

Estas clases solo se pueden crear instancias correctamente cuando las devuelve el Método SendAsyncT o mediante la extensión HttpResponseMessage AsT en un en la propiedad .

Lote

La carpeta contiene tres clases para gestionar el envío de solicitudes OData $. Más información:Ejecute las operaciones por lotes mediante API web

BatchRequest

El constructor inicializa un que se puede usar con el método SendAsyncT para enviar solicitudes en lotes. El constructor requiere que se pase el valor como parámetro.

tiene las siguientes propiedades.

Cuando o están configurados, están encapsulados en HttpMessageContent y se añaden al de la solicitud. El método privado aplica los cambios requeridos a los encabezados y devuelve el para las propiedades y .

ChangeSet

Un conjunto de cambios representa un grupo de solicitudes que deben completarse dentro de una transacción.

Contiene una sola propiedad:

BatchResponse

tiene una sola propiedad:

tiene un método privado utilizado por el captador de la propiedad para analizar el devuelto al individual.

Para acceder a las propiedades de tipo de las instancias de devueltas, puede usar el método de extensión HttpResponseMessage AsT.

Métodos

Para las operaciones que se realizan con frecuencia, la carpeta contiene extensiones de la clase . Estos métodos permiten utilizar las clases *Request correspondientes en una sola línea.

Se incluyen los siguientes métodos:

Dentro de una aplicación de ejemplo que utiliza , cuando la operación no representa una API que se encuentra en Dataverse de forma predeterminada, el método se define en la aplicación en lugar de en .

Por ejemplo, el ejemplo de acciones y funciones de API web (C#) utiliza una API personalizada que no está incluida en Dataverse hasta que se instale una solución que contenga la API personalizada. La definición de este método se encuentra en la aplicación de muestra que lo utiliza: FunctionsAndActions/Methods/IsSystemAdmin.cs

Tipos

La carpeta contiene las clases o enumeraciones que corresponden a ComplexTypes o EnumTypes necesarias como parámetros o propiedades de respuesta para los mensajes.

Metadata

La carpeta contiene y específicos para operaciones que trabajan con definiciones de esquemas de Dataverse. Estas clases suelen tener muchas propiedades que devuelven tipos complejos. Estos tipos se utilizan en el ejemplo de operaciones de esquema de tabla de API web (C#).

Vea también

Ejemplo de operaciones básicas de la API web (C#)
Ejemplo de datos de consulta de API web (C#)
Ejemplo de operaciones condicionales de la API web (C#)
Ejemplo de funciones y acciones de la API web (C#)
Ejemplo de operaciones de esquema de tabla de API web (C#)
Ejemplo de operaciones en paralelo de la API web WebApiService (C#)
Ejemplo de operaciones paralelas de API web con componentes de flujo de datos TPL (C#)