Sdílet prostřednictvím

Vytvoření balíčků pro nástroj Package Deployer

  • Článek

Package Deployer umožňuje správcům nasadit balíčky na instance Microsoft Dataverse. Balíček Package Deployer může být tvořen jakoukoli nebo všemi následujícími položkami:

  • Jeden nebo více souborů řešení aplikace Dataverse.
  • Ploché soubory nebo soubory konfiguračních dat z nástroje pro migraci konfigurace. Další informace o tomto nástroji viz Přesunutí dat konfigurace mezi instancemi a organizacemi pomocí nástroje Configuration Migration tool.
  • Vlastní kód, který lze spustit před, během nebo po nasazení balíčku do instance Dataverse.
  • HTML obsah specifický pro balíček, který se může zobrazit na začátku nebo konci procesu nasazení. Tento obsah může být užitečný pro poskytnutí popisu řešení a souborů, které jsou nasazeny v balíčku.

Poznámka:

Existuje další typ balíčku nazývaný balíček modulu plug-in. Tento druh balíčku je určen pro sestavení závislá na modulech plug-in a nemá žádný vztah s balíčky Package Deployer.

Předpoklady

  • Ujistěte se, že máte připravena všechna řešení a další soubory, které chcete zahrnout do balíčku.
  • Visual Studio 2019 nebo pozdější nebo Visual Studio Code.

Přehled procesu

Chcete-li vytvořit balíček Package Deployer, proveďte následující kroky.

  • Vytvořte projekt Visual Studio nebo MSBuild
  • Přidejte řešení a další soubory do projektu
  • Aktualizujte poskytnuté soubory HTML (volitelné)
  • Zadejte hodnoty konfigurace balíčku
  • Definujte vlastní kód pro balíček
  • Sestavte a nasaďte balíček

Tyto kroky jsou podrobně popsány v tomto článku.

Vytvoření projektu balíčku

Prvním krokem je vytvoření projektu Visual Studio nebo MSBuild pro balíček. Chcete-li to provést, musíte mít na vývojovém počítači nainstalované jedno ze dvou dostupných rozšíření nástrojů. Pokud používáte Visual Studio Code, nainstalujte Microsoft Power Platform CLI. V opačném případě, pokud používáte Visual Studio 2019 nebo novější, nainstalujte Power Platform Tools pro Visual Studio.

Vyberte příslušnou kartu níže a zjistěte, jak vytvořit projekt pomocí požadovaného rozšíření nástroje. Výstup obou nástrojů je projekt v podobném formátu.

Spusťte příkaz pac package init k vytvoření počátečního balíčku. Další informace: pac package

pac package init help
pac package init --outputDirectory DeploymentPackage

Výsledný výstup rozhraní příkazového řádku obsahuje složky a soubory zobrazené níže. Jako příklad zde byl použit název složky „DeploymentPackage“.

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

Ve vytvořeném projektu najděte konfigurační soubor ImportConfig.xml ve složce PkgAssets a soubor PackageImportExtension.cs. Tyto soubory upravíte, jak je popsáno dále v tomto článku.

Přidání souborů balíčku

Po vytvoření projektu balíčku můžete začít přidávat řešení a další soubory do tohoto projektu.

Při použití rozhraní příkazového řádku můžete do projektu balíčku přidat externí balíčky, řešení a odkazy pomocí jednoho z dílčích příkazů pro přidání. Příkazem pac package help zobrazíte seznam dílčích příkazů. Nyní přidejme řešení do našeho balíčku.

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

Konfigurace balíčku

Definujte konfiguraci balíčku přidáním informací o vašem balíčku do souboru ImportConfig.xml v projektu. V části Referenční informace o souboru ImportConfig najdete příklad a popisy platných prvků a atributů k použití.

Přidání vlastního kódu

