Scrivere un plug-in

Data di pubblicazione: novembre 2016

Si applica a: Dynamics CRM 2015

I plug-in sono classi personalizzate che implementano l'interfaccia IPlugin. È possibile scrivere un plug-in in qualsiasi linguaggio conforme a CLR, ad esempio .NET Framework 4.5.2Microsoft Visual C# e Microsoft Visual Basic .NET. Per poter compilare il codice del plug-in, è necessario aggiungere Microsoft.Xrm.Sdk.dll e i riferimenti all'assembly di Microsoft.Crm.Sdk.Proxy.dll al progetto. Questi assembly sono disponibili nella cartella SDK\Bin di SDK.Scarica il pacchetto SDK di Microsoft Dynamics CRM.

In questo argomento

Progettazione dei plug-in

Scrittura di un plug-in di base

Scrivere un costruttore del plug-in

Supportare l'esecuzione offline

Web Access per i plug-in isolati (in modalità sandbox)

Utilizzare i tipi con associazione anticipata

Assembly del plug-in

Progettazione dei plug-in

Nella progettazione dei plug-in è necessario tener conto della funzionalità salvataggio automatico dell'applicazione Web introdotta in Aggiornamento di Microsoft Dynamics CRM 2015 e Microsoft Dynamics CRM Online 2015. Il salvataggio automatico è abilitato per impostazione predefinita, ma può essere disabilitato a livello di organizzazione. Quando il salvataggio automatico è abilitato, non esiste alcun pulsante Salva. L'applicazione Web salverà i dati nel modulo automaticamente 30 secondi dopo l'ultima modifica non salvata. È possibile applicare gli script dei moduli per disabilitare i comportamenti del salvataggio automatico a livello di modulo. A seconda di come è stato registrato il plug-in, il salvataggio automatico potrebbe comportare delle chiamate più frequenti del plug-in per singole modifiche del campo anziché un'unica chiamata del plug-in per tutte le modifiche. Si può presupporre che gli utenti possano salvare i record in qualsiasi momento, sia che tale operazione venga effettuata utilizzando Ctrl+S che premendo un pulsante di salvataggio oppure automaticamente a causa della funzionalità di salvataggio automatico.

È consigliabile registrare il plug-in o il flusso di lavoro su entità e campi specifici importanti. Evitare di registrare un plug-in o un flusso di lavoro per le modifiche a tutti i campi delle entità. Se si dispone di un plug-in o di un flusso di lavoro esistente implementato prima della disponibilità della funzionalità di salvataggio automatico, sarà necessario verificare nuovamente tale codice per verificarne il funzionamento appropriato. Per ulteriori informazioni, vedere la pagina TechNet: Gestire il salvataggio automatico.

Scrittura di un plug-in di base

Nel seguente esempio viene illustrato parte del codice comune disponibile in un plug-in. Per questo esempio, il codice omette tutte le regole business personalizzate che determinano l'esecuzione dell'attività desiderata del plug-in. Tuttavia, il codice visualizza una classe plug-in che implementa l'interfaccia IPlugin e il metodo Execute obbligatorio.

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

Il parametro IServiceProvider del metodo Execute è un contenitore per diversi oggetti utili dei servizi a cui è possibile accedere in un plug-in. Il provider di servizi contiene riferimenti dell'istanza al contesto di esecuzione, IOrganizationServiceFactory, ITracingService e altro ancora. Nel codice di esempio viene illustrato come ottenere riferimenti al contesto di esecuzione, IOrganizationService e ITracingService dal parametro del provider di servizi. Per ulteriori informazioni sul servizio di analisi, vedere Eseguire il debug di un plug-in.

Il contesto di esecuzione contiene numerose informazioni sull'evento che ha determinato l'esecuzione del plug-in e sui dati contenuti nel messaggio attualmente elaborato dalla pipeline. Per ulteriori informazioni sul contesto dati, vedere Informazioni sul contesto dati passato a un plug-in.

