Esercizio - Scrittura del primo plug-in

30 minuti

In questo scenario un'organizzazione deve essere certa che i dati dei numeri di telefono vengano immessi in un formato coerente. Per raggiungere questo obiettivo occorre creare un plug-in da eseguire durante la fase di creazione/aggiornamento che sia in grado di rimuovere tutti i caratteri non numerici da un numero di telefono prima di salvarlo in Dataverse. Si creerà quindi un altro plug-in da eseguire durante retrieve/retrievemultiple contatto per riformattare il numero di telefono in modo da includere parentesi e trattini, se esistenti.

Esercizio 1 - Creazione/aggiornamento del plug-in

In questo esercizio si creerà un plug-in da eseguire durante la creazione e l'aggiornamento. Questo plug-in rimuove tutti i caratteri non numerici da un numero di telefono.

Ogni esercizio è costituito da uno scenario e da obiettivi di apprendimento. Lo scenario descrive lo scopo degli esercizi, mentre gli obiettivi sono organizzati in elenchi puntati.

Nota

Se non si dispone degli strumenti di Dynamics 365 SDK, fare riferimento alla pagina Download di strumenti da NuGet per scaricarli.

Attività 1 - Creazione di un plug-in

Avviare Visual Studio 2022.
Selezionare File > Nuovo > Progetto.
Selezionare Libreria di classi (.NET Framework) e selezionare Avanti.
Immettere D365PackageProject nel campo Nome progetto, selezionare una posizione in cui salvare il progetto, selezionare .NET Framework 4.6.2 nel campo Framework, quindi selezionare Crea.
Fare clic con il pulsante destro del mouse sul progetto e selezionare Gestisci pacchetti NuGet.
Selezionare la scheda Sfoglia, cercare e selezionare microsoft.crmsdk.coreassemblies, quindi selezionare Installa.
Leggere le condizioni di licenza e selezionare Accetta per accettarle.
Chiudere la finestra Gestione pacchetti NuGet.
Fare clic con il pulsante destro del mouse su Class1.cs e scegliere Elimina.
Fare clic con il pulsante destro del mouse sul progetto, quindi scegliere Aggiungi > Classe.
Alla nuova classe assegnare il nome PreOperationFormatPhoneCreateUpdate e selezionare Aggiungi.

Aggiungere le istruzioni using alla nuova classe nel seguente modo:

 using Microsoft.Xrm.Sdk;

 using System.Text.RegularExpressions;

Impostare la classe come pubblica e implementare l'interfaccia IPlugin.
Implementare il membro di interfaccia.

La classe dovrebbe essere simile a quella illustrata nell'immagine seguente.

Attività 2. Formattare un numero di telefono

Recuperare il contesto di esecuzione dal provider di servizi. Sostituire l'eccezione nel metodo Execute con il frammento di codice seguente.
```
 IPluginExecutionContext context =
 (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));
```

Controllare il parametro di input in Target. Aggiungere il frammento seguente al metodo Execute.

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

 throw new InvalidPluginExecutionException("No target found");

Aggiungere il frammento seguente al metodo Execute. Questo frammento recupera l'entità di destinazione dal parametro di input e verifica se i relativi attributi contengono telephone1 (telefono ufficio per i contatti, telefono per gli account).
```
 var entity = context.InputParameters["Target"] as Entity;

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

 return;
```
Aggiungere il seguente frammento di codice alla funzione Execute. Questo frammento di codice rimuove tutti i caratteri non numerici dal numero di telefono fornito dall'utente.
```
 string phoneNumber = (string)entity["telephone1"];

 var formattedNumber = Regex.Replace(phoneNumber, @"[^\d]", "");
```
Impostare telephone1 sul numero di telefono formattato. Aggiungere il frammento seguente al metodo Execute.
```
 entity["telephone1"] = formattedNumber;
```
Il metodo Execute dovrebbe essere simile a quello illustrato nell'immagine seguente.
Fare clic con il pulsante destro del mouse sul progetto e selezionare Proprietà.
Selezionare la scheda Firma, selezionare la casella Firma assembly, quindi scegliere Nuovo file chiave.
Immettere contoso.snk nel campo Nome file di chiave, deselezionare la casella di controllo Proteggi file di chiave con una password, quindi selezionare OK.
Chiudere la scheda Proprietà.
Compilare il progetto e assicurarsi che la compilazione abbia esito positivo.

Attività 3 - Registrazione di un plug-in e dei passaggi

Nota

