Escribir un complemento

 

Publicado: enero de 2017

Se aplica a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Los complementos son clases personalizadas que implementan la interfaz de IPlugin. Puede escribir un complemento en cualquier .NET Framework 4.5.2 lenguaje compatible con CLR como Microsoft Visual C# y Microsoft Visual Basic .NET. Para poder compilar código de complementos, debe agregar referencias de ensamblado de Microsoft.Xrm.Sdk.dll y Microsoft.Crm.Sdk.Proxy.dll al proyecto. Estos ensamblados pueden encontrarse en la carpeta SDK\Bin de SDK.Descargue el paquete de SDK de Microsoft Dynamics CRM.

En este tema

Diseño de complementos

Escritura de un complemento básico

Escribir un constructor de complementos

Compatibilidad con la ejecución sin conexión

Acceso web para complementos aislados (en el espacio aislado)

Usar tipos de enlace de tiempo de compilación

Ensamblados de complementos

Diseño de complementos

El diseño de complementos debe tener en cuenta la función de almacenamiento automático de la aplicación web introducida en Microsoft Dynamics 365 (en línea y local). El almacenamiento automático está habilitado de manera predeterminada pero puede deshabilitarse a nivel de organización. Cuando el almacenamiento automático esté activado, no habrá botón Guardar. La aplicación web guardará los datos del formulario automáticamente 30 segundos después del último cambio sin guardar. Puede aplicar scripts de formularios para deshabilitar los comportamientos del almacenamiento automático a nivel de formulario. En función de cómo haya registrado el complemento, es posible que el almacenamiento automático provoque que se llame con más frecuencia al complemento para los cambios individuales en el campo en lugar de realizar una invocación del complemento para todos los cambios. Debe asumir que cualquier usuario puede guardar un registro en cualquier momento, mediante Ctrl+S, pulsando un botón guardar o automáticamente debido a la función de almacenamiento automático.

Es recomendable registrar el complemento o el flujo de trabajo en entidades y campos específicos que resulten más importantes. Evite registrar un complemento o un flujo de trabajo para los cambios en todos los campos de la entidad. Si tiene una complemento o flujo de trabajo existente que se ha implementado antes de que estuviera disponible la función de almacenamiento automático, debe volver a probar este código para verificar que funcione correctamente. Si desea obtener más información, consulte TechNet: Administrar el autoguardado.

Escritura de un complemento básico

El siguiente ejemplo muestra parte del código común encontrado en un complemento. En esta muestra, el código omite las lógicas de negocios personalizadas que llevarían a cabo la tarea prevista del complemento. Sin embargo, el código muestra una clase de complemento que implementa la interfaz de IPlugin y el método de Execute necesario.

using System;
using System.ServiceModel;
using Microsoft.Xrm.Sdk;

public class MyPlugin: IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        // Extract the tracing service for use in debugging sandboxed plug-ins.
        // If you are not registering the plug-in in the sandbox, then you do
        // not have to add any tracing service related code.
        ITracingService tracingService =
            (ITracingService)serviceProvider.GetService(typeof(ITracingService));

        // Obtain the execution context from the service provider.
        IPluginExecutionContext context = (IPluginExecutionContext)
            serviceProvider.GetService(typeof(IPluginExecutionContext));

        // The InputParameters collection contains all the data passed in the message request.
        if (context.InputParameters.Contains("Target") &&
            context.InputParameters["Target"] is Entity)
        {
            // Obtain the target entity from the input parameters.
            Entity entity = (Entity)context.InputParameters["Target"];

            // Verify that the target entity represents an entity type you are expecting. 
            // For example, an account. If not, the plug-in was not registered correctly.
            if (entity.LogicalName != "account")
                return;

            // Obtain the organization service reference which you will need for
            // web service calls.
            IOrganizationServiceFactory serviceFactory = 
                (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
            IOrganizationService service = serviceFactory.CreateOrganizationService(context.UserId);

            try
            {
                // Plug-in business logic goes here.
            }

            catch (FaultException<OrganizationServiceFault> ex)
            {
                throw new InvalidPluginExecutionException("An error occurred in MyPlug-in.", ex);
            }

            catch (Exception ex)
            {
                tracingService.Trace("MyPlugin: {0}", ex.ToString());
                throw;
            }
        }
    }
}

El parámetro IServiceProvider del método Execute es un contenedor para varios objetos útiles al que se puede acceder desde un complemento. El proveedor de servicios contiene referencias de la instancia al contexto de ejecución, IOrganizationServiceFactory, ITracingService, etc. El código de ejemplo demuestra cómo obtener referencias al contexto de ejecución, IOrganizationService y ITracingService desde el parámetro del proveedor de servicios. Para obtener más información sobre el servicio de seguimiento, consulte el Depurar un complemento.

