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

Article
04/26/2022
3 minutes de lecture

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 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 à WhoAmI Function la réponse sera WhoAmIResponse ComplexType. Le programme affichera alors la valeur de propriété UserId obtenue à partir de la réponse.

Notes

Il s’agit d’un exemple très simple expliquant comment se connecter avec un minimum de code. Le Démarrage rapide amélioré s'appuiera sur cet exemple pour appliquer de meilleurs modèles de conception.

Vous pouvez trouver l'intégralité de la solution Visual Studio pour ce projet (.NET Framework) dans le référentiel PowerApps-Exemples sous cds/webapi/C#/QuickStart. Il existe également une version .NET 5 de l'exemple sous cds/webapi/C#-NETx/Démarrage rapide.

Conditions préalables

Visual Studio 2019
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 Visual C #

Notes

Pour vous authentifier, vous devez avoir une application enregistrée dans Azure Active Directory (AD). Cet exemple de démarrage rapide fournit une valeur clientid d’enregistrement d’application que vous pouvez utiliser pour exécuter un exemple de code publié par Microsoft. Cependant, pour vos propres applications personnalisées, vous devez enregistrer vos applications auprès d'AD. Pour plus d’informations : Guide pas-à-pas : Enregistrer une application avec Azure Active Directory

Créer un projet Visual Studio

Lancez Visual Studio et sélectionnez Créer un nouveau projet.
Créez un nouveau projet d'application console (.NET Framework).
Configurez le projet pour utiliser .NET Framework 4.6.2.
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. Nous allons maintenant apporter les assemblages requis pour notre projet.
Recherchez le package NuGet Microsoft.IdentityModel.Clients.ActiveDirectory, sélectionnez-le, puis choisissez Installer.

Notes

Vous serez invité.e à prévisualiser et à valider les ajouts d'assemblage et d'accepter les accords de licence, pour les packages installés et leur contenu.

Pour utiliser la Bibliothèque d'authentification Microsoft (MSAL) au lieu de la Bibliothèque d'authentification Azure Active Directory (ADAL), recherchez et installez le package Microsoft.Identity.Client au lieu du package Microsoft.IdentityModel.Clients.ActiveDirectory.
Accédez à la dernière version du package Newtonsoft.Json NuGet et installez la dernière version.

Modifiez Program.cs

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

Remplacez le contenu entier de Program.cs par le code suivant. Si vous avez utilisé un nom différent de WebAPIQuickStart pour votre projet, vous devrez modifier le nom de l'espace de noms dans le nouveau code pour qu'il corresponde au nom de votre projet.

C#/ADAL
C#/MSAL

using Microsoft.IdentityModel.Clients.ActiveDirectory;
using Newtonsoft.Json.Linq;
using System;
using System.Net.Http;
using System.Net.Http.Headers;

