Condividi tramite

Creare azioni personalizzate

  • Articolo

 

Data di pubblicazione: gennaio 2017

Si applica a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

È possibile estendere le funzionalità di Microsoft Dynamics 365 creando messaggi personalizzati denominati azioni. Queste azioni avranno classi richiesta/risposta associate e un'azione Web API verrà generata. Le azioni vengono in genere utilizzate per aggiungere nuove funzionalità specifiche del domino al servizio Web dell'organizzazione o per combinare più richieste di messaggi dei servizi Web dell'organizzazione in un'unica richiesta. Ad esempio, in un call center di supporto, è possibile combinare i messaggi Create, Assign e Setstate in un nuovo singolo messaggio Escalate.

Le regole business di un'azione vengono implementate mediante un flusso di lavoro. Quando si crea un'azione, il flusso di lavoro in tempo reale associato viene registrato automaticamente per essere eseguito nella fase 30 (operazione principale) della pipeline di esecuzione. Per ulteriori informazioni sui flussi di lavoro in tempo reale, vedere Categorie di processo Dynamics 365.

Mentre le azioni sono supportate in Microsoft Dynamics 365 (online e locale), la creazione di un'azione nel codice (con XAML) è supportata solo nelle distribuzioni locali e IFD. I clienti online devono creare azioni in modo interattivo nell'applicazione Web.

In questo argomento

Informazioni sulle definizioni di azione

Autorizzazioni obbligatorie

Creare un'azione tramite il codice

Inserisce un'azione in un pacchetto per la distribuzione

Generare tipi con associazione anticipata per un'azione

Eseguire un'azione tramite l'API Web

Eseguire un'azione usando il servizio organizzazione

Eseguire un'azione tramite un processo

Controllare le azioni ad esecuzione lunga

Informazioni sulle definizioni di azione

Un'azione viene definita utilizzando un record dell'entità Workflow, simile a un flusso di lavoro in tempo reale. L'elenco seguente include alcuni punti chiave che mostrano in che cosa consiste un'azione e come funziona:

  • Può essere associata a una singola entità o essere globale (non associata a una particolare entità).

  • Viene eseguita nella fase 30 dell'operazione principale della pipeline di esecuzione dell'evento.

  • Supporta la chiamata di plug-in registrati nelle fasi delle operazioni preliminari e successive della pipeline di esecuzione dell'evento.

  • Può avere plug-in registrati nelle fasi delle operazioni preliminari e successive solo quando il suo stato è Attivata.

  • È disponibile mediante gli endpoint organization.svc e organization.svc / web, ma non l'endpoint organizationdata.svc (OData).

  • Può essere eseguita tramite una risorsa Web JavaScript.Ulteriori informazioni:Eseguire un'azione tramite una risorsa Web di JavaScript

  • Viene sempre eseguita nel contesto di sicurezza dell'utente chiamante.

  • Il record non può essere eliminato finché sono presenti passaggi dei plug-in registrati nell'azione.

  • Può, facoltativamente, mediante un'impostazione di configurazione, partecipare alla transazione di database corrente.

  • Non supporta un ambito in cui l'esecuzione sia limitata a un utente, a una business unit oppure a un'organizzazione. Le azioni vengono sempre eseguite nell'ambito di un'organizzazione.

  • Supporta gli argomenti di input e di output.

  • Supporta il controllo delle modifiche dei dati.

  • Non è supportata con client offline.

  • Può essere richiamata da una chiamata al metodo del servizio Web.

  • Può essere richiamata direttamente da un flusso di lavoro.

Autorizzazioni obbligatorie

Per attivare il flusso di lavoro in tempo reale di un'azione per l'esecuzione, è necessario il privilegio di sicurezza denominato Attiva i processi in tempo reale (prvActivateSynchronousWorkflow). Si tratta di un'aggiunta ai privilegi necessari per creare un flusso di lavoro. Per ulteriori informazioni su questi privilegi vedere l'associazione dell'interfaccia utente nella scheda Personalizzazione.

Creare un'azione tramite il codice

