Créer des classes d’entité à liaison anticipée à l’aide de l’outil de génération de code

Article
10/10/2023

Important

Si vous utilisez Dataverse, vous devez utiliser la Power Platform commande CLI pac modelbuilder build. CrmSvcUtil.exe fonctionne toujours avec Dataverse, mais nous vous recommandons d’utiliser la pac modelbuilder build commande en raison de l’expérience améliorée et des nouvelles fonctionnalités qui seront ajoutées. Apprenez-en davantage sur la génération de classes à liaison anticipée pour le SDK pour .NET avec Dataverse.

Étant donné que la Power Platform CLI n’est pas disponible pour Dynamics 365 Customer Engagement (on-premises), vous devez utiliser CrmSvcUtil.exe.

CrmSvcUtil.exe est un outil de génération de code de ligne de commande à utiliser avec Dynamics 365 for Customer Engagement. Cet outil génère des classes .NET Framework à liaison anticipée qui représentent le modèle de données d’entité utilisé par Dynamics 365 Customer Engagement (on-premises).

L’outil de génération de code (CrmSvcUtil.exe) est distribué dans le cadre du package Microsoft.CrmSdk.CoreTools NuGet. Pour plus d’informations sur le téléchargement de l’outil de génération de code (CrmSvcUtil.exe), voir Outils de développement Dataverse.

Générer des classes d’entité

L’outil CrmSvcUtil.exe crée un fichier de sortie Microsoft Visual C# ou Visual Basic .NET qui contient des classes fortement typées pour les tables de votre environnement. Cela inclut les tables et les colonnes personnalisées. Ce fichier de sortie contient une classe dérivée de Entity pour chaque table qui assure la liaison anticipée et la prise en charge IntelliSense dans Visual Studio pour vous aider lorsque vous écrivez du code. Les classes générées sont des classes partielles qui peuvent être étendues avec une logique métier personnalisée dans des fichiers distincts. Vous pouvez également écrire des extensions pour cet outil afin de personnaliser ses fonctionnalités. Pour plus d’informations, voir Créer des extensions pour l’outil de génération de code.

Générer une classe OrganizationServiceContext

L’outil permet également de générer une classe dérivée de la classe OrganizationServiceContext qui sert de conteneur d’entité dans l’EDM. Ce contexte de service fournit les installations de suivi des modifications et de gestion des entités, de l’accès concurrentiel et des relations. Cette classe expose également une méthode SaveChanges() qui écrit, insère, met à jour et supprime des lignes de table dans Dynamics 365 Customer Engagement (on-premises). Pour plus d’informations, consultez Utiliser OrganizationServiceContext.

Utiliser les classes générées

Les classes créées par l’outil de génération de code sont conçues pour être intégrées dans une bibliothèque de classes pouvant être référencée par les projets qui utilisent Dynamics 365 Customer Engagement (on-premises). Après avoir généré le ou les fichiers de classe à l’aide de l’outil, vous devez les ajouter à votre projet Visual Studio. Vous devez également ajouter les références à plusieurs assemblys dont dépendent les classes générées.

Voici les assemblys devant être référencés dans votre projet lorsque vous utilisez le fichier de code généré.

Microsoft.Crm.Sdk.Proxy.dll
Microsoft.Xrm.Sdk.dll

Ces assemblys font partie du package Microsoft.CrmSdk.CoreAssemblies ou Microsoft.PowerPlatform.Dataverse.Client NuGet. Utilisez l’un de ces packages NuGet pour ajouter les assemblys requis à votre projet Visual Studio.

Exécuter l’outil de génération de code

L’outil de génération de code accepte plusieurs paramètres qui déterminent le contenu du fichier créé. Les paramètres peuvent être transmis à partir de la ligne de commande lorsque vous exécutez l’outil, ou dans un fichier de configuration d’application .NET.

Exécutez l’application CrmSvcUtil.exe à partir du dossier où elle est installée. Si vous l’exécutez à partir d’un autre emplacement de dossier, assurez-vous qu’une copie de l’assembly Microsoft.Xrm.Sdk.dll se trouve dans le même dossier.

L’exemple suivant présente le format d’exécution de l’outil à partir de la ligne de commande avec Dynamics 365 Customer Engagement (on-premises). Pour utiliser une connexion d’environnement interactive, il vous suffit de fournir ces options :

CrmSvcUtil.exe /interactivelogin ^
/out:<outputFilename>.cs ^
/namespace:<outputNamespace> ^
/serviceContextName:<serviceContextName> ^
/generateActions