namespace WebAPIQuickStart
{
    class Program
    {
        static void Main()
        {
            // TODO Specify the Dataverse environment URL to connect with.
            string resource = "https://<env-name>.<region>.dynamics.com";

            // Azure Active Directory app registration shared by all Power App samples.
            // For your custom apps, you will need to register them with Azure AD yourself.
            // See https://docs.microsoft.com/powerapps/developer/data-platform/walkthrough-register-app-azure-active-directory
            var clientId = "51f81489-12ee-4a9e-aaae-a2591f45987d";
            var redirectUri = new Uri("app://58145B91-0C36-4500-8554-080854F2AC97");

            #region Authentication

            // The authentication context used to acquire the web service access token
            var authContext = new AuthenticationContext(
                "https://login.microsoftonline.com/common", false);

            // Get the web service access token. Its lifetime is about one hour after
            // which it must be refreshed. For this simple sample, no refresh is needed.
            // See https://docs.microsoft.com/powerapps/developer/data-platform/authenticate-oauth
            var token = authContext.AcquireTokenAsync(
                resource, clientId, redirectUri,
                new PlatformParameters(
                    PromptBehavior.SelectAccount   // Prompt the user for a logon account.
                ),
                UserIdentifier.AnyUser
            ).Result;
            #endregion Authentication

            #region Client configuration

            var client = new HttpClient
            {
                // See https://docs.microsoft.com/en-us/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 = client.GetAsync("WhoAmI").Result;

            if (response.IsSuccessStatusCode)
            {
                // Parse the JSON formatted service response to obtain the user ID.  
                JObject body = JObject.Parse(
                    response.Content.ReadAsStringAsync().Result);
                Guid userId = (Guid)body["UserId"];

                Console.WriteLine("Your user ID is {0}", userId);
            }
            else
            {
                Console.WriteLine("Web API call failed");
                Console.WriteLine("Reason: " + response.ReasonPhrase);
            }
            #endregion Web API call

            // Pause program execution.
            Console.ReadKey();
        }
    }
}

using Microsoft.Identity.Client;
using Newtonsoft.Json.Linq;
using System;
using System.Net.Http;
using System.Net.Http.Headers;

namespace PowerApps.Samples
{
    class Program
    {
        static void Main()
        {
            // TODO Specify the Dataverse environment name to connect with.
            string resource = "https://<env-name>.api.<region>.dynamics.com";

            // Azure Active Directory app registration shared by all Power App samples.
            // For your custom apps, you will need to register them with Azure AD yourself.
            // See https://docs.microsoft.com/powerapps/developer/data-platform/walkthrough-register-app-azure-active-directory
            var clientId = "51f81489-12ee-4a9e-aaae-a2591f45987d";
            var redirectUri = "app://58145B91-0C36-4500-8554-080854F2AC97";

            #region Authentication

            var authBuilder = PublicClientApplicationBuilder.Create(clientId)
                             .WithAuthority(AadAuthorityAudience.AzureAdMultipleOrgs)
                             .WithRedirectUri(redirectUri)
                             .Build();
            var scope = resource + "/.default";
            string[] scopes = { scope };

            AuthenticationResult token = 
                authBuilder.AcquireTokenInteractive(scopes).ExecuteAsync().Result;
            #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 = client.GetAsync("WhoAmI").Result;

            if (response.IsSuccessStatusCode)
            {
                // Parse the JSON formatted service response to obtain the user ID.  
                JObject body = JObject.Parse(
                    response.Content.ReadAsStringAsync().Result);
                Guid userId = (Guid)body["UserId"];

                Console.WriteLine("Your user ID is {0}", userId);
            }
            else
            {
                Console.WriteLine("Web API call failed");
                Console.WriteLine("Reason: " + response.ReasonPhrase);
            }
            #endregion Web API call

            // Pause program execution by waiting for a key press.
            Console.ReadKey();
        }
    }
}

Juste en dessous du commentaire TODO dans le code ci-dessus, remplacez la valeur 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é /api/data/v9.x.
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

Appuyez sur F5 pour générer et exécuter le programme. Le résultat doit ressembler à ce qui suit :

Your user ID is 969effb0-98ae-478c-b547-53a2968c2e75
Avec la fenêtre de console active, appuyez sur n'importe quelle touche pour terminer le programme.

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, mais cela ne représente pas nécessairement un bon modèle pour créer une application.

La rubrique Démarrage rapide amélioré montre comment implémenter des méthodes de gestion des exceptions, une méthode d’authentification de base utilisant une chaîne de connexion, une méthode réutilisable pour actualiser le token et explique comment créer des méthodes réutilisables pour effectuer des opérations sur les données.

Étapes suivantes

Découvrez comment structurer votre code pour une meilleure conception.

Démarrage rapide amélioré

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).

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

Conditions préalables

Créer un projet Visual Studio

Modifiez Program.cs

Exécuter le programme

Félicitations !

Étapes suivantes

Commentaires