In genere, un'azione viene implementata da un addetto alla personalizzazione tramite la progettazione dei flussi di lavoro interattiva dell'applicazione Web. Tuttavia, se si desidera, gli sviluppatori possono implementare azioni mediante le chiamate SDK e la distribuzione a un server locale o IFD.

Gli attributi di entità del flusso di lavoro utilizzati per un'azione sono descritti nella tabella seguente. Il codice di esempio per un flusso di lavoro in tempo reale è disponibile nell'argomento Creare un flusso di lavoro in tempo reale nel codice.

Attributo di flusso di lavoro

Descrizione

Category

Impostato su WorkflowCategory.CustomOperation.

SyncWorkflowLogOnError

Quando è true, gli errori vengono registrati in ProcessSession. A differenza dei flussi di lavoro asincroni, l'esecuzione del flusso di lavoro in tempo reale non viene registrata nei record del System Job.

Mode

Non utilizzato.

IsTransacted

Impostato su true se l'azione partecipa alla transazione di database; in caso contrario, false. Il valore predefinito è true.

UniqueName

Nome univoco per l'azione. Il nome è composto da un prefisso dell'autore + "_" + il nome univoco.

Xaml

Impostato sul codice XAML che definisce il flusso di lavoro in tempo reale dell'azione. Non è possibile fare riferimento a un altro flusso di lavoro in tempo reale esistente.

Aggiungere gli argomenti di input e di output

Le azioni supportano argomenti di input e di output che è possibile aggiungere al flusso di lavoro tramite un tipo DynamicActivityProperty. Quando si aggiungono questi argomenti al flusso di lavoro di un'azione, essi diventano proprietà nelle classi di richiesta e risposta del messaggio associate all'azione. Ad esempio, nell'esempio seguente viene illustrato il codice C# e XAML per due degli argomenti di input e per uno di output.

DynamicActivityProperty inputProperty1 = new DynamicActivityProperty     { Name = "Subject", Type = typeof(InArgument<string>) };
DynamicActivityProperty inputProperty2 = new DynamicActivityProperty     { Name = "EntityCollection", Type = typeof(InArgument<EntityCollection>) };
DynamicActivityProperty outputProperty1 = new DynamicActivityProperty     { Name = "Output", Type = typeof(OutArgument<string>) };

inputProperty1.Attributes.Add(new ArgumentRequiredAttribute(true));
inputProperty1.Attributes.Add(new ArgumentDescriptionAttribute("The subject"));
inputProperty1.Attributes.Add(new ArgumentDirectionAttribute(Microsoft.Xrm.Sdk.Workflow.ArgumentDirection.Input));

inputProperty2.Attributes.Add(new ArgumentRequiredAttribute(false));
inputProperty2.Attributes.Add(new ArgumentDescriptionAttribute("The entity collection"));
inputProperty2.Attributes.Add(new ArgumentDirectionAttribute(Microsoft.Xrm.Sdk.Workflow.ArgumentDirection.Input));

outputProperty1.Attributes.Add(new ArgumentRequiredAttribute(false));
outputProperty1.Attributes.Add(new ArgumentDescriptionAttribute("The output"));
outputProperty1.Attributes.Add(new ArgumentDirectionAttribute(Microsoft.Xrm.Sdk.Workflow.ArgumentDirection.Output));

<x:Property Name="Subject"
            Type="InArgument(x:String)">
 <x:Property.Attributes>
  <mxsw:ArgumentRequiredAttribute Value="True" />
  <mxsw:ArgumentTargetAttribute Value="False" />
  <mxsw:ArgumentDescriptionAttribute Value="The subject " />
  <mxsw:ArgumentDirectionAttribute Value="Input" />
  <mxsw:ArgumentEntityAttribute Value="" />
 </x:Property.Attributes>
</x:Property>
<x:Property Name="EntityCollection"
            Type="InArgument(mxs:EntityCollection)">
 <x:Property.Attributes>
  <mxsw:ArgumentRequiredAttribute Value="False" />
  <mxsw:ArgumentTargetAttribute Value="False" />
  <mxsw:ArgumentDescriptionAttribute Value="The entity collection" />
  <mxsw:ArgumentDirectionAttribute Value="Input" />
  <mxsw:ArgumentEntityAttribute Value="" />
 </x:Property.Attributes>
