4.2 Generación de Clases con pac modelbuilder

Si decides usar Early-Bound (y para la mayoría de proyectos profesionales es la opción correcta), necesitas saber cómo generar las clases tipadas. Esta lección te guía por las diferentes herramientas disponibles y cómo integrar las clases generadas en tu proyecto.

Objetivos de aprendizaje

• Generar clases Early-Bound con Power Platform CLI
• Conocer alternativas como XrmToolBox y CrmSvcUtil
• Integrar las clases en tu proyecto correctamente
• Mantener las clases actualizadas cuando el esquema cambie

Power Platform CLI: el método moderno

Power Platform CLI (pac) es la herramienta oficial y más actualizada para generar clases Early-Bound. Ya deberías tenerla instalada del módulo anterior.

Paso 1: Autenticarse

Antes de generar clases, necesitas autenticarte contra el entorno de Dataverse:

pac auth create --url https://tuorganizacion.crm.dynamics.com

Esto abre una ventana de navegador para iniciar sesión. Una vez autenticado, las credenciales se guardan y puedes ejecutar comandos sin volver a autenticar.

Puedes verificar tus autenticaciones guardadas con:

pac auth list

Paso 2: Generar las clases

El comando principal es pac modelbuilder build. Tienes varias opciones:

# Generar solo entidades específicas (recomendado)
pac modelbuilder build --outdirectory ./Generated --entitynamesfilter "account;contact;opportunity;lead"

# Generar todas las entidades (archivo muy grande)
pac modelbuilder build --outdirectory ./Generated

# Especificar namespace personalizado
pac modelbuilder build --outdirectory ./Generated --entitynamesfilter "account;contact" --namespace "MiEmpresa.Dataverse.Entities"

Te recomiendo generar solo las entidades que realmente usas. Generar todas las entidades produce un archivo de cientos de KB o incluso varios MB, lo que aumenta el tamaño de tu DLL sin necesidad.

Paso 3: Añadir al proyecto

La generación crea archivos .cs en la carpeta especificada. Añádelos a tu proyecto de Visual Studio:

1. En Solution Explorer, clic derecho en el proyecto
2. Add → Existing Item
3. Selecciona los archivos .cs generados
4. Compila para verificar que no hay errores

Alternativamente, si la carpeta está dentro de tu proyecto, Visual Studio debería detectar automáticamente los archivos nuevos.

XrmToolBox: la alternativa visual

Si prefieres una interfaz gráfica, XrmToolBox tiene el plugin "Early Bound Generator" que ofrece una experiencia más visual.

Para usarlo:

1. Abre XrmToolBox y conecta a tu entorno
2. Busca e instala "Early Bound Generator" desde el Plugin Store
3. Abre la herramienta
4. Selecciona las entidades que quieres generar usando las checkboxes
5. Configura opciones como namespace y nombre del archivo
6. Clic en Create Entities

La ventaja de esta herramienta es que puedes ver visualmente todas las entidades disponibles y seleccionar exactamente cuáles incluir. También guarda tus preferencias para regeneraciones futuras.

CrmSvcUtil: el método clásico

CrmSvcUtil es la herramienta original de Microsoft para generar clases. Todavía funciona, pero es más complicada de usar que las alternativas modernas:

CrmSvcUtil.exe ^
  /connectionstring:"AuthType=OAuth;Url=https://tuorg.crm.dynamics.com;Username=usuario@tuorg.onmicrosoft.com" ^
  /out:Entities.cs ^
  /namespace:MiEmpresa.Dataverse.Entities ^
  /serviceContextName:DataverseContext

El problema principal es la autenticación. Con MFA habilitado (que es el estándar hoy), necesitas configurar OAuth correctamente, lo que puede ser complicado. Por eso recomiendo pac modelbuilder como primera opción.

Usando las clases en tu plugin

Una vez las clases están en tu proyecto, úsalas añadiendo el using correspondiente:

using MiEmpresa.Dataverse.Entities;  // Tu namespace

public class MiPlugin : IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        var context = (IPluginExecutionContext)
            serviceProvider.GetService(typeof(IPluginExecutionContext));
        var factory = (IOrganizationServiceFactory)
            serviceProvider.GetService(typeof(IOrganizationServiceFactory));
        
        IOrganizationService service = factory.CreateOrganizationService(context.UserId);
        
        // Convertir Target a tipo Early-Bound
        Entity target = (Entity)context.InputParameters["Target"];
        Account cuenta = target.ToEntity();
        
        // Usar propiedades tipadas
        string nombre = cuenta.Name;
        Money credito = cuenta.CreditLimit;
        EntityReference contactoPrincipal = cuenta.PrimaryContactId;
        
        // Crear nuevo registro con Early-Bound
        Contact nuevoContacto = new Contact
        {
            FirstName = "María",
            LastName = "García",
            ParentCustomerId = cuenta.ToEntityReference()
        };
        
        Guid nuevoId = service.Create(nuevoContacto);
        
        // Consultar con tipos específicos
        QueryExpression query = new QueryExpression(Account.EntityLogicalName);
        query.ColumnSet = new ColumnSet(
            nameof(Account.Name).ToLower(),
            nameof(Account.Telephone1).ToLower()
        );
        
        EntityCollection resultados = service.RetrieveMultiple(query);
        foreach (Entity e in resultados.Entities)
        {
            Account acc = e.ToEntity();
            string tel = acc.Telephone1;
        }
    }
}

El patrón de nombres de campos

Cuando usas nombres de campos en QueryExpression o ColumnSet, ten cuidado: los nombres lógicos en Dataverse son siempre minúsculas, pero las propiedades de las clases Early-Bound usan PascalCase.

// Los nombres lógicos son minúsculas
new ColumnSet("name", "telephone1", "creditlimit")

// Las propiedades son PascalCase
string nombre = cuenta.Name;

// Si quieres evitar strings, puedes hacer:
new ColumnSet(nameof(Account.Name).ToLower(), nameof(Account.Telephone1).ToLower())

Manteniendo las clases actualizadas

El esquema de Dataverse cambia: añades campos, creas entidades, modificas relaciones. Cuando esto sucede, las clases generadas quedan desactualizadas.

El proceso de actualización es simple:

1. Regenera las clases con la misma herramienta que usaste originalmente
2. Reemplaza los archivos antiguos con los nuevos
3. Compila el proyecto
4. Si hay errores, significa que algún código usaba algo que ya no existe
5. Una vez compilado, redespliega el plugin

Te recomiendo guardar el comando de generación en un script o documentarlo, para que cualquier miembro del equipo pueda regenerar las clases fácilmente.

Puntos clave

• pac modelbuilder build es la forma moderna y recomendada de generar clases
• Genera solo las entidades que necesitas para mantener el assembly pequeño
• XrmToolBox Early Bound Generator ofrece una alternativa visual
• Usa ToEntity<T>() para convertir de Entity genérico a tipo específico
• Los nombres lógicos son minúsculas, las propiedades PascalCase
• Regenera las clases cuando el esquema de Dataverse cambie

Para profundizar

• pac modelbuilder - Documentación oficial
• Early Bound Generator para XrmToolBox