Démarrer un projet de l'API Web de Dynamics 365 dans Visual Studio (C#)

Article
04/18/2017

Date de publication : janvier 2017

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

Cette rubrique montre comment créer un projet dans Microsoft Visual Studio qui génère une application console qui utilise l'API Web de Dynamics 365. Elle illustre les références communes et les ressources de projet que la plupart des applications, notamment les exemples en C# du Kit de développement logiciel (SDK), utilisent pour implémenter des solutions basées sur l'API Web.

Configuration requise

Les conditions préalables suivantes sont requises pour générer l'application console décrite dans cette section.

Microsoft Visual Studio 2015 installé sur votre ordinateur de développement. Toute édition, notamment Visual Studio Expressdevrait être suffisante pour utiliser l'API Web de Dynamics 365. Pour plus d'informations sur les versions de Microsoft Visual Studio prises en charge, voir Visual Studio et le .NET Framework.
Un client NuGet doit être installé : l'utilitaire de ligne de commande ou l'extension Visual Studio. Pour plus d'informations, voir Installation de NuGet.
Une connexion Internet est nécessaire pour télécharger le package NuGet contenant la bibliothèque d'aide de l'API Web de Dynamics 365, ainsi que d'autres packages dépendants.
Éventuellement, téléchargez le SDK de Microsoft Dynamics 365ici. Bien que le SDK de Microsoft Dynamics 365 ne soit pas nécessaire pour générer ou exécuter ces exemples de l'API Web, la plupart des développeurs Dynamics 365 souhaitent l'installer, car il contient un ensemble complet de ressources supplémentaires, et le kit de développement logiciel (SDK) est requis pour accéder à d'autres interfaces de Dynamics 365.

Créer un projet

La procédure suivante explique comment créer un projet d’application console en C# qui utilise le Microsoft .NET Framework. Pour plus d’informations sur les versions prises en charge du .NET Framework, consultez Extensions prises en charge pour Microsoft Dynamics 365.

Nouveau projet

Dans Microsoft Visual Studio, cliquez sur Nouveau projet. La boîte de dialogue Nouveau projet s'affiche.
Dans le volet de navigation de gauche, sous Modèles, sélectionnez Visual C#.
Au-dessus de la liste des modèles disponibles, sélectionnez .NET Framework 4.5.2.
Dans la liste de modèles, sélectionnez Application console. (Choisissez éventuellement le type de projet adapté à votre solution). Tous les exemples en C# de l'API Web sont des applications console.
Dans les zones de texte en bas du formulaire, indiquez le nom et l'emplacement du projet, puis sélectionnez OK. (Pour cette rubrique, le nom de solution « StartWebAPI-CS » a été utilisé). Les fichiers d'origine de la solution sont générés et la solution est chargée dans Microsoft Visual Studio.
Dans le menu Projet, ouvrez le formulaire des propriétés du projet et vérifiez que l’infrastructure cible a la valeur NET Framework 4.5.2.

Ajouter toutes les ressources requises à votre projet.

Les procédures suivantes expliquent comment ajouter tous les packages et références gérés nécessaires à votre projet. Considérez cela comme un ensemble de base de ressources dont la plupart des applications de code managé auront besoin pour appeler les opérations de l'API Web.

Ajouter le package NuGet de la bibliothèque d'aide

La bibliothèque d'aide de l'API Web du Kit de développement logiciel (SDK) de Dynamics 365 contient des classes pour vous aider à effectuer des opérations supplémentaires, comme la configuration de l'application, l'authentification du serveur Dynamics 365, la gestion des exceptions et la communication Web. Pour plus d'informations, voir Utiliser la bibliothèque d'aide de l'API Web Microsoft Dynamics 365 (C#). L'utilisation de ces classes est facultative, bien qu'elles soient utilisées de manière extensive dans les exemples de l'API Web. La bibliothèque d'aide de l'API Web du Kit de développement Web (SDK) de Dynamics 365 est distribuée dans le formulaire de code source en tant que package NuGet. Les prochaines mises à jour seront distribuées en tant que mises à jour de package NuGet.

Si vous avez installé l'utilitaire de ligne de commande NuGet ou utilisez la console Gestionnaire de packages dans Visual Studio :

Publiez la commande suivante pour installer le package de la bibliothèque d'aide.

