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.

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

Prezentare generală a proceselor

Pentru a crea un pachet Package Deployer , urmați pașii următori.

  • Creează 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 crearea unui 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ă folosești Visual Studio Code, instalează Microsoft Power Platform CLI. În caz contrar, dacă folosești Visual Studio 2019 sau mai târziu, instalează unelte Power Platform 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. Vei 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()  
{
  // 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. Mai multe informații: Deploy pachete folosind 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 suprascriere 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 instanța Dataverse țintă.

      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. Înlocuiți metoda OverrideSolutionImportDecision pentru a returna o enumerare UserRequestedImportAction care controlează dacă importul unei soluții va fi omis, actualizat sau actualizat (implicit).

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

    6. Suprascrieți limba selectată în prezent pentru importul datelor de configurare utilizând definiția metodei de suprascriere din OverrideConfigurationDataFileLanguage. Dacă ID-ul de setări regionale specificat (LCID) pentru limba specificată nu se găsește î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 de date (OverrideDataImportSafetyChecks = true) poate fi eficientă aici dacă sunteți sigur că instanța țintă Dataverse nu conține date.

    7. 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 anterior, înainte de începerea importului soluției, sunt importate acum.

    8. Modificați numele implicit al dosarului pachetului dvs. în numele de pachet dorit. Pentru a face acest lucru, redenumiți folderul PkgFolder (sau PkgAssets) din panoul Solution Explorer și apoi editați valoarea returnării sub proprietatea 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. 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 care apare pe pagina de selecție a pachetului din vrăjitorul Dynamics 365 Package Deployer.

    10. 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 lângă numele pachetului pe pagina de selectare a pachetului din expert. Package Deployer

    11. 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) Funcţie Utilizat pentru a crea un nou element de progres în interfața utilizator (UI).
    RaiseUpdateEvent(String, ProgressPanelItemStatus) Funcţie 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) Funcţie Folosit pentru a eșua importul de stare curentă cu un mesaj de excepție.
    IsRoleAssociatedWithTeam(Guid, Guid) Funcţie Utilizat pentru a determina dacă un rol este asociat cu o echipă specificată.
    IsWorkflowActive(Guid) Funcţie 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 dacă această variabilă are valori nule înainte de a o utiliza, deoarece este posibil să nu fie setată la o valoare.
    CrmSvc Proprietate Un pointer către clasa CrmServiceClient care permite unui pachet să adreseze Dynamics 365 din interiorul pachetului. Utilizați acest indicator pentru a executa metode SDK și alte acțiuni în metodele suprasolicitate.
    DataImportBypass Proprietate Specifică dacă Dynamics 365 Package Deployer sare peste toate operațiunile de import de date, cum ar fi importul datelor de probă Dataverse, date de fișiere plate și date exportate din instrumentul de migrare a configurației. Specificați adevărat sau fals. Implicit este false.
    OverrideDataImportSafetyChecks Proprietate Specifică dacă Dynamics 365 Package Deployer ocolește unele dintre verificările 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 țintă Dataverse 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 se construiește și se implementează 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, ai putea î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 pasul 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ă

Poți vedea un folder .NET (de exemplu, net472) care conține un folder pdpublishing. DLL-ul dvs. și alte fișiere de proiect sunt în acel dosar pdpublish.

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

Implementare

După ce creezi un pachet, îl poți implementa în instanța Dataverse folosind 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, urmează informațiile detaliate despre implementarea pachetelor din articolul Deploy packages using 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 asamblărilor de pachete semnate astfel încât să puteți urmări un asamblaj până la sursa sa.
  • Testați pachetul pe o instanță de preproducție, de preferință o imagine în oglindă a instanței de producție, înainte de a-l rula pe o instanță de producție.
  • Faceți o copie de rezervă a instanței de producție înainte de a implementa pachetul.

Vedeți și

Instrumentul Solution Packager

  • Last updated on