Lorsque vous exécutez l’outil avec l’option interactivelogin (raccourci il), une boîte de dialogue s’ouvre et vous pouvez préciser les identifiants de connexion ainsi que le serveur auquel vous souhaitez vous connecter.

Vous pouvez également préciser les paramètres que vous souhaitez transmettre directement dans la ligne de commande ou via un fichier (.bat) séquentiel que vous pouvez exécuter pour générer de nouvelles classes.

CrmSvcUtil.exe ^
/url:https://<organizationUrlName>.api.crm.dynamics.com/XRMServices/2011/Organization.svc ^
/out:<outputFilename>.cs ^
/username:<username> ^
/password:<password> ^
/namespace:<outputNamespace> ^
/serviceContextName:<serviceContextName>

Par exemple :

CrmSvcUtil.exe ^
/url:https://myorganization.api.crm.dynamics.com/XRMServices/2011/Organization.svc ^
/out:MyOrganizationSdkTypes.cs ^
/username:you@yourOrg.onmicrosoft.com ^
/password:myp455w0rd ^
/namespace:MyOrg ^
/serviceContextName:MyContext

Note

Les exemples utilisent le caractère (^) pour diviser la liste des paramètres pour une meilleure lisibilité. Vous pouvez composer les paramètres de commande avec des arguments à l’aide du Bloc-notes, puis les coller dans la ligne de commande.

Pour les paramètres username et password, saisissez le nom d’utilisateur et le mot de passe utilisés pour vous connecter à votre environnement Dynamics 365 Customer Engagement (on-premises).
Pour le paramètre url, vous pouvez rechercher l’URL correcte dans Power Apps ou dans l’application Web héritée en sélectionnant Paramètres, en accédant à Personnalisations, puis en choisissant Ressources du développeur. L’URL est affichée sous Service d’organisation.

Authentification basée sur les revendications

Les exemples suivants montrent comment utiliser l’outil de génération de code avec l’authentification basée sur les revendications. Notez que le nom d’utilisateur et le mot de passe sont des paramètres facultatifs. Si vos informations d’identification pour le serveur Dynamics 365 Customer Engagement (on-premises) cible sont stockées dans l’archivage sécurisé des informations d’identification Windows, il n’est pas nécessaire de les entrer pour exécuter l’outil de génération de code.

Active Directory

L’exemple suivant montre comment exécuter l’outil de génération de code à l’aide de l’authentification basée sur les revendications dans Active Directory. Notez l’utilisation de https, car cet exemple de serveur utilise Transport Layer Security (TLS) ou Secure Sockets Layer (SSL).

CrmSvcUtil.exe ^
/url:https://myport:555/MyOrg/XRMServices/2011/Organization.svc ^
/out:GeneratedCode.cs ^
/username:administrator ^
/password:myp455w0rd

Déploiement avec accès via Internet (IFD)

L’exemple suivant montre comment exécuter l’outil de génération de code à l’aide de l’authentification basée sur les revendications avec IFD.

CrmSvcUtil.exe ^
/url:https://myorg.crm.com:555/XRMServices/2011/Organization.svc ^
/out:GeneratedCode.cs ^
/username:administrator ^
/password:myp455w0rd

Paramètres

Pour afficher les derniers paramètres de ligne de commande pris en charge, utilisez la commande suivante.

CrmSvcUtil.exe /?

Le tableau suivant répertorie les paramètres de l’outil de génération de code au moment de la dernière mise à jour de cette rubrique et fournit une brève description de l’utilisation des paramètres de commande.

