Condividi tramite

Creare pacchetti per lo strumento Package Deployer

  • Articolo

Package Deployer consente agli amministratori di distribuire pacchetti nelle istanze di Microsoft Dataverse. Un pacchetto Package Deployer può essere dato da uno o tutti i seguenti elementi:

  • Uno o più file di soluzione di Dataverse.
  • File flat o file di dati di configurazione esportati dallo strumento di migrazione della configurazione. Per ulteriori informazioni sullo strumento, vedi Spostare i dati di configurazione tra le istanze e le organizzazioni con lo strumento di migrazione della configurazione.
  • Codice personalizzato che può essere eseguito prima, durante o dopo la distribuzione dell'istanza di Dataverse.
  • Contenuto HTML specifico del pacchetto che può essere visualizzato all'inizio e alla fine del processo di distribuzione. Questo contenuto può essere utile per fornire una descrizione delle soluzioni e dei file distribuiti nel pacchetto.

Nota

C'è un altro tipo di pacchetto chiamato pacchetto di plug-in. Questo tipo di pacchetto è per assembly dipendenti dal plug-in e non ha alcuna relazione con i pacchetti Package Deployer.

Prerequisiti

  • Assicurati di aver preparato tutte le soluzioni e altri file che desideri includere nel pacchetto.
  • Visual Studio 2019 o versioni successive oppure Visual Studio Code.

Panoramica processo

Per creare un pacchetto Package Deployer, esegui i passaggi seguenti.

  • Creare un progetto Visual Studio o MSBuild
  • Aggiungi soluzioni e altri file al progetto
  • Aggiorna i file HTML forniti (facoltativo)
  • Specifica i valori di configurazione per il pacchetto
  • Definisci il codice personalizzato per il pacchetto
  • Creazione e sviluppo del pacchetto

Questi passaggi sono descritti in dettaglio in questo articolo.

Creare un progetto per il pacchetto

Il primo passaggio è creare un progetto Visual Studio o MSBuild per il pacchetto. Per farlo, devi avere una delle due estensioni dello strumento disponibili installata sul tuo computer di sviluppo. Se utilizzi Visual Studio Code, installa Microsoft Power Platform CLI. Altrimenti, se si utilizza Visual Studio 2019 o successivo, installa Power Platform Tools per Visual Studio.

Seleziona la scheda appropriata di seguito per scoprire come creare un progetto utilizzando l'estensione dello strumento desiderata. Entrambi gli strumenti generano il progetto in un formato simile.

Esegui il comando pac package init per creare il pacchetto iniziale. Maggiori informazioni: pac package

pac package init help
pac package init --outputDirectory DeploymentPackage

L'output dell'interfaccia della riga di comando risultante contiene le cartelle ei file mostrati di seguito. Il nome della cartella "DeploymentPackage" è stato utilizzato qui come esempio.

C:.
└───DeploymentPackage
    │   DeploymentPackage.csproj
    │   PackageImportExtension.cs
    │
    └───PkgAssets
            ImportConfig.xml
            manifest.ppkg.json

Nel progetto creato, trova il file di configurazione ImportConfig.xml nella cartella PkgAssets e il file PackageImportExtension.cs. Modificherai questi file come descritto più avanti in questo articolo.

Aggiungere file pacchetto

Dopo aver creato un progetto di pacchetto, puoi iniziare ad aggiungere soluzioni e altri file a quel progetto.

Quando si utilizza l'interfaccia della riga di comando, è possibile aggiungere pacchetti, soluzioni e riferimenti al progetto del pacchetto esterni utilizzando uno dei comandi secondari Aggiungi. Immettere pac package help per visualizzare l'elenco dei comandi secondari. Aggiungiamo una soluzione al nostro pacchetto.

> pac package add-solution help

Commands:
Usage: pac package add-solution --path [--import-order] [--skip-validation] [--publish-workflows-activate-plugins] [--overwrite-unmanaged-customizations] [--import-mode] [--missing-dependency-behavior] [--dependency-overrides]

> cd .\DeploymentPackage\
> pac package add-solution --path ..\TestSolution_1_0_0_1_managed.zip

The item was added successfully.

Configurare il pacchetto