La piattaforma fornisce gli URL del servizio Web corretti e le credenziali di rete quando si ottiene il riferimento al servizio Web dell'organizzazione dal provider di servizi. La creazione di un'istanza del proxy del servizio Web non è supportata in quando crea problemi di autenticazione e blocco critico. Una volta che si dispone del riferimento al servizio dell'organizzazione, è possibile utilizzarlo per effettuare chiamate al metodo del servizio Web dell'organizzazione. È possibile recuperare o modificare i dati aziendali in una sola organizzazione Microsoft Dynamics 365 emettendo una o più richieste di messaggio al servizio Web. Per ulteriori informazioni sulle richieste di messaggio, vedere Utilizzare i messaggi (classi di richiesta e di risposta) con il metodo Execute.

Un plug-in tipico deve accedere alle informazioni nel contesto, eseguire le operazioni aziendali necessarie e gestire le eccezioni. Per ulteriori informazioni sulla gestione delle eccezioni in un plug-in, vedere Gestire le eccezioni nei plug-in. Un esempio di plug-in più completo è disponibile nell'argomento Esempio: creare un plug-in di base.

Scrivere un costruttore del plug-in

La piattaforma Microsoft Dynamics 365 supporta il costruttore del plug-in facoltativo che accetta uno o due parametri stringa. Se si scrive un costruttore come questo, è possibile passare le stringhe di informazioni al plug-in in fase di esecuzione.

Nell'esempio seguente viene illustrato il formato del costruttore. In questo esempio la classe del plug-in è denominata SamplePlugin.

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

Il primo parametro stringa del costruttore contiene informazioni pubbliche (non protette). Il secondo parametro stringa contiene informazioni non pubbliche (protette). In questa discussione, "protetto" fa riferimento a un valore crittografato, mentre "non protetto" è un valore non crittografato. Quando si utilizza Microsoft Dynamics CRM per Microsoft Office Outlook con accesso offline, la stringa protetta non viene passata a un plug-in eseguito mentre Dynamics CRM per Outlook è offline.

Le informazioni passate al costruttore del plug-in in queste stringhe vengono specificate quando il plug-in viene registrato con Microsoft Dynamics 365. Quando si utilizza lo strumento per la registrazione dei plug-in per registrare un plug-in, è possibile immettere informazioni protette e non protette nei campi Configurazione sicura e Configurazione non protetta forniti nel modulo Registra nuovo passaggio. Quando si registra un plug-in a livello di programmazione utilizzando Microsoft Dynamics CRM SDK, SdkMessageProcessingStep.Configuration contiene il valore non protetto e SdkMessageProcessingStep.SecureConfigId fa riferimento a un record SdkMessageProcessingStepSecureConfig contenente il valore protetto.

Supportare l'esecuzione offline

È possibile registrare i plug-in perché vengano eseguiti in modalità online, offline o in entrambe le modalità. La modalità offline è supportata solo in Microsoft Dynamics CRM per Microsoft Office Outlook con accesso offline. Il codice del plug-in può stabilire se il plug-in viene eseguito in modalità offline controllando la proprietà IsExecutingOffline.

Quando si progetta un plug-in che verrà registrato sia per l'esecuzione online che offline, ricordare che il plug-in può essere eseguito due volte. La prima volta è mentre Microsoft Dynamics CRM per Microsoft Office Outlook con accesso offline è offline. Il plug-in viene eseguito di nuovo quando Dynamics CRM per Outlook è connesso e si verifica la sincronizzazione tra Dynamics CRM per Outlook e il server Microsoft Dynamics 365. È possibile verificare la proprietà IsOfflinePlayback per determinare se il plug-in è in esecuzione a causa della sincronizzazione.

Web Access per i plug-in isolati (in modalità sandbox)

Se si intende registrare il plug-in in modalità sandbox, è comunque possibile accedere agli indirizzi Web dal codice del plug-in. È possibile utilizzare una classe di .NET Framework nel codice del plug-in che consente di accedere al Web nell'ambito delle restrizioni di accesso al Web descritte Isolamento di plug-in, attendibilità e statistiche. Ad esempio, il seguente codice del plug-in consente di scaricare una pagina 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);

