Ejercicio: Escribir el primer complemento

30 minutos

En este escenario, las organizaciones necesitan que los datos del número de teléfono se introduzcan en un formato uniforme. Para lograr este objetivo, creará un complemento que se ejecutará en la creación/actualización y que eliminará todos los caracteres no numéricos de un número de teléfono antes de guardarlo en Dataverse. Luego, creará otro complemento que se ejecutará en la acción retrieve/retrievemultiple de contactos para reformatear el número de teléfono de modo que incluya paréntesis y guiones, en caso de que sea necesario.

Ejercicio 1: Crear/actualizar complemento

En este ejercicio, creará un complemento que se ejecutará en la creación y actualización. Este complemento eliminará todos los caracteres no numéricos de un número de teléfono.

Cada ejercicio consiste en un escenario y objetivos de aprendizaje. Este escenario describe el propósito de los ejercicios, mientras que los objetivos se enumeran y tienen distintos puntos.

Nota

Si no tiene las herramientas de Dynamics 365 SDK, consulte Descargar herramientas de NuGet para descargarlas.

Tarea 1: Crear un complemento

Inicie Visual Studio 2022.
Seleccione Archivo > Nuevo > Proyecto.
Seleccione Biblioteca de clases (.NET Framework) y seleccione Siguiente.
Introduzca D365PackageProject como Nombre de proyecto, seleccione una ubicación para guardar el proyecto, seleccione .NET Framework 4.6.2 como Marco de referencia y luego seleccione Crear.
Haga clic con el botón derecho en el proyecto y seleccione Administrar paquetes NuGet.
Seleccione la pestaña Examinar, busque y seleccione microsoft.crmsdk.coreassemblies y luego seleccione Instalar.
Lea los términos de la licencia y luego seleccione Aceptar si está de acuerdo.
Cierre el administrador de paquetes NuGet.
Haga clic con el botón derecho en Class1.cs y en Eliminar.
Haga clic con el botón derecho en el proyecto y luego seleccione Agregar > Clase.
Llame a la nueva clase PreOperationFormatPhoneCreateUpdate y seleccione Agregar.
Agregue las instrucciones using a la nueva clase de la siguiente manera:
```
 using Microsoft.Xrm.Sdk;

 using System.Text.RegularExpressions;
```
Haga pública la clase e implemente la interfaz IPlugin.
Implemente el miembro de la interfaz.

Su clase ahora debería parecerse a la de la imagen siguiente.

Tarea 2: Formatear un número de teléfono

Obtenga el contexto de ejecución del proveedor de servicios. Reemplace la excepción en el método Execute con el siguiente fragmento.
```
 IPluginExecutionContext context =
 (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));
```

Compruebe el parámetro de entrada de Target. Añada el siguiente fragmento de código al método Execute.

 if (!context.InputParameters.ContainsKey("Target"))

 throw new InvalidPluginExecutionException("No target found");

Añada el siguiente fragmento de código al método Execute. Este fragmento obtendrá la entidad de destino del parámetro de entrada y comprobará si sus atributos contienen telephone1 (Teléfono del trabajo de los contactos, Teléfono de las cuentas).
```
 var entity = context.InputParameters["Target"] as Entity;

 if (!entity.Attributes.Contains("telephone1"))

 return;
```
Añada el siguiente fragmento de código a la función Execute. Este fragmento eliminará todos los caracteres no numéricos del número de teléfono proporcionado por el usuario.
```
 string phoneNumber = (string)entity["telephone1"];

 var formattedNumber = Regex.Replace(phoneNumber, @"[^\d]", "");
```
Establezca telephone1 en el número de teléfono formateado. Añada el siguiente fragmento de código al método Execute.
```
 entity["telephone1"] = formattedNumber;
```
El método Execute ahora debería parecerse al de la imagen siguiente.
Haga clic con el botón derecho en el proyecto y seleccione Propiedades.
Seleccione la pestaña Firma, marque la casilla Firmar el ensamblado y seleccione Nuevo archivo de claves.
Introduzca contoso.snk en el campo Nombre de archivo de claves, desactive la casilla Proteger mi archivo de claves con una contraseña y seleccione Aceptar.
Cierre la pestaña Propiedades.
Compile el proyecto y asegúrese de que la compilación tenga éxito.

Tarea 3: Registrar un complemento y pasos

Nota

Si no tiene las herramientas de Dynamics 365 SDK, consulte Descargar herramientas de NuGet para descargarlas.

