Iniciar um projeto de API Web do Dynamics 365 no Visual Studio (C#)

Artigo
04/18/2017

Publicado: janeiro de 2017

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

Este tópico demonstra como criar um novo projeto no Microsoft Visual Studio para compilar um aplicativo de console que use a API Web do Dynamics 365. Ele ilustra os recursos de projeto e as referências comuns que a maioria dos aplicativos, incluindo os exemplos do SDK para C#, usam para implementar soluções com base em API Web.

Pré-requisitos

Os seguintes pré-requisitos são necessários para compilar os aplicativos de console descritos nesta seção.

O Microsoft Visual Studio 2015 é instalado em seu computador de desenvolvimento. Qualquer edição, incluindo o Visual Studio Express, deve ser suficiente para trabalhar com a API Web do Dynamics 365. Para obter mais informações sobre que versões do Microsoft Visual Studio são compatíveis, consulte Visual Studio e o .NET Framework.
Um cliente NuGet deve estar instalado: o utilitário de linha de comando ou a extensão do Visual Studio. Para obter mais informações, consulte Instalando o NuGet.
É necessário ter uma conexão à Internet para baixar o pacote do NuGet que contém a Biblioteca Auxiliar da API Web do Dynamics 365 e outros pacotes dependentes.
Você também pode baixá-lo SDK do Microsoft Dynamics 365aqui. Embora não seja necessário ter o SDK do Microsoft Dynamics 365 para compilar ou executar os exemplos da API Web, a maioria dos desenvolvedores Dynamics 365 irá querer instalá-lo porque ele contém um conjunto avançado de recursos suplementares. Além disso, o SDK é necessário para acessar outras interfaces do Dynamics 365.

Criar um projeto

O procedimento a seguir demonstra como criar um projeto de aplicativo de console na linguagem C# que usa o Microsoft .NET Framework. Para obter mais informações sobre as versões com suporte do .NET Framework, consulte Extensões suportadas para o Microsoft Dynamics 365.

Novo projeto

No Microsoft Visual Studio, clique em Novo Projeto. A caixa de diálogo Novo Projeto é exibida.
No painel de navegação esquerdo, em Modelos, selecione Visual C#.
Na lista de modelos disponíveis, selecione .NET Framework 4.5.2.
Na lista de modelos, selecione Aplicativo de console. (Você também pode escolher o tipo de projeto adequado à sua solução.) Todos os exemplos em linguagem C# de API Web são aplicativos de console.
Nas caixas de texto próximas à parte inferior do formulário, forneça o nome e a localização do projeto e selecione OK. (Neste tópico, nome de solução “StartWebAPI- CS“ é usado.) Os arquivos de solução iniciais serão gerados e a solução será carregada no Microsoft Visual Studio.
No menu Projeto, abra o formulário de propriedades do projeto e verifique se a estrutura de destino para está definida como .NET Framework 4.5.2.

Adicionar todos os recursos necessários ao projeto

Os procedimentos a seguir explicam como adicionar todos os pacotes e referências gerenciados necessários ao projeto. Considere isso um conjunto base de recursos que a maioria dos aplicativos de código gerenciado precisará para invocar operações de API Web.

Adicionar o pacote NuGet da biblioteca auxiliar

A Biblioteca Auxiliar da API Web do SDK do Dynamics 365 contém classes que ajudam nas operações suplementares, como a configuração de aplicativos, a autenticação do servidor Dynamics 365, o tratamento de exceções e as comunicações Web. Para obter mais informações, consulte Use a Microsoft Dynamics 365 Biblioteca Auxiliar da API Web (C#). O uso dessas classes é opcional, embora elas sejam usadas de forma extensiva nos exemplos de API Web. A Biblioteca Auxiliar da API Web do SDK do Dynamics 365 é distribuída no formato de código-fonte no formulário como um pacote do NuGet. As atualizações futuras serão distribuídas como atualizações dos pacotes do NuGet.

Se você instalou o utilitário de linha de comando do NuGet ou está usando o Console do Gerenciador de Pacotes do Visual Studio:

Use o comando a seguir para instalar o pacote da biblioteca auxiliar.

Install-Package Microsoft.CrmSdk.WebApi.Samples.HelperCode
Diversas mensagens são exibidas sobre o processamento dos pacotes de dependência. Se uma caixa de diálogo Aceitação de Licença for exibida, leia os termos da licença e clique Aceitar.
Passe a etapa 6 abaixo para confirmar a instalação do pacote da biblioteca auxiliar.

Se você tiver instalado a extensão do Gerenciador de Pacotes do NuGet:

No menu Projetos , selecione Gerenciar Pacotes do NuGet. A guia Gerenciador de Pacotes do NuGet será exibida.
No canto superior direito, defina o menu suspenso de origem Pacote como Nuget.org.
No canto superior esquerdo, clique em Procurar e digite “Dynamics 365 HelperCode” na caixa de pesquisa e pressione Enter.
Clique em Instalar. Se a caixa de diálogo Visualizar for exibida, clique em OK.
A caixa de diálogo Aceitação de Licenciamento será exibida. Leia os termos da licença e clique Aceito.
Navegue até a janela Gerenciador de Soluções. Confirme se uma nova pasta de solução chamada Código Auxiliar da API Web foi adicionada.

O pacote da Biblioteca Auxiliar da API Web do SDK do Dynamics 365, Microsoft.CrmSdk.WebApi.Samples.HelperCode, depende dos seguintes pacotes, que serão baixados e instalados automaticamente junto com o pacote da biblioteca auxiliar:

Newtonsoft.Json – contém Json.NET, um framework JSON popular licenciados pelo MIT para .NET.
Microsoft.IdentityModel.Clients.ActiveDirectory – contém os binários da Biblioteca de Autenticação do Active Directory (ADAL), que fornece funcionalidade de autenticação para clientes .NET.

Aviso

O pacote da Biblioteca Auxiliar da API Web do SDK do Dynamics 365 foi compilado em relação a versões desses dois pacotes de suporte. Por isso, você deve atualizar diretamente o pacote da biblioteca auxiliar do NuGet. Essa operação atualizará os pacotes de suporte apropriados se necessário. Quando você atualiza um desses pacotes de suporte separadamente, a versão mais recente do pacote pode ser incompatível com a biblioteca auxiliar.

Verificar as referências necessárias do assembly

No Gerenciador de Soluções, expanda o nó Referências .
Confirme se as referências a seguir foram adicionadas ao projeto.
Se você tiver a funcionalidade adicional que usa rotineiramente nos aplicativos, poderá adicionar as referências associadas aos assemblies necessários agora. Para obter mais informações, consulte Como adicionar ou remover referências usando a caixa de diálogo Adicionar Referência.

Como a API Web do Dynamics 365 é baseada em princípios REST, ela não requer o acesso dos assemblies cliente. Contudo, outras APIs compatíveis com o Microsoft Dynamics 365 exigem isso; para obter mais informações, consulte Assemblies incluídos no Microsoft Dynamics 365 SDK.

Adicionar instruções típicas

No Gerenciador de Soluções, abra Program.cs para editá-lo.
Na parte superior do arquivo, adicione as instruções using a seguir, que fazem referência a namespaces comumente usados nas soluções baseadas em API Web do Dynamics 365.
```
using Microsoft.Crm.Sdk.Samples.HelperCode;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
```
Se você tiver adicionado referências ou assemblies usados rotineiramente nas seções anteriores, talvez também queira adicionar instruções using correspondentes a esses recursos.
Salve o arquivo.

Adicionar código de conexão

Esta seção explica como adicionar um conjunto básico de configurações e instruções para executar essas operações. Para obter mais informações sobre o código comum usado, consulte Use a Microsoft Dynamics 365 Biblioteca Auxiliar da API Web (C#).

Editar o arquivo de configuração do aplicativo

No Gerenciador de Soluções, abra o arquivo App.config para editá-lo. Adicione as duas seções a seguir a ele, depois da seção <startup> e salve o arquivo.

<connectionStrings>
    <clear />

    <!-- When providing a password, make sure to set the app.config file's security so that only you can read it. -->
    <add name="default"   connectionString="Url=http://myserver/myorg/; Username=name; Password=password; Domain=domain" />
    <add name="CrmOnline" connectionString="Url=https://mydomain.crm.dynamics.com/; Username=someone@mydomain.onmicrosoft.com; Password=password" />
  </connectionStrings>

  <appSettings>
    <!--For information on how to register an app and obtain the ClientId and RedirectUrl
        values see https://msdn.microsoft.com/dynamics/crm/mt149065 -->
    <!--Active Directory application registration. -->
    <!--These are dummy values and should be replaced with your actual app registration values.-->
    <add key="ClientId" value="e5cf0024-a66a-4f16-85ce-99ba97a24bb2" />
    <add key="RedirectUrl" value="https://localhost/SdkSample" />

    <!-- Use an alternate configuration file for connection string and setting values. This optional setting
    enables use of an app.config file shared among multiple applications. If the specified file does
    not exist, this setting is ignored.-->
    <add key="AlternateConfig" value="C:\Temp\crmsample.exe.config"/>
  </appSettings>

Ao desenvolver ou implantar uma solução, a conexão e os valores de registro de aplicativo reais devem ser substituídos por valores de espaço reservado de exemplo. Para obter mais informações, consulte Código auxiliar de API da Web: Classes de configuração.

Adicionar código para chamar a biblioteca auxiliar

Edite o arquivo de Program.cs.
Adicione a propriedade a seguir à classe Program. Essa propriedade será inicializada depois que uma conexão for concluída com êxito com o servidor do Dynamics 365.

private HttpClient httpClient;

No método Main, adicione as instruções a seguir.

Program app = new Program();
try
{
    String[] arguments = Environment.GetCommandLineArgs();
    app.ConnectToCRM(arguments);
}
catch (System.Exception ex)
{ ; }
finally
{
    if (app.httpClient != null)
    { app.httpClient.Dispose(); }
}

Em seguida, adicione o método ConnectToCRM, que usa a as classes Configuration e Authentication da biblioteca auxiliar. O código a seguir demonstra valores de atribuição das propriedades HttpClient para que você possa acessar a versão de lançamento da API Web do Dynamics 365.

private void ConnectToCRM(String[] cmdargs)
{
    Configuration config = null;
    if (cmdargs.Length > 0)
        config = new FileConfiguration(cmdargs[0]);
    else
        config = new FileConfiguration(null);
    Authentication auth = new Authentication(config);
    httpClient = new HttpClient(auth.ClientHandler, true);
    httpClient.BaseAddress = new Uri(config.ServiceUrl + "api/data/v8.1/");
    httpClient.Timeout = new TimeSpan(0, 2, 0);
    httpClient.DefaultRequestHeaders.Add("OData-MaxVersion", "4.0");
    httpClient.DefaultRequestHeaders.Add("OData-Version", "4.0");
    httpClient.DefaultRequestHeaders.Accept.Add(
        new MediaTypeWithQualityHeaderValue("application/json"));
}

Adicionar código de tratamento de erro

As alterações a seguir adicionam código para capturar e relatar exceções, incluindo erros de API Web, ao console. Se você estiver se direcionando a um ambiente diferente, modifique o código de tratamento de exceções de forma apropriada para aquele ambiente.

Em Main, adicione a instrução a seguir ao bloco catch.

DisplayException(ex);

Adicione o método correspondente à classe Program.

private static void DisplayException(Exception ex)
{
    Console.WriteLine("The application terminated with an error.");
    Console.WriteLine(ex.Message);
    while (ex.InnerException != null)
    {
        Console.WriteLine("\t* {0}", ex.InnerException.Message);
        ex = ex.InnerException;
    }
}

Salve os arquivos na solução.

Próximas etapas

Neste ponto, a solução pode ser compilada sem erros. Se você editar o arquivo de configuração do aplicativo para fornecer valores para Servidor do Microsoft Dynamics 365, o programa também deverá se conectar com êxito ao servidor. A solução representa um quadro de esboço que está pronto para aceitar o código personalizado, incluindo chamadas à API Web do Dynamics 365.

Dica

Antes de sair deste tópico, considere salvar o projeto como um modelo de projeto. Você pode reutilizar esse modelo para projetos de aprendizado futuros e economizar tempo e esforço na configuração de novos projetos. Para fazer isso, enquanto o projeto está aberto no Microsoft Visual Studio, no menu Arquivo, selecione Exportar modelo. Siga as instruções do Assistente de Exportação de Modelo para criar o modelo.

Confira Também

Introdução à API Web do Microsoft Dynamics 365 (C#)
Use a Microsoft Dynamics 365 Biblioteca Auxiliar da API Web (C#)
Executar operações usando A API

Microsoft Dynamics 365

Compartilhar via