Bibliothèque de classes WebAPIService (C#)

  • Article

WebAPIService est un exemple de projet de bibliothèque de classes .NET 6.0 qui illustre plusieurs fonctionnalités importantes que vous devez inclure lorsque vous utilisez l’API web Dataverse.

Cette bibliothèque démontre comment :

  • Gérer Dataverse limites 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.

Notes

Cette bibliothèque d’exemples est une aide qui est utilisée par tous les exemples de l’API web Dataverse C#, mais ce n’est pas un SDK. Elle est testée uniquement pour confirmer que les exemples qui l’utilisent s’exécutent correctement. Cet exemple de code est fourni « tel quel » sans garantie de réutilisation.

Cette bibliothèque ne gèrent pas les actions suivantes :

  • Gérer l’authentification. Cela dépend d’une fonction passée depuis une application qui fournit le jeton à utiliser. Tous les exemples d’API web dépendent d’une classe d’applications partagée qui gère l’authentification à l’aide de la Bibliothèque d’authentification Microsoft (MSAL). MSAL prend en charge plusieurs types de flux d’authentification différents. Ces exemples utilisent le flux Nom d’utilisateur/mot de passe (ROPC) pour plus de simplicité, mais ce flux n’est pas recommandé. Pour vos applications, vous devez utiliser l’un des autres flux. Plus d’informations : Support du flux d’authentification dans la bibliothèque d’authentification Microsoft.
  • Fournir toutes les capacités de génération de code. Toutes les classes utilisées dans les exemples sont écrites à la main. Toutes les données d’entité commerciale utilisent la célèbre classe Json.NET JObject plutôt qu’une classe représentant le type d’entité.
  • Fournir un modèle d’objet pour composer des requêtes OData. Toutes les requêtes affichent la syntaxe de requête OData en tant que paramètres de requête.

Code

Vous pouvez trouver le code source de la bibliothèque de classes WebApiService et la solution Visual Studio à PowerApps-Samples/dataverse/webapi/C#-NETx/WebAPIService

Liste de classes

Les classes suivantes sont incluses dans le WebAPIService.

Classe Service

La classe Service propose des méthodes pour envoyer des requêtes à Dataverse via un HttpClient géré à l’aide de IHttpClientFactory.

Le Service est le composant principal de tous les exemples et vous pouvez l’utiliser pour effectuer toutes les opérations démontrées avec un exemple de code. Tout ce qui est inclus dans WebAPIService ou dans l’un des exemples qui l’utilisent permet la réutilisation du code et permet de démontrer les capacités de l’API web Dataverse à un niveau supérieur.

Le constructeur Service accepte une instance de classe Config, qui contient deux propriétés requises : GetAccessToken et Url. Toutes les autres propriétés représentent des options qui ont des valeurs par défaut.

Le constructeur utilise l’injection de dépendances pour créer un IHttpClientFactory qui peut renvoyer un HttpClient désigné avec les propriétés spécifiées dans la fonction ConfigureHttpClient. Le fait que ce client utilise ou non des cookies dépend de la définition ou non du paramètre Config.DisableCookies. Dans le constructeur, la politique définie par la méthode static GetRetryPolicy qui contrôle la manière dont les erreurs transitoires et les limites de protection de service Dataverse sont gérées.

Méthodes de service

La classe Service propose les méthodes suivantes :

Méthode SendAsync

Cette méthode est en fin de compte responsable de toutes les opérations.

Cette méthode :

Méthode SendAsync<T>

Cette méthode facilite le renvoi d’une classe qui inclut les propriétés trouvées dans les ComplexTypes renvoyés par les actions et les fonctions OData dans l’API web Dataverse.

L’exemple suivant montre l’utilisation avec la fonction WhoAmI function :

static async Task WhoAmI(Service service)
{
   var response = await service.SendAsync<WhoAmIResponse>(new WhoAmIRequest());

   Console.WriteLine($"Your user ID is {response.UserId}");
}
Méthode ParseError

Cette méthode analyse le contenu d’une HttpResponseMessage pour détecter un échec HttpRequestMessage pour renvoyer une ServiceException. La Méthode SendAsync utilise cette méthode lorsque la Propriété HttpResponseMessage.IsSuccessStatusCode est fausse. Vous pouvez également l’utiliser pour extraire des informations d’erreur des instances HttpResponseMessage renvoyées par BatchResponse.HttpResponseMessages quand la propriété BatchRequest.ContinueOnError est définie sur true. Plus d’informations : Traitement

Propriétés de service

Le service a une seule propriété : BaseAddress.

Propriétés BaseAddress

Cette propriété renvoie l’URL de base définie dans Config.Url. Vous avez besoin de cette URL lors de l’instanciation de la classe BatchRequest et pour l’ajouter à une URL relative chaque fois qu’une URL absolue est requise.

Classe Config

La classe Config contient des propriétés qui contrôlent le comportement de l’application, comme indiqué dans le tableau suivant :

Property Type Description
GetAccessToken Func<Task<string>> Une fonction fournie par l’application cliente pour renvoyer un jeton d’accès.
Url string? URL de base de l’environnement. Par exemple : https://org.api.crm.dynamics.com
CallerObjectId Guid Valeur SystemUser.ActiveDirectoryGuid à appliquer pour l’emprunt d’identité. Par défaut, Guid.Empty
Pour plus d’informations : Emprunter l’identité d’un autre utilisateur à l’aide de l’API Web
TimeoutInSeconds ushort Temps d’attente avant expiration. La valeur par défaut est 120 secondes.
MaxRetries byte Nombre maximal de nouvelles tentatives lorsque les limites de protection du service se produisent. La valeur par défaut est 3.
Version string Version du service à utiliser. La valeur par défaut est v9.2
DisableCookies bool S’il faut désactiver les cookies pour améliorer les performances dans les scénarios de chargement de données en masse. Pour plus d’informations : Affinité de serveur

Classe EntityReference

La classe EntityReference représente une référence à un enregistrement dans une table Dataverse. OData identifie les ressources avec une URL. EntityReference fournit des méthodes pour faciliter la création et l’accès aux propriétés des URL.

Constructeurs EntityReference

Utilisez les constructeurs suivants pour instancier un EntityReference.

EntityReference(string entitySetName, Guid ? ID)

Crée une référence d’entité à l’aide de EntitySetName et de Guid.

EntityReference(string uri)

Analyse une URL absolue ou relative pour créer une référence d’entité, y compris les URL qui utilisent des clés alternatives.

EntityReference(string setName, Dictionary<string, string>? keyAttributes)

Utilisez ce constructeur pour instancier une référence d’entité à l’aide d’un clé secondaire.

Notes

Les valeurs de clé doivent être des valeurs de chaîne. Cela ne convertit pas les autres types en chaînes appropriées.

Propriétés EntityReference

EntityReference contient les propriétés publiques suivantes :

Property Type Description
Id Guid? La valeur de clé primaire de l’enregistrement lorsque vous n’utilisez pas de clé secondaire.
KeyAttributes Dictionary<string, string> Les valeurs de chaîne qui représentent les valeurs clé secondaire utilisées dans une URL.
SetName string Le EntitySetName du type d’entité.
Path string URL relative à l’enregistrement.

Méthodes EntityReference

EntityReference contient les méthodes publiques suivantes. Aucune d’entre elles ne nécessite de paramètres.

Nom de la méthode Type renvoyé Description
AsODataId string Renvoie une chaîne formatée pour être utilisée comme référence de paramètre à un enregistrement dans l’URL d’une fonction OData.
AsJObject JObject Renvoie un JObject qui peut être utilisé comme référence de paramètre à un enregistrement dans une action OData.

Classes Error

ODataError, Error et ODataException sont des classes utilisées pour désérialiser les erreurs renvoyées par le service. Vous n’avez pas besoin de travailler directement avec eux.

ServiceException

ServiceException est une classe d’exception qui contient les propriétés de l’erreur renvoyée par le service. Utilisez la méthode ParseError pour obtenir une instance de cette exception.

Extensions

WebApiService a une méthode d’extension d’un type .NET.

HttpResponseMessage As<T>

Cette extension instancie une instance de T où T est issue de HttpResponseMessage et copie les propriétés du message HttpResponseMessage vers la classe dérivée. La méthode Service SendAsync<T> utilise cette méthode, mais peut également être utilisée séparément. Par exemple, lorsque vous utilisez la classe BatchRequest, les articles dans les BatchResponse.HttpResponseMessages sont de type HttpResponseMessage. Vous pouvez utiliser cette extension pour les convertir dans la classe dérivée appropriée afin de faciliter l’accès à toutes les propriétés.

Messages

Le dossier Messages inclut des classes qui proviennent de HttpRequestMessage ou HttpResponseMessage.

Ces classes fournissent des définitions réutilisables des requêtes et des réponses qui correspondent aux opérations OData que vous pouvez utiliser dans n’importe quel environnement Dataverse.

Ces classes fournissent également des exemples d’opérations spécifiques qui peuvent être appliquées à l’aide de HttpRequestMessage et HttpResponseMessage sans dériver de ces types.

Dans une application, vous pouvez également créer des messages personnalisés, par exemple représentant une API personnalisée dans votre environnement, en utilisant le même modèle. Il s’agit de classes modulaires et il n’est pas nécessaire de les inclure dans le dossier WebAPIService.Messages.

Par exemple, l’Exemple de fonctions et d’actions d’API Web (C#) utilise une API personnalisée qui n’est pas incluse dans Dataverse jusqu’à ce qu’une solution contenant l’API personnalisée soit installée. La définition des classes correspondantes pour utiliser ce message se trouve dans l’exemple d’application qui l’utilise :

*Classe de demande

Ces classes ont généralement un constructeur avec des paramètres qui instancie un HttpRequestMessage avec les données nécessaires à l’exécution de l’opération. Ils peuvent avoir des propriétés distinctes, selon le cas.

L’exemple le plus simple de ce modèle est la classe WhoAmIRequest.

namespace PowerApps.Samples.Messages
{
    /// <summary>
    /// Contains the data to perform the WhoAmI function
    /// </summary>
    public sealed class WhoAmIRequest : HttpRequestMessage
    {
        /// <summary>
        /// Initializes the WhoAmIRequest
        /// </summary>
        public WhoAmIRequest()
        {
            Method = HttpMethod.Get;
            RequestUri = new Uri(
                uriString: "WhoAmI", 
                uriKind: UriKind.Relative);
        }
    }
}

Les noms de ces classes correspondent généralement aux classes du kit de développement logiciel Dataverse Microsoft.Xrm.Sdk.Messages Namespace, mais ne se limitent pas à ces opérations. L’API web permet d’effectuer certaines opérations qui ne peuvent pas être effectuées avec le kit de développement logiciel, par exemple CreateRetrieveRequest est un message qui crée un enregistrement et le récupère. Le SDK Dataverse ne fournit pas cette fonctionnalité dans une seule requête.

*Classes de réponse

Si *les classes de requête renvoient une valeur, il y a une *classe de réponse correspondante pour accéder aux propriétés renvoyées. Si la *demande renvoie 204 No Content, l’opération renvoie un HttpResponseMessage, mais il n’y a pas de classe dérivée. Utilisez la méthode SendAsync pour envoyer ces demandes.

Les classes *Réponse fournissent des propriétés typées qui accèdent aux propriétés HttpResponseMessage``Headers ou Content et les analysent pour donner accès au type complexe renvoyé par l’opération.

La classe WhoAmIResponse est un exemple. Dans cette classe, vous pouvez trouver tout le code nécessaire pour extraire les propriétés du WhoAmIResponse ComplexType.

using Newtonsoft.Json.Linq;

namespace PowerApps.Samples.Messages
{
    // This class must be instantiated by either:
    // - The Service.SendAsync<T> method
    // - The HttpResponseMessage.As<T> extension in Extensions.cs

    /// <summary>
    /// Contains the response from the WhoAmIRequest
    /// </summary>
    public sealed class WhoAmIResponse : HttpResponseMessage
    {

        // Cache the async content
        private string? _content;

        //Provides JObject for property getters
        private JObject _jObject
        {
            get
            {
                _content ??= Content.ReadAsStringAsync().GetAwaiter().GetResult();

                return JObject.Parse(_content);
            }
        }

        /// <summary>
        /// Gets the ID of the business to which the logged on user belongs.
        /// </summary>
        public Guid BusinessUnitId => (Guid)_jObject.GetValue(nameof(BusinessUnitId));

        /// <summary>
        /// Gets ID of the user who is logged on.
        /// </summary>
        public Guid UserId => (Guid)_jObject.GetValue(nameof(UserId));

        /// <summary>
        /// Gets ID of the organization that the user belongs to.
        /// </summary>
        public Guid OrganizationId => (Guid)_jObject.GetValue(nameof(OrganizationId));
    }
}

Ces classes ne peuvent être correctement instanciées que lorsqu’elles sont renvoyées par la méthode SendAsync<T> ou en utilisant l’extension HttpResponseMessage en tant que<T> extension sur un HttpResponseMessage dans la propriété BatchResponse.HttpResponseMessages.

Lot

Le dossier Batch contient trois classes pour gérer l’envoi de demandes $batch OData. Pour plus d’informations : Exécuter des opérations par lots à l’aide de l’API Web.

BatchRequest

Le constructeur BatchRequest lance un message HttpRequestMessage qui peut être utilisé avec la méthode SendAsync<T> pour envoyer des requêtes par lots. Le constructeur exige que la valeur Service.BaseAddress soit transmise comme paramètre.

BatchRequest contient les propriétés suivantes.

Property Type Description
ContinueOnError Bool Contrôle si l’opération par lots doit continuer lorsqu’une erreur se produit.
ChangeSets List<ChangeSet> Un ou plusieurs ensembles de modifications à inclure dans le lot.
Requests List<HttpRequestMessage> Une ou plusieurs HttpMessageRequest à envoyer en dehors de tout ChangeSet.

Lorsque ChangeSets ou Requests sont définis, ils sont encapsulés dans HttpMessageContent et ajoutés au Content de la demande. La méthode ToMessageContent privée applique les modifications requises aux en-têtes et renvoie le HttpMessageContent pour les deux propriétés ChangeSets et Requests.

ChangeSet

Un ensemble de modifications représente un groupe de demandes qui doivent se terminer dans une transaction.

Il contient une seule propriété :

Property Type Description
Requests List<HttpRequestMessage> Une ou plusieurs HttpMessageRequest à effectuer dans le cadre de la transaction.

BatchResponse

BatchResponse a une seule propriété :

Property Type Description
HttpResponseMessages List<HttpResponseMessage> Réponses de l’opération $batch.

BatchResponse dispose d’une méthode ParseMultipartContent privée utilisée par la propriété HttpResponseMessages pour analyser le contenu MultipartContent saisi dans le message individuel HttpResponseMessage.

Pour accéder aux propriétés de type des instances HttpResponseMessage renvoyées, vous pouvez utiliser la méthode d’extension HttpResponseMessage As<T>.

Méthodes

Pour les opérations fréquemment effectuées, le dossier Methods contient des extensions de la classe Service. Ces méthodes permettent d’utiliser les classes *Demande correspondantes sur une seule ligne.

Les méthodes suivantes sont fournies :

méthode Type renvoyé Description
Create Task<EntityReference> Crée un enregistrement.
CreateRetrieve Task<JObject> Crée un nouvel enregistrement et le récupère.
Delete Task Supprime un enregistrement.
FetchXml Task<FetchXmlResponse> Récupère les résultats d’une requête FetchXml. La demande est envoyée avec POST en utilisant $batch pour atténuer les problèmes lorsque les URL longues envoyées avec GET peuvent dépasser les limites.
GetColumnValue<T> Task<T> Récupère une seule valeur de colonne d’une ligne de table.
Retrieve Task<JObject> Récupère un enregistrement.
RetrieveMultiple Task<RetrieveMultipleResponse> Récupère plusieurs enregistrements.
SetColumnValue<T> Task Définit la valeur d’une colonne pour une ligne de table.
Update Task Met à jour un enregistrement.
Upsert Task<UpsertResponse> Effectue une opération Upsert sur un enregistrement.

Dans un exemple d’application utilisant WebAPIService, lorsque l’opération ne représente pas une API trouvée dans Dataverse par défaut, la méthode est définie dans l’application plutôt que dans le WebAPIService.

Par exemple, l’Exemple de fonctions et d’actions d’API Web (C#) utilise une API personnalisée qui n’est pas incluse dans Dataverse jusqu’à ce qu’une solution contenant l’API personnalisée soit installée. La définition de cette méthode se trouve dans l’exemple d’application qui l’utilise : FunctionsAndActions/Methods/IsSystemAdmin.cs

Types

Le dossier Types contient toutes les classes ou énumérations qui correspondent à ComplexTypes ou EnumTypes nécessaires en tant que paramètres ou propriétés de réponse pour les messages.

Metadata

Le dossier Metadata contient Messages et Types spécifiques aux opérations qui utilisent les définitions de schéma Dataverse. Ces classes possèdent souvent de nombreuses propriétés qui renvoient des types complexes. Ces types sont utilisés dans l’exemple d’opérations de schéma de table de l’API web (C#).

Voir aussi

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#)
Exemple d’opérations de schéma de table de l’API web (C#)
Exemple d′opérations parallèles de l′API web WebApiService (C#)
Exemple d’opérations parallèles d’API Web avec des composants de flux de données TPL (C#)

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