Tworzenie pakietów dla narzędzia Package Deployer

Artykuł
06/26/2024

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.

Uwaga

Istnieje inny typ pakietu o nazwie pakiet plug-in. Ten rodzaj pakietu jest dla zestawów zależnych od dodatku plug-in i nie ma relacji z pakietami Package Deployer.

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.

Utwórz projekt Visual Studio lub MSBuild
Dodawanie rozwiązań i innych plików do projektu
Zaktualizuj podane pliki HTML (opcjonalnie)
Określanie wartości konfiguracji dla pakietu
Definiowanie niestandardowego kodu dla pakietu
Tworzenie i wdrażanie pakietu

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.

Power Platform CLI
Power Platform Narzędzia

Uruchom polecenie pac package init, aby utworzyć początkowy pakiet. Więcej informacji: pac package

pac package init help
pac package init --outputDirectory DeploymentPackage

Wynikowe wyjście interfejsu wiersza polecenia zawiera foldery i pliki pokazane poniżej. W tym miejscu jako przykład została użyta nazwa folderu "DeploymentPackage".

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

W utworzonym projekcie znajdź plik konfiguracyjny ImportConfig.xml w folderze PkgAssets oraz plik PackageImportExtension.cs. Pliki te zostaną zmodyfikowane w sposób opisany w dalszej części tego artykułu.

Można utworzyć projekt Visual Studio przy użyciu szablonu rozwiązania Power Platform, a następnie dodać projekt pakietu przy użyciu szablonu projektu wdrożenia pakietu Power Platform lub utworzyć projekt bezpośrednio przy użyciu szablonu projektu wdrożenia pakietu Power Platform.

Dodawanie pakietu do projektu.

Uwaga

Nie należy wybierać szablonu pakietu Power Platform. Ten szablon jest dla pakietów dodatku plug-in.

Wynikowe rozwiązanie i projekt programu Visual Studio zawiera foldery i pliki pokazane poniżej. W tym miejscu jako przykład została użyta nazwa folderu "Deployment-package". Treść folderu Content nie została tutaj pokazana.

C:.
│   Deployment-package.csproj
│   Deployment-package.sln
│   GettingStarted.html
│   PackageTemplate.cs
│
├───PkgFolder
│   │   ImportConfig.xml
│   │
│   └───Content

W utworzonym projekcie znajdź plik konfiguracyjny ImportConfig.xml w folderze PkgFolder oraz plik PackageTemplate.cs. Pliki te zostaną zmodyfikowane w sposób opisany w dalszej części tego artykułu.

Więcej informacji o używaniu rozszerzenia Power Platform Tools: Szybki Start: Tworzenie projektu Power Platform Tools

Dodaj pliki pakietów

Po utworzeniu projektu pakietu możesz rozpocząć dodawanie rozwiązań i innych plików do tego projektu.

Power Platform CLI
Power Platform Narzędzia

Korzystając z interfejsu wiersza polecenia, możesz dodawać zewnętrzne pakiety, rozwiązania i odwołania do projektu pakietu za pomocą jednej z podkomend add. Wprowadź pac package help, aby wyświetlić listę podwykonawców. Dodamy teraz rozwiązanie do naszego pakietu.

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

W okienku Eksploratora rozwiązań dodaj rozwiązania Dataverse i pliki w folderze PkgFolder. Pliki HTML należą do folderu Zawartość. Więcej informacji o tej zawartości w formacie HTML później.
Dla każdego pliku dodanego w okienku Właściwości ustaw wartość Kopiuj do katalogu wyjściowego na Zawsze kopiuj. Ustawienie tej wartości gwarantuje, że Twoje pliki będą dostępne w wygenerowanym pakiecie.

Następnie należy zaktualizować pliki dotyczące języka HTML.

W okienku Eksploratora rozwiązań rozwiń węzeł PkgFolder>Zawartość>en-us. Znajdź dwa foldery o nazwie EndHTML i WelcomeHTML. Te foldery zawierają kod HTML i skojarzone pliki, które umożliwiają wyświetlenie (użytkownikowi) informacji na końcu i na początku procesu wdrażania pakietu. Dokonaj edycji plików w folderze HTML tych folderów, aby dodać informacje do wyświetlenia o pakiecie.
Pliki HTML w pakiecie można również dodać w innych językach, dzięki czemu zawartość HTML będzie wyświetlana w języku na podstawie ustawień regionalnych komputera użytkownika. Aby to zrobić:
1. Utwórz kopię folderu en-us w obszarze PkgFolder>Zawartość.
2. Zmień nazwę skopiowanego folderu na odpowiedni język. Na przykład w przypadku języka hiszpańskiego należy zmienić nazwę pliku na es–ES.
3. Zmodyfikuj zawartość plików HTML, aby dodać do niej zawartość w języku hiszpańskim.

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.

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

W pliku C# możesz:

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

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.

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

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

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

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 o następujących wartościach: 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.

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.

Power Platform CLI
Power Platform Narzędzia

Aby zbudować pakiet utworzony za pomocą CLI, można załadować plik .csproj do Visual Studio, ale zamiast tego użyjemy polecenia dotnet i MSBuild. W przykładzie poniżej przyjęto, że katalog roboczy zawiera plik *.csproj.

> dotnet publish

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

Możesz opcjonalnie zobaczyć szczegóły wbudowanego pakietu.

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

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

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

Uwaga

Może się pojawić folder .NET (np. net472) zawierający folder pdpublish. Biblioteka DLL i inne pliki projektów znajdują się w folderze pdpublish.

<PackageName.DLL>: zestaw zawiera niestandardowy kod 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.