Inicie la aplicación de la herramienta de registro del complemento.
Seleccione Crear una nueva conexión.
Seleccione Office 365, seleccione la casilla Mostrar opciones avanzadas, introduzca sus credenciales y, a continuación, seleccione Iniciar sesión.
Seleccione Registrar y luego seleccione Registrar nuevo ensamblado.
Seleccione Examinar.
Navegue hasta la carpeta Bin > Debug de la biblioteca de clases que creó, seleccione D365PackageProject.dll y luego seleccione Abrir.
Seleccione Registrar complementos seleccionados.
Seleccione Aceptar.
Expanda el ensamblado recién registrado.
Haga clic con el botón derecho en el complemento y seleccione Registrar nuevo paso.
Seleccione Crear para Mensaje y seleccione contacto como Entidad primaria.
Seleccione Preoperación para Etapa de canalización de eventos de ejecución y luego seleccione Registrar nuevo paso.
Seleccione Cerrar.
Haga clic con el botón derecho en el complemento y seleccione Registrar nuevo paso otra vez.
Seleccione Actualizar para Mensaje, seleccione contacto para Entidad primaria y luego seleccione la búsqueda Atributos.
Desactive la casilla Seleccionar todo, seleccione la casilla Teléfono del trabajo y luego seleccione Aceptar.
Seleccione Preoperación para Etapa de canalización de eventos de ejecución y luego seleccione Registrar nuevo paso.

Tarea 4: Probar el complemento

Vaya a su Maker Portal y asegúrese de que tiene seleccionado el entorno correcto.
Seleccione Aplicaciones e inicie la aplicación Recaudación de fondos.
Seleccione Panel de información y abra uno de los contactos.
Seleccione + Nuevo.
Introduzca Prueba para Nombre, Contacto para Apellido, (123)-555-0100 para Teléfono del trabajo y luego seleccione Guardar.

El registro debe guardarse y el Teléfono del trabajo debería mostrar solo los valores numéricos.
Cambie el Teléfono del trabajo a 001-123-555-0100 y espere unos segundos.

El registro debe actualizarse y el Teléfono del trabajo debería mostrar solo los valores numéricos.

Ejercicio 2: crear/recuperar múltiples complementos

En este ejercicio, creará un complemento que se ejecutará en retrieve y retrieve multiple. Este complemento agregará paréntesis y guiones a los números de teléfono.

Cada ejercicio consiste en un escenario y objetivos de aprendizaje. Este escenario describe el propósito de los ejercicios, mientras que los objetivos se enumeran y tienen distintos puntos.

Tarea 1: Crear un complemento

Inicie Visual Studio.
Abra el proyecto que creó en el ejercicio 1.
Haga clic con el botón derecho en el proyecto y seleccione Agregar > Clase.
En el campo Nombre, introduzca PostOperationFormatPhoneOnRetrieveMultiple para la clase y luego seleccione Agregar.
Agregue las instrucciones using a la nueva clase de la siguiente manera:
```
 using Microsoft.Xrm.Sdk;
```
Haga pública la clase e implemente la interfaz IPlugin.
Implemente el miembro de la interfaz. Su clase ahora debería parecerse a la de la imagen siguiente.

Tarea 2: Formatear el número de teléfono para recuperar

Obtenga el contexto de ejecución del proveedor de servicios. Reemplace la excepción en el método Execute con el siguiente fragmento.
```
 IPluginExecutionContext context =
 (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));
```
Compruebe si el nombre del mensaje es Retrieve o RetrieveMultiple. Añada el siguiente fragmento de código al método Execute.
```
 if (context.MessageName.Equals("Retrieve"))	
 {

 }	
 else if(context.MessageName.Equals("RetrieveMultiple"))	
 {

 }
```

Compruebe si los parámetros de salida contienen una entidad empresarial y si es un tipo de entidad. Pegue el siguiente fragmento dentro de la condición retrieve if.

 if (!context.OutputParameters.Contains("BusinessEntity") && context.OutputParameters["BusinessEntity"] is Entity)
 throw new InvalidPluginExecutionException("No business entity found");

Obtenga la entidad y compruebe si contiene el campo telephone1. Agregue el siguiente fragmento dentro de la condición if retrieve.

 var entity = (Entity)context.OutputParameters["BusinessEntity"];

 if (!entity.Attributes.Contains("telephone1"))	
     return;

