Crear las clases de entidad con enlace en tiempo de compilación con la herramienta de generación de código

Artículo
10/10/2023

Importante

Si está utilizando Dataverse, debe usar el comando de compilación Power Platform CLI pac modelbuilder. CrmSvcUtil.exe todavía funciona con Dataverse, pero recomendamos usar el comando pac modelbuilder build debido a la experiencia mejorada y las nuevas características que se agregarán. Obtenga más información sobre cómo generar clases enlazadas de forma anticipada para el SDK para .NET con Dataverse.

Debido a que la CLI de Power Platform no está disponible para Dynamics 365 Customer Engagement (on-premises), debe usar CrmSvcUtil.exe.

CrmSvcUtil.exe es una herramienta de generación de código de línea de comandos para usar con Dynamics 365 for Customer Engagement. Esta herramienta genera clases de enlace en tiempo de compilación de .NET Framework que representan el modelo de datos de la entidad usado por Dynamics 365 Customer Engagement (on-premises).

La herramienta de generación de código (CrmSvcUtil.exe) se distribuye como parte del paquete de NuGet Microsoft.CrmSdk.CoreTools. Para obtener información sobre cómo descargar la herramienta de generación de código (CrmSvcUtil.exe), consulte Herramientas de desarrollo de Dataverse.

Generar clases de entidad

La herramienta CrmSvcUtil crea un archivo de salida de Microsoft Visual C# o Visual Basic .NET que contiene las clases con establecimiento rígido de tipos para las tablas de su entorno. Esto incluye tablas y columnas personalizadas. Este archivo de salida contiene una clase derivada de Entity para cada tabla y brinda enlace en tiempo de compilación y soporte de IntelliSense en Visual Studio para ayudarlo a medida que escribe el código personalizado. Las clases generadas son las clases parciales que pueden ampliarse con lógica empresarial personalizada en archivos separados. También puede escribir extensiones para esta herramienta, para personalizar su funcionalidad. Para obtener más información, consulte Crear extensiones para la herramienta de generación de código.

Generar una clase OrganizationServiceContext

La herramienta también se puede usar para generar una clase derivada de clases de OrganizationServiceContext que actúa como un contenedor de entidad en EDM. Este contexto de servicio proporciona las instalaciones para realizar el seguimiento de los cambios y la administración de identidades, simultaneidad, y relaciones. Esta clase también expone un método de SaveChanges() que permite escribir insertos, actualizar y eliminar filas de tabla en Dynamics 365 Customer Engagement (on-premises). Para obtener más información, consulte Usar OrganizationServiceContext.

Use clases generadas

Las clases creadas por la herramienta de generación de códigos están diseñadas para integrarse a una biblioteca de clases referenciada por los proyectos que usan Dynamics 365 Customer Engagement (on-premises). Después de haber generado los archivos de clase mediante la herramienta, debería agregar los archivos al proyecto de Visual Studio. También deberá agregar referencias a varios ensamblados de los que dependen las clases generadas.

A continuación se enumeran los ensamblados a los que se debe hacer referencia en el proyecto cuando se usa el archivo de código generado.

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

Estos ensamblados forman parte de Microsoft.CrmSdk.CoreAssemblies o del paquete Microsoft.PowerPlatform.Dataverse.Client NuGet. Use uno de estos paquetes NuGet para agregar los ensamblados necesarios al proyecto de Visual Studio.

Ejecutar la herramienta de generación de código

La herramienta de generación de código toma varios parámetros que determinan los contenidos del archivo que se va a crear. Los parámetros se pueden efectuar desde la línea de comandos al ejecutar la herramienta o en un archivo de configuración de la aplicación conectado a .NET.

Ejecute la aplicación CrmSvcUtil.exe desde la carpeta donde está instalada. Si ejecuta la herramienta desde otra ubicación de la carpeta, asegúrese de que una copia del ensamblado Microsoft.Xrm.Sdk.dll se encuentre en la misma carpeta.

