Tutorial: Ejemplo de API Web (C#)

Artículo
11/16/2023

En este inicio rápido, creará una aplicación de consola simple para conectarse a su entorno de Microsoft Dataverse e invocar la función de API web función WhoAmI. Esta función recupera información sobre los usuarios registrados en Dataverse. Una vez que comprenda la funcionalidad básica que se describe aquí, puede pasar a otras operaciones de API web, como crear, recuperar, actualizar y eliminar filas de tablas de Dataverse.

Este programa autenticará y usará un HttpClient para enviar una solicitud GET a la función WhoAmI. La respuesta será un WhoAmIResponse ComplexType. A continuación, el programa mostrará valor de propiedad UserId obtenido de la respuesta.

Nota

Esto es un ejemplo muy sencillo para mostrar cómo estar conectado con un mínimo de código.

Puede encontrar la solución completa de Visual Studio para este proyecto de .NET 6 en el repositorio PowerApps-Samples de dataverse/webapi/C#-NETx/QuickStart. También hay una versión .NET Framework del ejemplo en dataverse/webapi/C#/QuickStart.

Requisitos previos

Visual Studio 2022 o posterior
Conexión a Internet
Cuenta de usuario válida para un entorno de Dataverse
Dirección URL al entorno de Dataverse con el que quiere conectarse
Comprensión básica de lenguaje C#

Nota

Para autenticarse debe tener una aplicación registrada en Microsoft Entra ID. Este ejemplo de tutorial proporciona un valor clientid de registro de la aplicación que puede usar con el fin de ejecutar el código de instalación publicado por Microsoft. Sin embargo, para sus propias aplicaciones personalizadas, debe registrar sus aplicaciones con AD. Más información: Tutorial: Registrar una aplicación con Microsoft Entra ID

Crear proyecto de Visual Studio

Inicie Visual Studio 2022 y seleccione Crear un nuevo proyecto.
Crear un nuevo proyecto de aplicación de aplicación de consola.
Configure el proyecto estableciendo una Ubicación y un Nombre de proyecto.
Configure el proyecto seleccionando .NET 6.0 (Soporte a largo plazo) y No usar declaraciones de nivel superior. A continuación, haga clic en Crear.
En el Explorador de soluciones haga clic con el botón secundario en el proyecto que ha creado y seleccione Administrar paquetes de NuGet... en el menú contextual. NuGet le permite incluir los ensamblajes necesarios en su proyecto.
Busque el paquete Microsoft Authentication Library (MSAL) NuGet con el nombre Microsoft.Identity.Client, selecciónelo y, luego, elija Instalar.

Nota

Se le pedirá que acepte los términos de la licencia antes de la instalación. Haga clic en Acepto en el diálogo Aceptación de licencia.

Edite Program.cs

Siga los próximos pasos para agregar código para el programa principal.

Reemplace el contenido completo de Program.cs con el siguiente 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; }
   }
}

Directamente debajo del comentario TODO en el código anterior, reemplace el valor variable de resource con la URL real de su entorno de prueba de Dataverse. Para encontrar el valor de URL para su entorno de prueba, siga estos pasos:
1. En su navegador, vaya a Power Apps.
2. Seleccione el icono de entornos (a la derecha del campo de búsqueda) y elija un entorno de prueba.
3. Seleccione el icono de configuración y elija Herramientas y recursos de desarrollo.
4. Copie la URL del punto de conexión de la API web desde "https:" hasta ".com" dejando el final /api/data/v9.2.
5. Reemplace el valor de la cadena de recursos en el código del programa con ese valor de URL del punto de conexión. Por ejemplo:
  string resource = "https://contoso.api.crm.dynamics.com";

Ejecutar el programa

Presione F5 para crear y ejecutar el programa.

Se abrirá una ventana del navegador y le pedirá que elija una cuenta. Elija la cuenta que utiliza para acceder a su entorno Dataverse . Si esa cuenta no aparece en la lista, haga clic en Usar otra cuenta.

Una vez seleccionada la cuenta, introduzca su contraseña y haga clic en iniciar sesión.

Mire la ventana de la aplicación de la consola. El resultado deberá ser ahora similar a esto:

Your user ID is 4026be43-6b69-e111-8f65-78e7d1620f5e

C:\Projects\webapi-quickstart\bin\Debug\net6.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 . . .

Enhorabuena.

Se ha conectado con éxito a la API web.

El ejemplo de inicio rápido muestra un enfoque básico para crear un proyecto de Visual Studio sin ningún control de las excepciones o sin método para actualizar el token de acceso. Esto es suficiente para verificar que puede conectarse y probar diferentes operaciones.

Para ver un ejemplo más completo que demuestre los patrones de diseño recomendados, revise la Biblioteca de clases WebAPIService (C#). Este es el proyecto que usamos para nuestros Ejemplos de operaciones de datos de la API web (C#). Demuestra:

Administrar los límites de la API de protección del servicio de Dataverse con la resiliencia de .NET y la biblioteca de manejo de fallas transitorias Polly.
Administrar un HttpClient en .NET usando IHttpClientFactory.
Usar datos de configuración para gestionar el comportamiento del cliente.
Gestionar 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.

Pasos siguientes

Pruebe a crear una aplicación web.

Inicio rápido: muestra de API web de Blazor Server (C#)

Aprender más acerca de las Capacidades de API web de Dataverse mediante la comprensión de los documentos de servicio.

Tipos y operaciones de API web

Nota

¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)

La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).

Tutorial: Ejemplo de API Web (C#)

Requisitos previos

Crear proyecto de Visual Studio

Edite Program.cs

Ejecutar el programa

Enhorabuena.

Pasos siguientes

Comentarios

Recursos adicionales