Install-Package Microsoft.CrmSdk.WebApi.Samples.HelperCode
Plusieurs messages s'affichent concernant le traitement des packages de dépendance. Si une boîte de dialogue Acceptation de la licence s'affiche, lisez les termes du contrat de licence et cliquez sur Accepter.
Passez à l'étape 6 ci-dessous pour confirmer l'installation du package de la bibliothèque d'aide.

Si vous avez installé l'extension Gestionnaire de packages NuGet :

Dans le menu Projet, sélectionnez Gérer les packages NuGet. L'onglet Gestionnaire de packages NuGet s'affiche.
Dans l'angle supérieur droit, définissez la liste déroulante source Package sur Nuget.org.
Dans l'angle supérieur gauche, cliquez sur Parcourir, entrez « Dynamics 365 HelperCode » dans la zone de recherche, puis appuyez sur Entrée.
Cliquez sur Installer. Si la boîte de dialogue Aperçu s'affiche, cliquez sur OK.
La boîte de dialogue Acceptation de la licence s'affiche. Examinez les termes du contrat de licence et cliquez sur J'accepte.
Accédez à la fenêtre Explorateur de solutions. Confirmez qu'un nouveau dossier de solution nommé Code d'aide de l'API Web a été ajouté.

Le package de la bibliothèque d'aide de l'API Web du Kit de développement logiciel (SDK) de Dynamics 365, Microsoft.CrmSdk.WebApi.Samples.HelperCode, dépend des autres packages suivants, qui sont automatiquement téléchargés et installés avec le package de la bibliothèque d'aide :

Newtonsoft.Json : contient Json.NET, une structure JSON sous licence MIT classique pour .NET.
Microsoft.IdentityModel.Clients.ActiveDirectory : contient les fichiers binaires de la bibliothèque d'authentification Active Directory (ADAL), qui fournit des fonctionnalités d'authentification pour les clients .NET.

Avertissement

Le package de la bibliothèque d'aide de l'API Web du Kit de développement logiciel (SDK) de Dynamics 365 a été généré sur des versions spécifiques de ces deux autres packages de prise en charge. De ce fait, vous devez directement mettre à jour le package NuGet de la bibliothèque d'aide. Cette opération met à jour les packages de prise en charge appropriés, si nécessaire. Si vous mettez à jour séparément un de ces packages de prise en charge, une nouvelle version de ce package risque d'être incompatible avec la bibliothèque d'aide.

Vérifier les références d'assembly requises

Dans l'Explorateur de solutions, développez le nœud Références.
Confirmez que les références suivantes ont été ajoutées au projet.
Si vous utilisez régulièrement des fonctionnalités supplémentaires dans vos applications, vous pouvez ajouter les références associées aux assemblys requis. Pour plus d'informations, voir Procédure d'ajout ou de suppression de références à l'aide de la boîte de dialogue Ajouter une référence.

Comme l'API Web de Dynamics 365 est basée sur les principes REST, elle ne requiert pas l'accès aux assemblys côté client. Toutefois, d'autres API prises en charge par Microsoft Dynamics 365 requièrent ces assemblys. Pour plus d'informations, voir Assemblys incluses dans le SDK Microsoft Dynamics 365.

Ajouter des instructions using classiques

Dans l'Explorateur de solutions, ouvrez Program.cs pour modification.
En haut du fichier, ajoutez les instructions using suivantes, qui font référence aux espaces de noms couramment utilisés dans les solutions basées sur l'API Web de Dynamics 365.
```
using Microsoft.Crm.Sdk.Samples.HelperCode;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
```
Si vous avez ajouté des assemblys ou références régulièrement utilisés dans les sections précédentes, vous pouvez également ajouter des instructions using correspondantes pour ces ressources.
Enregistrez le fichier.

Ajouter un code de connexion

