Générer des classes à liaison anticipée pour le SDK pour .NET

Création de classes à liaison anticipée pour vos projets .NET :

• Améliore la lisibilité et la maintenabilité du code.
• Diminue le risque d’erreurs car elles fournissent une vérification du type au moment de la compilation.
• Améliore la productivité des développeurs, car les développeurs peuvent découvrir des tables, des colonnes et des options de choix à l’aide d’IntelliSense.
• Fournit la classe OrganizationServiceContext afin de pouvoir écrire des requêtes Dataverse à l’aide de LINQ et d’autres fonctionnalités fonctionnent avec des données.

En savoir plus :

• Programmation à liaison tardive et à liaison précoce
• Utiliser OrganizationServiceContext

Utilisez la commande pac modelbuilder build de Power Platform CLI pour générer des classes de code de liaison anticipée. Vous pouvez également utiliser l’outil de génération de code CrmSvcUtil.exe, mais pour Dataverse, nous vous recommandons d’utiliser la commande pac modelbuilder build. Découvrez comment utiliser l’outil CrmSvcUtil.exe pour générer des classes à liaison anticipée pour le SDK pour .NET

Comme beaucoup de commandes Power Platform CLI, pac modelbuilder build a de nombreux paramètres que vous pouvez utiliser pour contrôler le résultat. Dans cet article, nous vous recommandons de commencer par utiliser le paramètre --settingsTemplateFile pour la plupart des cas d’utilisation. Utilisez ce paramètre pour faire référence à un fichier JSON dans lequel vous pouvez contrôler tous les autres paramètres disponibles. De cette façon, vous n’avez pas besoin de composer une longue liste de paramètres et vous pouvez mettre à jour la configuration appropriée pour votre projet afin d’autoriser la régénération des classes lorsque vous en avez besoin.

Vous pouvez toujours utiliser la commande build avec des paramètres si vous préférez. Voir Utilisation des paramètres.

Démarrage

Avant de commencer :

1. Installer l’interface de ligne de commande Power Platform
2. Connectez-vous à votre environnement en utilisant les commandes Power Platform CLI pac auth.

Procédez comme suit pour commencer :

1. Dans votre projet .NET, ajoutez une référence de package NuGet à :

   • Pour une application client : Microsoft.PowerPlatform.Dataverse.Client
   • Pour un projet de plug-in Dataverse : Microsoft.CrmSdk.CoreAssemblies

2. Créez un dossier appelé model.

3. Dans le dossier model, ajoutez un fichier builderSettings.json avec les paramètres suivants :

   {
   "emitentityetc-comment": "Generate a constants structure that contains all of the field names by entity at the time of code generation.",
   "emitEntityETC": false,
   "emitfieldsclasses-comment": "Generate a constants structure that contains all of the field names by entity at the time of code generation.",
   "emitFieldsClasses": false,
   "emitvirtualattributes-comment": "When set, includes the Virtual Attributes of entities in the generated code.",
   "emitVirtualAttributes": false,
   "entitynamesfilter-comment": "Filters the list of entities are retrieved when reading data from Dataverse.",
   "entityNamesFilter": [
      "account",
      "contact"
   ],
   "entitytypesfolder-comment": "Folder name that contains entities.",
   "entityTypesFolder": "Entities",
   "generateGlobalOptionSets-comment": "Emit all Global OptionSets. Note: If an entity contains a reference to a global optionset, it is emitted even if this switch is not present.",
   "generateGlobalOptionSets": false,
   "generatesdkmessages-comment": "When set, emits Sdk message classes as part of code generation",
   "generateSdkMessages": true,
   "language-comment": "The language to use for the generated proxy code. This value can be either 'CS' or 'VB'. The default language is 'CS'.",
   "language": "CS",
   "logLevel-comment": "Log level. The default value is 'Off'.",
   "logLevel": "Off",
   "messagenamesfilter-comment": "Filters the list of messages that are retrieved when reading data from Dataverse.",
   "messageNamesFilter": [
      "searchautocomplete",
      "searchquery",
      "sample_*"
   ],
   "messagestypesfolder-comment": "Folder name that contains messages.",
   "messagesTypesFolder": "Messages",
   "namespace-comment": "The namespace for the generated code.",
   "namespace": "ExampleProject",
   "optionsetstypesfolder-comment": "Folder name that contains option sets.",
   "optionSetsTypesFolder": "OptionSets",
   "serviceContextName-comment": "The name for the generated service context. If a value is passed in, it's used for the Service Context. If not, no Service Context is generated.",
   "serviceContextName": "OrgContext",
   "suppressGeneratedCodeAttribute-comment": "When set, this suppress all generated objects being tagged with the code generation engine and version",
   "suppressGeneratedCodeAttribute": true,
   "suppressINotifyPattern-comment": "When enabled, doesn't write the INotify wrappers for properties and classes.",
   "suppressINotifyPattern": true
   }
   

   Remarque

   Ce fichier est une version modifiée du fichier que vous pouvez générer en utilisant pac modelbuilder build avec le paramètre --writesettingsTemplateFile. Découvrez comment générer le fichier sans commentaires dans Utilisation des paramètres.

