Vytvorenie balíkov pre nástroj Package Deployer

Package Deployer umožňuje správcom nasadiť balíky na inštancie systému Microsoft Dataverse. Balík Package Deployer môže obsahovať čokoľvek z tohto:

• Jeden alebo viac súborov riešenia Dataverse.
• Textové súbory alebo súbor konfiguračných údajov z Configuration Migration Tool. Viac informácií o nástroji sa dozviete v časti Presun konfiguračných údajov cez inštancie a organizácie s nástrojom Configuration Migration Tool.
• Vlastný kód, ktorý sa spustí pred, počas, alebo po nasadení balíka do inštancie Dataverse.
• Obsah HTML špecifický pre balík, ktorý môžete zobraziť na začiatku a na konci procesu nasadenia. Tento obsah môže byť užitočný pre popis riešení a súborov, ktoré sú nasadené v balíčku.

Požiadavky

• Uistite sa, že máte pripravené všetky riešenia a iné súbory, ktoré chcete zahrnúť do balíka.
• Visual Studio 2019 alebo neskôr, alebo Visual Studio Kód.

Prehľad procesov

Ak chcete vytvoriť balík Package Deployer , vykonajte nasledujúce kroky.

Tieto kroky sú podrobne popísané v tomto článku.

Vytvorenie projektu balíka

Prvým krokom je vytvorenie projektu Visual Studio alebo MSBuild pre balík. Aby ste to dosiahli, musíte mať na svojom vývojovom počítači nainštalované jedno z dvoch dostupných rozšírení nástrojov. Ak používate Visual Studio Code, nainštalujte Microsoft Power Platform CLI. V opačnom prípade, ak používate Visual Studio 2019 alebo novší, nainštalujte si Power Platform nástroje pre Visual Studio.

Vyberte príslušnú kartu nižšie a zistite, ako vytvoriť projekt pomocou požadovaného rozšírenia nástroja. Oba nástroje vydávajú projekt v podobnom formáte.

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

Pridať súbory balíka

Po vytvorení projektu balíka môžete začať pridávať riešenia a ďalšie súbory do tohto projektu.

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

Konfigurácia balíka

Definujte konfiguráciu balíka pridaním informácií o vašom balíku do súboru ImportConfig.xml, ktorý je k dispozícii v projekte. Príklad a popis platných prvkov a atribútov, ktoré sa majú použiť, nájdete v Referenčná príručka ImportConfig .

Pridať vlastný kód

Môžete pridať vlastný kód, ktorý sa spustí pred, počas a po importe balíka do prostredia. Postupujte podľa týchto pokynov.

1. Upravte PackageTemplate.cs (alebo PackageImportExtension.cs) v koreňovom priečinku projektu.

