Partajați prin

Crearea de pachete pentru instrumentul Package Deployer

  • Articol

Package Deployer permite administratorilor să implementeze pachete pe instanțe Microsoft Dataverse. Un pachet Package Deployer poate consta în următoarele elemente:

  • Unul sau mai multe fișiere soluție Dataverse.
  • Fișiere plate sau fișiere de date de configurare din instrumentul Migrare configurare. Pentru informații suplimentare despre instrument, consultați Mutați date de configurare în instanțe și organizații cu instrumentul Migrare configurare.
  • Codul particularizat care poate rula înaintea, în timpul, sau după ce pachetul este implementat în instanța Dataverse.
  • Conținutul HTML specific pachetului care se poate afișa la începutul și la sfârșitul procesului de implementare. Acest conținut poate fi util pentru a furniza o descriere a soluțiilor și fișierelor implementate în pachet.

Notă

Există un alt tip de pachet numit pachet de inserturi. Acest tip de pachet este pentru ansambluri dependente de inserturi și nu are nicio relație cu pachetele Package Deployer.

Cerințe preliminare

  • Asigurați-vă că aveți toate soluțiile și alte fișiere pregătite pe care doriți să le includeți în pachet.
  • Visual Studio 2019 sau mai târziu sau Visual Studio Cod.

Prezentare generală a procesului

Pentru a crea un Package Deployer pachet, parcurgeți următorii pași.

  • Creați un proiect Visual Studio sau MSBuild
  • Adăugați soluții și alte fișiere la proiect
  • Actualizați fișierele HTML furnizate (opțional)
  • Specificați valorile de configurare pentru pachet
  • Definiți codul personalizat pentru pachet
  • Construiți și implementați pachetul

Acești pași sunt descriși în detaliu în acest articol.

Crearea unui proiect de pachet

Primul pas este să creați un proiect Visual Studio sau MSBuild pentru pachet. Pentru a face acest lucru, trebuie să aveți una dintre cele două extensii de instrumente disponibile instalată pe computerul de dezvoltare. Dacă utilizați Visual Studio Code, instalați CLI Microsoft Power Platform. În caz contrar, dacă utilizați Visual Studio 2019 sau o versiune ulterioară, instalați Power Platform instrumente pentru Visual Studio.

Selectați fila corespunzătoare de mai jos pentru a afla cum să creați un proiect folosind extensia de instrumente dorită. Ambele instrumente produc proiectul într-un format similar.

Rulați comanda pac package init pentru a crea pachetul inițial. Mai multe informații: pachet pac

pac package init help
pac package init --outputDirectory DeploymentPackage

Ieșirea CLI rezultată conține dosarele și fișierele prezentate mai jos. Numele dosarului „DeploymentPackage” a fost folosit aici ca exemplu.

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

În proiectul creat, găsiți fișierul de configurare ImportConfig.xml în folderul PkgAssets și fișierul PackageImportExtension.cs. Veți modifica aceste fișiere așa cum este descris mai târziu în acest articol.

Adăugarea de fișiere unui pachet

După ce ați creat un proiect de pachet, puteți începe să adăugați soluții și alte fișiere la acel proiect.

Când utilizați CLI, puteți adăuga pachete externe, soluții și referințe la proiectul dvs. de pachet folosind una dintre subcomenzile adăugare. Introduceți pac package help pentru a vedea lista subcomenzilor. Să adăugăm o soluție la pachetul nostru.

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

Configurarea pachetului

Definiți configurația pachetului adăugând informații despre pachetul dvs. în fișierul ImportConfig.xml din proiect. Consultați ImportConfig Reference pentru un exemplu și descrieri ale elementelor și atributelor valide de utilizat.

Adăugarea unui cod personalizat

