Dela via

Skapa paket för verktyget Package Deployer

  • Artikel

Package Deployer gör det möjligt för administratörer att distribuera paket på Microsoft Dataverse-instanser. Ett Package Deployer paket kan bestå av några eller alla av följande:

  • En eller flera Dataverse-lösningsfiler.
  • Platta filer eller exporterade datafiler från Configuration Migration Tool. Mer information om verktyget finns i Flytta konfigurationsdata över instanser och organisationer med Configuration Migration Tool.
  • Anpassad kod som kan köras före, under eller efter att paketet distribuerats till Dataverse-instansen.
  • HTML-innehåll som är specifikt för paketet och som kan visas i början och slutet av distributionsprocessen. Detta innehåll kan vara användbart för att ge en beskrivning av de lösningar och filer som distribueras i paketet.

Kommentar

Det finns en annan pakettyp som kallas plugin-programpaket. Den sortens paket är för plugin-beroende sammansättningar och har ingen relation till Package Deployer-paket.

Förutsättningar

  • Kontrollera att du har alla de lösningar och andra filer redo som du vill ta med i paketet.
  • Visual Studio 2019 eller senare eller Visual Studio Code.

Översikt över processen

Att skapa en Package Deployer paketet, utför följande steg.

  • Skapa ett Visual Studio eller MSBuild projekt
  • Lägga till lösningar och andra filer i projektet
  • Uppdatera medföljande HTML-filer (valfritt)
  • Ange konfigurationsvärdena för paketet
  • Definiera en anpassad kod för paketet
  • Skapa och distribuera paketet

Dessa steg beskrivs i detalj i den här artikeln.

Skapa ett paketprojekt

Det första steget är att skapa ett Visual Studio eller MSBuild-projekt för paketet. För att kunna göra detta måste du ha ett av två tillgängliga verktygstillägg installerat på utvecklingsdatorn. Om du använder Visual Studio Code installerar du Microsoft Power Platform CLI. Annars, om du använder Visual Studio 2019 eller senare, installerar du Power Platform-verktyg för Visual Studio.

Markera fliken nedan om du vill ta reda på hur du skapar ett projekt med det önskade verktygstillägget. Båda verktygen matar ut projektet i ett liknande format.

Kör kommandot pac package init för att skapa det ursprungliga paketet. Mer information: pac-paket

pac package init help
pac package init --outputDirectory DeploymentPackage

Den resulterande CLI-utdata innehåller programmen och filerna som visas nedan. Namnet på mappen DeploymentPackage användes här som exempel.

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

I det skapade projektet hittar du konfigurationsfilen ImportConfig.xml i mappen PkgAssets och filen PackageImportExtension.cs. Du kommer att ändra dessa filer enligt beskrivningen längre fram i den här artikeln.

Lägg till paketfiler

När du har skapat ett paketprojekt kan du börja lägga till lösningar och andra filer i det projektet.

När du använder CLI kan du lägga till externa paket, lösningar och referenser till ditt paketprojekt med hjälp av ett av underkommandona lägg till. Ange pac package help om du vill visa listan över underkommandon. Vi lägger till en lösning i vårt paket.

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

Konfigurera paketet

Definiera pakets konfiguration genom att lägga till information om paketet i filen ImportConfig.xml i projektet. Se ImportConfig-referensen för ett exempel och beskrivningar av de giltiga elementen och attributen.

Lägg till anpassad kod