</x:Property>
<x:Property Name="Output"
            Type="OutArgument(x:String)">
 <x:Property.Attributes>
  <mxsw:ArgumentRequiredAttribute Value="False" />
  <mxsw:ArgumentTargetAttribute Value="False" />
  <mxsw:ArgumentDescriptionAttribute Value="The output" />
  <mxsw:ArgumentDirectionAttribute Value="Output" />
  <mxsw:ArgumentEntityAttribute Value="" />
 </x:Property.Attributes>
</x:Property>

I nomi utilizzati per le proprietà devono essere coerenti con i nomi degli argomenti in quanto la creazione di codice definirà i nomi della proprietà di risposta o richiesta.

I tipi di argomenti supportati per gli argomenti di input e di output sono elencati nella tabella seguente.

Tipo .NET

Tipo di argomento

System.Int32

Integer

System.String

String

EntityReference

EntityReference

Entity

Entity

EntityCollection

EntityCollection

System.DateTime

DateTime

System.Double

Float

System.Decimal

Decimal

Money

Money

System.Boolean

Boolean

OptionSetValue

Picklist

Gli attributi degli argomenti supportati sono riportati nella tabella seguente.

Attributo di argomento

Descrizione

ArgumentRequiredAttribute

Indica se l'argomento è obbligatorio.

ArgumentDirectionAttribute

Indica se la direzione dell'argomento è un input o un output.

ArgumentDescriptionAttribute

Specifica una descrizione per l'argomento.

ArgumentEntityAttribute

Utilizzato se si desidera passare in un'entità.

ArgumentTargetAttribute

Questo attributo viene creato o aggiunto automaticamente. Punta all'entità primaria per cui il flusso di lavoro viene eseguito. Questo attributo è facoltativo per le azioni generali.

Inserisce un'azione in un pacchetto per la distribuzione

Per distribuire l'azione affinché possa essere importata in un'organizzazione Microsoft Dynamics 365, aggiungerla a una soluzione Dynamics 365. Questa operazione può essere facilmente eseguita tramite l'applicazione Web passando a Impostazioni> Personalizzazioni > Soluzioni. È inoltre possibile scrivere codice per creare la soluzione. Per ulteriori informazioni sulle soluzioni, vedere Comprimere e distribuire estensioni con soluzioni.

Generare tipi con associazione anticipata per un'azione

Usando lo strumento CrmSvcUtil nel pacchetto SDK, puoi generare le classi richiesta e risposta per l'azione da includere nel codice dell'applicazione. Tuttavia, prima di generare queste classi, assicurarsi di attivare l'azione.

Scarica il pacchetto SDK di Microsoft Dynamics CRM.

Nell'esempio seguente viene indicato il formato per eseguire lo strumento da riga di comando per un'installazione locale di Dynamics 365. I valori dei parametri per l'installazione devono essere specificati dall'utente.

    CrmSvcUtil.exe /url:http://<serverName>/<organizationName>/XRMServices/2011/Organization.svc /out:<outputFilename>.cs /username:<username> /password:<password> /domain:<domainName> /namespace:<outputNamespace> /serviceContextName:<serviceContextName> /generateActions

Nell'esempio seguente viene illustrato il formato per eseguire lo strumento da riga di comando con Microsoft Dynamics 365 (online). I valori dei parametri appropriati per l'account e il server devono essere specificati dall'utente.

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

Si noti l'utilizzo del parametro /generateActions.Ulteriori informazioni:Creare le classi di entità con associazione anticipata con lo strumento di generazione del codice (CrmSvcUtil.exe).

È possibile utilizzare tipi con associazione anticipata o ritardata con le classi generate di richiesta e di risposta per l'azione.

Eseguire un'azione tramite l'API Web