Se non si dispone degli strumenti di Dynamics 365 SDK, fare riferimento alla pagina Download di strumenti da NuGet per scaricarli.

Avviare Plug-in Registration Tool.
Selezionare Crea nuova connessione.
Selezionare Office 365, selezionare la casella di controllo Mostra avanzate, specificare le credenziali e quindi selezionare Accedi.
Selezionare Registra, quindi Registra nuovo assembly.
Selezionare Sfoglia.
Andare alla cartella Bin > Debug della libreria di classi creata, selezionare D365PackageProject.dll, quindi Apri.
Selezionare Registra plug-in selezionati.
Selezionare OK.
Espandere l'assembly appena registrato.
Fare clic con il pulsante destro del mouse sul plug-in e selezionare Registra nuovo passaggio.
Selezionare Crea in Messaggio e selezionare contatto in Entità primaria.
Selezionare PreOperation nell'area Fase di esecuzione pipeline eventi, quindi Registra nuovo passaggio.
Selezionare Chiudi.
Fare clic con il pulsante destro del mouse sul plug-in e selezionare di nuovo Registra nuovo passaggio.
Selezionare Aggiorna in Messaggio, selezionare contatto in Entità primaria, quindi selezionare la ricerca Attributi.
Deselezionare la casella di controllo Seleziona tutto, selezionare la casella di controllo Telefono ufficio, quindi selezionare OK.
Selezionare PreOperation nell'area Fase di esecuzione pipeline eventi, quindi Registra nuovo passaggio.

Attività 4. Verificare il plug-in

Andare a Maker Portal e assicurarsi che sia selezionato l'ambiente corretto.
Selezionare App e avviare l'applicazione Fundraiser.
Selezionare Dashboard e aprire uno dei contatti.
Selezionare + Nuovo.
Immettere Test nel campo Nome, Contatto nel campo Cognome, (123)-555-0100 nel campo Telefono ufficio, quindi selezionare Salva.

A questo punto, il record dovrebbe essere stato salvato e nel campo Telefono ufficio dovrebbero essere visualizzati solo valori numerici.
Nel campo Telefono ufficio modificare il valore immesso in 001-123-555-0100 e attendere qualche secondo.

A questo punto, il record dovrebbe essere stato aggiornato e nel campo Telefono ufficio dovrebbero essere visualizzati solo valori numerici.

Esercizio 2 - Creazione/recupero di più plug-in

In questo esercizio si creerà un plug-in da eseguire durante retrieve e retrieve multiple. Questo plug-in aggiunge parentesi e trattini ai numeri di telefono.

Ogni esercizio è costituito da uno scenario e da obiettivi di apprendimento. Lo scenario descrive lo scopo degli esercizi, mentre gli obiettivi sono organizzati in elenchi puntati.

Attività 1 - Creazione di un plug-in

Avviare Visual Studio.
Aprire il progetto creato nell'esercizio 1.
Fare clic con il pulsante destro del mouse sul progetto e selezionare Aggiungi > Classe.
Nel campo Nome immettere PostOperationFormatPhoneOnRetrieveMultiple per la classe, quindi selezionare Aggiungi.
Aggiungere le istruzioni using alla nuova classe nel seguente modo:
```
 using Microsoft.Xrm.Sdk;
```
Impostare la classe come pubblica e implementare l'interfaccia IPlugin.
Implementare il membro di interfaccia. La classe dovrebbe essere simile a quella illustrata nell'immagine seguente.

Attività 2 - Formattare il numero di telefono per il recupero

Recuperare il contesto di esecuzione dal provider di servizi. Sostituire l'eccezione nel metodo Execute con il frammento di codice seguente.
```
 IPluginExecutionContext context =
 (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));
```

Controllare se il nome del messaggio è Retrieve o RetrieveMultiple. Aggiungere il frammento seguente al metodo Execute.

 if (context.MessageName.Equals("Retrieve"))	
 {

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

 }

Verificare se i parametri di output contengono un'entità aziendale e se si tratta di un tipo di entità. Incollare il seguente frammento di codice all'interno dell'istruzione if della condizione retrieve.
```
 if (!context.OutputParameters.Contains("BusinessEntity") && context.OutputParameters["BusinessEntity"] is Entity)
 throw new InvalidPluginExecutionException("No business entity found");
```
Recuperare l'entità e controllare se contiene il campo telephone1. Aggiungere il seguente frammento di codice all'interno della condizione if retrieve.
```
 var entity = (Entity)context.OutputParameters["BusinessEntity"];

 if (!entity.Attributes.Contains("telephone1"))	
     return;
```
Aggiungere il frammento di codice seguente alla condizione if retrieve. Questo frammento di codice tenta di analizzare il valore telephone1 come long e restituisce il controllo se l'analisi ha esito negativo.
```
 if (!long.TryParse(entity["telephone1"].ToString(), out long phoneNumber))

 return;
```
Formattare il numero di telefono aggiungendo parentesi e trattini. Aggiungere il seguente frammento di codice all'interno della condizione if retrieve.
```
 var formattedNumber = String.Format("{0:(###) ###-####}", phoneNumber);
 entity["telephone1"] = formattedNumber;
```

