Tworzenie pakietów dla narzędzia Package Deployer

Narzędzie Package Deployer umożliwia administratorom wdrażanie pakietów w wystąpieniach usługi Microsoft Dataverse. Pakiet Package Deployer może składać się z dowolnych lub wszystkich następujących elementów:

• Jeden lub kilka plików rozwiązań Dataverse.
• Pliki proste lub wyeksportowane pliki danych konfiguracyjnych z narzędzia Migracja konfiguracji. Aby uzyskać więcej informacji na temat narzędzia, zobacz temat Przenoszenie danych konfiguracji między wystąpieniami oraz organizacjami za pomocą narzędzia Migracja konfiguracji.
• Kod niestandardowy uruchamiany przed wdrożeniem pakietu, w trakcie wdrażania lub po wdrożeniu do wystąpienia usługi Dataverse.
• Zawartość HTML właściwa dla pakietu, wyświetlana na początku i na końcu procesu wdrażania. Ta zawartość może być przydatna do przedstawienia opisu rozwiązań i plików wdrożonych w pakiecie.

Wymagania wstępne

• Upewnij się, że wszystkie rozwiązania i inne pliki, które chcesz uwzględnić w pakiecie, są gotowe.
• Visual Studio 2019 lub nowszy albo Visual Studio Code.

Omówienie procesu

Aby utworzyć pakiet Package Deployer, wykonaj następujące kroki.

Kroki te zostały szczegółowo opisane w tym artykule.

Tworzeniu pakietu projektu

Pierwszym krokiem jest utworzenie projektu Visual Studio lub MSBuild dla pakietu. W tym celu należy zainstalować na komputerze projektowy jedno z dwóch dostępnych rozszerzeń narzędzi. W przypadku używania Visual Studio Code zainstaluj interfejs wiersza polecenia Microsoft Power Platform CLI. W przeciwnym razie, jeśli używasz Visual Studio 2019 lub nowszej, należy zainstalować narzędzia Power Platform Tools dla programu Visual Studio.

Wybierz odpowiednią zakładkę poniżej, aby dowiedzieć się, jak utworzyć projekt przy użyciu żądanego rozszerzenia narzędzia. Oba narzędzia pozwalają na wyjściowy projekt w podobnym formacie.

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

Dodaj pliki pakietów

Po utworzeniu projektu pakietu możesz rozpocząć dodawanie rozwiązań i innych plików do tego 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.

Konfigurowanie pakietu

Zdefiniuj konfigurację pakietu, dodając informacje o pakiecie w pliku ImportConfig.xml w projekcie. Odwołaj się do Odwołania ImportConfig jako przykładu i opisu prawidłowych elementów i atrybutów, które mają być użyte.

Dodaj niestandardowy kod

Można dodać kod niestandardowy wykonywany przed, podczas i po zaimportowaniu pakietu do środowiska. W tym celu wykonaj następujące instrukcje.

1. Wyedy PackageTemplate.cs (lub PackageImportExtension.cs) w folderze głównym projektu.

