Exemple simple de démarrage rapide de l'API Web (C#)

Article
04/18/2017

S’applique à : Dynamics 365 (online), Dynamics 365 (on-premises)

Cet exemple montre comment s'authentifier auprès d'un serveur Microsoft Dynamics 365 Server et appeler une opération de base de l'API Web, la WhoAmI Function. À la différence des autres exemples de l'API Web, cet exemple ne dépend pas d'autres bibliothèques d'assistance non standard ou de fichiers sources supplémentaires. L'intégralité de son code source se trouve dans un fichier unique, Program.cs, pour permettre de comprendre plus facilement le flux logique et la procédure d'authentification. L'exemple fonctionne avec des déploiements en ligne, locaux et avec accès via Internet.

Besoins

La configuration requise pour cet exemple est la suivante :

Pour ouvrir et générer la solution, Microsoft Visual Studio 2015 ou une version ultérieure est requis. Des versions gratuites de ce produit sont disponibles au téléchargement : Visual Studio Express ou Communauté Visual Studio.
Une connexion Internet ou réseau pour se connecter à votre serveur Microsoft Dynamics 365 Server en ligne ou local, respectivement.
Un compte d'utilisateur sur votre serveur Microsoft Dynamics 365 Server (en ligne ou sur site).
Si Dynamics 365 (en ligne) est utilisé, l'exemple d'application doit être enregistré auprès d'Azure Active Directory, comme décrit dans Guide pas-à-pas : Enregistrer une application Dynamics 365 auprès d'Azure Active Directory.
Si Dynamics 365 (local) avec Déploiement avec accès via Internet (IFD) est utilisé, l'exemple d'application doit être enregistré auprès de votre client Azure Active Directory, comme décrit dans Guide pas-à-pas : Enregistrer une application Dynamics 365 auprès d'Active Directory.

Important

Par défaut, la solution ne sera pas générée initialement avec succès. Le code source doit être modifié au niveau des lignes indiquées par les commentaires //TODO pour fournir les informations d'enregistrement du compte d'utilisateur et/ou de l'application.

Montre ce qui suit

Cet exemple simple présente deux concepts de base requis pour le développement à l'aide de l'API Web : l'authentification auprès d'un serveur Microsoft Dynamics 365 Server et la création d'appels de base de l'API Web via le protocole HTTP.

L'authentification est nécessaire pour qu'une application cliente puisse accéder à une ressource Dynamics 365. Ce processus peut être complexe pour deux raisons : différents mécanismes d'authentification sont nécessaires pour les différents types de déploiements, et les mécanismes d'authentification basés sur le Web impliquent généralement plusieurs étapes par programme. L'authentification intégrée de Windows, requise pour les déploiements locaux, est relativement simple et ne requiert qu'un nom d'utilisateur et un mot de passe. Le programme agit par la suite comme agent de l'utilisateur authentifié.

En revanche, les déploiements en ligne et IFD requièrent l'enregistrement préalable de l'application cliente et utilisent un processus d'authentification OAuth à plusieurs étapes. La procédure d'enregistrement pour Dynamics 365 (en ligne) est décrite dans l'article Guide pas-à-pas : Enregistrer une application Dynamics 365 auprès d'Azure Active Directory. La procédure d'enregistrement pour Dynamics 365 (local) avec Déploiement avec accès via Internet (IFD) est décrite dans l'article Guide pas-à-pas : Enregistrer une application Dynamics 365 auprès d'Active Directory. Chaque demande suivante de l'API Web doit être authentifiée avec OAuth. Fort heureusement, une grande partie de la complexité de l'authentification OAuth peut être simplifiée en utilisant des bibliothèques d'authentification Active Directory (ADAL) pour les clients .NET, qui sont ajoutées à l'exemple en tant que package NuGet Microsoft.IdentityModel.Clients.ActiveDirectory. L'autorisation OAuth est davantage encapsulée dans cet exemple avec l'inclusion de la classe OAuthMessageHandler, qui ajoute l'en-tête d'autorisation OAuth requis aux demandes de message. Dans les exemples futurs, la prise en charge de la fonctionnalité d'authentification est séparée dans la Bibliothèque d'aide de l'API Web. Pour plus d'informations, voir Authentifier les utilisateurs dans Microsoft Dynamics 365.

