Exemplos de API Web (C#)

  • Artigo

 

Publicado: janeiro de 2017

Aplicável a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Este tópico fornece informações sobre os exemplos da API Web implementados com C#. Embora cada exemplo se concentre em um aspecto diferente da API Web do Microsoft Dynamics 365, eles compartilham características e a estrutura semelhantes.

Observação

Esta abordagem de implementação usa a criação de objeto de baixo nível e chamadas de mensagem HTTP explícitas. Esta abordagem permite o controle e a demonstração das propriedades de objeto de baixo nível que controla o comportamento da API Web. Ela se destina a ajudar você a compreender os trabalhos internos, mas não representa necessariamente uma abordagem que fornecerá a melhor experiência de produtividade do desenvolvedor.

Em comparação, as bibliotecas de nível mais alto, como a Biblioteca OData, abstraem muito dessa lógica de cliente de baixo nível. O Modelo T4 OData pode ser opcionalmente usado em conjunto com a Biblioteca OData para gerar classes de entidade de cliente automaticamente.

Neste tópico

Pré-requisitos

Listagem de exemplos da API Web (C#)

Como baixar e executar os exemplos

Elementos comuns encontrados em cada exemplo

Pré-requisitos

O que se segue é necessário para compilar e executar os exemplos em C# da API Web do Dynamics 365:

  • Uma versão do Microsoft Visual Studio 2015 ou posterior. Uma versão gratuita, o Visual Studio Community, está disponível para download aqui.

  • Uma conexão com a Internet para baixar e atualizar os pacotes NuGet referenciados.

  • Acesso ao Dynamics 365 Online ou local (ou posterior). Para todos os tipos de instalação do Dynamics 365, será necessária uma conta de usuário com privilégios para executar operações CRUD.

  • Para executar exemplos no Dynamics 365 (online), você deve registrar seu aplicativo no Azure Active Directory para obter uma ID de cliente e a URL de redirecionamento. Para obter mais informações, consulte Passo a passo: Registrar o aplicativo Dynamics 365 com Ative Directory do Azure.

Listagem de exemplos da API Web (C#)

A tabela a seguir lista os exemplos implementados em C#. Cada exemplo é descrito de uma forma mais geral em um tópico de grupo de exemplos correspondente que se concentra em mensagens de solicitação e de resposta HTTP, como detalhado no tópico Exemplos de API Web.

Amostra

Grupo de exemplo

Descrição

Amostra de operações básicas API da Web (C#)

Amostra de operações básicas API da Web

Demonstra como criar, recuperar, atualizar, excluir, associar e desassociar os registros de entidade do Dynamics 365.

Exemplo de dados de consulta de API da Web (C#)

Exemplo de dados de consulta de API da Web

Demonstra como usar funções e sintaxe de consulta OData v4, bem como funções de consulta do Microsoft Dynamics 365. Inclui exemplos de trabalho com consultas predefinidas e o uso do FetchXML para a execução de consultas.

Amostra de operações de condição API da Web (C#)

Amostra de operações de condição de API da Web

Demonstra como executar operações condicionais especificadas com os critérios de ETag.

Exemplo de funções API da Web e ações (C#)

Exemplo de funções API da Web e ações

Demonstra como usar as funções e as ações associadas e não associadas, incluindo ações personalizadas.

Como baixar e executar os exemplos

O código fonte de cada exemplo está disponível na Galeria de Códigos do MSDN O link para download de cada exemplo está incluído no tópico de exemplo. O download do exemplo é um arquivo .zip compactado, que contém os arquivos de solução do Visual Studio 2015 para o exemplo. Para obter mais informações, consulte a seção Executar este exemplo em cada tópico de exemplo.

Elementos comuns encontrados em cada exemplo

Muitos dos exemplos têm uma estrutura semelhante e contêm métodos e recursos comuns, geralmente para fornecer a infraestrutura básica para um programa C# da API Web.

Vários desses elementos comuns também estão presentes durante a criação de uma nova solução que acessará a API Web do Dynamics 365. Para obter mais informações, consulte Iniciar um projeto de API Web do Dynamics 365 no Visual Studio (C#).

Bibliotecas e estruturas utilizadas

Esta implementação do C# depende do seguinte código auxiliar para comunicação HTTP, configuração do aplicativo, autenticação, manipulação de erros e serialização do JSON.

Biblioteca Json.NET

Como o C# e a maioria das linguagens gerenciadas não dão suporte nativo ao formato de dados JSON, a melhor abordagem atual é usar uma biblioteca para esta funcionalidade. Para obter mais informações, consulte Introdução a JavaScript Object Notation (JSON) em JavaScript e .NET. O Json.NET é uma opção popular para projetos .NET. Ele oferece uma estrutura robusta, com bom desempenho, de software livre (licenciada pelo MIT) para serialização, conversão, análise, consultas e formatação de dados JSON. Para obter mais informações, consulte a documentação do Json.NET.

Nos exemplos do C#, esta biblioteca é principalmente usada para serializar dados entre objetos .NET e corpos de mensagem HTTP. Embora a biblioteca forneça vários métodos para cumprir essa tarefa, a abordagem usada pelos exemplos é criar instâncias individuais de JObject para representar as instâncias de entidade do Dynamics 365 (registros). Por exemplo, o código a seguir cria a variável contact1 que representa uma instância do Dynamics 365 contact EntityType e então fornece valores para um conjunto de propriedades select para esse tipo.

JObject contact1 = new JObject();
contact1.Add("firstname", "Peter");
contact1.Add("lastname", "Cambel");
contact1.Add("annualincome", 80000);
contact1["jobtitle"] = "Junior Developer";

O uso da notação de colchetes na última instrução é equivalente ao método Add. Essa instanciação também poderia ser realizada por meio do uso do método estático Parse:

JObject contact1 = JObject.Parse(@"{firstname: 'Peter', lastname: 'Cambel', "
+ @"annualincome: 80000, jobtitle: 'Junior Developer'}");

Como o JObject representa um tipo JSON geral, seu uso impede a verificação de tipo em tempo de execução. Por exemplo, embora a instrução a seguir seja sintaticamente válida, potencialmente ela levará a erros em tempo de execução porque o contact EntityType não contém uma propriedade age.

contact1.Add("age", 37); //Possible error--no age property exists in contact!

Assim que a variável entity tiver sido inicializada, poderá então ser enviada em um corpo de mensagem, com assistência de várias classes System.Net.Http, por exemplo:

HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, "contacts");
request.Content = new StringContent(contact1.ToString(), Encoding.UTF8, "application/json");
HttpResponseMessage response = await httpClient.SendAsync(request1);

Você também pode criar instâncias de JObject ao desserializar instâncias de entity durante operações de recuperação, por exemplo:

//contact2Uri contains a reference to an existing CRM contact instance.
string queryOptions = "?$select=fullname,annualincome,jobtitle,description";
HttpResponseMessage response = await httpClient.GetAsync(contact2Uri + queryOptions);
JObject contact2 = JsonConvert.DeserializeObject<JObject>(await response.Content.ReadAsStringAsync());

Manipulação de êxito e de erro de resposta

Em geral, os exemplos usam uma abordagem simples para o processamento de respostas HTTP. Se a solicitação for bem-sucedida, as informações sobre a operação normalmente terão o console como saída. Se a resposta também transportar uma carga JSON ou cabeçalhos úteis, essas informações só serão processadas após o êxito. E, pro fim, se uma entidade do Dynamics 365 tiver sido criada, a coleção entityUris será atualizada com o URI desse recurso. O método Método DeleteRequiredRecords usa essa coleção para excluir opcionalmente os dados criados pelo exemplo do seu servidor Dynamics 365.

Se a solicitação tiver falhado, o programa terá como saída uma mensagem contextual sobre a operação que falhou e então lançará uma exceção personalizada do tipo CrmHttpResponseException. O manipulador de exceções tem como saída mais informações sobre a exceção e então o controle passa para um bloco finally que inclui lógica de limpeza, novamente incluindo uma chamada a DeleteRequiredRecords. O código a seguir demonstra essa abordagem de manipulação de erros em uma solicitação POST para criar um registro.

if (response.StatusCode == HttpStatusCode.NoContent)  //204
{
Console.WriteLine("POST succeeded, entity created!”);
//optionally process response message headers or body here, for example:
entityUri = response.Headers.GetValues("OData-EntityId").FirstOrDefault();
entityUris.Add(entityUri);
}
else
{
Console.WriteLine("Operation failed: {0}", response.ReasonPhrase);
throw new CrmHttpResponseException(response.Content);
}

HttpStatusCode.NoContent equivale a um status HTTP código 204, “Nenhum conteúdo”. Aqui, esse código de status indica que a solicitação POST foi bem-sucedida. Para obter mais informações, consulte Redigir solicitações HTTP e manipular erros.

Características e métodos

A maioria dos exemplos tem o mesmo padrão de arquitetura geral, com as seguintes características:

  • Todo o código de exemplo c# pertinente está contido no arquivo de origem principal chamado Program.cs, que contém uma única classe com o mesmo nome do projeto de exemplo.

  • As classes de exemplo, bem como a Use a Microsoft Dynamics 365 Biblioteca Auxiliar da API Web (C#), estão contidas no namespace Microsoft.Crm.Sdk.Samples.

  • Os exemplos estão livremente comentados: são fornecidos resumos nos níveis da classe e do método e a maioria das instruções individuais chave têm comentários na mesma linha ou de linha única associados. Os arquivos suplementares, como o arquivo de configuração do aplicativo App.config, também contêm comentários importantes.

  • A classe de exemplo principal é normalmente estruturada para conter o seguinte conjunto de métodos comum: Método Main, Método ConnectToCRM, Método CreateRequiredRecords, Método RunAsync, Método DisplayException e Método DeleteRequiredRecords.

Método Main

Por definição, esse método inicia a execução do exemplo. Ele só contém lógica de fluxo de controle de alto nível e de manipulação de erros, com frequência este código exato:

static void Main(string[] args)
{
FunctionsAndActions app = new FunctionsAndActions();
try
{
//Read configuration file and connect to specified CRM server.
app.ConnectToCRM(args);
app.CreateRequiredRecords();
Task.WaitAll(Task.Run(async () => await app.RunAsync()));
}
catch (System.Exception ex) { DisplayException(ex);
}
finally
{
if (app.httpClient != null)
{
app.DeleteRequiredRecords(true);
app.httpClient.Dispose();
}
Console.WriteLine("Press <Enter> to exit the program.");
Console.ReadLine();
}
}

Método ConnectToCRM

Esse método chama as bibliotecas auxiliares para ler o arquivo de configuração do aplicativo e então estabelece uma conexão com o servidor do Dynamics 365 especificado. O resultado destas etapas é a inicialização de uma propriedade de classe HttpClient que é usada no programa para enviar solicitações da Web e receber respostas. Observe que as seguintes propriedades estão definidas neste objeto:

//Define the Web API address, the max period of execute time, the Odata
// version, and the expected response payload format.
httpClient.BaseAddress = new Uri(config.ServiceUrl + "api/data/v8.1/");
httpClient.Timeout = new TimeSpan(0, 2, 0);  // 2 minute timeout
httpClient.DefaultRequestHeaders.Add("OData-MaxVersion", "4.0");
httpClient.DefaultRequestHeaders.Add("OData-Version", "4.0");
httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

Para obter mais informações sobre a configuração e a autenticação do aplicativo de exemplo, consulte Use a Microsoft Dynamics 365 Biblioteca Auxiliar da API Web (C#).

Método CreateRequiredRecords

Esse método cria e inicializa registros de entidade exigidos pelo exemplo, somente quando essas operações não forem de interesse principal no exemplo. Por exemplo, o Amostra de operações básicas API da Web (C#) não contém esse método porque a criação de registro é uma das principais considerações do exemplo.

Método RunAsync

Esse método assíncrono contém o código fonte pertinente ou, para programas mais longos, chama métodos que agrupam o código de exemplo pertinente. O código contido é explicado por comentários inseridos e localizados na seção Comentários de cada tópico de exemplo correspondente.

Método DisplayException

Esse método auxiliar exibe informações sobre a exceção, incluindo exceções internas, no console padrão.

Método DeleteRequiredRecords

Esse método auxiliar opcionalmente exclui registros de exemplo e outros recursos de servidor do Dynamics 365 criados no programa e, em particular, pelo método Método CreateRequiredRecords. Ele consulta o usuário em relação à verificação desta operação, então itera na coleção entityUris e tenta excluir cada elemento com uma mensagem HTTP DELETE.

Confira Também

Use a API da Web do Microsoft Dynamics 365
Exemplos de API Web
Exemplos de API da Web (JavaScript do cliente)
Amostra de operações básicas API da Web (C#)
Exemplo de dados de consulta de API da Web (C#)
Amostra de operações de condição API da Web (C#)
Exemplo de funções API da Web e ações (C#)

Microsoft Dynamics 365

© 2017 Microsoft. Todos os direitos reservados. Direitos autorais