Definisci la configurazione del pacchetto aggiungendo informazioni sul pacchetto nel file ImportConfig.xml, nel progetto. Fai riferimento a Riferimento ImportConfig per un esempio e le descrizioni degli elementi e degli attributi validi da utilizzare.

Aggiungi codice personalizzato

È possibile aggiungere codice personalizzato che viene eseguito prima, durante e dopo l'importazione del pacchetto in un ambiente. A tale scopo, segui le istruzioni riportate di seguito.

  1. Modifica il file PackageTemplate.cs (o PackageImportExtension.cs) nella cartella principale del progetto.

  2. Nel file C# è possibile:

    1. Immettere il codice personalizzato da eseguire quando il pacchetto viene inizializzato nella definizione del metodo di override di InitializeCustomExtension.

      Questo metodo può essere utilizzato per consentire agli utenti di utilizzare i parametri di runtime durante l'esecuzione di un pacchetto. Come sviluppatore puoi aggiungere supporto per tutti i parametri di runtime al pacchetto utilizzando la proprietà RuntimeSettings se disponi di un codice per elaborarlo in base all'input dell'utente.

      Ad esempio, il seguente codice di esempio abilita un parametro di runtime chiamato SkipChecks per il pacchetto con due possibili valori: true o false. Il codice di esempio controlla se l'utente ha specificato i parametri di runtime durante l'esecuzione di Package Deployer (utilizzando la riga comandi o PowerShell) e quindi di conseguenza elabora le informazioni. Se non è stato specificato nessun parametro runtime dall'utente mentre esegue il pacchetto, il valore della proprietà RuntimeSettings sarà null.

      public override void InitializeCustomExtension()  
{  
// Do nothing.  

// Validate the state of the runtime settings object.  
if (RuntimeSettings != null)  
{  
PackageLog.Log(string.Format("Runtime Settings populated.  Count = {0}", RuntimeSettings.Count));  
foreach (var setting in RuntimeSettings)  
{  
PackageLog.Log(string.Format("Key={0} | Value={1}", setting.Key, setting.Value.ToString()));  
}  

// Check to see if skip checks is present.  
if ( RuntimeSettings.ContainsKey("SkipChecks") )  
{  
bool bSkipChecks = false;  
if (bool.TryParse((string)RuntimeSettings["SkipChecks"], out bSkipChecks))  
OverrideDataImportSafetyChecks = bSkipChecks;  
}  
}  
else  
PackageLog.Log("Runtime Settings not populated");  
}

      Questo codice consente all'amministratore di utilizzare la riga di comando oppure il cmdlet Import-CrmPackage per specificare se ignorare i controlli di sicurezza durante l'esecuzione di Package Deployer per importare il pacchetto. Altre informazioni: Distribuire pacchetti con Package Deployer e Windows PowerShell

    2. Immetti il codice personalizzato da eseguire prima che vengano importate le soluzioni nella definizione del metodo di sovrascrittura di PreSolutionImport per specificare se mantenere o sovrascrivere le personalizzazioni mentre si aggiorna la soluzione specificata in un'istanza Dataverse di destinazione e se attivare automaticamente i plug-in e i flussi di lavoro.

    3. Utilizza la definizione del metodo override di RunSolutionUpgradeMigrationStep per eseguire la trasformazione o l'aggiornamento dei dati tra due versioni di una soluzione. Questo metodo viene chiamato solo se la soluzione che stai importando è già presente nell'istanza Dataverse di destinazione.

      Questa funzione prevede i parametri seguenti:

      Parametro Descrizione
      solutionName Nome della soluzione.
      oldVersion Numero di versione della soluzione precedente.
      newVersion Numero di versione della nuova soluzione.
      oldSolutionId GUID della soluzione precedente.
      newSolutionId GUID della nuova soluzione.

    4. Immetti il codice personalizzato da eseguire prima che venga completata l'importazione della soluzione nella definizione di override del metodo BeforeImportStage. I dati di esempio e alcuni file flat per soluzioni specificate nel file ImportConfig.xml sono importati prima che venga completata l'importazione della soluzione.

    5. Sostituisci la lingua al momento selezionata per l'importazione dei dati di configurazione utilizzando la definizione del metodo di override di OverrideConfigurationDataFileLanguage. Se l'ID delle impostazioni locali specificato della lingua specificata non è disponibile nell'elenco delle lingue disponibili nel pacchetto, viene incluso il file dei dati predefinito.

      Specifica le lingue disponibili per i dati di configurazione nel nodo <cmtdatafiles> nel file ImportConfig.xml. Il file di importazione dei dati di configurazione predefinito è specificato nell'attributo crmmigdataimportfile nel file ImportConfig.xml.

      Ignorare i controlli dei dati (OverrideDataImportSafetyChecks = true) può essere efficace se sei sicuro che l'istanza Dataverse di destinazione non contenga alcun dato.

    6. Immetti il codice personalizzato da eseguire dopo il completamento dell'importazione nella definizione della sovrascrittura del metodo AfterPrimaryImport>. I file flat rimanenti che non sono stati importati in precedenza, prima dell'importazione della soluzione verranno ora importati.

    7. Modifica il nome predefinito della cartella del pacchetto al nome del pacchetto desiderato. A tale scopo, rinomina la cartella PkgFolder (o PkgAssets) nel riquadro Esplora soluzioni, quindi modifica il valore restituito nella GetImportPackageDataFolderName proprietà .

      public override string GetImportPackageDataFolderName  
{  
get  
{  
// WARNING this value directly correlates to the folder name in the Solution Explorer where the ImportConfig.xml and sub content is located.  
// Changing this name requires that you also change the correlating name in the Solution Explorer  
return "PkgFolder";  
}  
}

    8. Modificare il nome del pacchetto modificando il valore restituito nella proprietà GetNameOfImport.

      public override string GetNameOfImport(bool plural)  
{  
return "Package Short Name";  
}

      Questo valore restituito è il nome del pacchetto che appare nella pagina di selezione del pacchetto nella creazione guidata di Dynamics 365 Package Deployer.

    9. Modificare la descrizione del pacchetto modificando il valore restituito nella proprietà GetImportPackageDescriptionText.

      
