Partager via

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

  • Article

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 ils peuvent découvrir des tables, colonnes et options de choix à l’aide d’IntelliSense.
  • Fournit la classe OrganisationServiceContext pour vous permettre d’écrire des requêtes Dataverse avec LINQ et d’autres fonctionnalités fonctionnent avec des données.

En savoir plus :

Utilisez la commande pac modelbuilder bluid de Power Platform CLI pour générer des classes de code à 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 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 où tous les autres paramètres disponibles peuvent être contrôlés. De cette façon, il n’est pas nécessaire de composer une longue liste de paramètres et la configuration appropriée pour votre projet peut être mise à jour pour permettre la régénération des classes lorsque vous en avez besoin.

Bien sûr, vous pouvez toujours utiliser la commande build avec les paramètres si vous préférez. Voir Utilisation des paramètres.

Démarrage

Avant de commencer :

  1. Installer Power Platform CLI
  2. Connectez-vous à votre environnement à l’aide des commandes pac auth de Power Platform CLI.

Procédez comme suit pour commencer :

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

  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
}

    Notes

    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 à liaison anticipée pour l’environnement connecté en utilisant les paramètres définis dans builderSettings.json, où C:\projects\exampleproject\ représente le chemin d’accès à votre projet et model est le 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 répertoire exampleproject :

    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, voici le résultat auquel vous devez vous attendre :

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, notez qu’elle génère uniquement des classes pour les tables spécifiées par entityNamesFilter et uniquement les messages spécifiés dans messageNamesFilter. Vous devez spécifier les tables (entités) et les messages que vous utilisez dans votre projet. Sinon, les classes pour toutes les tables et tous les messages sont générées.

Pour messageNamesFilter, vous pouvez utiliser * comme caractère générique dans ces valeurs. Ceci 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 pouvez contrôler dans le fichier de paramètres :

  • Les classes d’entité sont écrites dans le dossier spécifié par le paramètre entityTypesFolder.
  • Les classes de message sont écrites dans le dossier spécifié par le paramètre messagesTypesFolder.
  • La classe OrganizationServiceContext est écrite dans un fichier avec le nom spécifié par le paramètre serviceContextName.
  • Toutes les classes font partie de l’espace de noms que vous définissez dans le paramètre namespace.

Notes

Si vous générez des classes de messages, vous devez toujours inclure un nom pour le paramètre serviceContextName. Consultez Inclure serviceContextName lors de la génération de classes de messages

Voici comment les fichiers et dossiers apparaissent dans Visual Studio :

Exemple de sortie de la commande pac modelbuilder build dans l’explorateur Visual Studio

Avec ces fichiers écrits dans votre projet, vous êtes maintenant prêt à 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

Il n’est pas nécessaire d’utiliser le fichier de paramètres builderSettings.json et le paramètre --settingsTemplateFile avec pac modelbuilder build. Vous pouvez appeler la commande directement en utilisant les paramètres. Vous pouvez trouver la documentation de référence et des exemples dans la Documentation de référence de pac modelbuilder build.

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

Voici un exemple montrant comment générer des fichiers avec les mêmes paramètres que l’exemple dans la section Démarrer en utilisant des 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 builderSettings.json suivant dans le dossier model :

{
  "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 messages, vous devez toujours inclure un nom pour le paramètre serviceContextName afin qu’une classe OrganisationServiceContext 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 paramètre OrganizationServiceContext, vous obtiendrez l’erreur suivante lorsque vous tenterez 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 Générateur à liaison anticipée V2 est un plug-in XrmToolBox créé par la communauté pour fournir une interface utilisateur et de nombreuses autres configurations pour générer des types à liaison anticipée.

Notes

Les outils de la communauté ne sont pas un produit de Microsoft et n′étendent pas le support aux outils de la communauté. Si vous avez des questions relatives à cet outil, contactez l′éditeur. Pour plus d′informations : XrmToolBox.

Pour Dynamics 365 Customer Engagement on-premises

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

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

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