Můžete přidat vlastní kód, který se spustí před, během a po importu balíčku do prostředí. Postup je následující.

  1. Upravte soubor PackageTemplate.cs (nebo PackageImportExtension.cs) v kořenové složce projektu.

  2. V souboru C# můžete:

    1. Zadat vlastní kód, který se má provést při inicializaci balíčku v definici metody přepsání InitializeCustomExtension.

      Tuto metodu lze použít k tomu, aby uživatelé mohli používat parametry modulu runtime při spuštění balíčku. Jako vývojář můžete do balíčku přidat podporu libovolného parametru modulu runtime pomocí vlastnosti RuntimeSettings, pokud máte kód pro zpracování na základě vstupu uživatele.

      Následující ukázkový kód například povoluje volaný parametr modulu runtime SkipChecks pro balíček, který má dvě možné hodnoty: true nebo false. Ukázkový kód zkontroluje, zda uživatel během spuštění nástroje Package Deployer určil nějaké parametry modulu runtime (buď pomocí příkazového řádku nebo prostředí PowerShell), a poté informace příslušným způsobem zpracovává. Pokud uživatel při spuštění balíčku nezadá žádný parametr modulu runtime, hodnota vlastnosti RuntimeSettings bude null.

      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ávci používat příkazový řádek nebo rutinu Import-CrmPackage k zadání, zda přeskočit bezpečnostní kontroly při spuštění nástroje Package Deployer pro import balíčku. Další informace: Nasazení balíčků pomocí nástroje Package Deployer a prostředí Windows PowerShell

    2. Zadat vlastní kód, který se má provést před importem řešení v definici metody přepsání PreSolutionImport pro určení, zda se mají zachovat nebo přepsat vlastní nastavení při aktualizaci zadaného řešení v cílové instanci Dataverse a zda se mají automaticky aktivovat moduly plugin a pracovní postupy.

    3. Použít definici metody přepsání RunSolutionUpgradeMigrationStep k provedení transformace nebo upgradu dat mezi dvěma verzemi řešení. Tato metoda se volá, pouze pokud se importované řešení již nachází v cílové instanci Dataverse.

      Tato funkce očekává následující parametry:

      Parametr Popis
      solutionName Název řešení
      oldVersion Číslo verze starého řešení
      newVersion Číslo verze nového řešení
      oldSolutionId Identifikátor GUID starého řešení.
      newSolutionId Identifikátor GUID nového řešení.

    4. Zadat vlastní kód, který se má provést před dokončením importu řešení v definici metody přepsání metody BeforeImportStage. Ukázková data a některé ploché soubory pro řešení uvedená v souboru ImportConfig.xml jsou importovány před dokončením importu řešení.

    5. Přepsat aktuálně vybraný jazyk pro import konfiguračních dat pomocí definice metody přepsání OverrideConfigurationDataFileLanguage. Pokud zadané ID národního prostředí (LCID) zadaného jazyka není nalezeno v seznamu dostupných jazyků v balíčku, bude importován výchozí datový soubor.

      Dostupné jazyky pro konfigurační data zadáte v uzlu <cmtdatafiles> v souboru ImportConfig.xml. Výchozí soubor pro import konfiguračních dat je uveden v atributu crmmigdataimportfile v souboru ImportConfig.xml.

      Přeskakování kontrol dat (OverrideDataImportSafetyChecks = true) zde může být efektivní, pokud jste si jisti, že cílová instance Dataverse neobsahuje žádná data.

    6. Zadat vlastní kód, který se má provést po dokončení importu v definici metody přepsání metody AfterPrimaryImport>. Zbývající ploché soubory, které nebyly importovány dříve, než byl zahájen import řešení, se nyní importují.

    7. Změňte výchozí název složky balíčku na požadovaný název balíčku. Chcete-li tak učinit, přejmenujte složku PkgFolder (nebo PkgAssets) v podokně Průzkumník řešení a poté upravte vrácenou hodnotu pod vlastností 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. Změnit název balíčku úpravou návratové hodnoty pod vlastností GetNameOfImport.

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

      Tato vrácená hodnota je název vašeho balíčku, který se objevuje na stránce pro výběr balíčku v průvodci nástrojem Dynamics 365 Package Deployer.

    9. Změnit popis balíčku úpravou návratové hodnoty pod vlastností GetImportPackageDescriptionText.

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

      Tato vrácená hodnota je popis vašeho balíčku, který se objevuje vedle názvu balíčku na stránce pro výběr balíčku v průvodci nástrojem Package Deployer.

    10. Změnit dlouhý název balíčku úpravou návratové hodnoty pod vlastností GetLongNameOfImport.

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

      Dlouhý název balíčku se objeví na další stránce poté, co jste vybrali balíček, který chcete nainstalovat.

  3. Balíček navíc obsahuje následující funkce a proměnné:

    Název Typ Popis
    CreateProgressItem(String) Function Slouží k vytvoření nové položky postupu v uživatelském rozhraní (UI).
    RaiseUpdateEvent(String, ProgressPanelItemStatus) Function Slouží k aktualizaci postupu vytvořeného voláním CreateProgressItem(String).

    ProgressPanelItemStatus je výčet s následujícími hodnotami:

    Pracovní = 0
    Dokončeno = 1
    Chyba = 2
    Varování = 3
    Neznámé = 4
    RaiseFailEvent(String, Exception) Function Slouží k selhání importu aktuálního stavu pomocí zprávy o výjimce.
    IsRoleAssoicatedWithTeam(Guid, Guid) Function Slouží k určení, zda je role přidružena k zadanému týmu.
    IsWorkflowActive(Guid) Function Slouží k určení, zda je zadaný pracovní postup aktivní.
    PackageLog Ukazatel třídy Ukazatel inicializovaného rozhraní protokolování balíčku. Toto rozhraní používá balíček k protokolování zpráv a výjimek do souboru protokolu balíčku.
    RootControlDispatcher Vlastnost Rozhraní dispečera sloužící k tomu, abyste mohli během implementace balíčku vykreslit vlastní uživatelské rozhraní. Toto rozhraní slouží k zalomení všech prvků nebo příkazů uživatelského rozhraní. Před použitím této proměnné je důležité zkontrolovat, zda obsahuje nebo neobsahuje hodnotu null, protože může být nastavena na hodnotu.
    CrmSvc Vlastnost Ukazatel na třídu CrmServiceClient, která umožňuje, aby balíček adresoval Dynamics 365 z balíčku. Tento ukazatel použijte k provedení metod SDK a dalších akcí v přepsaných metodách.
    DataImportBypass Vlastnost Zadejte, zda Dynamics 365 Package Deployer přeskočí všechny operace importu dat, jako je import ukázkových dat Dataverse, data plochých souborů a data exportovaná z Configuration Migration Tool. Zadejte true nebo false. Výchozí hodnota je false.
    OverrideDataImportSafetyChecks Vlastnost Určete, zda Dynamics 365 Package Deployer vynechává některé ze svých bezpečnostních kontrol, což pomáhá zlepšit výkonnost importu. Zadejte true nebo false. Výchozí hodnota je false.

    Měli byste nastavit tuto vlastnost na true, pouze pokud cílová instance Dataverse neobsahuje žádná data.

  4. Uložte projekt. Dalším krokem je sestavení balíčku.

