Partager via

Exemples de l'API Web (C#)

  • Article

 

Date de publication : janvier 2017

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

Cette rubrique fournit des informations sur les exemples de l'API Web implémentés en C#. Chaque exemple porte sur un aspect différent de l'API Web de Microsoft Dynamics 365, mais ils partagent des caractéristiques et une structure similaires.

Notes

Cette approche d'implémentation utilise la création d'objets de faible niveau et des appels de message HTTP explicites. Cette approche permet de contrôler et de démontrer les propriétés d'objet de faible niveau qui contrôlent le comportement de l'API Web. Elle a pour but de vous aider à comprendre le fonctionnement interne mais ne représente pas nécessairement une approche qui optimise la productivité des développeurs.

En revanche, les bibliothèques de niveau supérieur, comme la Bibliothèque OData, font largement abstraction de cette logique client de faible niveau. Le modèle OData T4 peut éventuellement être utilisé conjointement avec la bibliothèque OData pour générer automatiquement des classes d'entité client.

Contenu de la rubrique

Configuration requise

Liste des exemples de l'API Web (C#)

Comment télécharger et exécuter les exemples

Éléments communs disponibles dans chaque exemple

Configuration requise

Les éléments suivants sont requis pour générer et exécuter les exemples C# de l'API Web de Dynamics 365 :

  • Une version de Microsoft Visual Studio 2015 ou une version ultérieure. Une version gratuite, Visual Studio Community, est disponible au téléchargement ici.

  • Une connexion Internet pour télécharger et mettre à jour les packages NuGet référencés.

  • Un accès à Dynamics Dynamics 365 en ligne ou local (ou une version ultérieure). Pour tous les types d'installation Dynamics 365, un compte d'utilisateur doté de privilèges pour exécuter des opérations CRUD est requis.

  • Afin d'exécuter les exemples sur Dynamics 365 (en ligne), vous devez enregistrer votre application auprès d'Azure Active Directory pour obtenir un ID client et une URL de redirection. Pour plus d'informations, voir Guide pas-à-pas : Enregistrer une application Dynamics 365 auprès d'Azure Active Directory.

Liste des exemples de l'API Web (C#)

Le tableau suivant répertorie les exemples implémentés en C#. Chaque exemple est décrit de manière plus générale dans un exemple de rubrique de groupe correspondant qui porte sur les message de demande et de réponse HTTP, comme détaillé dans la rubrique Exemples d'API Web.

Exemple

Exemple de groupe

Description

