Início rápido: exemplo de API Web (C#)

Neste início rápido, você cria um aplicativo de console que se conecta ao seu ambiente do Microsoft Dataverse e invoca uma função simples. Depois de entender a funcionalidade básica descrita aqui, você poderá explorar outras operações de API Web, como criar, recuperar, atualizar e excluir linhas de tabela do Dataverse.

Este programa autentica e usa um HttpClient para enviar uma solicitação GET para a Função WhoAmI. Essa função recupera informações sobre o usuário conectado do Dataverse. A resposta é um WhoAmIResponse ComplexType. O programa exibe o valor da propriedade UserId obtido da resposta.

Você pode encontrar a solução completa do Visual Studio para este projeto do .NET 10 no repositório PowerApps-Samples em dataverse/webapi/C#-NETx/QuickStart.

Pré-requisitos

• Visual Studio 2026 ou posterior
• Conexão com a Internet
• Conta de usuário válida para um ambiente do Dataverse
• Url para o ambiente do Dataverse com o qual você deseja se conectar
• Compreensão básica da linguagem C#

Criar projeto do Visual Studio

1. Inicie o Visual Studio 2026 e selecione Criar um novo projeto.

   

2. Crie um novo projeto de Aplicativo de Console .

   

3. Configure o projeto definindo um nome de Local e Projeto.

   

4. Configure o projeto selecionando o .NET 10.0 (Suporte de Longo Prazo) e não use instruções de nível superior. Em seguida, selecione Criar.

   

5. No Gerenciador de Soluções, clique com o botão direito do mouse no projeto criado e selecione Gerenciar Pacotes NuGet... no menu de contexto. O NuGet permite que você traga assemblies necessários para seu projeto.

6. Procure o pacote NuGet da MSAL (Biblioteca de Autenticação da Microsoft) nomeado Microsoft.Identity.Client, selecione-o e, em seguida, escolha Instalar.

   

   Observação

   Você será solicitado a aceitar os termos de licença antes de instalar. Selecione Aceito na caixa de diálogo Aceitação da Licença.

Editar Program.cs

Siga estas próximas etapas para adicionar código ao programa principal.

1. Substitua todo o conteúdo de Program.cs pelo seguinte código.

   using Microsoft.Identity.Client;  // Microsoft Authentication Library (MSAL)
   using System;
   using System.Net.Http;
   using System.Net.Http.Headers;
   using System.Text.Json;
   using System.Threading.Tasks;
   
   namespace PowerApps.Samples
   {
      /// <summary>
      /// Demonstrates Azure authentication and execution of a Dataverse Web API function.
      /// </summary>
      class Program
      {
         static async Task Main()
         {
               // TODO Specify the Dataverse environment name to connect with.
               // See https://learn.microsoft.com/power-apps/developer/data-platform/webapi/compose-http-requests-handle-errors#web-api-url-and-versions
               string resource = "https://<env-name>.api.<region>.dynamics.com";
   
               // Microsoft Entra ID app registration shared by all Power App samples.
               var clientId = "51f81489-12ee-4a9e-aaae-a2591f45987d";
               var redirectUri = "http://localhost"; // Loopback for the interactive login.
   
               // For your custom apps, you will need to register them with Microsoft Entra ID yourself.
               // See https://docs.microsoft.com/powerapps/developer/data-platform/walkthrough-register-app-azure-active-directory
   
               #region Authentication
   
               var authBuilder = PublicClientApplicationBuilder.Create(clientId)
                              .WithAuthority(AadAuthorityAudience.AzureAdMultipleOrgs)
                              .WithRedirectUri(redirectUri)
                              .Build();
               var scope = resource + "/user_impersonation";
               string[] scopes = { scope };
   
               AuthenticationResult token =
                  await authBuilder.AcquireTokenInteractive(scopes).ExecuteAsync();
               #endregion Authentication
   
               #region Client configuration
   
               var client = new HttpClient
               {
                  // See https://docs.microsoft.com/powerapps/developer/data-platform/webapi/compose-http-requests-handle-errors#web-api-url-and-versions
                  BaseAddress = new Uri(resource + "/api/data/v9.2/"),
                  Timeout = new TimeSpan(0, 2, 0)    // Standard two minute timeout on web service calls.
               };
   
               // Default headers for each Web API call.
               // See https://docs.microsoft.com/powerapps/developer/data-platform/webapi/compose-http-requests-handle-errors#http-headers
               HttpRequestHeaders headers = client.DefaultRequestHeaders;
               headers.Authorization = new AuthenticationHeaderValue("Bearer", token.AccessToken);
               headers.Add("OData-MaxVersion", "4.0");
               headers.Add("OData-Version", "4.0");
               headers.Accept.Add(
                  new MediaTypeWithQualityHeaderValue("application/json"));
               #endregion Client configuration
   
               #region Web API call
   
               // Invoke the Web API 'WhoAmI' unbound function.
               // See https://docs.microsoft.com/powerapps/developer/data-platform/webapi/compose-http-requests-handle-errors
               // See https://docs.microsoft.com/powerapps/developer/data-platform/webapi/use-web-api-functions#unbound-functions
               var response = await client.GetAsync("WhoAmI");
   
               if (response.IsSuccessStatusCode)
               {
                  // Parse the JSON formatted service response (WhoAmIResponse) to obtain the user ID value.
                  // See https://learn.microsoft.com/power-apps/developer/data-platform/webapi/reference/whoamiresponse
                  Guid userId = new();
   
                  string jsonContent = await response.Content.ReadAsStringAsync();
   
                  // Using System.Text.Json
                  using (JsonDocument doc = JsonDocument.Parse(jsonContent))
                  {
                     JsonElement root = doc.RootElement;
                     JsonElement userIdElement = root.GetProperty("UserId");
                     userId = userIdElement.GetGuid();
                  }
   
                  // Alternate code, but requires that the WhoAmIResponse class be defined (see below).
                  // WhoAmIResponse whoAmIresponse = JsonSerializer.Deserialize<WhoAmIResponse>(jsonContent);
                  // userId = whoAmIresponse.UserId;
   
                  Console.WriteLine($"Your user ID is {userId}");
               }
               else
               {
                  Console.WriteLine("Web API call failed");
                  Console.WriteLine("Reason: " + response.ReasonPhrase);
               }
               #endregion Web API call
         }
      }
   
      /// <summary>
      /// WhoAmIResponse class definition 
      /// </summary>
      /// <remarks>To be used for JSON deserialization.</remarks>
      /// <see cref="https://learn.microsoft.com/power-apps/developer/data-platform/webapi/reference/whoamiresponse"/>
      public class WhoAmIResponse
      {
         public Guid BusinessUnitId { get; set; }
         public Guid UserId { get; set; }
         public Guid OrganizationId { get; set; }
      }
   }
   

2. Logo abaixo do comentário TODO no código anterior, substitua o valor da resource variável pela URL real do ambiente de teste do Dataverse. Para localizar o valor da URL para seu ambiente de teste, siga estas etapas:

   1. Vá para Power Apps.
   2. Selecione o ícone de ambientes (à direita do campo de pesquisa) e escolha um ambiente de teste.
   3. Selecione o do ícone de configurações. E escolha recursos do Desenvolvedor.
   4. Copie a URL do ponto de extremidade da API Web de https: a .com sem o final /api/data/v9.2.
   5. Substitua o valor da cadeia de caracteres de recurso no código do programa pelo valor da URL do ponto de extremidade. Por exemplo:

      string resource = "https://contoso.api.crm.dynamics.com";

Executar o programa

1. Pressione F5 para compilar e executar o programa.

   Uma janela do navegador é aberta e solicita que você escolha uma conta. Escolha a conta que você usa para acessar seu ambiente do Dataverse. Se essa conta não aparecer na lista, selecione Usar outra conta.

   Depois de selecionar a conta, insira sua senha e selecione Entrar.

2. Examine a janela do aplicativo de console. A saída deve ser semelhante a esta:

   Your user ID is 22cc22cc-dd33-ee44-ff55-66aa66aa66aa
   
   C:\projects\webapi-quickstart\bin\Debug\net10.0\webapi-quickstart.exe (process 21524) exited with code 0.
   To automatically close the console when debugging stops, enable Tools->Options->Debugging->Automatically close the console when debugging stops.
   Press any key to close this window . . .
   

Parabéns!

Você se conectou à API Web.

Este exemplo de início rápido mostra uma abordagem simples para criar um projeto do Visual Studio sem qualquer tratamento de exceção ou método para atualizar o token de acesso. Essa abordagem é suficiente para verificar se você pode se conectar e tentar operações diferentes.

Código de exemplo do .NET

Para obter um exemplo mais completo que demonstra os padrões de design recomendados, consulte a biblioteca de classes WebAPIService (C#). Ele demonstra:

• Gerenciando os limites da API de proteção de serviço do Dataverse com a biblioteca de resiliência do .NET e tratamento de falhas transitórias 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:
  • Criando classes que herdam de HttpRequestMessage e HttpResponseMessage.
  • Métodos que usam essas classes.
  • Um padrão modular para adicionar novos recursos conforme necessário. The [Web API Data operations Samples (C#)](web-api-samples-csharp.md) use theBiblioteca de classes do WebAPIService.

Próximas Etapas 

Tente criar um aplicativo Web.

Saiba mais sobre os recursos da API Web do Dataverse compreendendo os documentos de serviço.

Saiba mais sobre os recursos da API Web do Dataverse executando e estudando o código de exemplo.