Paramètre	Raccourci	Description
`url`		URL du service d’organisation. Obligatoire, sauf si vous utilisez `interactivelogin`
`out`	`o`	Nom de fichier du code généré. Requise
`language`	`l`	Langage de génération du code. Les valeurs possibles sont « CS » ou « VB ». La valeur par défaut est « CS ».
`namespace`	`n`	Espace de noms du code généré. La valeur par défaut est l’espace de noms global.
`username`	`u`	Nom d’utilisateur à utiliser lorsque vous vous connectez au serveur pour l’authentification.
`password`	`p`	Mot de passe à utiliser lorsque vous vous connectez au serveur pour l’authentification.
`domain`	`d`	Domaine d’authentification lorsque vous vous connectez au serveur local.
`servicecontextname`		Nom de la classe de contexte générée. Si aucune valeur n’est fournie, aucun contexte de service n’est créé.
`help`	`?`	Affiche les informations d’utilisation.
`nologo`		Supprimer la bannière au moment de l’exécution.
`generateActions`		Génère les classes de demande et de réponse pour les actions personnalisées.
`interactivelogin`	`il`	Lorsqu’elle est utilisée, une boîte de dialogue de connexion au service Dynamics 365 Customer Engagement (on-premises) s’affiche. Tous les autres paramètres de connexion spécifiés sur la ligne de commande sont ignorés.
`connectionstring`	`connstr`	Contient des informations, fournies sous forme de chaîne unique, pour se connecter à une organisation Dynamics 365 Customer Engagement (on-premises). Tous les autres paramètres de connexion spécifiés sur la ligne de commande sont ignorés. Pour plus d’informations, voir Utiliser les chaînes de connexion des outils XRM.
`suppressGeneratedCodeAttribute`	`sgca`	Supprime le GeneratedCodeAttribute sur toutes les classes
`emitfieldsclasses`	`emitfc`	Génère une classe de champs par entité qui contient tous les noms de champs lors de la génération du code
`entitynamesfilter`		Filtre la liste des entités récupérées lors de la lecture des données à partir de Dynamics 365 Customer Engagement (on-premises). Transmis sous forme de liste séparée par des points-virgules en utilisant le formulaire <entitylogicalname>;<entitylogicalname>;...
`messagenamesfilter`		Filtre la liste des messages récupérés lors de la lecture des données de Dynamics 365 Customer Engagement (on-premises). Transmis en tant que liste séparée par des points-virgules. Les messages obligatoires (Create, Update, Delete, Retrieve, RetrieveMultiple, Associate et DisAssociate) sont toujours inclus. Un astérisque * peut être utilisé pour continuer ou suivre un message en autorisant tous les messages commençant ou se terminant par une chaîne. La liste prend du format <messagename>;<messagename>, ...
`splitfiles`		Divise le résultat en fichiers par type, organisés par entité, message et groupes d’options. lorsqu’elle est activée, la propriété `out` est ignorée et la propriété `outdirectory` est requise à la place
`outdirectory`	`outdir`	Écrit des fichiers d’entité, de message et de groupe d’options dans un répertoire de sortie spécifié. Valable uniquement avec l’option `splitfiles`
`entitytypesfolder`		Nom du dossier qui contiendra les entités. Le nom de dossier par défaut est « Entités ». Valable uniquement avec l’option `splitfiles`.
`messagestypesfolder`		Nom du dossier qui contiendra les messages. Le nom par défaut est « Messages ». Valable uniquement avec l’option `splitfiles`
`optionsetstypesfolder`		Nom du dossier qui contiendra les groupes d’options. Le nom par défaut est « OptionSets » Valable uniquement avec l’option `splitfiles`
`generateGlobalOptionSets`		Émet tous les groupes d’options globaux. Remarque : si une entité contient une référence à un groupe d’options global, elle est émise même si ce changement n’est pas présent
`legacyMode`		Désactive les groupes d’options d’émission et de nombreuses fonctionnalités de code plus récentes pour prendre en charge la compatibilité avec les anciennes extensions personnalisées

Utiliser le fichier de configuration

Le fichier de configuration CrmSvcUtil.exe.config doit se trouver dans le même dossier que l’outil CrmSvcUtil.exe. Il utilise les paires clé-valeur standard dans la section appSettings. Toutefois, si vous entrez une valeur dans la ligne de commande, cette valeur est utilisée à la place de celle contenue dans le fichier de configuration. Les paires clé-valeur disponibles dans le fichier de configuration d’application qui ne correspondent pas aux paramètres attendus sont ignorées.

N’incluez pas les paramètres url et namespace dans le fichier de configuration. Ceux-ci doivent être entrés à partir de la ligne de commande lorsque l’outil CrmSvcUtil.exe est exécuté.

L’exemple suivant montre comment configurer le fichier de sortie et les paramètres de nom de domaine dans le fichier de configuration d’application à l’aide de raccourcis clavier.

<appSettings>    
    <add key="o" value="CrmProxy.cs"/>    
    <add key="d" value="mydomain"/>
</appSettings>

Activer le traçage

Pour activer le traçage lorsque vous exécutez l’outil, ajoutez les lignes suivantes au fichier de configuration :

<system.diagnostics>   
   <trace autoflush="false" indentsize="4">   
      <listeners>   
         <add name="configConsoleListener" type="System.Diagnostics.ConsoleTraceListener">   
            <filter type="System.Diagnostics.EventTypeFilter" initializeData="Error" />   
         </add>   
      </listeners>   
   </trace>   
</system.diagnostics>

Pour plus d’informations sur les options de traçage prises en charge, voir Configurer le traçage pour les outils XRM.

Outils de la communauté

Early Bound Generator est un outil provenant de la communauté XrmToolbox. Consultez la rubrique Outils et ressources de développeur pour obtenir des outils supplémentaires développés par la communauté.