public override string GetImportPackageDescriptionText  
{  
get { return "Package Description"; }  
}

      Questo valore restituito è la descrizione del pacchetto che appare insieme al nome del pacchetto nella pagina di selezione del pacchetto nella procedura guidata di Package Deployer.

    10. Modificare il nome esteso del pacchetto modificando il valore restituito nella proprietà GetLongNameOfImport.

      
public override string GetLongNameOfImport  
{  
get { return "Package Long Name"; }  
}

      Il nome esteso del pacchetto viene visualizzato nella pagina successiva dopo aver selezionato il pacchetto da installare.

  3. Inoltre, per il pacchetto sono disponibili la funzione e le variabili seguenti:

    Nome Tipo Descrizione
    CreateProgressItem(String) Funzione Viene utilizzato per creare un nuovo elemento dello stato nell'interfaccia utente (IU).
    RaiseUpdateEvent(String, ProgressPanelItemStatus) Funzione Viene utilizzato per aggiornare lo stato creato dalla chiamata a CreateProgressItem(String).

    ProgressPanelItemStatus è un'enumerazione con i seguenti valori:

    In esecuzione = 0
    Completato = 1
    Non riuscito = 2
    Avviso = 3
    Sconosciuto = 4
    RaiseFailEvent(String, Exception) Function Viene utilizzato per l'importazione dello stato corrente non riuscita con la generazione di un messaggio di eccezione.
    IsRoleAssoicatedWithTeam(Guid, Guid) Funzione Viene utilizzato per determinare se un ruolo è associato a un team specificato.
    IsWorkflowActive(Guid) Funzione Viene utilizzato per determinare se un flusso di lavoro specificato è attivo.
    PackageLog Puntatore delle classi Un puntatore all'interfaccia di registrazione inizializzata per il pacchetto. Questa interfaccia viene utilizzata da un pacchetto per registrare i messaggi e le eccezioni nel file di registro del pacchetto.
    RootControlDispatcher Proprietà Un'interfaccia del dispatcher utilizzata per consentire il controllo per il rendering dell'interfaccia utente durante la distribuzione del pacchetto. Utilizzare questa interfaccia per eseguire il wrapping di eventuali elementi o comandi dell'interfaccia utente. È importante verificare questa variabile per rilevare la presenza di valori Null prima di utilizzarla, in quanto potrebbe non essere impostata su un valore.
    CrmSvc Proprietà Un puntatore alla classe CrmServiceClient che consente a un pacchetto di indirizzare Dynamics 365 dall'interno del pacchetto. Utilizza questo puntatore per eseguire i metodi SDK e altre operazioni nei metodi sottoposti a override.
    DataImportBypass Proprietà Specifica se Dynamics 365 Package Deployer ignora tutte le operazioni di importazione dei dati come l'importazione dei dati di esempio Dataverse e i dati esportati dallo strumento di migrazione della configurazione. Specifica vero o falso. Il valore predefinito è false.
    OverrideDataImportSafetyChecks Proprietà Specifica se Dynamics 365 Package Deployer ignora alcuni dei controlli di sicurezza. Ciò aiuta a migliorare le prestazioni di importazione. Specifica true o false. Il valore predefinito è false.

    È consigliabile impostare questa proprietà su true solo se l'istanza di destinazione di Dataverse non contiene alcun dato.

  4. Salvare il progetto. Il prossimo passaggio è la creazione del pacchetto.