Sicurezza Nota

Affinché i plug-in in modalità sandbox possano accedere ai servizi Web esterni, il server in cui è installato il ruolo del Servizio di elaborazione in modalità sandbox deve essere esposto a Internet e l'account eseguito dal servizio sandbox deve disporre di accesso a Internet. Sono necessarie solo le connessioni in uscita sulle porte 80 e 443. L'accesso per le connessioni in ingresso non è necessario. Utilizzare il pannello di controllo di Windows Firewall per abilitare le connessioni in uscita per l'applicazione Microsoft.Crm.Sandbox.WorkerProcess situata sul server nella cartella in %PROGRAMMI%\Microsoft Dynamics CRM\Server\bin.

Utilizzare i tipi con associazione anticipata

Per utilizzare i tipi con associazione anticipata di Microsoft Dynamics 365 nel codice del plug-in, è sufficiente includere i file dei tipi, generati utilizzando il programma CrmSvcUtil, nel progetto plug-in di Microsoft Visual Studio.

La conversione di un'entità con associazione tardiva a un'entità con associazione anticipata viene gestita come segue:

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

Nella riga di codice precedente, la variabile acct è un tipo con associazione anticipata. Tutti i valori Entity che vengono assegnati a IPluginExecutionContext devono essere tipi con associazione tardiva. Se il tipo con associazione anticipata viene assegnato al contesto, si verificherà una SerializationException. Per ulteriori informazioni, vedere Informazioni sul contesto dati passato a un plug-in. Verificare di non combinare i tipi e di utilizzare un tipo con associazione anticipata in cui il tipo di associazione tardiva viene denominato come illustrato nel codice seguente.

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

Nell'esempio precedente, non si desidera archiviare un'istanza con associazione anticipata nel contesto plug-in dove dovrebbe andare un'istanza con associazione tardiva. Questo consente di evitare di richiedere alla piattaforma di eseguire conversioni tra tipi con associazione anticipata e tipi con associazione tardiva prima di chiamare un plug-in e quando si ritorna dal plug-in alla piattaforma.

Assembly del plug-in

Un assembly può contenere uno o più tipi di plug-in. Al termine della registrazione e della distribuzione dell'assembly del plug-in, i plug-in possono eseguire l'operazione desiderata in risposta a un evento della fase di esecuzione di Microsoft Dynamics 365.

Sicurezza Nota
In Microsoft Dynamics 365, gli assembly del plug-in per funzionare correttamente devono essere leggibili da tutti. Pertanto, ai fini della sicurezza è consigliabile sviluppare codice del plug-in non contenente alcuna informazione di accesso al sistema, informazioni riservate o segreti aziendali della società.

Ogni assembly del plug-in deve essere firmato, tramite la scheda Firma del foglio delle proprietà del progetto in Microsoft Visual Studio o lo strumento Nome complesso, prima di essere registrato e distribuito in Microsoft Dynamics 365. Per ulteriori informazioni sullo strumento Nome complesso, eseguire il programma sn.exe, senza alcun argomento, da una finestra del prompt dei comandi di Microsoft Visual Studio.

Se l'assembly contiene un plug-in che può essere eseguito mentre Dynamics CRM per Outlook è offline, esiste comunque una sicurezza aggiuntiva che la piattaforma di Microsoft Dynamics 365 richiede per gli assembly. Per ulteriori informazioni, vedere Procedura dettagliata: Configurare la sicurezza dell'assembly per un plug-in offline.

Vedere anche

Sviluppo dei plug-in
Informazioni sul contesto dati passato a un plug-in
Scrivere un plug-in personalizzato che riconosce Azure
Registrare e distribuire plug-in
Gestire le eccezioni nei plug-in
Esempio: creare un plug-in di base
Esempio: accesso Web da un plug-in in modalità sandbox
Eseguire lo strumento di generazione del codice
Blog: Utilizzo dei plug-in per modificare le visualizzazioni

© 2017 Microsoft. Tutti i diritti sono riservati. Copyright