Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
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:
Modifica il file PackageTemplate.cs o il file PackageImportExtension.cs nella cartella radice del progetto.
Nel file C# è possibile:
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
SkipChecksper 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.
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.Usare la definizione del metodo di override di
RunSolutionUpgradeMigrationStepper 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 solutionNameNome della soluzione. oldVersionNumero di versione della soluzione precedente. newVersionNumero di versione della nuova soluzione. oldSolutionIdGUID della soluzione precedente. newSolutionIdGUID della nuova soluzione. Esegui l'override del metodo
OverrideSolutionImportDecisionper 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); }Immettere il codice personalizzato da eseguire prima che l'importazione della soluzione venga completata nella definizione di override del
BeforeImportStagemetodo . Lo strumento importa i dati di esempio e alcuni file flat per le soluzioni specificate nelImportConfig.xmlfile prima del completamento dell'importazione della soluzione.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 fileImportConfig.xml. Specificare il file di importazione dei dati di configurazione predefinito nell'attributocrmmigdataimportfilenel fileImportConfig.xml.Ignorare i controlli dei dati (OverrideDataImportSafetyChecks = true) può essere efficace se sei sicuro che l'istanza Dataverse di destinazione non contenga alcun dato.
Immettere il codice personalizzato da eseguire al termine dell'importazione nella definizione di override del
AfterPrimaryImportmetodo. Lo strumento importa i file flat rimanenti che non sono stati importati in precedenza, prima dell'avvio dell'importazione della soluzione.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"; } }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.
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.
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.
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 = 4RaiseFailEvent(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 trueofalse. 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 trueofalse. Il valore predefinito èfalse.
Impostare questa proprietà sutruesolo se l'istanza di Dataverse di destinazione non contiene dati.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.zipNote
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.