Creare pacchetti per lo strumento Package Deployer

Package Deployer consente agli amministratori di distribuire pacchetti in istanze di Microsoft Dataverse. Un Package Deployer package può consistere in 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 del pacchetto all'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.

Note

Esiste un altro tipo di pacchetto denominato pacchetto 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 versione successiva o Visual Studio Code.

Panoramica processo

Per creare un pacchetto Package Deployer, seguire questa procedura:

  • 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

Questo articolo descrive in dettaglio questi passaggi.

Creare un progetto pacchetto

Creare prima di tutto un progetto Visual Studio o MSBuild per il pacchetto. Per creare il progetto, installare una delle due estensioni dello strumento disponibili sul computer di sviluppo. Se usi Visual Studio Code, installa Microsoft Power Platform CLI. Se si usa Visual Studio 2019 o versione successiva, installare gli strumenti di Power Platform per Visual Studio.

Per informazioni su come creare un progetto usando l'estensione dello strumento desiderata, selezionare la scheda appropriata nella sezione seguente. Entrambi gli strumenti generano il progetto in un formato simile.

Esegui il comando pac package init per creare il pacchetto iniziale. Per altre informazioni, vedere pacchetto pac.

pac package init help
pac package init --outputDirectory DeploymentPackage

L'output della CLI include le cartelle e i file seguenti. Il nome DeploymentPackage viene usato qui come esempio.

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

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

Aggiungere file di pacchetto

Dopo aver creato un progetto di pacchetto, è possibile iniziare ad aggiungere soluzioni e altri file al progetto.

Quando si usa la CLI, è possibile aggiungere pacchetti, soluzioni e riferimenti esterni al progetto di pacchetto usando uno dei sottocomandi add. 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. Per un esempio e le descrizioni degli attributi e degli elementi validi da usare, vedi Informazioni di riferimento su ImportConfig.

Aggiungi codice personalizzato