Cette section explique comment ajouter un ensemble de base de paramètres et d'instructions pour exécuter ces opérations. Pour plus d'informations sur le code courant utilisé, voir Utiliser la bibliothèque d'aide de l'API Web Microsoft Dynamics 365 (C#)

Modifier le fichier de configuration de l'application

Dans l'Explorateur de solutions, ouvrez le fichier App.config pour modification. Ajoutez-lui les deux sections suivantes, après la section <startup> existante, puis enregistrez le fichier.

<connectionStrings>
    <clear />

    <!-- When providing a password, make sure to set the app.config file's security so that only you can read it. -->
    <add name="default"   connectionString="Url=http://myserver/myorg/; Username=name; Password=password; Domain=domain" />
    <add name="CrmOnline" connectionString="Url=https://mydomain.crm.dynamics.com/; Username=someone@mydomain.onmicrosoft.com; Password=password" />
  </connectionStrings>

  <appSettings>
    <!--For information on how to register an app and obtain the ClientId and RedirectUrl
        values see https://msdn.microsoft.com/dynamics/crm/mt149065 -->
    <!--Active Directory application registration. -->
    <!--These are dummy values and should be replaced with your actual app registration values.-->
    <add key="ClientId" value="e5cf0024-a66a-4f16-85ce-99ba97a24bb2" />
    <add key="RedirectUrl" value="https://localhost/SdkSample" />

    <!-- Use an alternate configuration file for connection string and setting values. This optional setting
    enables use of an app.config file shared among multiple applications. If the specified file does
    not exist, this setting is ignored.-->
    <add key="AlternateConfig" value="C:\Temp\crmsample.exe.config"/>
  </appSettings>

Lors du développement ou du déploiement d'une solution, les valeurs de connexion et d'enregistrement de l'application réelles doivent être remplacées par les exemples de valeurs d'espace réservé. Pour plus d'informations, voir Code d'aide de l'API Web : classes de configuration.

Ajouter du code pour appeler la bibliothèque d'aide

Modifiez le fichier Program.cs.
Ajoutez la propriété suivante à la classe Program. Cette propriété sera initialisée après la connexion réussie à un serveur Dynamics 365.

private HttpClient httpClient;

Dans la méthode Main, ajoutez les instructions suivantes.

Program app = new Program();
try
{
    String[] arguments = Environment.GetCommandLineArgs();
    app.ConnectToCRM(arguments);
}
catch (System.Exception ex)
{ ; }
finally
{
    if (app.httpClient != null)
    { app.httpClient.Dispose(); }
}

Ajoutez ensuite la méthode ConnectToCRM, qui utilise les classes Configuration et Authentication de la bibliothèque d'aide. Le code suivant illustre l'attribution de valeurs aux propriétés HttpClient afin que vous puissiez accéder à la version de l'API Web de Dynamics 365.

private void ConnectToCRM(String[] cmdargs)
{
    Configuration config = null;
    if (cmdargs.Length > 0)
        config = new FileConfiguration(cmdargs[0]);
    else
        config = new FileConfiguration(null);
    Authentication auth = new Authentication(config);
    httpClient = new HttpClient(auth.ClientHandler, true);
    httpClient.BaseAddress = new Uri(config.ServiceUrl + "api/data/v8.1/");
    httpClient.Timeout = new TimeSpan(0, 2, 0);
    httpClient.DefaultRequestHeaders.Add("OData-MaxVersion", "4.0");
    httpClient.DefaultRequestHeaders.Add("OData-Version", "4.0");
    httpClient.DefaultRequestHeaders.Accept.Add(
        new MediaTypeWithQualityHeaderValue("application/json"));
}

Ajouter un code de gestion des erreurs

Les modifications suivantes ajoutent du code pour intercepter et signaler les exceptions, notamment les erreurs de l'API Web, à la console. Si vous ciblez un autre environnement, modifiez le code de gestion des exceptions de manière appropriée pour cet environnement.

Dans la méthode Main, ajoutez l'instruction suivante au bloc catch.

DisplayException(ex);

Ajoutez la méthode correspondante à la classe Program.

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;
    }
}

Enregistrez tous les fichiers de la solution.

Étapes suivantes

À ce stade, la solution peut être générée sans erreurs. Si vous modifiez le fichier de configuration de l'application pour fournir des valeurs pour votre serveur Microsoft Dynamics 365 Server, le programme doit également se connecter à ce serveur. La solution représente une structure qui est prête à accepter du code personnalisé, notamment des appels à l'API Web de Dynamics 365.

Conseil

Avant de quitter cette rubrique, pensez à enregistrer votre projet comme modèle de projet. Vous pouvez ensuite réutiliser ce modèle pour de futurs projets de formation et économiser ainsi du temps et des efforts lors de la configuration de nouveaux projets. Pour cela, tandis que votre projet est ouvert dans Microsoft Visual Studio, dans le menu Fichier, sélectionnez Exporter le modèle. Suivez les instructions de l'Assistant Exporter le modèle pour créer le modèle.

Voir aussi

Se familiariser avec l'API Web Microsoft Dynamics 365 (C#)
Utiliser la bibliothèque d'aide de l'API Web Microsoft Dynamics 365 (C#)
Effectuer des opérations à l'aide de l'API Web

Microsoft Dynamics 365

Partager via