Compartilhar via

Biblioteca de classes WebAPIService (C#)

WebAPIService é um projeto de biblioteca de classes do .NET 6.0 de exemplo que demonstra vários recursos importantes que você deve incluir ao usar a API Web do Dataverse.

Exibir este exemplo no Github

Esta biblioteca demonstra:

  • Gerenciamento dos limites de proteção de serviço do Dataverse com o uso da biblioteca de resiliência e tratamento de falhas transitórias do .NET, Polly.
  • Gerenciando um HttpClient no .NET usando IHttpClientFactory.
  • Usando dados de configuração para gerenciar o comportamento do cliente.
  • Gerenciando erros retornados pela API Web do Dataverse.
  • Um padrão de reutilização de código por:

Observação

Esta biblioteca de exemplo é um auxiliar usado por todos os exemplos de API Web do C# do Dataverse, mas não é um SDK. Ele é testado apenas para confirmar se os exemplos que o usam são executados com êxito. Este código de exemplo é fornecido 'as-is' sem garantia para reutilização.

Esta biblioteca não:

  • Gerenciar a autenticação. Depende de uma função passada de um aplicativo que fornece o token de acesso a ser usado. Todos os exemplos de API Web dependem de uma classe de aplicativo compartilhado que gerencia a autenticação usando a MSAL (Biblioteca de Autenticação da Microsoft). A MSAL dá suporte a vários tipos diferentes de fluxos de autenticação. Esses exemplos usam o fluxo ROPC (nome de usuário/senha) para simplificar, mas esse fluxo não é recomendado. Para seus aplicativos, você deve usar um dos outros fluxos. Mais informações: Suporte ao fluxo de autenticação na Biblioteca de Autenticação da Microsoft.
  • Forneça todos os recursos de geração de código. Todas as classes usadas nos exemplos são escritas manualmente. Todos os dados de entidade de negócios usam o conhecido Json.NET Classe JObject em vez de uma classe que representa o tipo de entidade.
  • Forneça um modelo de objeto para compor consultas OData. Todas as consultas mostram a sintaxe da consulta OData como parâmetros de consulta.

Code

Você pode encontrar o código-fonte da WebApiService biblioteca de classes e a solução do Visual Studio no PowerApps-Samples/dataverse/webapi/C#-NETx/WebAPIService

Lista de classes

As seguintes classes estão incluídas no WebAPIService.

Classe de Serviço

A Service classe fornece métodos para enviar solicitações para o Dataverse por meio de um HttpClient gerenciado usando IHttpClientFactory.

O Service é o componente principal para todos os exemplos, e você pode usá-lo para concluir quaisquer operações demonstradas com o código de exemplo. Tudo o que está incluído no WebAPIService ou em qualquer um dos exemplos que o utilizam proporciona a reutilização de código e permite que as capacidades da API Web do Dataverse sejam demonstradas em um nível mais avançado.

O Service construtor aceita uma instância de classe Config , que contém duas propriedades necessárias: GetAccessToken e Url. Todas as outras propriedades representam opções que têm valores padrão.

O construtor usa a injeção de dependência para criar um IHttpClientFactory que pode retornar um HttpClient nomeado com as propriedades especificadas na função ConfigureHttpClient. Se esse cliente usa cookies ou não é baseado em se o Config.DisableCookies parâmetro está definido. No construtor, a política definida pelo método estático GetRetryPolicy, que controla como são gerenciados os erros transitórios e os limites de proteção do serviço do Dataverse.

Métodos de serviço

A Service classe tem os seguintes métodos:

Método SendAsync

Esse método é, em última análise, responsável por todas as operações.

Este método:

Método SendAsync<T>

Esse método facilita o retorno de uma classe que inclui propriedades encontradas nos ComplexTypes retornados por Ações e Funções do OData na API Web do Dataverse.

O exemplo a seguir mostra o uso com a função 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

Esse método faz a análise do conteúdo de um HttpResponseMessage para um HttpRequestMessage mal-sucedido a fim de retornar um ServiceException. O método SendAsync usa esse método quando a propriedade HttpResponseMessage.IsSuccessStatusCode é falsa. Você também pode usá-lo para extrair informações de erro de instâncias HttpResponseMessage retornadas por BatchResponse.HttpResponseMessages quando a propriedade BatchRequest.ContinueOnError é definida como true. Mais informações: Lote

Propriedades do serviço

O serviço tem uma única propriedade: BaseAddress.

Propriedade BaseAddress

Essa propriedade retorna o conjunto de URL base no Config.Url. Você precisa dessa URL ao instanciar a classe BatchRequest e acrescentar a uma URL relativa sempre que uma URL absoluta for necessária.

Classe Config

A classe Config contém propriedades que controlam o comportamento do aplicativo, conforme mostrado na tabela a seguir:

Propriedade Tipo Description
GetAccessToken Func<Task<string>> Uma função fornecida pelo aplicativo cliente para retornar um token de acesso.
Url string? A URL base do ambiente. Por exemplo: https://org.api.crm.dynamics.com
CallerObjectId Guid O valor SystemUser.ActiveDirectoryGuid para a finalidade de impersonificação. O padrão é Guid.Empty
Mais informações: representar outro usuário usando a API Web
TimeoutInSeconds ushort Quanto tempo aguardar para um timeout. O padrão é 120 segundos.
MaxRetries byte Número máximo de vezes para tentar novamente quando ocorrem limites de proteção de serviço. O padrão é 3.
Version string A versão do serviço a ser usada. O padrão é v9.2
DisableCookies bool Se os cookies devem ser desabilitados para obter desempenho em cenários de carregamento de dados em massa. Mais informações: afinidade de servidor

Classe EntityReference

A EntityReference classe representa uma referência a um registro em uma tabela do Dataverse. O OData identifica recursos com uma URL. EntityReference fornece métodos para facilitar a criação e o acesso de propriedades de URLs.

Construtores de EntityReference

Utilize os construtores a seguir para instanciar um EntityReference.

EntityReference(string nomeDoConjuntoDeEntidades, Guid? Identificador)

Cria uma referência de entidade usando o EntitySetName e um Guid.

EntityReference(string uri)

Analisa uma URL absoluta ou relativa para criar uma referência de entidade, incluindo URLs que usam chaves alternativas.

EntityReference(string setName, Dictionary<string, string>? keyAttributes)

Use esse construtor para instanciar uma referência de entidade usando uma chave alternativa.

Observação

Os valores de chave devem ser valores de cadeia de caracteres. Isso não converte outros tipos em cadeias de caracteres apropriadas.

Propriedades de EntityReference

EntityReference tem as seguintes propriedades públicas:

Propriedade Tipo Description
Id Guid? O valor da chave primária do registro ao não usar uma chave alternativa.
KeyAttributes Dictionary<string, string> Os valores de cadeia de caracteres que representam valores de chave alternativos usados em uma URL.
SetName string O EntitySetName do tipo de entidade.
Path string Uma URL relativa para o registro.

Métodos de EntityReference

EntityReference tem os seguintes métodos públicos. Nenhum deles exige parâmetros.

Nome do método Tipo de retorno Description
AsODataId string Retorna uma cadeia de caracteres formatada para uso como referência de parâmetro a um registro na URL de uma Função OData.
AsJObject JObject Retorna um JObject que pode ser usado como uma referência de parâmetro a um registro em uma Ação OData.

Classes de erro

ODataError, Errore ODataException são classes usadas para desserializar erros retornados pelo serviço. Você não precisa trabalhar com eles diretamente.

Exceção de serviço

ServiceException é uma classe exception que contém propriedades do erro retornado pelo serviço. Use o Método ParseError para obter uma instância dessa exceção.

Extensions

WebApiService tem um método de extensão de um tipo .NET.

HttpResponseMessage Como<T>

Essa extensão cria uma instância de T onde T é derivada de HttpResponseMessage e copia as propriedades de HttpResponseMessage para a classe derivada. O Servicemétodo SendAsync<T> usa esse método, mas também pode ser usado separadamente. Por exemplo, ao usar a classe BatchRequest , os itens no BatchResponse.HttpResponseMessages são HttpResponseMessage tipos. Você pode usar essa extensão para convertê-las na classe derivada apropriada para facilitar o acesso a quaisquer propriedades.

Messages

A Messages pasta inclui classes que herdam de HttpRequestMessage ou HttpResponseMessage.

Essas classes fornecem definições reutilizáveis de solicitações e respostas que correspondem às operações OData que você pode usar em qualquer ambiente do Dataverse.

Essas classes também fornecem exemplos de operações específicas que podem ser aplicadas usando HttpRequestMessage e HttpResponseMessage sem derivar desses tipos.

Em um aplicativo, você também pode criar mensagens personalizadas, por exemplo, representando uma API personalizada em seu ambiente, usando o mesmo padrão. Essas são classes modulares e não precisam ser incluídas na WebAPIService.Messages pasta.

Por exemplo, o Exemplo de Ações e Funções da API Web (C#) usa uma API personalizada que não está incluída no Dataverse até que uma solução que contenha a API personalizada seja instalada. A definição das classes correspondentes para usar essa mensagem está localizada no aplicativo de exemplo que a usa:

*Classes de solicitação

Essas classes geralmente têm um construtor com parâmetros que instanciam um HttpRequestMessage com os dados necessários para executar a operação. Eles podem ter propriedades separadas conforme apropriado.

O exemplo mais simples desse padrão é a WhoAmIRequest classe.

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

Os nomes dessas classes geralmente se alinham com as classes no Namespace Microsoft.Xrm.Sdk.Messages do SDK do Dataverse, mas não se limitam a essas operações. A API Web fornece para executar algumas operações que não podem ser feitas com o SDK, por exemplo CreateRetrieveRequest , é a mensagem que cria um registro e o recupera. O SDK do Dataverse não fornece essa funcionalidade em uma única solicitação.

*Classes de resposta

Quando *Classes de solicitação retornam um valor, há uma classe *Response correspondente para acessar as propriedades retornadas. Se a solicitação *retornar 204 No Content, a operação retornará um HttpResponseMessage , mas não haverá classe derivada. Use o método SendAsync para enviar essas solicitações.

As classes de resposta fornecem propriedades tipadas que acessam as propriedades HttpResponseMessage, Headers ou Content e as analisam para fornecer acesso ao Tipo Complexo retornado pela operação.

A WhoAmIResponse classe é um exemplo. Nessa classe, você pode encontrar todo o código necessário para extrair as propriedades do 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));
    }
}