2. V súbore C# môžete:

   1. Zadajte vlastný kód, ktorý sa má vykonať po inicializácii balíka v definícii metódy prepísania InitializeCustomExtension.

      Túto metódu je možné použiť na to, aby používatelia mohli používať parametre runtime počas spúšťania balíka. Ako vývojár môžete do balíka pridať podporu ľubovoľného parametra runtime pomocou vlastnosti RuntimeSettings, pokiaľ máte kód na jej spracovanie na základe vstupu používateľa.

      Napríklad nasledujúci vzorový kód umožňuje spustenie parametra runtime s názvom SkipChecks pre balík, ktorý má dve možné hodnoty: true alebo false. Vzorový kód skontroluje, či užívateľ zadal počas behu Package Deployer nejaké parametre runtime (buď pomocou príkazového riadka alebo PowerShell) a potom príslušné informácie spracuje. Ak používateľ počas spúšťania balíka neurčí žiadny parameter runtime, hodnota vlastnosti RuntimeSettings bude prázdna.

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

      Tento kód umožňuje správcovi používať príkazový riadok alebo cmdlet Import-CrmPackage, aby určil, či sa majú preskočiť kontroly bezpečnosti počas nástroja Package Deployer na import balíka. Ďalšie informácie: Nasadenie balíkov pomocou nástrojov Package Deployer a Windows PowerShell

   2. Zadajte vlastný kód, ktorý sa má vykonať pred importom riešení v definícii metódy prepísania PreSolutionImport na určenie, či sa majú zachovať alebo prepísať prispôsobenia pri aktualizácii zadaného riešenia v cieľovej inštancii Dataverse a či sa majú automaticky aktivovať doplnky a pracovné postupy.

   3. Na vykonanie transformácie údajov alebo inovácie medzi dvoma verziami riešenia použite definíciu metódy prepísania RunSolutionUpgradeMigrationStep . Táto metóda sa volá iba vtedy, ak sa riešenie, ktoré importujete, už nachádza v cieli Dataverse príklad.

      Táto funkcia očakáva nasledujúce parametre:

      Parameter	Popis
      solutionName	Názov riešenia
      oldVersion	Číslo verzie starého riešenia
      newVersion	Číslo verzie nového riešenia
      oldSolutionId	GUID starého riešenia.
      newSolutionId	GUID nového riešenia.

   4. Zadajte vlastný kód, ktorý sa má vykonať pred dokončením importu riešenia v definícii prepísania metódy BeforeImportStage. Vzorové údaje a niektoré textové súbory pre riešenia uvedené v súbore ImportConfig.xml sa importujú pred dokončením importu riešenia.

   5. Prepíšte aktuálne vybratý jazyk pre import konfiguračných údajov pomocou definície metódy prepísania OverrideConfigurationDataFileLanguage. Ak zadané ID miestneho nastavenia (LCID) zadaného jazyka nenájdete v zozname dostupných jazykov v balíku, importuje sa predvolený dátový súbor.

      Dostupné jazyky pre konfiguračné údaje zadáte v uzle <cmtdatafiles> v súbore ImportConfig.xml. Predvolený súbor na import konfiguračných údajov je uvedený v atribúte crmmigdataimportfile v súbore ImportConfig.xml.

      Preskočenie kontrol údajov (OverrideDataImportSafetyChecks = true) tu môže byť účinné, ak ste si istí, že cieľová Dataverse inštancia neobsahuje žiadne údaje.

   6. Zadajte vlastný kód, ktorý sa má vykonať po dokončení importu v definícii prepísania metódy AfterPrimaryImport>. Zostávajúce ploché súbory, ktoré neboli importované skôr, pred spustením importu riešenia, sa importujú teraz.

   7. Zmeňte predvolený názov priečinka balíka na požadovaný názov balíka. Ak to chcete urobiť, premenujte priečinok PkgFolder (alebo PkgAssets) na table Prieskumník riešení a potom upravte návratovú hodnotu pod vlastnosťou 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. Zmeňte názov balíka úpravou návratovej hodnoty pod vlastnosťou GetNameOfImport.

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

      Táto vrátená hodnota je názov vášho balíka, ktorý sa zobrazí na stránke výberu balíka v sprievodcovi Dynamics 365 Package Deployer .

   9. Zmeňte popis balíka úpravou návratovej hodnoty pod vlastnosťou GetImportPackageDescriptionText.

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

      Táto vrátená hodnota je popis balíka, ktorý sa zobrazuje vedľa názvu balíka na stránke výberu balíka v sprievodcovi Package Deployer .

   10. Zmeňte dlhý názov balíka úpravou návratovej hodnoty pod vlastnosťou GetLongNameOfImport.

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

       Dlhý názov balíka sa zobrazí na ďalšej stránke potom, čo ste vybrali balík na inštaláciu.

