Utwórz pakiety dla narzędzia Package Deployer

Package Deployerumożliwia administratorom wdrażanie pakietów w instancjach Microsoft Dataverse. Package Deployer może składać się z dowolnych lub wszystkich następujących elementów:

• Jeden lub kilka plików rozwiązań aplikacji 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, który można uruchomić przed, w trakcie lub po wdrożeniu pakietu w wystąpieniu 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. Wtedy 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()  
      {
        // 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");
        }  
      } 
      

      Ten 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 CRM Package Deployer i programu Windows PowerShell

   2. Wprowadź niestandardowy kod do wykonania przed zaimportowaniem rozwiązań w definicji metody zastępowania w PreSolutionImport, aby określić, czy zachować, czy nadpisać dostosowania podczas aktualizowania określonego rozwiązania w docelowej instancji Dataverse oraz czy automatycznie aktywować wtyczki i przepływy pracy.

   3. Użyj definicji metody nadpisywania z RunSolutionUpgradeMigrationStep, aby przeprowadzić transformację danych lub uaktualnienie 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. Zastąp metodę OverrideSolutionImportDecision , aby zwrócić wyliczenie UserRequestedImportAction kontrolujące, czy import rozwiązania zostanie pominięty, zaktualizowany lub uaktualniony (wartość domyślna).

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

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

      Sprawdzanie poprawności danych (OverrideDataImportSafetyChecks = true) może w tym miejscu być skuteczne, jeśli użytkownik ma pewność, że docelowe wystąpienie Dataverse nie zawiera żadnych danych.

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

   8. 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 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. 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 wdrażania pakietów Package Deployer Dynamics 365.

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

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

       Ta zwrócona wartość to opis pakietu wyświetlany obok nazwy pakietu na stronie wyboru pakietu w kreatorze narzędzia Package Deployer.

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

   Imię i 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.
   <xref:Microsoft.Xrm.Tooling.PackageDeployment.CrmPackageExtentionBase.ImportExtension.IsRoleAssociatedWithTeam(System.Guid,System.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ść	Określ, czy program Dynamics 365 Package Deployer pomija wszystkie operacje importu danych, takie jak importowanie przykładowych danych Dataverse, danych w pliku tekstowym i danych eksportowanych z Configuration Migration Tooli. Wybierz wartość true lub false. Wartość domyślna to false.
   OverrideDataImportSafetyChecks	Właściwość	Określ, czy Dynamics 365 Package Deployer pomija niektóre kontrole bezpieczeństwa, co pomaga poprawić wydajność importu. Wybierz wartość true lub false. Wartość domyślna to false. Należy ustawić tę właściwość true tylko wtedy, gdy docelowe wystąpienie 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 w sekcji Dodaj kod niestandardowy. 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 go wdrożyć w instancji Dataverse przy użyciu narzędzia Package Deployer, programu Windows PowerShell lub polecenia CLI.

• 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

Poniżej znajduje się kilka wskazówek dotyczących najlepszych praktyk, których należy przestrzegać podczas pracy z pakietami narzędzia 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