Essas classes só podem ser instanciadas corretamente quando retornadas pelo Método SendAsync<T> ou usando a extensão HttpResponseMessage As<T> em uma HttpResponseMessage propriedade BatchResponse.HttpResponseMessages.

Lote

A Batch pasta contém três classes para gerenciar o envio de solicitações OData $batch . Mais informações: executar operações em lote usando a API Web.

BatchRequest

O BatchRequest construtor inicializa um HttpRequestMessage que pode ser usado com o SendAsync<T> Método para enviar solicitações em lotes. O construtor requer que o Service.BaseAddress valor seja passado como um parâmetro.

BatchRequest tem as propriedades a seguir.

Propriedade Tipo Description
ContinueOnError Bool Controla se a operação em lote deve continuar quando ocorrer um erro.
ChangeSets List<ChangeSet> Um ou mais conjuntos de alterações a serem incluídos no lote.
Requests List<HttpRequestMessage> Um ou mais HttpMessageRequest devem ser enviados para fora de qualquer ChangeSet.

Quando ChangeSets ou Requests são definidos, eles são encapsulados em HttpMessageContent e adicionados Content à solicitação. O método privado ToMessageContent aplica as alterações necessárias aos cabeçalhos e retorna HttpMessageContent para as propriedades ChangeSets e Requests.