El contexto de ejecución contiene una gran cantidad de información sobre el evento que hizo que el complemento se ejecutara y los datos contenidos en el mensaje que está siendo procesado actualmente por la canalización. Para obtener más información sobre el contexto de datos, consulte Comprender el contexto de los datos pasados a un complemento.

La plataforma proporciona las direcciones URL del servicio web correctas y las credenciales de red cuando obtiene la referencia del servicio web de la organización del proveedor de servicios. No se admite crear una instancia del proxy de servicio web propio porque crea problemas de interbloqueo y autenticación. Una vez que tenga la referencia de servicio de la organización, puede usarla para realizar llamadas al método al servicio web de la organización. Puede recuperar o cambiar datos profesionales en una sola organización de Microsoft Dynamics 365 emitiendo una o varias solicitudes de mensaje al servicio web. Para obtener más información acerca de las solicitudes de los mensajes, consulte Usar mensajes (clases de respuesta y solicitud) con el método Execute.

Un complemento típico debe tener acceso a la información del contexto, realizar las operaciones empresariales necesarias y supervisar excepciones. Para obtener más información acerca de la supervisión de excepciones en un complemento, consulte Administrar las excepciones en complementos. En el tema Ejemplo: Crear un complemento básico se facilita una muestra de complemento más completa.

Importante

Para mejorar el rendimiento, Microsoft Dynamics 365 almacena en la caché las instancias de complementos. El método Execute se debe escribir para que no tenga estado porque no se llama al constructor para cada invocación del complemento. Además, varios subprocesos del sistema podrían ejecutar el complemento al mismo tiempo. Toda la información de estado por invocación se almacena en el contexto para que no utilice variables globales ni intente almacenar datos en variables integrantes para usar durante la siguiente invocación del complemento a menos que los datos hayan sido obtenidos del parámetro de configuración proporcionado al constructor. Los cambios realizados en un registro de complementos provocarán que se reinicie el complemento.

Escribir un constructor de complementos

La plataforma de Microsoft Dynamics 365 admite un constructor de complementos opcional que acepte uno o dos parámetros de cadena. Si escribe un constructor como este, puede pasar cualquier cadena de información al complemento en tiempo de ejecución.

El siguiente ejemplo muestra el formato del constructor. En este ejemplo, la clase del complemento se denomina SamplePlugin.

public SamplePlugin()
public SamplePlugin(string unsecure)
public SamplePlugin(string unsecure, string secure)

El parámetro de la primera cadena del constructor contiene información (insegura) pública. El segundo parámetro de cadena contiene información (segura) no pública. En esta discusión, seguro hace referencia a un valor cifrado, mientras no seguro es un valor sin cifrar. Cuando se usa Microsoft Dynamics 365 para Microsoft Office Outlook con acceso sin conexión, la cadena segura no se pasa a un complemento que se ejecute mientras Dynamics 365 para Outlook está sin conexión.

La información pasada al constructor de complementos en estas cadenas se especifica cuando el complemento se registra con Microsoft Dynamics 365. Al usar la herramienta de registro de complementos para registrar un complemento, puede introducir información segura e insegura en los campos Configuración segura y Configuración insegura proporcionados en el formulario Registrar nuevo paso. Al registrar un complemento mediante programación usando SDK de Microsoft Dynamics 365, SdkMessageProcessingStep.Configuration contiene el valor no seguro y SdkMessageProcessingStep.SecureConfigId hace referencia a un registro SdkMessageProcessingStepSecureConfig que contiene el valor seguro.

Compatibilidad con la ejecución sin conexión

Puede registrar complementos para ejecutar en modo en línea, sin conexión o en ambos. El modo sin conexión solamente se admite en Microsoft Dynamics 365 para Microsoft Office Outlook con acceso sin conexión. El código de complementos puede comprobar si se está ejecutando en modo sin conexión mediante la comprobación de la propiedad IsExecutingOffline.

Cuando diseñe un complemento que se registre para la ejecución en línea y sin conexión, recuerde que el complemento se puede ejecutar dos veces. La primera vez es mientras Microsoft Dynamics 365 para Microsoft Office Outlook con acceso sin conexión está sin conexión. El complemento se ejecuta de nuevo cuando Dynamics 365 para Outlook se conecta y se produce la sincronización entre Dynamics 365 para Outlook y el servidor Microsoft Dynamics 365. Para comprobar la propiedad IsOfflinePlayback para determinar si el complemento se está ejecutando debido a esta sincronización.

Acceso web para complementos aislados (en el espacio aislado)