L'API Web de Dynamics 365 est une API REST basée sur la Spécification OData. Elle prend donc en charge les requêtes HTTP standardisées sur les entités, et l'appel de fonctions et d'actions. Cet exemple illustre l'appel de la fonction WhoAmI Function avec une requête GET, et l'utilisation des informations fournies par cette fonction dans la réponse HTTP obtenue. Plusieurs bibliothèques standard sont utilisées par cet exemple pour aider à cet appel :

Les classes .NET Framework issues des espaces de noms System.Net et System.Net.Http sont utilisées pour la communication HTTP.
Comme C# n'assure pas la prise en charge native de JSON, l'Infrastructure Json.NET Open Source est fournie avec son Package NuGet.
La programmation asynchrone est prise en charge par l'espace de noms System.Threading.Tasks. En raison de retards potentiels, l'accès Web utilise généralement des mécanismes asynchrones. Pour plus d'informations, voir Programmation asynchrone avec Async et Await.

Exécuter cet exemple

Accédez d'abord à l'Exemple simple de démarrage rapide de l'API Web (C#), téléchargez l'exemple de fichier d'archive, Simple Web API quick-start sample (CS.zip), puis extrayez son contenu dans un dossier local. Ce dossier doit contenir les fichiers suivants :

Fichier	Fonction/Description
Program.cs	Contient le code source pour cet exemple.
SimpleWebApi.sln SimpleWebApi.csproj packages.config AssemblyInfo.cs App.config	Fichiers de configuration standard de la solution, du projet, de la configuration du package NuGet, des informations d'assembly et de l'application Microsoft Visual Studio 2015 pour cet exemple.

Utilisez ensuite la procédure suivante pour exécuter cet exemple.

Recherchez le fichier de solution SimpleWebApi.sln et double-cliquez dessus pour charger la solution dans Visual Studio.
Dans l'Explorateur de solutions, double-cliquez sur le fichier Program.cs pour l'ouvrir dans l'éditeur.
Recherchez les commentaires //TODO dans la méthode Main, ajoutez les valeurs de chaîne de connexion requises et annulez les commentaires des lignes associées.
Générez la solution SimpleWebApi. Tous les packages NuGet requis qui manquent ou doivent être mis à jour sont téléchargés et installés automatiquement.
Exécutez le projet SimpleWebApi à partir de Visual Studio. Tous les exemples de solution sont configurés pour s'exécuter en mode débogage par défaut.
Le comportement dépend du type de déploiement.
- Pour les déploiements en ligne et IFD, l'application console ouvre une nouvelle fenêtre pour vous permettre d'entrer vos informations d'identification utilisateur et votre mot de passe.
- Pour les déploiements locaux, l'application console vous invite à entrer un mot de passe pour le compte Dynamics 365 fourni.
Entrez ces informations et appuyez sur Enter.

Liste des codes

La source la plus actuelle pour ce fichier se trouve dans l'exemple de package de téléchargement.

Program.cs

namespace Microsoft.Crm.Sdk.Samples
{
    /// <summary>
    /// A basic Web API client application for Dynamics 365 (CRM). This sample authenticates 
    /// the user and then calls the WhoAmI Web API function. 
    /// </summary>
    /// <remarks> 
    /// Prerequisites: 
    ///   -  To run this application, you must have a CRM Online or on-premise account. 
    ///   -  For CRM Online or Internet-facing deployments (IFD), the application must be registered  
    ///      with Azure Active Directory as described in this article: 
    ///      https://msdn.microsoft.com/en-us/library/dn531010.aspx
    ///   
    /// The WhoAmI Web API function is documented here: 
    ///    https://msdn.microsoft.com/en-us/library/mt607925.aspx
    /// </remarks>
    static class SimpleWebApi
    {
        //TODO: Uncomment then substitute your correct Dynamics 365 organization service 
        // address for either CRM Online or on-premise (end with a forward-slash).
        //private static string serviceUrl = "https://mydomain.crm.dynamics.com/myorg/";   // CRM Online
        //private static string serviceUrl = "https://<organization name>.<domain name>/";   // CRM IFD
        //private statics string serviceUrl = "http://myserver/myorg/";        // CRM on-premises

        //TODO: For an on-premises deployment, set your organization credentials here. (If
        // online or IFD, you can you can disregard or set to null.)
        private static string userAccount = "<user-account>";  //CRM user account
        private static string domain = "<server-domain>";  //CRM server domain