4. Utilisez la commande suivante pour générer des classes liées anticipées pour l’environnement connecté à l’aide des paramètres définis dans builderSettings.json. Le C:\projects\exampleproject\ chemin d’accès représente le chemin d’accès à votre projet et model correspond au dossier que vous avez créé.

   PS C:\projects\exampleproject\model> pac modelbuilder build -o . -stf .\builderSettings.json
   

   Cette commande utilise ces paramètres :

   • Raccourci -o pour le paramètre --outdirectory obligatoire avec une valeur de ., pour indiquer le répertoire actuel.
   • Raccourci -stf pour le paramètre --settingsTemplateFile avec une valeur de .\builderSettings.json, pour indiquer le répertoire actuel builderSettings.json.

   Vous pouvez également utiliser cette commande à partir du exampleproject répertoire :

   PS C:\projects\exampleproject>pac modelbuilder build -o model -stf model\builderSettings.json
   

Comprendre quels fichiers sont écrits

Avec l’une ou l’autre commande, vous recevez la sortie suivante :

Connected to... Your Organization
Connected as you@yourorganization.onmicrosoft.com
Begin reading metadata from MetadataProviderService
      Begin Reading Metadata from Server
      Read 2 Entities - 00:00:00.732
      Read 0 Global OptionSets - 00:00:00.000
      Read 12 SDK Messages - 00:00:00.889
      Completed Reading Metadata from Server - 00:00:01.694
Completed reading metadata from MetadataProviderService - 00:00:01.697
Begin Writing Code Files
      Processing 2 Entities
      Wrote 2 Entities - 00:00:00.0625873
      Processing 12 Messages
      Wrote 3 Message(s). Skipped 9 Message(s) - 00:00:00.0091589
      Processing 0 Global OptionSets
      Wrote 0 Global OptionSets - 00:00:00.0000045
      Code written to C:\projects\exampleproject\model\Entities\account.cs.
      Code written to C:\projects\exampleproject\model\Entities\contact.cs.
      Code written to C:\projects\exampleproject\model\Messages\searchquery.cs.
      Code written to C:\projects\exampleproject\model\Messages\searchautocomplete.cs.
      Code written to C:\projects\exampleproject\model\OrgContext.cs.
      Code written to C:\projects\exampleproject\model\EntityOptionSetEnum.cs.
Completed Writing Code Files - 00:00:00.116
Generation Complete - 00:00:01.815
PS C:\projects\exampleproject\model>

Lorsque vous inspectez la sortie, vous voyez qu’elle génère uniquement des classes pour les tables spécifiées par entityNamesFilter et uniquement les messages spécifiés dans le messageNamesFilter. Spécifiez les tables (entités) et les messages que vous utilisez dans votre projet. Sinon, la commande génère des classes pour toutes les tables et tous les messages.

Pour messageNamesFilter, utilisez * comme caractère générique dans ces valeurs. Ce filtre est utile lorsque les messages de votre solution partagent un préfixe de personnalisation commun.

pac modelbuilder build écrit les fichiers dans des dossiers avec des noms que vous contrôlez dans le fichier de paramètres :

• Les classes d’entité vont au dossier spécifié par le entityTypesFolder paramètre.
• Les classes de message vont au dossier spécifié par le messagesTypesFolder paramètre.
• La classe OrganizationServiceContext accède à un fichier portant le nom spécifié par le serviceContextName paramètre.
• Toutes les classes font partie de l’espace de noms que vous définissez dans le paramètre namespace.

Remarque

Si vous générez des classes de message, incluez toujours un nom pour le serviceContextName paramètre. Voir Inclure serviceContextName lors de la génération de classes de message.

Voici comment les fichiers et dossiers apparaissent dans Visual Studio :

Une fois ces fichiers ajoutés à votre projet, vous pouvez désormais utiliser les classes à liaison anticipée.

Si vous souhaitez les modifier, supprimez les fichiers du dossier model autre que builderSettings.json, modifiez les paramètres dans builderSettings.json et générez-les à nouveau.

Utilisation des paramètres

Vous n’avez pas besoin d’utiliser le builderSettings.json fichier de paramètres ou le --settingsTemplateFile paramètre avec pac modelbuilder build. Vous pouvez appeler la commande à l’aide de paramètres directement. Pour obtenir de la documentation de référence et des exemples, consultez la documentation de référence de build pac modelbuilder.

