Crearea de pachete pentru instrumentul Package Deployer

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.

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.

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.

pac package init help
pac package init --outputDirectory DeploymentPackage

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

C:.
│   Deployment-package.csproj
│   Deployment-package.sln
│   GettingStarted.html
│   PackageTemplate.cs
│
├───PkgFolder
│   │   ImportConfig.xml
│   │
│   └───Content

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.

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

      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 a 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 = adevărat) 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 asistentul 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 un 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 importului. 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.

> dotnet publish

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

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

• <PackageName>.DLL: ansamblul conține codul personalizat 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 ansamblurilor de pachete semnate 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 de rezervă pentru instanță de producție înainte de a implementa pachetul.

Consultați și

Instrumentul Solution Packager