El siguiente ejemplo muestra el formato para ejecutar la herramienta desde la línea de comandos con Dynamics 365 Customer Engagement (on-premises). Para usar un inicio de sesión interactivo, puede proporcionar simplemente estas opciones:

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

Al ejecutar la herramienta con la opción interactivelogin (de acceso directo il), se abrirá un cuadró de diálogo y podrá especificar sus credenciales de inicio de sesión y el servidor al que desea conectarse.

También puede especificar los parámetros que desea transmitir directamente a la línea de comandos o mediante un archivo por lotes (.bat) puede ejecutar para generar nuevas clases.

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

Por ejemplo:

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

Nota

Los ejemplos usan el carácter (^) para desglosar la lista de parámetros para mejorar la legibilidad. Puede crear los parámetros de comando con argumentos mediante el bloc de notas y después pegándolos en la línea de comandos.

Para los parámetros username y password, escriba el nombre de usuario y la contraseña que se usan para iniciar sesión en su entorno de Dynamics 365 Customer Engagement (on-premises).
Para el parámetro url, puede buscar la dirección URL correcta en Power Apps, o en la aplicación web heredada seleccionando Configuración, navegando a Personalizaciones y luego eligiendo Recursos de desarrollador. La URL se muestra en Servicio de organización.

Autenticación basada en notificaciones

Los siguientes ejemplos muestran cómo usar la herramienta de generación de códigos con autenticación basada en notificaciones. Tenga en cuenta que el nombre de usuario y la contraseña son parámetros opcionales. Si las credenciales del servidor de destino de aplicaciones Dynamics 365 Customer Engagement (on-premises) se guardan en el almacén de credenciales de Windows, no tiene que proporcionarlas para ejecutar la herramienta de generación de códigos.

Active Directory

El siguiente ejemplo muestra cómo ejecutar la herramienta de generación de códigos mediante la autenticación de notificaciones en Active Directory. Tenga en cuenta el uso de https porque este servidor de ejemplo utiliza seguridad de la capa de transporte (TLS) o capa de sockets seguros (SSL).

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

Implementación con conexión a Internet (IFD)

El siguiente ejemplo muestra cómo ejecutar la herramienta de generación de códigos mediante la autenticación de notificaciones con IFD.

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

Parámetros

Para ver los últimos parámetros de línea de comandos admitidos, use el siguiente comando.

CrmSvcUtil.exe /?

La siguiente tabla enumera los parámetros de la herramienta de generación de código en el momento en que se actualizó por última vez este tema y proporciona una breve descripción del uso de los parámetros de comando.