3. Balík má navyše k dispozícii nasledujúce funkcie a premenné:

   Meno	Typ	Popis
   CreateProgressItem(String)	Function	Používa sa na vytvorenie novej položky postupu v používateľskom rozhraní (UI).
   RaiseUpdateEvent(String, ProgressPanelItemStatus)	Function	Používa sa na aktualizáciu postupu vytvoreného volaním do CreateProgressItem(String). ProgressPanelItemStatus je enumerácia s nasledujúcimi hodnotami: Pracuje sa = 0 Dokončené = 1 Zlyhanie = 2 Upozornenie = 3 Neznáme = 4
   RaiseFailEvent(String, Exception)	Function	Používa sa na zlyhanie importu aktuálneho stavu pomocou správy o výnimke.
   IsRoleAssoicatedWithTeam(Guid, Guid)	Function	Používa sa na určenie, či je rola priradená konkrétnemu tímu.
   IsWorkflowActive(Guid)	Function	Používa sa na určenie, či je zadaný pracovný postup aktívny.
   PackageLog	Ukazovateľ triedy	Ukazovateľ na inicializované logovacie rozhranie balíka. Toto rozhranie používa balík na zaznamenávanie správ a výnimiek zo súboru denníka balíka.
   RootControlDispatcher	Vlastnosť	Dispečerské rozhranie, ktoré vám umožňuje ovládať vykreslenie vlastného používateľského rozhrania počas nasadenia balíka. Toto rozhranie slúži na zabalenie akýchkoľvek prvkov alebo príkazov používateľského rozhrania. Pred použitím tejto premennej je dôležité skontrolovať, či neobsahuje hodnoty null, pretože nemusí byť nastavená na hodnotu.
   CrmSvc	Vlastnosť	Ukazovateľ na triedu CrmServiceClient, ktorá umožňuje balíku adresovať Dynamics 365 zvnútra balíka. Tento ukazovateľ použite na spustenie metód SDK a ďalších akcií v prepísaných metódach.
   DataImportBypass	Vlastnosť	Uveďte, či Dynamics 365 Package Deployer preskočí všetky operácie importu údajov, napríklad import vzorových údajov Dataverse, údajov textových súborov a údaje exportované z nástroja Configuration Migration Tool. Zadajte možnosť true alebo false. Predvolené je false.
   OverrideDataImportSafetyChecks	Vlastnosť	Zadajte, či Dynamics 365 Package Deployer obchádza niektoré z jeho bezpečnostných kontrol, čo pomáha pri zlepšovaní výkonu importu. Zadajte true alebo false. Predvolené je false. Túto vlastnosť by ste mali nastaviť na true iba ak cieľová Dataverse inštancia neobsahuje žiadne údaje.

4. Uložte svoj projekt. Ďalším krokom je vytvorenie balíka.

Vytvorenie a nasadenie

Nasledujúce časti popisujú, ako zostaviť a nasadiť balík.

Zostava

Vytvorenie balíka je popísané nižšie v závislosti od toho, ktorý nástroj používate.

> 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

Váš balík obsahuje nasledujúce súbory pod priečinkom <Project>\Bin\Debug.

• <PackageName> priečinok: Názov priečinka je rovnaký ako ten, ktorý ste zmenili pre názov priečinka balíčka v krok 2.g tejto sekcie Pridať vlastný kód. Tento priečinok obsahuje všetky riešenia, konfiguračné údaje, textové súbory a obsah balíka.

• <PackageName>.dll: Zostava obsahuje vlastný kód pre váš balík. Podľa predvoleného nastavenia názov zostavy je rovnaký ako váš názov projektu.

Nasadiť

Po vytvorení balíka ho môžete nasadiť v inštancii Dataverse pomocou nástroja Package Deployer, Windows PowerShell alebo príkazu CLI.

• Na nasadenie pomocou nástroja Package Deployer je najprv potrebné stiahnuť si nástroj podľa opisu vývojových nástrojov Dataverse. Ďalej postupujte podľa podrobných informácií o nasadení balíka v článku Nasadenie balíkov pomocou Package Deployer alebo Windows PowerShell.

• Ak chcete nasadiť pomocou CLI, použite príkaz pac package deploy.

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

  Poznámka

  Ak chcete nasadiť balík do cieľového prostredia pomocou CLI, musíte najprv nastaviť profil autentifikácie a vybrať organizáciu. Ďalšie informácie: pac auth create, pac org select

Osvedčené postupy

Nižšie je uvedených niekoľko tipov na osvedčené postupy, ktoré treba dodržiavať pri práci s balíkmi Package Deployer.

Vytváranie balíkov

Pri vytváraní balíkov musia vývojári:

• Uistite sa, že zostavy balíkov sú podpísané.

Nasadenie balíkov

Pri nasadzovaní balíčkov musia správcovia Dataverse:

• Trvajte na podpísaných zostavách balíkov , aby ste mohli zostavu sledovať späť k jej zdroju.
• Pred spustením na výrobná inštancia otestujte balík na predprodukčnej inštancii, pokiaľ možno zrkadlový obraz výrobná inštancia.
• Pred nasadením balíka si zálohujte výrobná inštancia .

Pozrite si tiež

Nástroj Solution Packager