ChangeSet

Um conjunto de alterações representa um grupo de solicitações que devem ser concluídas em uma transação.

Ele contém uma única propriedade:

Propriedade Tipo Description
Requests List<HttpRequestMessage> Um ou mais HttpMessageRequest a serem executados dentro da transação.

Resposta em lote

BatchResponse tem uma única propriedade:

Propriedade Tipo Description
HttpResponseMessages List<HttpResponseMessage> As respostas da operação $batch.

BatchResponse tem um método privado ParseMultipartContent usado pelo método getter da propriedade HttpResponseMessages para analisar o MultipartContent retornado, dividindo-o em HttpResponseMessage individuais.

Para acessar as propriedades de tipo das HttpResponseMessage instâncias retornadas, você pode usar o método de extensão HttpResponseMessage As<T> .

Methods

Para operações que são executadas com frequência, a Methods pasta contém extensões da Service classe. Esses métodos permitem usar as classes *Request correspondentes em uma única linha.

Os seguintes métodos estão incluídos:

Método Tipo de retorno Description
Create Task<EntityReference> Cria um novo registro.
CreateRetrieve Task<JObject> Cria um novo registro e o recupera.
Delete Task Exclui um registro.
FetchXml Task<FetchXmlResponse> Recupera os resultados de uma consulta FetchXml. A solicitação é enviada com POST utilizando $batch para mitigar problemas em que URLs longas enviadas com GET podem exceder os limites.
GetColumnValue<T> Task<T> Recupera um valor de coluna única de uma linha de tabela.
Retrieve Task<JObject> Recupera um registro.
RetrieveMultiple Task<RetrieveMultipleResponse> Recupera vários registros.
SetColumnValue<T> Task Define o valor de uma coluna para uma linha de tabela.
Update Task Atualiza um registro.
Upsert Task<UpsertResponse> Executa a operação Upsert em um registro.

Em um aplicativo de exemplo usando WebAPIService, quando a operação não representa uma API encontrada no Dataverse por padrão, o método é definido no aplicativo em vez de no WebAPIService.

Por exemplo, o Exemplo de Ações e Funções da API Web (C#) usa uma API personalizada que não está incluída no Dataverse até que uma solução que contenha a API personalizada seja instalada. A definição desse método está localizada no aplicativo de exemplo que o usa: FunctionsAndActions/Methods/IsSystemAdmin.cs

Tipos

A Types pasta contém classes ou enums que correspondem a ComplexTypes ou EnumTypes necessários como parâmetros ou propriedades de resposta para mensagens.

Metadados

A pasta Metadata contém Messages e Types específicas para operações que funcionam com definições de esquema do Dataverse. Essas classes frequentemente têm muitas propriedades que retornam tipos complexos. Esses tipos são usados no exemplo de operações de esquema de tabela da API Web (C#).

Consulte também

Exemplo de operações básicas da API Web (C#)
Exemplo de Dados de Consulta da API Web (C#)
Exemplo de Operações Condicionais da API Web (C#)
Exemplo de ações e funções da API Web (C#)
Exemplo de operações de esquema de tabela de API Web (C#)
Exemplo de operações paralelas de WebApiService da API Web (C#)
Exemplo de operações paralelas da API Web com componentes de fluxo de dados TPL (C#)

  • Last updated on