2. W pliku C# możesz:

   1. Wprowadź kod niestandardowy do wykonania po zainicjowaniu pakietu w definicji metody zastępowania dla elementu InitializeCustomExtension.

      Tej metody można użyć, aby umożliwić użytkownikom korzystanie z parametrów środowiska uruchomieniowego podczas uruchamiania pakietu. Jako deweloper możesz dodać do pakietu obsługę każdego parametru środowiska uruchomieniowego, korzystając z właściwości RuntimeSettings, pod warunkiem, że kod będzie przetwarzać go w zależności od danych wprowadzonych przez użytkownika.

      Na przykład poniższy przykładowy kod włącza parametr środowiska uruchomieniowego o nazwie SkipChecks dla pakietu zawierającego dwie możliwe wartości: true lub false. Przykładowy kod sprawdza, czy użytkownik określił parametry środowiska uruchomieniowego podczas uruchamiania narzędzia Package Deployer (korzystając z wiersza polecenia lub programu PowerShell), a następnie przetwarza te informacje w odpowiedni sposób. Jeśli użytkownik nie określił żadnych parametrów środowiska uruchomieniowego podczas uruchamiania pakietu, właściwość RuntimeSettings będzie mieć wartość 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");  
      }  
      

      Kod umożliwia administratorowi użycie wiersza polecenia lub polecenia cmdlet Import-CrmPackage do określenia, czy podczas importowania pakietu przy użyciu narzędzia Package Deployer będzie pomijane sprawdzanie bezpieczeństwa. Więcej informacji: Wdrażanie pakietów za pomocą narzędzia Package Deployer i programu Windows PowerShell

   2. Wprowadź kod niestandardowy do wykonania przed zaimportowaniem rozwiązań w definicji metody zastępowania dla elementu PreSolutionImport, aby określić, czy operacje dostosowywania mają być zachowywane czy zastępowane podczas aktualizowania określonego rozwiązania w docelowym wystąpieniu usługi Dataverse, oraz aby określić, czy dodatki plug-in i przepływy pracy mają być aktywowane automatycznie.

   3. Użyj nadrzędnej definicji metody RunSolutionUpgradeMigrationStep, aby wykonać transformację danych lub aktualizację między dwiema wersjami rozwiązania Ta metoda jest wywoływana tylko wtedy, gdy importowane rozwiązanie jest już obecne w docelowej instancji Dataverse.

      Ta funkcja oczekuje następujących parametrów:

      Parametr	Opis
      solutionName	Nazwa rozwiązania
      oldVersion	Numer wersji starego rozwiązania
      newVersion	Numer wersji nowego rozwiązania
      oldSolutionId	Identyfikator GUID starego rozwiązania.
      newSolutionId	Identyfikator GUID nowego rozwiązania.

   4. Wprowadź kod niestandardowy do wykonania przed ukończeniem importu rozwiązania w definicji zastępowania dla metody BeforeImportStage. Przykładowe dane i niektóre pliki proste dla rozwiązań określonych w pliku ImportConfig.xml są importowane przed ukończeniem importu rozwiązania.

   5. Zastąp obecnie wybrany język na potrzeby importu danych konfiguracji, korzystając z definicji metody zastępowania dla elementu OverrideConfigurationDataFileLanguage. Jeśli podany identyfikator lokalizacji (LCID) określonego języka nie zostanie znaleziony na liście dostępnych języków w pakiecie, importowany jest domyślny plik danych.

      Języki dostępne dla danych konfiguracji są określane w węźle <cmtdatafiles> pliku ImportConfig.xml. Domyślny plik importu danych konfiguracji jest określany w atrybucie crmmigdataimportfile pliku ImportConfig.xml.

      Pomijanie sprawdzania danych (OverrideDataImportSafetyChecks = true) może być tutaj skuteczne, jeśli masz pewność, że docelowa instancja Dataverse nie zawiera żadnych danych.

   6. Wprowadź kod niestandardowy do wykonania po ukończeniu importu w definicji zastępowania dla metody AfterPrimaryImport>. Pozostałe pliki płaskie, które nie zostały zaimportowane wcześniej, przed rozpoczęciem importu rozwiązania, są importowane teraz.

   7. Zmień domyślną nazwę folderu pakietu na żądaną nazwę pakietu. W tym celu zmień nazwę folderu PkgFolder (lub PkgAssets) w okienku Eksploratora rozwiązań, a następnie edytuj wartość zwracaną w ramach właściwości 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. Zmień nazwę pakietu, edytując wartość zwracaną w ramach właściwości GetNameOfImport.

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

      Ta zwrócona wartość to nazwa pakietu, która pojawia się na stronie wyboru pakietu w kreatorze Dynamics 365 Package Deployer.

   9. Zmień opis pakietu, edytując wartość zwracaną w ramach właściwości GetImportPackageDescriptionText.

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

      Zwracana wartość to opis pakietu, który pojawia się obok nazwy pakietu na stronie wyboru pakietu w kreatorze Package Deployer.

   10. Zmień długą nazwę pakietu, edytując wartość zwracaną w ramach właściwości GetLongNameOfImport.

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

       Długa nazwa pakietu zostanie wyświetlona na następnej stronie po wybraniu pakietu do zainstalowania.

