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

  • Artículo

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

  • Mejora la legibilidad y el mantenimiento del código.
  • Disminuye el riesgo de errores porque proporcionan verificación de tipos en tiempo de compilación.
  • Mejora la productividad de los desarrolladores porque pueden descubrir tablas, columnas y opciones de elección mediante IntelliSense.
  • Proporciona la clase OrganizationServiceContext para que pueda escribir consultas Dataverse que utilizan LINQ y otras capacidades 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. Utilice este parámetro para hacer referencia a un archivo JSON donde se pueden controlar todas las demás configuraciones disponibles. De esta manera, no necesita redactar una larga lista de parámetros y la configuración apropiada para su proyecto se puede actualizar para permitir la regeneración de las clases cuando las necesite.

Por supuesto, aún puede usar el comando de compilación con parámetros si lo prefiere. Consulte Uso de parámetros.

Tareas iniciales

Antes de comenzar:

  1. Instale Power Platform CLI.
  2. Conéctese a su entorno mediante comandos de Power Platform CLI pac auth.

Use los siguientes pasos para comenzar:

  1. En su proyecto .NET, agregue una referencia de paquete NuGet para:

  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. Utilice el siguiente comando para generar clases enlazadas tempranamente para el entorno conectado utilizando la configuración definida en builderSettings.json donde C:\projects\exampleproject\ representa la ruta a su proyecto y model es la carpeta que ha creado.

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

    Este comando usa estos parámetros:

    • -o acceso directo para el parámetro --outdirectory con un valor de ., para indicar el directorio actual.
    • acceso directo -stf para el parámetro --settingsTemplateFile con un valor de .\builderSettings.json, para indicar el directorio actual builderSettings.json.

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

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

Comprender qué archivos están escritos

Con cualquiera de los comandos, el siguiente es el resultado que debería esperar:

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>

Cuando inspecciona la salida, observe que solo genera clases para las tablas especificadas por entityNamesFilter y solo los mensajes especificados en messageNamesFilter. Debe especificar qué tablas (entidades) y mensajes utiliza en su proyecto. De lo contrario, se generan clases para todas las tablas y mensajes.

Para messageNamesFilter, puede usar * como carácter comodín en estos valores. Esto resulta útil cuando los mensajes de su solución comparten un prefijo de personalización común.

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

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

Nota

Si está generando clases de mensajes, siempre debe incluir un nombre para la configuración serviceContextName. Consulte Incluir serviceContextName al generar clases de mensajes

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 utilizar el archivo de configuración builderSettings.json y el parámetro --settingsTemplateFile con pac modelbuilder build. Puede invocar el comando usando parámetros directamente. Puede encontrar documentación de referencia y ejemplos en la documentación de referencia de compilación de pac modelbuilder.

Si está utilizando el archivo de configuración builderSettings.json y el parámetro --settingsTemplateFile, puede usar los parámetros en la línea de comando para anular la configuración.

A continuación se muestra un ejemplo que muestra cómo generar archivos con la misma configuración que el ejemplo de la sección Introducción usando 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

Esto 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 utiliza parámetros escribe el siguiente archivo builderSettings.json en la carpeta 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
}

Incluir serviceContextName al generar clases de mensajes

Si está generando clases de mensajes, siempre debe incluir un nombre para el parámetro serviceContextName para que una clase OrganizationServiceContext se genere con su 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 cuando intente utilizar 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

El Early Bound Generator V2 es un complemento XrmToolBox creado por la comunidad para proporcionar una interfaz de usuario y muchas otras configuraciones para generar tipos de enlace temprano.

Nota

Las herramientas de la comunidad no son un producto de Microsoft y no se incluyen en el soporte técnico. Si tiene alguna duda relacionada con la herramienta, póngase en contacto con el Editor. Más información: 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 en tiempo de ejecución y en tiempo de compilación
Ejemplo: operaciones de tabla de enlace anticipado
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

Nota

¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)

La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).