La sezione Retrieve del metodo Execute dovrebbe risultare simile a quella illustrata nell'immagine seguente.

Attività 3 - Formattare il numero di telefono per retrieve multiple

Aggiungere il frammento di codice seguente all'interno della condizione retrieve multiple. Questo frammento di codice controllerà se i parametri di output contengono BusinessEntityCollection e se il relativo tipo è EntityCollection.

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

Recuperare la raccolta di entità dai parametri di output. Aggiungere il seguente frammento di codice all'interno della condizione retrieve multiple.
```
 var entityCollection = (EntityCollection)context.OutputParameters["BusinessEntityCollection"];
```

Eseguire l'iterazione tra entità nella raccolta di entità.

 foreach (var entity in entityCollection.Entities)	
 {

 }

Aggiungere il seguente frammento di codice all'interno della condizione foreach. Questo frammento di codice eseguirà la stessa operazione della condizione 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 sezione retrieve multiple del metodo Execute dovrebbe essere simile a quella illustrata nell'immagine seguente.

Compilare di nuovo il progetto e assicurarsi che la compilazione abbia esito positivo.

Attività 4 - Aggiornamento dell'assembly del plug-in e registrazione dei passaggi

Avviare Plug-in Registration Tool e selezionare Crea nuova connessione.
Selezionare Office 365, quindi Mostra avanzate, fornire le proprie credenziali e scegliere Accedi.
Selezionare l'assembly registrato nell'Esercizio 1, quindi scegliere Aggiorna.
Selezionare Sfoglia.
Andare alla cartella debug del progetto, selezionare D365PackageProject.dll, quindi selezionare Apri.
Selezionare i plug-in, quindi selezionare Aggiorna plug-in selezionati.
Selezionare OK.
Fare clic con il pulsante destro del mouse sul nuovo plug-in e selezionare Registra nuovo passaggio.
Selezionare Retrieve nel campo Messaggio, selezionare contatto nel campo Entità primaria e quindi selezionare PostOperation nel campo Fase di esecuzione pipeline eventi. Assicurarsi di aver selezionato Sincrona nel campo Modalità di esecuzione e quindi selezionare Registra nuovo passaggio.
Fare clic con il pulsante destro del mouse sul plug-in e selezionare di nuovo Registra nuovo passaggio.
Selezionare RetrieveMultiple nel campo Messaggio, selezionare contatto nel campo Entità primaria e selezionare PostOperation nel campo Fase di esecuzione pipeline eventi. Assicurarsi di aver selezionato Sincrona nel campo Modalità di esecuzione e quindi selezionare Registra nuovo passaggio.

Attività 5. Verificare il plug-in

Andare a Maker Portal e verificare di trovarsi nell'ambiente corretto.
Selezionare App. Selezionare l'applicazione Fundraiser, quindi selezionare Modifica. Si aggiungerà la tabella Contact all'applicazione.
Selezionare + Nuova pagina.
Selezionare Tabella Dataverse, quindi selezionare Avanti.
Selezionare Tabella esistente. Selezionare la tabella Contact, quindi selezionare Aggiungi.
Selezionare Riproduci.
Selezionare Salva e continua.
Selezionare di nuovo Riproduci.
Selezionare Contatti.
I record esistenti che non sono stati salvati con il nuovo formato non cambieranno. Selezionare + Nuovo.
Specificare le seguenti informazioni, quindi selezionare Salva. A questo punto il record viene salvato e il plug-in applica il nuovo formato.
Selezionare di nuovo Contatti. Il record creato dovrebbe avere il nuovo formato.
Selezionare uno dei contatti esistenti per aprirlo.
Modificare il valore del campo Telefono ufficio nel seguente modo:
Selezionare Salva. Dovrebbe essere applicato il nuovo formato. Selezionare di nuovo Contatti.

Il telefono modificato dovrebbe avere il nuovo formato.

Commenti e suggerimenti

Questa pagina è stata utile?