        //TODO: For CRM Online or IFD deployments, substitute your app registration values  
        // here. (If on-premise, you can disregard or set to null.)
        private static string clientId = "<app-reg-guid>";     //e.g. "e5cf0024-a66a-4f16-85ce-99ba97a24bb2"
        private static string redirectUrl = "<redirect-URL>";  //e.g. "https://localhost/SdkSample"

        static public void Main(string[] args)
        {
            //One message handler for OAuth authentication, and the other for Windows integrated 
            // authentication.  (Assumes that HTTPS protocol only used for CRM Online.)
            HttpMessageHandler messageHandler;
            if (serviceUrl.StartsWith("https://"))
            {
                messageHandler = new OAuthMessageHandler(serviceUrl, clientId, redirectUrl,
                         new HttpClientHandler());
            }
            else
            {
                //Prompt for user account password required for on-premise credentials.  (Better
                // approach is to use the SecureString class here.)
                Console.Write("Please enter the password for account {0}: ", userAccount);
                string password = Console.ReadLine().Trim();
                NetworkCredential credentials = new NetworkCredential(userAccount, password, domain);
                messageHandler = new HttpClientHandler() { Credentials = credentials };
            }
            try
            {
                //Create an HTTP client to send a request message to the CRM Web service.
                using (HttpClient httpClient = new HttpClient(messageHandler))
                {
                    //Specify the Web API address of the service and the period of time each request 
                    // has to execute.
                    httpClient.BaseAddress = new Uri(serviceUrl);
                    httpClient.Timeout = new TimeSpan(0, 2, 0);  //2 minutes

                    //Send the WhoAmI request to the Web API using a GET request. 
                    var response = httpClient.GetAsync("api/data/v8.1/WhoAmI",
                            HttpCompletionOption.ResponseHeadersRead).Result;
                    if (response.IsSuccessStatusCode)
                    {
                        //Get the response content and parse it.
                        JObject body = JObject.Parse(response.Content.ReadAsStringAsync().Result);
                        Guid userId = (Guid)body["UserId"];
                        Console.WriteLine("Your system user ID is: {0}", userId);
                    }
                    else
                    {
                        Console.WriteLine("The request failed with a status of '{0}'",
                               response.ReasonPhrase);
                    }
                }
            }
            catch (Exception ex)
            {
                DisplayException(ex);
                throw;
            }
            finally
            {
                Console.WriteLine("Press <Enter> to exit the program.");
                Console.ReadLine();
            }
        }

        /// <summary> Displays exception information to the console. </summary>
        /// <param name="ex">The exception to output</param>
        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;
            }
        }
    }

    /// <summary>
    ///Custom HTTP message handler that uses OAuth authentication thru ADAL.
    /// </summary>
    class OAuthMessageHandler : DelegatingHandler
    {
        private AuthenticationHeaderValue authHeader;

        public OAuthMessageHandler(string serviceUrl, string clientId, string redirectUrl,
                HttpMessageHandler innerHandler)
            : base(innerHandler)
        {
            // Obtain the Azure Active Directory Authentication Library (ADAL) authentication context.
            AuthenticationParameters ap = AuthenticationParameters.CreateFromResourceUrlAsync(
                    new Uri(serviceUrl + "api/data/")).Result;
            AuthenticationContext authContext = new AuthenticationContext(ap.Authority, false);
            //Note that an Azure AD access token has finite lifetime, default expiration is 60 minutes.
            AuthenticationResult authResult = authContext.AcquireToken(serviceUrl, clientId, new Uri(redirectUrl));
            authHeader = new AuthenticationHeaderValue("Bearer", authResult.AccessToken);
        }

        protected override Task<HttpResponseMessage> SendAsync(
                 HttpRequestMessage request, System.Threading.CancellationToken cancellationToken)
        {
            request.Headers.Authorization = authHeader;
            return base.SendAsync(request, cancellationToken);
        }
    }
}

Voir aussi

Web API Reference
Exemples d'API Web
Utiliser la bibliothèque d'aide de l'API Web Microsoft Dynamics 365 (C#)
Authentifier les utilisateurs dans Microsoft Dynamics 365

Microsoft Dynamics 365

Partager via