È possibile aggiungere codice personalizzato eseguito prima, durante e dopo l'importazione del pacchetto in un ambiente. Per aggiungere codice personalizzato, seguire queste istruzioni:

  1. Modifica il file PackageTemplate.cs o il file PackageImportExtension.cs nella cartella radice 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.

      Usare questo metodo per consentire agli utenti di usare 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 verifica se l'utente specifica i parametri di runtime durante l'esecuzione di Package Deployer (usando la riga di comando o PowerShell) e quindi elabora le informazioni di conseguenza. Se l'utente non specifica un parametro di runtime durante l'esecuzione del pacchetto, il valore della RuntimeSettings proprietà è Null.

      public override void InitializeCustomExtension()  
      {
        // 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 usare la riga di comando o il cmdlet Import-CrmPackage per specificare se ignorare i controlli di sicurezza durante l'esecuzione dello strumento Package Deployer per importare il pacchetto. Per altre informazioni, vedere Distribuire pacchetti con Package Deployer e Windows PowerShell.

    2. Immettere il codice personalizzato da eseguire prima dell'importazione delle soluzioni nella definizione del metodo di override di PreSolutionImport. Usa questo metodo 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. Usare la definizione del metodo di override di RunSolutionUpgradeMigrationStep per eseguire la trasformazione o l'aggiornamento dei dati tra due versioni di una soluzione. Questo metodo viene eseguito solo se la soluzione importata è già presente nell'istanza di Dataverse di destinazione.

      Questa funzione prevede i parametri seguenti:

      Parametro Description
      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. Esegui l'override del metodo OverrideSolutionImportDecision per restituire un'enumerazione UserRequestedImportAction che controlla se l'importazione di una soluzione viene ignorata o aggiornata (impostazione predefinita).

      public override UserRequestedImportAction OverrideSolutionImportDecision(
        string solutionUniqueName, Version organizationVersion,
        Version packageSolutionVersion, Version inboundSolutionVersion,
        Version deployedSolutionVersion, ImportAction systemSelectedImportAction )
      {
        return systemSelectedImportAction == 
            ImportAction.Import ? UserRequestedImportAction.ForceUpdate
            : base.OverrideSolutionImportDecision(solutionUniqueName, organizationVersion,
            packageSolutionVersion, inboundSolutionVersion, deployedSolutionVersion,
            systemSelectedImportAction);
      }
      
    5. Immettere il codice personalizzato da eseguire prima che l'importazione della soluzione venga completata nella definizione di override del BeforeImportStage metodo . Lo strumento importa i dati di esempio e alcuni file flat per le soluzioni specificate nel ImportConfig.xml file prima del completamento dell'importazione della soluzione.

    6. Eseguire l'override della lingua attualmente selezionata per l'importazione dei dati di configurazione usando 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. Specificare il file di importazione dei dati di configurazione predefinito 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.

    7. Immettere il codice personalizzato da eseguire al termine dell'importazione nella definizione di override del AfterPrimaryImport metodo. Lo strumento importa i file flat rimanenti che non sono stati importati in precedenza, prima dell'avvio dell'importazione della soluzione.

    8. 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 proprietà GetImportPackageDataFolderName.

      public override string GetImportPackageDataFolderName  
      {  
          get  
          {  
              // WARNING this value directly correlates to the folder name in Solution 
              // Explorer where the ImportConfig.xml and sub content is located.  
              // Changing this name requires that you also change the correlating name
              // in Solution Explorer.
              return "PkgFolder";  
          }  
      }  
      
    9. 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 viene visualizzato nella pagina di selezione del pacchetto nella procedura di creazione guidata di Package Deployer di Dynamics 365.

    10. 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.

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

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

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

  3. Il pacchetto ha anche accesso alle funzioni e alle variabili seguenti:

    Name Type Description
    CreateProgressItem(String) Funzione Crea un nuovo elemento di avanzamento nell'interfaccia utente (UI).
    RaiseUpdateEvent(String, ProgressPanelItemStatus) Funzione Aggiorna lo stato di avanzamento creato dalla chiamata a CreateProgressItem(String).

    ProgressPanelItemStatus è un enum con i seguenti valori:

    Funzionante = 0
    Completato = 1
    Non riuscito = 2
    Avviso = 3
    Sconosciuto = 4
    RaiseFailEvent(String, Exception) Funzione Non supporta l'importazione dello stato corrente non riuscita con la generazione di un messaggio di eccezione.
    IsRoleAssociatedWithTeam(Guid, Guid) Funzione Determina se un ruolo è associato a un team specificato.
    IsWorkflowActive(Guid) Funzione Determina se un flusso di lavoro specificato è attivo.
    PackageLog Puntatore delle classi Un puntatore all'interfaccia di log inizializzata del pacchetto. Il pacchetto usa questa interfaccia per registrare messaggi ed eccezioni nel file di log del pacchetto.
    RootControlDispatcher Proprietà Interfaccia dispatcher usata dal controllo per eseguire il rendering della propria interfaccia utente durante la distribuzione del pacchetto. Utilizzare questa interfaccia per eseguire il wrapping di eventuali elementi o comandi dell'interfaccia utente. Controllare la presenza di valori Null per questa variabile prima di usarla, perché potrebbe non essere impostata su un valore.
    CrmSvc Proprietà Puntatore alla CrmServiceClient classe che consente a un pacchetto di accedere a Dynamics 365 dall'interno del pacchetto. Utilizza questo puntatore per eseguire i metodi SDK e altre operazioni nei metodi sottoposti a override.
    DataImportBypass Proprietà Specificare se Dynamics 365 Package Deployer ignora tutte le operazioni di importazione dei dati, ad esempio l'importazione di dati di esempio di Dataverse, i dati di file flat e i dati esportati dallo strumento di migrazione della configurazione. Specificare true o false. Il valore predefinito è false.
    OverrideDataImportSafetyChecks Proprietà Indica se Package Deployer di Dynamics 365 ignora alcuni dei controlli di sicurezza. Ciò aiuterà a migliorare le prestazioni di importazione. Specificare true o false. Il valore predefinito è false.

    Impostare questa proprietà su true solo se l'istanza di Dataverse di destinazione non contiene dati.
  4. Salva il tuo progetto. Il prossimo passaggio è la creazione del pacchetto.

Crea e distribuisci

Le sezioni seguenti descrivono come creare e distribuire un pacchetto.

Costruire

Le sezioni seguenti descrivono come compilare il pacchetto, a seconda dello strumento in uso.

Per compilare un pacchetto creato con l'interfaccia della riga di comando, è possibile caricare il .csproj file in Visual Studio, ma è anche possibile usare il dotnet comando e MSBuild. Nell'esempio seguente si presuppone che la directory di lavoro contenga il *.csproj file .

> dotnet publish

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

Facoltativamente, è possibile visualizzare i dettagli del pacchetto compilato.

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

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

  • <PackageName> folder: il nome della cartella corrisponde al nome scelto per la cartella del pacchetto nel passaggio 2.g della sezione Aggiungi codice personalizzato . Questa contiene tutte le soluzioni, i dati di configurazione, i file flat e i contenuti per il pacchetto.

Note

Potrebbe essere visualizzata una cartella .NET ,ad esempio net472, che contiene una pdpublish cartella. La DLL e altri file di progetto si trovano in tale pdpublish cartella.

  • <PackageName>.dll: l'assembly .NET contiene il codice personalizzato per il pacchetto. Per impostazione predefinita, il nome dell'assembly corrisponde al nome del progetto.

Distribuisci

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

  • Per eseguire la distribuzione con lo strumento Package Deployer, scaricare prima di tutto lo strumento come descritto in Strumenti di sviluppo di Dataverse. Seguire quindi le informazioni dettagliate sulla distribuzione dei pacchetti nell'articolo Deploy packages using Package Deployer or Windows PowerShell.

  • Per distribuire usando la CLI, utilizza il comando pac package deploy.

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

    Note

    Per distribuire un pacchetto in un ambiente di destinazione usando l'interfaccia della riga di comando, è prima necessario configurare un profilo di autenticazione e selezionare un'organizzazione. Per altre informazioni, vedere pac auth create e 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 dei pacchetti siano firmati.

Distribuzione dei pacchetti

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

  • Insistere sui pacchetti di assembly firmati in modo da poter risalire all'origine di un assembly.
  • Testare il pacchetto su un'istanza di pre-produzione, preferibilmente un'immagine speculare dell'istanza di produzione, prima di eseguirla su un'istanza di produzione.
  • Eseguire il backup dell'istanza di produzione prima di distribuire il pacchetto.

Vedere anche

Strumento per la creazione di pacchetti di soluzioni