Du kan lägga till anpassad kod som körs före, under och efter att paketet har importerats till en miljö. Följ anvisningarna nedan för att göra detta.

  1. Redigera PackageTemplate.cs (eller PackageImportExtension.cs) filen i projektets rotmapp.

  2. I C#-filen kan du:

    1. Ange egen kod som ska köras när paketet initieras i metoddefinitionen för åsidosättning för InitializeCustomExtension.

      Denna metod kan användas för att låta användarna använda körningsparametrar medan ett paket körs. Som utvecklare kan du lägga till stöd för valfri körningsparameter i paketet genom att använda egenskapen RuntimeSettings så länge du har kod för att bearbeta den baserat på användarindatan.

      Följande exempelkod aktiverar t.ex. en körningsparameter kallad SkipChecks för paketet som har två möjliga värden: "true" eller "false" (sant eller falskt). Exempelkoden kontrollerar om användaren har angett alla körningsparametrar under körning av Package Deployer (antingen med hjälp av kommandoraden eller PowerShell) och sedan behandlar informationen i enlighet med detta. Om ingen körningsparameter anges av användaren när paketet körs kommer värdet för RuntimeSettings att vara "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");  
}

      Denna kod låter administratören använda kommandoraden eller cmdlet Import-CrmPackage för att ange om säkerhetskontroller ska ignoreras när verktyget Package Deployer körs för import av paketet. Mer information: Distribuera paket med hjälp av Package Deployer och Windows PowerShell

    2. Ange egen kod som ska köras innan lösningarna importeras i metoddefinitionen för åsidosättning för PreSolutionImport om du vill ange huruvida anpassningar ska bibehållas eller skrivas över när den angivna lösningen i en målinstans Dataverse ska uppdateras, samt huruvida plugin-moduler och arbetsflöden ska aktiveras automatiskt.

    3. Använd åsidosättningsmetoden för RunSolutionUpgradeMigrationStep för att utföra dataomvandling eller uppgradering mellan två versioner av en lösning. Denna metod anropas endast om lösningen du importerar redan finns i målinstansen Dataverse.

      Med den här funktionen förväntas följande parametrar:

      Parameter Beskrivning
      solutionName Namn på lösningen
      oldVersion Versionsnummer för den tidigare lösningen
      newVersion Versionsnummer för den nya lösningen
      oldSolutionId GUID för den tidigare lösningen
      newSolutionId GUID för den nya lösningen.

    4. Ange egen kod som ska köras innan lösningsimporten slutförs i metoddefinitionen för åsidosättning för metoden BeforeImportStage. Exempeldata och vissa flata filer för lösningar som anges i filen ImportConfig.xml importeras innan lösningsimporten har slutförts.

    5. Åsidosätt det för tillfället valda språket för konfigurationsdataimport med hjälp av metoddefinitionen för åsidosättning för OverrideConfigurationDataFileLanguage. Om det angivna språkets språk-ID (LCID) inte finns i listan över tillgängliga språk i paketet importeras standarddatafilen.

      Du anger tillgängliga språk för konfigurationsdata i <cmtdatafiles>-noden i ImportConfig.xml-filen. Importfilen med standarkonfigurationsdata anges i crmmigdataimportfile-attributet i ImportConfig.xml-filen.

      Att hoppa över datagranskningar (OverrideDataImportSafetyChecks = true) kan vara effektivt om du är säker på att Dataverse-målinstansen inte innehåller någon data.

    6. Ange egen kod som ska köras efter det att importen slutförs i metoddefinitionen för åsidosättning för metoden AfterPrimaryImport>. De återstående flata filer som inte importerades tidigare importeras nu innan lösningsimporten startas.

    7. Ändra standardnamnet för paketets mapp till önskat paketnamn. Det gör du genom att byta namn på PkgFolder (eller PkgAssets) mappen i rutan lösningsutforskaren och sedan redigera returvärdet under egenskapen 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. Ändra paketnamnet genom att redigera returvärdet under egenskapen GetNameOfImport.

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

      Detta returnerade värde är namnet på ditt paket som visas på paketvalssidan i Dynamics 365 Package Deployer.

    9. Ändra paketbeskrivningen genom att redigera returvärdet under egenskapen GetImportPackageDescriptionText.

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

      Detta returnerade värde är paketbeskrivningen som visas bredvid paketnamnet på paketvalssidan i Package Deployer-guiden.

    10. Ändra det långa paketnamnet genom att redigera returvärdet under egenskapen GetLongNameOfImport.

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

      Paketets långa namn visas på nästa sida när du har valt det paket du vill installera.

  3. Dessutom är följande funktion och variabler tillgängliga för paketet:

    Namn Typ Beskrivning
    CreateProgressItem(String) Function Används för att skapa ett nytt förloppsobjekt i användargränssnittet (UI).
    RaiseUpdateEvent(String, ProgressPanelItemStatus) Function Används för att uppdatera det förlopp som skapas av anropet till CreateProgressItem(String).

    ProgressPanelItemStatus är en uppräkning (enum) med följande värden:

    Arbetar = 0
    Slutförd = 1
    Misslyckades = 2
    Varning = 3
    Okänt = 4
    RaiseFailEvent(String, Exception) Function Används för att ange aktuell statusimport som "misslyckad" med ett undantagsmeddelande.
    IsRoleAssoicatedWithTeam(Guid, Guid) Function Används för att avgöra om en roll är associerad med ett angivet team.
    IsWorkflowActive(Guid) Function Används för att avgöra om ett angivet arbetsflöde är aktivt.
    PackageLog Klasspekare En pekare till det initierade loggningsgränssnittet för paketet. Detta gränssnitt används av ett paket för att logga meddelanden och undantag i paketets loggfil.
    RootControlDispatcher Egenskap Ett avsändargränssnitt som används för att tillåta kontrollen att återge sitt eget användargränssnitt vid paketdistribution. Använd det här gränssnittet om du vill omsluta användargränssnittselement eller -kommandon. Det är viktigt att du kontrollerar variabeln för null-värden innan du använder den, detta eftersom det inte är säkert att den är inställd på ett värde.
    CrmSvc Egenskap En pekare till en CrmServiceClient-klass som tillåter ett paket att adressera Dynamics 365 inifrån paketet. Använd denna pekare om du vill köra SDK-metoder och andra åtgärder i de åsidosatta metoderna.
    DataImportBypass Egenskap Ange om Dynamics 365 ska Package Deployer hoppa över alla dataimportåtgärder, t.ex. import av Dataverse exempeldata, flatfilsdata och data som exporterats från Configuration Migration Tool. Ange "true" eller "false". Standard är false.
    OverrideDataImportSafetyChecks Egenskap Ange detta alternativ om du vill ange huruvida Dynamics 365 Package Deployer ska kringgå vissa av sina säkerhetskontroller, vilket bidrar till att förbättra importprestandan. Ange true eller false. Standard är false.

    Du bör ställa in den här egenskapen till true om Dataverse-målinstansen inte innehåller några data.

  4. Spara ditt projekt. Nästa steg är att skapa paketet.