Si vous utilisez le builderSettings.json fichier de paramètres et le --settingsTemplateFile paramètre, vous pouvez utiliser des paramètres de ligne de commande pour remplacer ces paramètres.

Voici un exemple qui montre comment générer des fichiers à l’aide des mêmes paramètres que l’exemple de la section Prise en main à l’aide de paramètres :

PS C:\>pac modelbuilder build `
   --outdirectory C:\projects\exampleproject\model `
   --entitynamesfilter 'account;contact' `
   --generatesdkmessages `
   --messagenamesfilter 'searchautocomplete;searchquery;sample_*' `
   --namespace ExampleProject `
   --serviceContextName OrgContext `
   --suppressGeneratedCodeAttribute `
   --suppressINotifyPattern `
   --writesettingsTemplateFile

Cet exemple n’inclut pas tous les paramètres, car il utilise les options par défaut. Si vous utilisez le paramètre --writesettingsTemplateFile pour générer un fichier builderSettings.json, il n’inclut pas les commentaires dans l’exemple dans la section Démarrer de cet article. L’exemple qui utilise des paramètres écrit le fichier suivant builderSettings.json dans le model dossier :

{
  "suppressINotifyPattern": true,
  "suppressGeneratedCodeAttribute": true,
  "language": "CS",
  "namespace": "ExampleProject",
  "serviceContextName": "OrgContext",
  "generateSdkMessages": true,
  "generateGlobalOptionSets": false,
  "emitFieldsClasses": false,
  "entityTypesFolder": "Entities",
  "messagesTypesFolder": "Messages",
  "optionSetsTypesFolder": "OptionSets",
  "entityNamesFilter": [
    "account",
    "contact"
  ],
  "messageNamesFilter": [
    "searchautocomplete",
    "searchquery",
    "sample_*"
  ],
  "emitEntityETC": false,
  "emitVirtualAttributes": false
}

Inclure serviceContextName lors de la génération de classes de messages

Si vous générez des classes de message, incluez toujours un nom pour le serviceContextName paramètre afin qu’une classe OrganizationServiceContext soit générée avec votre code. Cette classe comprend une propriété importante qui permet d’utiliser les classes de messages générées. Si vous n’incluez pas de OrganizationServiceContext, vous obtenez l’erreur suivante lorsque vous essayez d’utiliser les classes de messages générées.

The formatter threw an exception while trying to deserialize the message: 
There was an error while trying to deserialize parameter http://schemas.microsoft.com/xrm/2011/Contracts/Services:request. 
The InnerException message was 'Error in line 1 position 700. Element 'http://schemas.microsoft.com/xrm/2011/Contracts/Services:request' contains data from a type that maps to the name 'http://schemas.microsoft.com/xrm/2011/new/:<your generated class name>'. 
The deserializer has no knowledge of any type that maps to this name. 
Consider changing the implementation of the ResolveName method on your DataContractResolver to return a non-null value for name '<your generated class name>' and namespace 'http://schemas.microsoft.com/xrm/2011/new/'.'.  
Please see InnerException for more details.

Outils de la communauté

Le Early Bound Generator V2 est un plug-in XrmToolBox créé par la communauté pour offrir une interface utilisateur permettant de générer le fichier builderSettings.json approprié et d’exécuter la commande pac modelbuilder build pour l’utilisateur. Étant donné que l’interface utilisateur génère uniquement le builderSettings.json fichier et appelle la pac modelbuilder build commande, vous pouvez toujours exécuter la commande dans un pipeline sans dépendance sur XrmToolBox. Le plug-in offre également des options de configuration que le pac modelbuilder n’offre pas. Par exemple, il permet de contrôler explicitement la classe et la casse des propriétés et la translittération spécifique à la langue des caractères. Le générateur à liaison anticipée V2 peut le faire à l’aide des fonctionnalités d’extensibilité du pac modelbuilder.

Remarque

Microsoft n'étend pas le support aux outils développés par la communauté. Si vous avez des questions sur l’outil, contactez l’éditeur. Pour plus d’informations, consultez XrmToolBox.

Pour Dynamics 365 Customer Engagement sur site

Power Platform CLI n’est pas disponible pour Dynamics 365 Customer Engagement on-premises. Vous devez utiliser l’outil de génération de code CrmSvcUtil.exe pour générer des classes à liaison anticipée. Découvrez comment utiliser CrmSvcUtil.exe pour générer des classes à liaison anticipée pour le SDK pour .NET

Articles associés

Programmation avec liaison tardive et anticipée
Exemple : Opérations de table à liaison anticipée
Outils et ressources de développeur
Outils de développement Dataverse
Découvrez comment utiliser CrmSvcUtil.exe pour générer des classes à liaison anticipée pour le SDK pour .NET