Exemple d'opérations de base de l'API Web (C#)

Exemple d'opérations de base de l'API Web

Montre comment créer, extraire, mettre à jour, supprimer, associer et dissocier des enregistrements d'entité Dynamics 365.

Exemples de données de requête d'API Web (C#)

Exemples de données de requête d'API Web

Montre comment utiliser la syntaxe et les fonctions de requête OData v4 ainsi que les fonctions de requête Microsoft Dynamics 365. Contient des exemples d'utilisation de requêtes prédéfinies et d'utilisation de FetchXML pour exécuter des requêtes.

Exemple d'opérations conditionnelles de l'API Web (C#)

Exemple d'opérations conditionnelles de l'API Web

Montre comment exécuter des opérations conditionnelles que vous spécifiez avec les critères ETag.

Exemple de fonctions et d'actions de l'API Web (C#)

Exemple de fonctions et d'actions de l'API Web

Montre comment utiliser les fonctions et les actions liées et non liées, notamment les actions personnalisées.

Comment télécharger et exécuter les exemples

Le code source de chaque exemple est disponible dans la galerie de codes MSDN. Le lien de téléchargement de chaque exemple est inclus dans l'exemple de rubrique. L'exemple de téléchargement est un fichier .zip compressé, qui contient les fichiers de la solution Visual Studio 2015 pour l'exemple. Pour plus d'informations, voir la section Exécuter cet exemple dans chaque exemple de rubrique.

Éléments communs disponibles dans chaque exemple

La plupart des exemples ont une structure similaire et contiennent des méthodes et des ressources communes, pour fournir généralement l'infrastructure de base d'un programme en C# de l'API Web.

La plupart de ces éléments communs sont également présents lors de la création d'une solution qui accède à l'API Web de Dynamics 365. Pour plus d'informations, voir Démarrer un projet de l'API Web de Dynamics 365 dans Visual Studio (C#).

Bibliothèques et structures utilisées

Cette implémentation en C# dépend du code d'aide suivant pour la communication HTTP, la configuration de l'application, l'authentification, la gestion des erreurs et la sérialisation JSON.

Bibliothèque Json.NET

Comme le langage C# et la plupart des autres langages gérés ne prennent pas en charge de manière native le format de données JSON, la meilleure approche actuelle consiste à utiliser une bibliothèque pour cette fonctionnalité. Pour plus d'informations, voir Introduction à JSON (JavaScript Object Notation) dans JavaScript et .NET. Json.NET est un choix fréquent pour les projets .NET Framework. Il fournit un environnement robuste, performant et open-source (Licence MIT) pour sérialiser, convertir, analyser, interroger et mettre en forme les données JSON. Pour plus d'informations, consultez la documentation de Json.NET.

Dans les exemples en C#, cette bibliothèque est principalement utilisée pour sérialiser les données entre les objets .NET et les corps de message HTTP. Bien que la bibliothèque fournisse plusieurs méthodes pour accomplir cette tâche, l'approche utilisée par les exemples consiste à créer des instances JObject individuelles pour représenter les instances d'entité Dynamics 365 (enregistrements). Par exemple, le code suivant crée la variable contact1 qui représente une instance contact EntityType de Dynamics 365, puis fournit des valeurs pour un ensemble de propriétés de ce type.

JObject contact1 = new JObject();
contact1.Add("firstname", "Peter");
contact1.Add("lastname", "Cambel");
contact1.Add("annualincome", 80000);
contact1["jobtitle"] = "Junior Developer";

L'utilisation de la notation entre crochets dans la dernière instruction est équivalente à la méthode Add. Cette instanciation peut également être effectuée à l'aide de la méthode statique Parse :

JObject contact1 = JObject.Parse(@"{firstname: 'Peter', lastname: 'Cambel', "
+ @"annualincome: 80000, jobtitle: 'Junior Developer'}");

Comme JObject représente un type JSON général, son utilisation exclut la vérification du type d'exécution. Par exemple, l'instruction suivante est syntaxiquement valide, mais elle peut générer des erreurs d'exécution, car contact EntityType ne contient pas de propriété age.

contact1.Add("age", 37); //Possible error--no age property exists in contact!

Une fois que la variable d'entité a été initialisée, elle peut ensuite être envoyée dans un corps de message, avec l'aide de plusieurs classes System.Net.Http, par exemple :

HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, "contacts");
request.Content = new StringContent(contact1.ToString(), Encoding.UTF8, "application/json");
HttpResponseMessage response = await httpClient.SendAsync(request1);

Vous pouvez également créer des instances JObject en désérialisant les instances d'entité durant les opérations de récupération, par exemple :

//contact2Uri contains a reference to an existing CRM contact instance.
string queryOptions = "?$select=fullname,annualincome,jobtitle,description";
HttpResponseMessage response = await httpClient.GetAsync(contact2Uri + queryOptions);
JObject contact2 = JsonConvert.DeserializeObject<JObject>(await response.Content.ReadAsStringAsync());

Succès des réponses et gestion des erreurs

Généralement les exemples adoptent une approche simple pour traiter les réponses HTTP. Si la demande aboutit, les informations sur l'opération sont généralement envoyées vers la console. Si la réponse contient également une charge JSON ou des en-têtes utiles, ces informations sont uniquement traitées en cas de succès. Enfin, si une entité Dynamics 365 a été créée, la collection entityUris est mise à jour avec l'URI de cette ressource. La méthode Méthode DeleteRequiredRecords utilise cette collection pour supprimer éventuellement les données créées par l'exemple à partir de votre serveur Dynamics 365.

Si la demande échoue, le programme affiche un message contextuel sur l'opération ayant échoué, puis lève une exception personnalisée de type CrmHttpResponseException. Le gestionnaire d'exceptions affiche d'autres informations sur l'exception, puis le contrôle passe à un bloc finally incluant la logique de nettoyage, notamment un appel à DeleteRequiredRecords. Le code suivant illustre cette approche de gestion des erreurs sur une demande POST pour créer un enregistrement.

if (response.StatusCode == HttpStatusCode.NoContent)  //204
{
Console.WriteLine("POST succeeded, entity created!”);
//optionally process response message headers or body here, for example:
entityUri = response.Headers.GetValues("OData-EntityId").FirstOrDefault();
entityUris.Add(entityUri);
}
else
{
Console.WriteLine("Operation failed: {0}", response.ReasonPhrase);
throw new CrmHttpResponseException(response.Content);
}

HttpStatusCode.NoContent est équivalent au code de statut HTTP 204, « Aucun contenu ». Ici, ce code de statut indique que la demande POST a abouti. Pour plus d'informations, voir Composer des demandes HTTP et gérer les erreurs.

Caractéristiques et méthodes

La plupart des exemples ont le même modèle architectural général, avec les caractéristiques suivantes :

  • L'exemple de code C# pertinent est contenu dans le fichier source principal nommé Program.cs, qui contient une classe unique portant le même nom que l'exemple de projet.

  • Les exemples de classe, ainsi que la Utiliser la bibliothèque d'aide de l'API Web Microsoft Dynamics 365 (C#), sont contenus dans l'espace de noms Microsoft.Crm.Sdk.Samples.

  • Les exemples sont largement commentés : des résumés sont fournis aux niveaux de la classe et de la méthode, et la plupart des principales instructions individuelles ont associé des commentaires sur une même ou une seule ligne. Les fichiers supplémentaires, tels que le fichier de configuration de l'application App.config, contiennent souvent des commentaires importants.

  • L'exemple de classe principal est généralement structuré pour contenir l'ensemble commun de méthodes ci-après : Méthode Main, Méthode ConnectToCRM, Méthode CreateRequiredRecords, Méthode RunAsync, Méthode DisplayException et Méthode DeleteRequiredRecords.

Méthode Main

Par définition, cette méthode commence l'exécution de l'exemple. Elle contient uniquement la logique de flux de contrôle et de gestion des exceptions de niveau supérieur, souvent identique au code suivant :

static void Main(string[] args)
{
FunctionsAndActions app = new FunctionsAndActions();
try
{
//Read configuration file and connect to specified CRM server.
app.ConnectToCRM(args);
app.CreateRequiredRecords();
Task.WaitAll(Task.Run(async () => await app.RunAsync()));
}
catch (System.Exception ex) { DisplayException(ex);
}
finally
{
if (app.httpClient != null)
{
app.DeleteRequiredRecords(true);
app.httpClient.Dispose();
}
Console.WriteLine("Press <Enter> to exit the program.");
Console.ReadLine();
}
}

Méthode ConnectToCRM

Cette méthode appelle les bibliothèques d'aide pour lire le fichier de configuration de l'application, puis établit une connexion au serveur Dynamics 365 spécifié. Le résultat de ces étapes est l'initialisation d'une propriété de classe HttpClient qui est utilisée dans l'ensemble du programme pour envoyer des demandes Web et recevoir des réponses. Notez que les propriétés suivantes sont définies sur cet objet :

//Define the Web API address, the max period of execute time, the Odata
// version, and the expected response payload format.
httpClient.BaseAddress = new Uri(config.ServiceUrl + "api/data/v8.1/");
httpClient.Timeout = new TimeSpan(0, 2, 0);  // 2 minute timeout
httpClient.DefaultRequestHeaders.Add("OData-MaxVersion", "4.0");
httpClient.DefaultRequestHeaders.Add("OData-Version", "4.0");
httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

Pour plus d'informations sur la configuration et l'authentification de l'exemple d'application, voir Utiliser la bibliothèque d'aide de l'API Web Microsoft Dynamics 365 (C#).

Méthode CreateRequiredRecords

Cette méthode crée et initialise des enregistrements d'entité requis par l'exemple, uniquement si ces opérations ne sont pas importantes dans l'exemple. Par exemple, l'Exemple d'opérations de base de l'API Web (C#) ne contient pas cette méthode, car la création d'enregistrements est un aspect important pour l'exemple.

Méthode RunAsync

Cette méthode asynchrone contient le code source pertinent ou, pour les programmes plus longs, appelle des méthodes qui regroupent l'exemple de code pertinent. Le code contenu est expliqué par des commentaires intégrés et des commentaires situés dans la section Remarques de chaque exemple de rubrique correspondant.

Méthode DisplayException

Cette méthode d'aide affiche des informations sur les exceptions, notamment pour les exceptions internes, sur la console standard.

Méthode DeleteRequiredRecords

Cette méthode complémentaire supprime éventuellement les exemples d'enregistrement et d'autres ressources du serveur Dynamics 365 créées dans le programme et en particulier par la méthode Méthode CreateRequiredRecords. Elle demande à l'utilisateur de vérifier cette opération, puis itère via la collection entityUris et tente de supprimer chaque élément avec un message DELETE HTTP.

Voir aussi

Utilisez l'API Web Microsoft Dynamics 365
Exemples d'API Web
Exemples d'API Web (Javascript côté client)
Exemple d'opérations de base de l'API Web (C#)
Exemples de données de requête d'API Web (C#)
Exemple d'opérations conditionnelles de l'API Web (C#)
Exemple de fonctions et d'actions de l'API Web (C#)

Microsoft Dynamics 365

© 2017 Microsoft. Tous droits réservés. Copyright