Skapa och distribuera

Följande avsnitt beskriver hur man bygger och distribuerar ett paket.

Version

Att bygga ditt paket beskrivs nedan beroende på vilket verktyg du använder.

För att bygga ett paket skapat med CLI kan du ladda .csproj-filen i Visual Studio, men istället kommer vi att använda kommandot dotnet och MSBuild. I exemplet nedan förutsätts att arbetskatalogen innehåller filen *.csproj.

> dotnet publish

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

Du kan även titta på informationen i det skapade paketet.

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

Paketet är följande filer under <Project>mappen \Bin\Debug.

  • <PackageName>-mappen: Mappnamnet är detsamma som du ändrade för ditt paketmappnamn i steg 2.g i det här avsnittet Lägg till anpassad kod. Denna mapp innehåller alla lösningar, konfigurationsdata, flata filer och innehåll för ditt paket.

Kommentar

Du kan se en .NET-mapp (t.ex. net472) som innehåller en mapp för publicering av filer. DLL-filen och andra projektfiler finns i mappen för publicering av e-post.

  • <PackageName>.dll: Sammansättningen innehåller den egna koden för ditt paket. Som standard är namnet på sammansättningen detsamma som för ditt projektnamn.

Distribuera

När du har skapat ett paket kan du distribuera det i Dataverse-instansen med antingen Package Deployer-verktyget, Windows PowerShell eller ett CLI-kommando.

  • Om du vill distribuera Package Deployer verktyget hämtar du först verktyget enligt beskrivningen i Dataverse utvecklingsverktygen. Följ sedan den detaljerade informationen om paketdistribution i artikeln Distribuera paket med Package Deployer eller Windows PowerShell.

  • För att distribuera med CLI, använd kommandot pac package deploy.

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

    Kommentar

    Om du vill distribuera ett paket till en målmiljö med hjälp av CLI måste du först konfigurera en autentiseringsprofil och välja en organisation. Mer information: pac auth create, pac org select

Regelverk

Nedan finns några tips om metodtips som du bör följa när du arbetar med Package Deployer-paket.

Skapa paket

När utvecklare skapar paket måste de:

  • Kontrollera att paket är signerade.

Distribuera paket

Vid distribution av paket Dataverse måste administratörerna göra följande:

  • Kräva att en signerad paketsammansättning så att ett paket kan såras tillbaka till källan.
  • Testa paketet på en förproduktionsinstans, helst en spegelbild av produktionsinstansen, innan den körs på en produktionsinstans.
  • Säkerhetskopiera produktionsinstansen innan paketet distribueras.

Se även

Verktyget lösningspaketeraren