Si tiene pensado registrar el complemento en el espacio aislado, todavía puede acceder a direcciones web desde el código del complemento. Puede usar cualquier clase de .NET Framework en el código del complemento que proporciona acceso web dentro de las restricciones de acceso web descritas en Aislamiento, relacioens de confianza y estadísticas de complementos. Por ejemplo, el siguiente código de complemento descarga una página web.

// Download the target URI using a Web client. Any .NET class that uses the
// HTTP or HTTPS protocols and a DNS lookup should work.
using (WebClient client = new WebClient())
{
    byte[] responseBytes = client.DownloadData(webAddress);
    string response = Encoding.UTF8.GetString(responseBytes);

Seguridad Nota

Para que los complementos del espacio aislado puedan tener acceso a servicios web externos, el servidor en el que el rol del servicio de procesamiento de espacios aislados está instalado debe estar expuesto a Internet, y la cuenta en la que se ejecuta el servicio del espacio aislado debe disponer de acceso a Internet. Solo se requieren las conexiones salientes de los puertos 80 y 443. No se requiere el acceso de la conexión entrante. Use el panel de control Firewall de Windows para habilitar las conexiones salientes de la aplicación Microsoft.Crm.Sandbox.WorkerProcess ubicada en el servidor en la carpeta %PROGRAMFILES%\Microsoft Dynamics 365\Server\bin.

Usar tipos de enlace de tiempo de compilación

Para usar tipos Microsoft Dynamics 365 en tiempo de compilación en su código de complemento, simplemente incluya el archivo de tipos generado mediante el programa CrmSvcUtil en el proyecto del complemento de Microsoft Visual Studio.

La conversión de una entidad enlazada en tiempo de ejecución a una entidad de enlace de tiempo de compilación se controla la siguiente manera:

Account acct = entity.ToEntity<Account>();

En la línea de código anterior, la variable acct es un tipo de enlace de tiempo de compilación. Todos los valores de Entity que se asignan a IPluginExecutionContext deben ser tipos enlazados en tiempo de ejecución. Si se asigna un tipo de enlace de tiempo de compilación, se producirá una SerializationException. Para obtener más información, vea Comprender el contexto de los datos pasados a un complemento. Asegúrese de no mezclar los tipos y utilice un tipo de enlace de tiempo de compilación en el que se haga una llamada a un tipo enlazado en tiempo de ejecución tal y como se muestra en el código siguiente.

context.InputParameters["Target"] = new Account() { Name = "MyAccount" }; // WRONG: Do not do this.

En el ejemplo anterior, no desea almacenar una instancia de enlace de tiempo de compilación en el contexto del complemento donde debería ir una instancia enlazada en tiempo de ejecución. Esto permite evitar requerir a la plataforma realizar la conversión entre tipos de enlace de tiempo de compilación y tipos de enlazado en tiempo de ejecución antes de efectuar una llamada a un complemento y al regresar del complemento a la plataforma.

Ensamblados de complementos

Pueden existir uno o más tipos de complementos en un ensamblado. Una vez registrado e implementado el ensamblado del complemento, los complementos pueden realizar la operación prevista en respuesta a un evento de tiempo de ejecución de Microsoft Dynamics 365.

Seguridad Nota
En Microsoft Dynamics 365, los ensamblados de complementos deben poder ser leídos por todo el mundo para que funcionen correctamente. Por lo tanto, se recomienda por motivos de seguridad desarrollar código de complementos que no contenga información de inicio de sesión del sistema, información confidencial ni secretos comerciales de la empresa.

Cada ensamblado de complemento deberá estar firmado, mediante la pestaña Firma de la hoja de propiedades del proyecto de Microsoft Visual Studio o la herramienta Nombre seguro antes de registrarse e implementarse en Microsoft Dynamics 365. Para obtener más información acerca de la herramienta Nombre seguro, ejecute el programa de sn.exe sin ningún argumento desde una ventana de símbolo del sistema de Microsoft Visual Studio.

Si el ensamblado contiene un complemento que se puede ejecutar mientras Dynamics 365 para Outlook está sin conexión, hay una seguridad adicional que la plataforma Microsoft Dynamics 365 impone en los ensamblados. Para obtener más información, vea Tutorial: configurar la seguridad de ensamblado para un complemento sin conexión.

Ver también

Desarrollo de complementos
Comprender el contexto de los datos pasados a un complemento
Escribir un complemento con Azure personalizado
Registrar e implementar complementos
Administrar las excepciones en complementos
Ejemplo: Crear un complemento básico
Ejemplo: acceso web desde un complemento de espacio aislado
Ejecutar la herramienta de generación de códigos
Blog: uso de complementos para modificar vistas

Microsoft Dynamics 365

© 2017 Microsoft. Todos los derechos reservados. Copyright