Démarrage rapide : exemple de l’API Web (C#)

Dans ce démarrage rapide, vous allez créer une application console simple pour vous connecter à votre environnement Microsoft Dataverse cible et invoquer la fonction WhoAmI Function de l’API web. Cette fonction récupère des informations sur les personnes connectées en tant qu’utilisateur Dataverse. Une fois que vous avez compris les fonctionnalités de base décrites ici, vous pouvez passer à d’autres opérations de l’API Web telles que la création, la récupération, la mise à jour et la suppression des lignes de table Dataverse.

Ce programme authentifiera et utilisera un HttpClient pour envoyer une demande GET à la fonction WhoAmI. La réponse sera un ComplexType WhoAmIResponse. Le programme affichera alors la valeur de propriété UserId obtenue à partir de la réponse.

Vous pouvez trouver la solution Visual Studio complète pour ce projet .NET 6 dans le référentiel PowerApps-Samples sous dataverse/webapi/C#-NETx/QuickStart. Il existe également une version .NET Framework de l’exemple sous cds/webapi/dataverse/webapi/C#-QuickStart.

Conditions préalables

• Visual Studio 2022 ou version ultérieure
• Connexion Internet
• Compte d’utilisateur valide pour un environnement Dataverse
• URL vers l’environnement Dataverse auquel vous souhaitez vous connecter
• Présentation de base du langage C#

Créer un projet Visual Studio

1. Lancez Visual Studio 2022 et sélectionnez Créer un nouveau projet.

   

2. Créez un nouveau projet Console App.

   

3. Configurez le projet en définissant un Emplacement et un Nom de projet.

   

4. Configurez le projet en sélectionnant .NET 6.0 (support à long terme) et Ne pas utiliser d’instructions de niveau supérieur. Cliquez ensuite sur Créer.

   

5. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet que vous avez créé, puis sélectionnez Gérer les packages NuGet… dans le menu contextuel. NuGet vous permet d’intégrer les assemblages requis dans votre projet.

6. Recherchez le package NuGet de la bibliothèque d’authentification Microsoft (MSAL) appelée Microsoft.Identity.Client , sélectionnez-le, puis choisissez Installer.

   

   Notes

   Vous serez invité à accepter les termes de la licence avant l’installation. Cliquez sur J’accepte dans la boîte de dialogue Acceptation de la licence.

Modifiez Program.cs

Suivez ces étapes pour ajouter du code au programme principal.

1. Remplacez tout le contenu de Program.cs par le code suivant.

   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://video2.skills-academy.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://video2.skills-academy.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://video2.skills-academy.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. Juste en dessous du commentaire TODO dans le code ci-dessus, remplacez la valeur de la variable resource avec l’URL réelle de votre environnement de test Dataverse. Pour trouver la valeur de l’URL de votre environnement de test, procédez comme suit :

   1. Accédez à Power Apps à l’aide de votre navigateur.
   2. Sélectionnez l’icône des environnements (à droite du champ de recherche) et choisissez un environnement de test.
   3. Sélectionnez l’icône des paramètres et choisissez Ressources de développeur.
   4. Copiez l’URL du point de terminaison de l’API web https: via .com en laissant de côté la fin /api/data/v9.2.
   5. Remplacez la valeur de chaîne de ressource dans le code du programme par cette valeur d’URL de point de terminaison. Par exemple :

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

Exécuter le programme

1. Appuyez sur F5 pour générer et exécuter le programme.

   Une fenêtre de navigateur s’ouvrira et vous invitera à choisir un compte. Choisissez le compte que vous utilisez pour accéder à votre environnement Dataverse. Si ce compte n’apparaît pas dans la liste, cliquez sur Utiliser un autre compte.

   Une fois le compte sélectionné, entrez votre mot de passe et cliquez sur Se connecter.

2. Regardez la fenêtre de l’application console. Le résultat doit ressembler à ce qui suit :

   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 . . .
   

Félicitations !

Vous vous êtes connecté(e) avec succès à l’API Web.

L’exemple de démarrage rapide affiche une approche simple pour créer un projet Visual Studio sans traitement ou méthode d’exception pour actualiser le jeton d’accès. Cela suffit pour vérifier que vous pouvez vous connecter et essayer différentes opérations.

Pour un exemple plus complet qui illustre les modèles de conception recommandés, consultez la bibliothèque de classes WebAPIService (C#). C’est le projet que nous utilisons pour nos Exemples d’opérations de données d’API Web (C#). Cela montre ce qui suit :

• Gérer Dataverse limites des API de protection des services avec la bibliothèque de résilience .NET et de gestion des erreurs transitoires Polly.
• Gestion d’un HttpClient dans .NET en utilisant IHttpClientFactory.
• Utiliser les données de configuration pour gérer le comportement du client.
• Gestion des erreurs renvoyées par l’API web Dataverse.
• Un modèle de réutilisation du code en :
  • Créant des classes qui proviennent de HttpRequestMessage et HttpResponseMessage.
  • Méthodes qui utilisent ces classes.
  • Un modèle modulaire pour ajouter de nouvelles fonctionnalités selon les besoins.

Étapes suivantes

Essayez de créer une application web.

En savoir plus sur les fonctionnalités de l’API web Dataverse en comprenant les documents de service.