Agregue el siguiente fragmento a la condición if retrieve. Este fragmento intentará analizar telephone1 como long y regresará si el análisis no tiene éxito.
```
 if (!long.TryParse(entity["telephone1"].ToString(), out long phoneNumber))

 return;
```
Formatee el número de teléfono agregando paréntesis y guiones. Agregue el siguiente fragmento dentro de la condición if retrieve.
```
 var formattedNumber = String.Format("{0:(###) ###-####}", phoneNumber);
 entity["telephone1"] = formattedNumber;
```

La parte recuperada del método Execute debería parecerse a la imagen siguiente.

Tarea 3: Formatear el número de teléfono para retrieve multiple

Agregue el siguiente fragmento de código dentro de la condición retrieve multiple. Este fragmento comprobará si los parámetros de salida contienen BusinessEntityCollection y si es del tipo EntityCollection.

 if(!context.OutputParameters.Contains("BusinessEntityCollection") && context.OutputParameters ["BusinessEntityCollection"] is EntityCollection)
     throw new InvalidPluginExecutionException("No business entity collection found");

Obtenga la colección de entidades de los parámetros de salida. Agregue el siguiente fragmento dentro de la condición retrieve multiple.
```
 var entityCollection = (EntityCollection)context.OutputParameters["BusinessEntityCollection"];
```
Itere a través de cada entidad en la colección de entidades.
```
 foreach (var entity in entityCollection.Entities)	
 {

 }
```

Agregue el siguiente fragmento dentro de la condición foreach. Este fragmento hará lo mismo que hace la condición retrieve.

 if (entity.Attributes.Contains("telephone1") && entity["telephone1"] != null)
 {
    if (long.TryParse(entity["telephone1"].ToString(), out long phoneNumber))
    {
        var formattedNumber = String.Format("{0:(###) ###-####}", phoneNumber);
        entity["telephone1"] = formattedNumber;
    }
 }

La parte de rretrieve multiple del método Execute debería parecerse a la imagen siguiente.

Vuelva a compilar el proyecto y asegúrese de que la compilación tenga éxito.

Tarea 4: Actualizar el ensamblado del complemento y registrar los pasos

Inicie Plug-in Registration Tool y seleccione Crear nueva conexión.
Seleccione Office 365 y Mostrar opciones avanzadas, introduzca sus credenciales y seleccione Iniciar sesión.
Seleccione el ensamblado que ya registró en el ejercicio 1 y, a continuación, seleccione Actualizar.
Seleccione Examinar.
Busque la carpeta debug del proyecto, seleccione D365PackageProject.dll y luego Abrir.
Seleccione los complementos y luego seleccione Actualizar complementos seleccionados.
Seleccione Aceptar.
Haga clic con el botón derecho en el nuevo complemento y seleccione Registrar nuevo paso.
Seleccione Retrieve para Mensaje, seleccione contacto para Entidad primaria y luego seleccione PostOperation para Etapa de canalización de eventos de ejecución. Asegúrese de tener Sincrónico seleccionado para Modo de ejecución y luego seleccione Registrar nuevo paso.
Haga clic con el botón derecho en el complemento y seleccione Registrar nuevo paso otra vez.
Seleccione RetrieveMultiple para Mensaje, seleccione contacto para Entidad primaria y luego seleccione PostOperation para Etapa de canalización de eventos de ejecución. Asegúrese de tener Sincrónico seleccionado para Modo de ejecución y luego seleccione Registrar nuevo paso.

Tarea 5: Probar el complemento

Vaya a su Maker Portal y asegúrese de que se encuentra en el entorno correcto.
Seleccione Aplicaciones. A continuación, seleccione la aplicación Recaudación de fondos y luego Editar. Agregará la tabla Contacto a la aplicación.
Seleccione la página + Nueva.
Seleccione la tabla de Dataverse y, después, Siguiente.
Seleccione Tabla existente. A continuación, seleccione la tabla Contacto y luego Agregar.
Seleccione Reproducir.
Seleccione Guardar y continuar.
Seleccione Reproducir de nuevo.
Seleccione Contactos.
Los registros existentes que no se guardaron con el nuevo formato no cambiarán. Seleccione + Nuevo.
Proporcione la siguiente información y luego seleccione Guardar. El registro debe guardarse y el complemento debe aplicar el nuevo formato.
Seleccione Contactos de nuevo. El registro que creó debe tener el nuevo formato.
Seleccione uno de los contactos existentes para abrirlo.
Edite el Teléfono del trabajo como sigue:
Seleccione Guardar. Se debe aplicar el nuevo formato. Seleccione Contactos una vez más.

El teléfono editado debería tener el nuevo formato.

Comentarios

¿Le ha resultado útil esta página?