3. Ponadto w pakiecie są dostępne następujące zmienne i funkcje:

   Nazwisko	Typ	Opis
   CreateProgressItem(String)	Function	Służy do tworzenia nowego elementu postępu w interfejsie użytkownika.
   RaiseUpdateEvent(String, ProgressPanelItemStatus)	Function	Służy do aktualizowania postępu utworzonego przez wywołanie do elementu CreateProgressItem(String). ProgressPanelItemStatus to wyliczenie z następującymi wartościami: Working (uruchomione) = 0 Complete (ukończone) = 1 Failed (niepowodzenie) = 2 Warning (ostrzeżenie) = 3 Unknown (nieznane) = 4
   RaiseFailEvent(String, Exception)	Function	Służy do wskazywania stanu niepowodzenia bieżącego importu za pomocą komunikatu wyjątku.
   IsRoleAssoicatedWithTeam(Guid, Guid)	Function	Służy do sprawdzania, czy rola została skojarzona z określonym zespołem.
   IsWorkflowActive(Guid)	Function	Służy do sprawdzania, czy określony przepływ pracy jest aktywny.
   PackageLog	Wskaźnik klasy	To wskaźnik do zainicjowanego interfejsu rejestrowania w pakiecie. Ten interfejs jest używany w pakiecie do rejestrowania komunikatów i wyjątków w pliku dziennika pakietów.
   RootControlDispatcher	Właściwości	To interfejs dyspozytora umożliwiający sterowanie renderowaniem własnego interfejsu użytkownika podczas wdrażania pakietu. Ten interfejs umożliwia zawijanie wszystkich elementów lub poleceń interfejsu użytkownika. Ważne jest, aby sprawdzić tę zmienną pod kątem wartości null przed jej użyciem, ponieważ może ona nie być ustawiona na wartość.
   CrmSvc	Właściwości	To wskaźnik do klasy CrmServiceClient, który umożliwia pakietowi kontaktowanie się z rozwiązaniem Dynamics 365 z poziomu pakietu. Wskaźnik służy do wykonywania metod zestawu SDK i innych akcji w zastąpionych metodach.
   DataImportBypass	Właściwości	Określ, czy w narzędziu Package Deployer usługi Dynamics 365 wszystkie operacje importu danych, takie jak importowanie przykładowych danych usługi Dataverse, danych plików prostych i danych wyeksportowanych z narzędziem Konfiguracji migracji, mają być pomijane. Wybierz wartość true lub false. Wartość domyślna to false.
   OverrideDataImportSafetyChecks	Właściwości	Określenie, czy Dynamics 365 Package Deployer pomija niektóre z kontroli bezpieczeństwa, co pomaga poprawić wydajność importu. Wybierz wartość true lub false. Wartość domyślna to false. Należy ustawić tę właściwość na true tylko wtedy, gdy docelowa instancja Dataverse nie zawiera żadnych danych.

4. Zapisz projekt. Następnym krokiem jest kompilacja pakietu.

Kompiluj i wdróż

Poniższe sekcje opisują sposób tworzenia i wdrażania pakietu.

Tworzenie

Tworzenie pakietu opisano poniżej w zależności od używanego narzędzia.

> 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

Pakiet to następujące pliki w folderze <Project>\Bin\Debug.

• <PackageName>, folder : nazwa folderu jest taka sama jak nazwa zmieniona dla nazwy folderu pakietu w kroku 2.g sekcji Dodawanie kodu niestandardowego. Ten folder zawiera wszystkie rozwiązania, dane konfiguracji, pliki proste oraz zawartość pakietu.

• <PackageName>.dll: zestaw z niestandardowym kodem dla pakietu. Domyślnie, nazwa zestawu jest taka sama jak nazwa projektu.

Wdrażaj

Po utworzeniu pakietu można wdrożyć go w wystąpieniu usługi Dataverse, korzystając z narzędzia Package Deployer, programu Windows PowerShell lub polecenia interfejsu wiersza polecenia.

• Aby wdrożyć za pomocą narzędzia Package Deployer, najpierw pobierz narzędzie zgodnie z opisem w Narzędzia programistyczne Dataverse. Następnie postępuj zgodnie ze szczegółowymi informacjami na temat wdrażania pakietów w artykule Wdrażaj pakiety za pomocą Package Deployer lub Windows PowerShell.

• Aby wdrożyć przy użyciu funkcji CLI, użyj tego polecenia pac package deploy.

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

  Uwaga

  Aby wdrożyć pakiet w środowisku docelowym przy użyciu interfejsu CLI, należy najpierw skonfigurować profil uwierzytelniania i wybrać organizację. Więcej informacji: pac auth create, pac org select

Najlepsze rozwiązania

Wymieniono poniżej kilka porad dotyczących najlepszych praktyk, które należy wykonać podczas pracy z pakietami Package Deployer.

Tworzenie pakietów

Podczas tworzenia pakietów deweloperzy muszą:

• Upewnij się, że zestawy pakietów są podpisane.

Wdrażanie pakietów

Podczas wdrażania pakietów administratorzy Dataverse muszą:

• Wymagać podpisanych zestawów pakietów, aby umożliwić śledzenie źródła zestawu.
• Przetestuj pakiet na instancji przedprodukcyjnej, najlepiej lustrzanym odbiciu instancji produkcyjnej, przed uruchomieniem go na instancji produkcyjnej.
• Wykonywać kopię zapasową wystąpienia produkcyjnego przed wdrożeniem pakietu.

Zobacz także

Narzędzie Solution Packager