Puteți adăuga un cod personalizat care se execută înainte, în timpul și după importarea pachetului într-un mediu. În acest scop, urmați aceste instrucțiuni.

  1. Editați fișierul PackageTemplate.cs (sau PackageImportExtension.cs) din dosarul rădăcină al proiectului.

  2. În fișierul C#, puteți:

    1. Introduceți codul personalizat pentru a executa atunci când pachetul este inițializat în definiția metodei de înlocuire a InitializeCustomExtension.

      Această metodă poate fi utilizată pentru a permite utilizatorilor să utilizeze parametrii de rulare în timpul rulării unui pachet. Ca dezvoltator, puteți adăuga asistență pentru orice parametru de execuție la pachetul dvs. utilizând proprietatea RuntimeSettings atâta timp cât aveți cod pentru procesarea acestuia pe baza intrării utilizatorului.

      De exemplu, următorul cod de eșantionare activează un parametru de rulare numit SkipChecks pentru pachetul care are două valori posibile: adevărat sau fals. Codul de eșantion verifică dacă utilizatorul a specificat parametri de execuție în timpul rulării Package Deployer (fie folosind linia de comandă sau PowerShell), apoi procesează informațiile în consecință. Dacă utilizatorul nu specifică niciun parametru de rulare în timpul rulării pachetului, valoarea proprietății RuntimeSettings va fi nulă.

      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");  
}

      Acest cod permite administratorului să utilizeze linia de comandă sau cmdlet Import-CrmPackage pentru a specifica dacă săriți verificările de siguranță în timpul rulării instrumentului Package Deployer pentru a importa pachetul. Informații suplimentare: Implementați pachete utilizând Package Deployer și Windows PowerShell

    2. Introduceți codul personalizat pentru a fi executat înainte ca soluțiile să fie importate în definiția metodei de anulare a PreSolutionImport pentru a specifica dacă mențineți sau rescrieți personalizările în timp ce actualizați soluția specificată într-o instanță țintă Dataverse și dacă activați automat inserturile și fluxurile de lucru.

    3. Utilizați definiția metodei de înlocuire a RunSolutionUpgradeMigrationStep pentru a efectua transformarea datelor sau actualizarea între două versiuni ale unei soluții. Această metodă este apelată numai dacă soluția pe care o importați este deja prezentă în țintă Dataverse instanță.

      Această funcție se așteaptă la următorii parametri:

      Parametru Descriere
      solutionName Numele soluției
      oldVersion Numărul de versiune al soluției vechi
      newVersion Numărul de versiune al soluției noi
      oldSolutionId GUID-ul soluției vechi.
      newSolutionId GUID-ul soluției noi.

    4. Introduceți codul particularizat pentru a executa înainte ca importul de soluție să se finalizeze în definiția de înlocuire a metodei BeforeImportStage. Datele eșantion și unele fișiere plane pentru soluții specificate în fișierul ImportConfig.xml sunt importate înainte de completarea importului de soluții.

    5. Suprascrieți limba selectată în prezent pentru importul datelor de configurare utilizând definiția metodei de înlocuire OverrideConfigurationDataFileLanguage. Dacă ID-ul de localizare specificat (LCID) al limbii specificate nu este găsit în lista de limbi disponibile din pachet, fișierul de date implicit este importat.

      Specificați limbile disponibile pentru datele de configurare din nodul <cmtdatafiles> în fișierul ImportConfig.xml. Fișierul implicit de importare a datelor de configurare este specificat în atributul crmmigdataimportfile în fișierul ImportConfig.xml.

      Omiterea verificărilor datelor (OverrideDataImportSafetyChecks = true) poate fi eficientă aici dacă sunteți sigur că instanța Dataverse țintă nu conține date.

    6. Introduceți codul particularizat pentru a executa după ce importul se finalizează în definiția de înlocuire a metodei AfterPrimaryImport>. Fișierele plate rămase care nu au fost importate mai devreme, înainte de începerea importului soluției, sunt importate acum.

    7. Modificați numele implicit al dosarului pachetului dvs. în numele de pachet dorit. Pentru a face acest lucru, redenumiți dosarul PkgFolder (sau PkgAssets) din panoul Explorator de soluții și apoi editați valoarea returnată sub proprietatea GetImportPackageDataFolderName.

      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. Schimbați numele pachetului prin editarea valorii de returnare sub proprietatea GetNameOfImport.

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

      Această valoare returnată este numele pachetului dvs. care apare pe pagina de selecție a pachetului din expertul Dynamics 365 Package Deployer .

    9. Schimbați descrierea pachetului prin editarea valorii de returnare sub proprietatea GetImportPackageDescriptionText.

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

      Această valoare returnată este descrierea pachetului care apare alături de numele pachetului pe pagina de selecție a pachetului din expertul Package Deployer .

    10. Schimbați numele lung al pachetului prin editarea valorii de returnare sub proprietatea GetLongNameOfImport.

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

      Numele lung al pachetului apare pe pagina următoare după ce ați selectat pachetul de instalat.

  3. În plus, următoarele funcții și variabile sunt disponibile pentru pachet:

    Nume Tip Descriere
    CreateProgressItem(String) Function Utilizat pentru a crea un nou element de progres în interfața utilizator (UI).
    RaiseUpdateEvent(String, ProgressPanelItemStatus) Function Utilizat pentru a actualiza progresul creat de apelul la CreateProgressItem(String).

    ProgressPanelItemStatus este o enumerare cu următoarele valori:

    Funcționează = 0
    Complet = 1
    Nereușit = 2
    Avertisment = 3
    Necunoscut = 4
    RaiseFailEvent(String, Exception) Function Folosit pentru a eșua importul de stare curentă cu un mesaj de excepție.
    IsRoleAssoicatedWithTeam(Guid, Guid) Function Utilizat pentru a determina dacă un rol este asociat cu o echipă specificată.
    IsWorkflowActive(Guid) Function Utilizat pentru a determina dacă un flux de lucru specificat este activ.
    PackageLog Indicator de clasă Un indicator către interfața de logare inițiată pentru pachet. Această interfață este folosită de un pachet pentru a înregistra mesaje și excepții de la fișierul jurnal de pachete.
    RootControlDispatcher Proprietate O interfață de dispecerat folosită pentru a permite controlului dvs. să-și redea propria UI în timpul implementării pachetului. Utilizați această interfață pentru a încadra orice elemente sau comenzi UI. Este important să verificați această variabilă pentru valori nule înainte de a o folosi, deoarece este posibil să nu fie setată la o valoare.
    CrmSvc Proprietate Un indicator pentru clasa CrmServiceClient care permite unui pachet să abordeze Dynamics 365 din interiorul pachetului. Utilizați acest indicator pentru a executa metode SDK și alte acțiuni în metodele suprasolicitate.
    DataImportBypass Proprietate Specificați dacă Dynamics 365 Package Deployer omite toate operațiunile de importare a datelor, cum ar fi importul eșantioanelor de date Dataverse, date de fișier plat și date exportate din instrumentul Migrare configurare. Specificați adevărat sau fals. Implicit este false.
    OverrideDataImportSafetyChecks Proprietate Specificați dacă Dynamics 365 Package Deployer ocolește unele dintre verificările sale de siguranță, ceea ce ajută la îmbunătățirea performanței de import. Specificați true sau false. Implicit este false.

    Ar trebui să setați această proprietate la true numai dacă instanța Dataverse țintă nu conține date.

  4. Salvați-vă proiectul. Următorul pas este să construiți pachetul.