Parámetro	Acceso directo	Descripción
`url`		La URL para el servicio de la organización. Requerido, a menos que use `interactivelogin`
`out`	`o`	El nombre de archivo para el código generado. Obligatorio
`language`	`l`	El idioma en el que generar el código. Puede ser "CS" o "VB". El valor predeterminado es "CS".
`namespace`	`n`	El espacio de nombres para el código generado. El valor predeterminado es el espacio de nombre global.
`username`	`u`	El nombre de usuario usado al conectar al servidor para la autenticación.
`password`	`p`	La contraseña de usuario usada al conectar al servidor para la autenticación.
`domain`	`d`	El dominio en el que se autentica al conectarse al servidor local.
`servicecontextname`		El nombre de la clase de contexto generada. Si no se proporciona un valor, no se crea ningún contexto del servicio.
`help`	`?`	Mostrar la información de uso.
`nologo`		Suprimir pancartas en tiempo de ejecución.
`generateActions`		Generar clases de solicitud y respuesta para acciones personalizadas.
`interactivelogin`	`il`	Cuando se utiliza, se mostrará un diálogo para iniciar sesión en el servicio Dynamics 365 Customer Engagement (on-premises). Se omiten todos los demás parámetros relacionados con la conexión especificados en la línea de comandos.
`connectionstring`	`connstr`	Contiene información, proporcionada como una sola cadena, para conectarse a una organización de Dynamics 365 Customer Engagement (on-premises). Se omiten todos los demás parámetros relacionados con la conexión especificados en la línea de comandos. Para obtener más información, consulte Usar cadenas de conexión en útiles de XRM.
`suppressGeneratedCodeAttribute`	`sgca`	Suprime GeneratedCodeAttribute en todas las clases
`emitfieldsclasses`	`emitfc`	Genera una clase Campos por entidad, que contiene todos los nombres de campo en el momento de generar el código
`entitynamesfilter`		Filtra la lista de entidades recuperadas al leer datos desde Dynamics 365 Customer Engagement (on-premises). Se pasa como una lista separada por punto y coma usando el formulario <entitylogicalname>;<entitylogicalname>;...
`messagenamesfilter`		Filtra la lista de mensajes que se recuperan al leer datos Dynamics 365 Customer Engagement (on-premises). Se pasa como una lista separada por punto y coma. Los mensajes requeridos (Crear, Actualizar, Eliminar, Recuperar, Recuperar varios, Asociar y Desasociar) siempre se incluyen. Los * pueden usarse para continuar o rastrear un mensaje, lo que permite que todos los mensajes comiencen o terminen con una cadena. La lista usa el formato <messagename>;<messagename>;...
`splitfiles`		Divide la salida en archivos por tipo, organizados por entidad, mensaje y conjuntos de opciones. cuando está habilitada, la propiedad `out` se ignora y en su lugar se requiere `outdirectory`
`outdirectory`	`outdir`	Entidad de escritura, mensaje y archivos de conjunto de opciones para un directorio de salida especificado. Válido solo con la opción `splitfiles`
`entitytypesfolder`		Nombre de carpeta que contendrá entidades. El nombre de carpeta predeterminado es "Entidades". Válido solo con la opción `splitfiles`.
`messagestypesfolder`		Nombre de carpeta que contendrá mensajes. El valor predeterminado es "Mensajes". Válido solo con la opción `splitfiles`
`optionsetstypesfolder`		Nombre de carpeta que contiene los conjuntos de opciones. El nombre predeterminado es "Conjuntos de opciones". Válido solo con la opción `splitfiles`
`generateGlobalOptionSets`		Emita todos los conjuntos de opciones globales. Nota: si una entidad contiene una referencia a un conjunto de opciones global, se emitirá aunque este modificador no esté presente
`legacyMode`		Deshabilite los conjuntos de opciones de emisión y muchas funciones de código más nuevas para admitir la compatibilidad con extensiones personalizadas más antiguas

Archivos el archivo de configuración

El archivo de configuración CrmSvcUtil.exe.config debe estar en la misma carpeta que la herramienta CrmSvcUtil.exe. El archivo de configuración usa los pares clave/valor estándar en la sección appSettings. Sin embargo, si introduce un valor en la línea de comandos, ese valor se usará en lugar del que aparece en el archivo de configuración. Se ignorarán todos los pares clave/valor que se encuentran en el archivo de configuración de la aplicación que no coinciden con los parámetros esperados.

En el archivo de configuración no se incluyen los parámetros url y namespace. Deben introducirse desde la línea de comandos cuando se ejecuta la herramienta CrmSvcUtil.exe.

El siguiente ejemplo muestra cómo configurar el archivo de salida y los parámetros del nombre de dominio del archivo de configuración de la aplicación mediante las teclas de método abreviado.

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

Habilitar seguimiento

Para habilitar el seguimiento luego de ejecutar la herramienta, agregue las siguientes líneas al archivo de configuración:

<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>

Para obtener más información acerca de las opciones de seguimiento admitidas, consulte Configurar el seguimiento de útiles de XRM.

Herramientas de la Comunidad

Generador de enlace en tiempo de compilación es una herramienta de la comunidad XrmToolbox. Consulte el tema Herramientas y recursos para desarrolladores para obtener información sobre herramientas desarrolladas por la comunidad.