Viene creata una nuova azione nell'API Web alla sua creazione. Se l'azione viene creata nel contesto di un'entità, viene associata all'entità. In caso contrario sarà un'azione non associata.Ulteriori informazioni:Utilizzare le azioni API Web.

Eseguire un'azione usando il servizio organizzazione

Per eseguire un'azione tramite il servizio Web dell'organizzazione utilizzando il codice gestito, completare la procedura seguente.

  1. Includi il file dei tipi con associazione anticipata generato usando lo strumento CrmSvcUtil nel progetto dell'applicazione.

  2. Nel codice dell'applicazione creare un'istanza della richiesta dell'azione e popolare tutte le proprietà richieste.

  3. Richiamare Execute, passando la richiesta come argomento.

Prima di eseguire il codice dell'applicazione, verificare che l'azione sia attivata. In caso contrario, verrà visualizzato un errore di runtime.

Eseguire un'azione tramite una risorsa Web di JavaScript

L'azione può essere eseguita usando l'API Web come qualsiasi azione di sistema.Ulteriori informazioni:Utilizzare le azioni API Web.

La libreria di esempio Sdk.Soap.js mostra come usare i messaggi con le risorse Web JavaScript e il servizio Organizzazione (organization.svc/web). Utilizzare l'esempio del generatore di messaggio di un'azione complementare Sdk.Soap.js per generare le librerie di JavaScript che è possibile utilizzare con Sdk.Soap.js in modo analogo in cui è possibile utilizzare le librerie per i messaggi di sistema fornite nell'esempio. I file generati utilizzando il generatore di messaggio di un'azione Sdk.Soap.js sono librerie distinte di JavaScript per ogni azione. Ogni libreria contiene una classe di richiesta e risposta che corrisponde alle classi generate da CrmSvcUtil.

Eseguire un'azione tramite un processo

Puoi eseguire un'azione da flussi di lavoro, interazioni o da altre azioni di processo. Le azioni personalizzate attivate sono disponibili per i processi selezionando la voce Esegui azione dal menu a discesa Aggiungi passaggio del modulo del processo dell'applicazione Web. Dopo aver aggiunto il passaggio al processo, puoi selezionare la nuova azione personalizzata o qualsiasi altra azione nell'elenco Azione fornito nel passaggio. Scegli Imposta proprietà nel passaggio per specificare eventuali parametri di input richiesti dall'azione personalizzata.

Nota

Se l'azione personalizzata include tipi di parametro non supportati, ad esempio elenco a discesa, entità o raccolta di entità, l'azione personalizzata non verrà visualizzata nell'elenco Azione.

La capacità di eseguire un'azione da un processo è stata introdotta con Aggiornamento 1 di Microsoft Dynamics CRM Online 2015.

La piattaforma Depth esistente assicura che non si verifica un ciclo infinito. Per ulteriori informazioni sui limiti di profondità, vedi MaxDepth.

Controllare le azioni ad esecuzione lunga

Se uno dei passaggi del flusso di lavoro in tempo reale è un'attività di flusso di lavoro personalizzata, tale attività del flusso di lavoro personalizzata viene eseguita internamente all'ambiente di runtime isolato sandbox e sarà soggetta al limite di timeout di due minuti, in modo analogo in cui vengono gestiti i plug-in delle sandbox. Tuttavia, non esistono restrizioni sulla quantità di tempo globale che l'azione stessa può richiedere. Inoltre, se un'azione partecipa a una transazione, dove è abilitato il rollback, verranno applicati i timeout SQL Server.

Suggerimento

Una procedura consigliata consiste nell'eseguire le operazioni a lunga esecuzione all'esterno di Microsoft Dynamics 365 utilizzando i processi asincroni o in background di .NET.

Vedere anche

Creazione di flussi di lavoro in tempo reale
Utilizzare le interazioni in Dynamics 365 per i processi guidati
Pipeline di esecuzione evento
Automatizzare i processi aziendali utilizzando il processo Dynamics 365
TechNet: Personalizzare il sistema

Microsoft Dynamics 365

© 2017 Microsoft. Tutti i diritti sono riservati. Copyright