Construire și implementare

Următoarele secțiuni descriu cum să construiți și să implementați un pachet.

Versiune

Construirea pachetului este descrisă mai jos, în funcție de instrumentul pe care îl utilizați.

Pentru a construi un pachet creat cu CLI, puteți încărca fișierul .csproj în Visual Studio, dar în schimb vom folosi comanda dotnet și MSBuild. Exemplul de mai jos presupune că directorul de lucru conține fișierul *.csproj.

> dotnet publish

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

Opțional, puteți vedea detaliile pachetului construit.

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

Pachetul dvs. este format din următoarele fișiere sub dosarul <Project>\Bin\Debug folder.

  • <PackageName> folder: numele folderului este același cu cel pe care l-ați modificat pentru numele folderului pachetului în pas 2.g din această secțiune Adăugați cod personalizat. Acest dosar conține toate soluțiile, date de configurare, fișiere plate și conținuturile pentru pachetul dvs.

Notă

Este posibil să vedeți un dosar .NET (de exemplu, net472) care conține un dosar pdpublish. DLL-ul dvs. și alte fișiere de proiect sunt în acel dosar pdpublish.

  • <PackageName>.dll: Ansamblul conține codul particularizat pentru pachetul dvs. În mod implicit, numele ansamblului este identic cu numele proiectului dvs.

Implementați

După ce creați un pachet, îl puteți implementa în instanța Dataverse utilizând fie instrumentul Package Deployer, Windows PowerShell sau o comandă CLI.

  • Pentru a implementa folosind instrumentul Package Deployer, mai întâi descărcați instrumentul așa cum este descris în instrumentele de dezvoltare Dataverse. Apoi, urmați informațiile detaliate despre implementarea pachetelor din articolul Implementați pachete folosind Package Deployer sau Windows PowerShell.

  • Pentru a implementa folosind CLI, utilizați comanda pac package deploy.

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

    Notă

    Pentru a implementa un pachet într-un mediu țintă folosind CLI, trebuie mai întâi să configurați un profil de autentificare și să selectați o organizație. Mai multe informații: creare aut pac, selectare org pac

Cele mai bune practici

Mai jos sunt enumerate câteva sfaturi privind cele mai bune practici ce pot fi urmate atunci când lucrați cu pachetele Package Deployer.

Crearea pachetelor

Când creează pachete, dezvoltatorii trebuie să:

  • Asigurați-vă că ansamblurile de pachete sunt semnate.

Implementarea pachetelor

Când implementează pachete, administratorii Dataverse trebuie să facă următoarele lucruri:

  • Insistați asupra semnării ansamblurilor de pachete, astfel încât să puteți urmări un ansamblu înapoi la sursă.
  • Testați pachetul pe o instanță de preproducție, de preferință o imagine în oglindă a instanță de producție, înainte de a-l rula pe un instanță de producție.
  • Faceți o copie a instanței de producție înainte de a implementa pachetul.

Consultați și

Instrumentul de împachetare soluții