Sestavení a nasazení

Následující části popisují, jak sestavit a nasadit balíček.

Sestavení

Sestavení balíčku je popsáno níže v závislosti na tom, jaký nástroj používáte.

Chcete-li sestavit balíček vytvořený pomocí CLI, můžete načíst soubor .csproj do Visual Studio, ale místo toho použijeme příkaz dotnet a MSBuild. Níže uvedený příklad předpokládá, že pracovní adresář obsahuje soubor *.csproj.

> dotnet publish

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

Volitelně se můžete podívat na detaily sestaveného balíčku.

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

Váš balíček tvoří následující soubory ve složce <Project>\Bin\Debug.

  • Složka <PackageName>: Název složky je stejný jako název složky, kterou jste změnili pro název složky balíčku v kroku 2.g této části Přidání vlastního kódu. Tato složka obsahuje všechna řešení, konfigurační data, ploché soubory a obsah balíčku.

Poznámka:

Můžete vidět složku .NET (např. net472) obsahující složku pdpublish. Vaše DLL a další soubory projektu jsou v této složce pdpublish.

  • <PackageName>.dll: Sestavení obsahuje vlastní kód vašeho balíčku. Výchozí název sestavení je stejný jako název projektu.

Nasadit

Po vytvoření balíčku jej můžete nasadit do instance Dataverse pomocí nástroje Package Deployer nebo prostředí Windows PowerShell nebo příkaz rozhraní příkazového řádku.

  • K nasazení pomocí nástroje Package Deployer si nejprve stáhněte tento nástroj, jak je popsáno v části Vývojové nástroje Dataverse. Dále postupujte podle podrobných informací o nasazení balíčků v článku Nasazení balíčků pomocí Package Deployer nebo Windows PowerShell.

  • Chcete-li provést nasazení pomocí rozhraní příkazového řádku, použijte příkaz pac package deploy.

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

    Poznámka:

    Chcete-li nasadit balíček do cílového prostředí pomocí rozhraní příkazového řádku, musíte nejprve nastavit profil ověřování a vybrat organizaci. Další informace: pac auth create, pac org select

Osvědčené postupy

Níže je uvedeno několik tipů osvědčených postupů, které byste měli dodržovat při práci s balíčky Package Deployer.

Vytváření balíčků

Při vytváření balíčků musí vývojáři:

  • Zajistit, že jsou podepsány sestavení balíčků.

Nasazování balíčků

Při nasazování balíčků musí správci aplikace Dataverse:

  • Trvat na sestavení podepsaného balíčku tak, abyste mohli sledovat sestavení zpět k jeho zdroji.
  • Otestovat balíček na předprodukční instanci, nejlépe zrcadlový obraz produkční instance, před jeho spuštěním v produkční instanci.
  • Zálohovat produkční instanci před nasazením balíčku.

Viz také

Nástroj Solution Packager