Crea e distribuisci

Le sezioni seguenti descrivono come creare e distribuire un pacchetto.

Crea

La creazione del tuo pacchetto è descritta di seguito a seconda dello strumento che stai utilizzando.

Per compilare un pacchetto creato con la CLI, è possibile caricare il file .csproj in Visual Studio, ma in questa sede utilizzeremo il comando dotnet e MSBuild. L'esempio seguente presuppone che la directory di lavoro contenga il file *.csproj.

> dotnet publish

DeploymentPackage -> C:\Users\peter\Downloads\DeploymentPackage\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip

Puoi facoltativamente visualizzare i dettagli del pacchetto costruito.

> pac package show --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip

Il pacchetto è costituito dai file seguenti nella cartella <Project>\Bin\Debug.

  • Cartella <PackageName>: il nome della cartella è lo stesso di quello modificato per il nome della cartella del pacchetto nel passaggio 2.g di questa sezione Aggiungi codice personalizzato. Questa contiene tutte le soluzioni, i dati di configurazione, i file flat e i contenuti per il pacchetto.

Nota

Potresti vedere una cartella .NET (ad esempio, net472) contenente una cartella pdpublish. La tua DLL e altri file di progetto si trovano in quella cartella pdpublish.

  • <PackageName>.dll: l'assembly include il codice personalizzato del pacchetto. Per impostazione predefinita, il nome dell'assembly è uguale al nome del progetto.

Distribuisci

Dopo aver creato un pacchetto, puoi distribuirlo nell'istanza di Dataverse utilizzando lo strumento Package Deployer, Windows PowerShell o un comando dell'interfaccia della riga di comando.

  • Per distribuire utilizzando lo strumento Package Deployer, scarica prima lo strumento come descritto in Strumenti di sviluppo Dataverse. Segui quindi le informazioni dettagliate sulla distribuzione dei pacchetti nell'articolo Distribuire pacchetti utilizzando Package Deployer o Windows PowerShell.

  • Per distribuire utilizzando l'interfaccia della riga di comando, usa il comando pac package deploy.

    > pac package deploy --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip

    Nota

    Per distribuire un pacchetto in un ambiente di destinazione utilizzando l'interfaccia della riga di comando, devi prima impostare un profilo di autenticazione e selezionare un'organizzazione. Maggiori informazioni: pac auth create, pac org select

Procedure consigliate

Di seguito sono elencati alcuni suggerimenti di procedure consigliate da seguire quando si usano i pacchetti Package Deployer.

Creazione di pacchetti

Durante la creazione di pacchetti, gli sviluppatori devono:

  • Assicurarsi che gli assembly del pacchetto siano firmati.

Distribuzione dei pacchetti

Durante la distribuzione di pacchetti, gli amministratori di Dataverse devono:

  • Insistere sull'utilizzo di un assembly del pacchetto firmato affinché sia possibile ricollegare un assembly alla relativa origine.
  • Verificare il pacchetto in un'istanza di preproduzione, preferibilmente un'immagine mirror dell'istanza di produzione, prima di eseguirlo in un'istanza di produzione.
  • Eseguire il backup dell'istanza di produzione prima di distribuire il pacchetto.

Vedi anche

Strumento per la creazione di pacchetti di soluzioni