Generar clases de enlace en tiempo de compilación para SDK para .NET

Creación de clases enlazadas anticipadamente para sus proyectos .NET:

  • Mejora la legibilidad y el mantenimiento del código.
  • Reduce el riesgo de errores, ya que ofrecen verificación de tipos en tiempo de compilación.
  • Mejora la productividad del desarrollador porque los desarrolladores pueden detectar tablas, columnas y opciones de elección mediante IntelliSense.
  • Proporciona la clase OrganizationServiceContext para que pueda escribir consultas de Dataverse mediante LINQ y otras funcionalidades que funcionan con datos.

Más información:

Use el comando de Power Platform CLI pac modelbuilder build para generar clases de código enlazadas anticipadamente. También puede utilizar la herramienta de generación de código CrmSvcUtil.exe, pero para Dataverse recomendamos utilizar el comando pac modelbuilder build. Aprenda a utilizar CrmSvcUtil.exe para generar clases enlazadas anticipadamente para el SDK para .NET

Como muchos comandos de Power Platform CLI, pac modelbuilder build tiene muchos parámetros que puede utilizar para controlar el resultado. En este artículo, le recomendamos que comience utilizando el parámetro --settingsTemplateFile para la mayoría de los casos de uso. Use este parámetro para hacer referencia a un archivo JSON donde puede controlar todas las demás opciones de configuración disponibles. De este modo, no es necesario crear una larga lista de parámetros y puede actualizar la configuración adecuada para que el proyecto permita la regeneración de las clases cuando las necesite.

Si lo prefiere, puede usar el comando build con parámetros. Consulte Uso de parámetros.

Comenzar

Antes de comenzar:

  1. Instale Power Platform CLI.
  2. Conéctese a su entorno mediante comandos de autenticación pac de la CLI de Power Platform.

Use los siguientes pasos para comenzar:

  1. En el proyecto de .NET, agregue una referencia a un paquete NuGet para una de estas opciones:

  2. Crear una carpeta llamada model.

  3. En la carpeta model, agregue un archivo builderSettings.json con la siguiente configuración:

    {
"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
}

    Nota

    Este archivo es una versión modificada del archivo que puede generar usando pac modelbuilder build con el parámetro --writesettingsTemplateFile. Aprenda cómo generar el archivo sin comentarios en Usando parámetros.

  4. Use el siguiente comando para generar clases enlazadas tempranas para el entorno conectado mediante la configuración definida en builderSettings.json. La ruta C:\projects\exampleproject\ indica la ruta de acceso a tu proyecto y model es la carpeta que has creado.

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

    Este comando usa estos parámetros:

    • -o forma abreviada del parámetro obligatorio --outdirectory con un valor de ., para indicar el directorio actual.
    • abreviatura -stf para el parámetro --settingsTemplateFile con el valor de .\builderSettings.json, para indicar el builderSettings.json directorio actual.

    También puede usar este comando desde el exampleproject directorio :

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

Comprender qué archivos están escritos

Con cualquiera de estos comandos, obtendrá la siguiente salida:

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>

Al inspeccionar la salida, verá que solo genera clases para las tablas especificadas por entityNamesFilter y solo los mensajes especificados en .messageNamesFilter Especifique qué tablas (entidades) y mensajes se usan en el proyecto. De lo contrario, el comando genera clases para todas las tablas y mensajes.

Para messageNamesFilter, use * como carácter comodín en estos valores. Este filtro es útil cuando los mensajes de la solución comparten un prefijo de personalización común.

pac modelbuilder build escribe los archivos en carpetas con nombres que controla en el archivo de configuración:

  • Las clases de entidad se guardan en la carpeta especificada en la configuración entityTypesFolder.
  • Las clases de mensajes se dirigen a la carpeta especificada en la configuración messagesTypesFolder.
  • La clase OrganizationServiceContext va a un archivo con el nombre especificado por la serviceContextName configuración.
  • Todas las clases son parte del espacio de nombres que configuró en la configuración namespace.

Nota

Si va a generar clases de mensaje, incluya siempre un nombre para la serviceContextName configuración. Consulte Incluir serviceContextName al generar clases de mensaje.

Así aparecen los archivos y carpetas en Visual Studio:

Ejemplo de resultado del comando de compilación pac modelbuilder en Visual Studio Explorer

Con estos archivos escritos en su proyecto, ahora está listo para usar clases enlazadas anticipadamente.

Si desea cambiarlos, elimine los archivos en la carpeta model que no sea builderSettings.json, cambie la configuración en builderSettings.json y generelos nuevamente.

Uso de parámetros

No es necesario usar el builderSettings.json archivo de configuración ni el --settingsTemplateFile parámetro con pac modelbuilder build. Puede invocar el comando mediante parámetros directamente. Para obtener documentación de referencia y ejemplos, consulte la documentación de referencia de compilación de pac modelbuilder.

Si usa el builderSettings.json archivo de configuración y el --settingsTemplateFile parámetro , puede usar parámetros de línea de comandos para invalidar esa configuración.

Este es un ejemplo que muestra cómo generar archivos mediante la misma configuración que el ejemplo de la sección Introducción mediante parámetros:

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

Este ejemplo no incluye todas las configuraciones porque usa las opciones predeterminadas. Si usa el parámetro --writesettingsTemplateFile para generar un archivo builderSettings.json, no incluye los comentarios en el ejemplo en la Sección de introducción de este artículo. El ejemplo que usa parámetros escribe el siguiente builderSettings.json archivo en la model carpeta :

{
  "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
}

Incluir serviceContextName al generar clases de mensajes

Si va a generar clases de mensaje, incluya siempre un nombre para el serviceContextName parámetro para que se genere una clase OrganizationServiceContext con el código. Esta clase incluye una propiedad importante para permitir el uso de clases de mensajes generados. Si no incluye un OrganizationServiceContext, obtendrá el siguiente error al intentar usar las clases de mensajes generadas.

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.

Herramientas de la Comunidad

Early Bound Generator V2 es un complemento de XrmToolBox creado por la comunidad que proporciona una interfaz de usuario para generar el archivo builderSettings.json correcto y ejecutar el comando pac modelbuilder build por el usuario. Puesto que la interfaz de usuario solo genera el archivo builderSettings.json y ejecuta el comando pac modelbuilder build, aún puede ejecutar el comando en una canalización sin depender de XrmToolBox. El complemento también proporciona opciones de configuración que pac modelbuilder no proporciona. Por ejemplo, proporciona la capacidad de controlar explícitamente la ordenación de clases y propiedades y la transliteración específica del lenguaje de caracteres. Early Bound Generator V2 puede hacer esto usando las funciones de extensibilidad de pac modelbuilder.

Nota

Microsoft no amplía el soporte técnico a las herramientas desarrolladas por la comunidad. Si tiene alguna pregunta sobre la herramienta, póngase en contacto con el publicador. Para obtener más información, vea XrmToolBox.

Para Dynamics 365 Customer Engagement local

El Power Platform CLI no está disponible para Dynamics 365 Customer Engagement local. Debe utilizar la herramienta de generación de código CrmSvcUtil.exe para generar clases enlazadas tempranamente. Aprenda a utilizar CrmSvcUtil.exe para generar clases enlazadas anticipadamente para el SDK para .NET

Programación con vinculación tardía y vinculación temprana
Ejemplo: operaciones de tabla con enlace temprano
Herramientas y recursos de desarrollo
Herramientas de desarrollo de Dataverse
Aprenda a utilizar CrmSvcUtil.exe para generar clases enlazadas anticipadamente para el SDK para .NET

  • Se actualizó por última vez el