Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
SolutionPackager to narzędzie, które może odwracalnie dekomponować skompresowany plik rozwiązania Microsoft Dataverse na wiele plików XML i inne pliki. Następnie można łatwo zarządzać tymi plikami, używając systemu kontroli źródła. W poniższych sekcjach pokazano, jak uruchomić narzędzie i jak używać narzędzia z rozwiązaniami zarządzanymi i niezarządzanymi.
Ważna
Narzędzie SolutionPackager nie jest już zalecanym sposobem rozpakowywania i pakowania rozwiązań. Możliwości narzędzia SolutionPackager są włączone do interfejsu wiersza polecenia platformy Power Platform. Polecenie pac solution zawiera wiele czasowników, w tym unpack, pack, clone, i sync, które korzystają z tych samych podstawowych możliwości narzędzia SolutionPackager.
Gdzie znaleźć narzędzie SolutionPackager
Narzędzie SolutionPackager jest dystrybuowane jako część pakietu NuGet Microsoft.CrmSdk.CoreTools . Aby zainstalować program, wykonaj następujące kroki.
- Pobierz pakiet NuGet.
- Zmień rozszerzenie nazwy pliku pakietu z .nupkg na .zip.
- Wyodrębnij zawartość ze skompresowanego pliku (ZIP).
Znajdź plik wykonywalny SolutionPackager.exe znajdujący się w folderze <nazwa-wyodrębnionego-folderu>/contents/bin/coretools. Uruchom program z folderu coretools lub dodaj ten folder do ścieżki.
Argumenty wiersza polecenia narzędzia SolutionPackager
SolutionPackager to narzędzie wiersza polecenia. Można go wywołać przy użyciu parametrów opisanych w poniższej tabeli.
| Argument | Description |
|---|---|
| /action: {Wypakuj|Spakuj} | To jest wymagane. Akcja, która ma zostać wykonana. Akcja może polegać na wyodrębnieniu rozwiązania z pliku .zip do folderu lub na spakowaniu folderu do pliku .zip. |
| /zipfile: <ścieżka do pliku> | To jest wymagane. Ścieżka i nazwa pliku rozwiązania w formacie .zip. Podczas wyodrębniania plik musi istnieć i być czytelny. Podczas pakowania plik jest zastępowany. |
| /folder: <ścieżka do folderu> | To jest wymagane. Ścieżka do folderu. Podczas wyodrębniania ten folder jest tworzony i wypełniany plikami składowymi. Podczas pakowania ten folder musi już istnieć i zawierać wcześniej wyodrębnione pliki składników. |
| /packagetype: {Unmanaged|Managed|Both} | Opcjonalny. Typ pakietu do przetworzenia. Wartość domyślna to "Niezarządzane". Pomiń ten argument w większości przypadków, ponieważ narzędzie może odczytać typ pakietu z zawartości pliku .zip lub z plików składników. W przypadku wyodrębniania i wybrania wartości Oba pliki ZIP rozwiązań zarządzanych i niezarządzanych muszą być obecne i przetwarzane w jednym folderze. W przypadku pakowania i wybrania opcji Oba, pliki .zip rozwiązań zarządzanych i niezarządzanych są tworzone z jednego folderu. Aby uzyskać więcej informacji, zobacz sekcję dotyczącą pracy z rozwiązaniami zarządzanymi i niezarządzanymi w dalszej części tego artykułu. |
| /allowWrite:{Tak|Nie} | Opcjonalny. Wartością domyślną jest Tak. Użyj tego argumentu tylko podczas wyodrębniania. Po określeniu /allowWrite:No narzędzie wykonuje wszystkie operacje, ale nie zapisuje ani nie usuwa żadnych plików. Operację wyodrębnienia można skutecznie ocenić, nie zastępując ani usuwając istniejących plików. |
| /allowDelete:{Yes|No|Prompt} | Opcjonalny. Wartość domyślna to Monit. Użyj tego argumentu tylko podczas wyodrębniania. Po określeniu /allowDelete:Yes narzędzie automatycznie usuwa wszystkie pliki obecne w folderze określonym przez parametr /folder, które nie są oczekiwane. Po określeniu /allowDelete:No narzędzie nie usuwa żadnych plików. Po określeniu /allowDelete:Prompt użytkownik jest monitowany za pośrednictwem konsoli, aby zezwolić lub odrzucić wszystkie operacje usuwania. Jeśli określisz /allowWrite:No, narzędzie nie usunie żadnych plików, nawet jeśli /allowDelete:Yes jest również określony. |
| /clobber | Opcjonalny. Użyj tego argumentu tylko podczas wyodrębniania. Po określeniu /clobber narzędzie zastępuje lub usuwa pliki, które mają ustawiony atrybut tylko do odczytu. W przeciwnym razie pliki z atrybutem tylko do odczytu nie są zastępowane ani usuwane. |
| /errorlevel: {Off|Error|Warning|Info|Verbose} | Opcjonalny. Wartość domyślna to Informacje. Ten argument wskazuje poziom rejestrowania informacji w danych wyjściowych. |
| /map: <ścieżka pliku> | Opcjonalny. Ścieżka i nazwa pliku .xml zawierającego dyrektywy mapowania plików. Gdy ten argument jest używany podczas wyodrębniania, pliki zazwyczaj odczytywane z poziomu folderu określonego przez parametr /folder są odczytywane z lokalizacji alternatywnych, zgodnie z opisem w pliku mapowania. W trakcie operacji pakowania pliki pasujące do dyrektyw nie są zapisywane. |
| /nologo | Opcjonalny. Zablokuj baner podczas działania. |
| /log: <ścieżka pliku> | Opcjonalny. Ścieżka i nazwa pliku dziennika. Jeśli plik już istnieje, nowe informacje rejestrowania są dołączane do pliku. |
| @ <ścieżka pliku> | Opcjonalny. Ścieżka i nazwa pliku, który zawiera argumenty wiersza poleceń dla narzędzia. |
| /sourceLoc: <ciąg> | Opcjonalny. Ten argument powoduje wygenerowanie pliku zasobów szablonu i jest ważny tylko w przypadku wyodrębniania. Możliwe wartości to auto lub kod LCID/ISO dla języka, który chcesz wyeksportować. Po użyciu tego argumentu narzędzie wyodrębnia zasoby tekstowe z podanej lokalizacji do neutralnego pliku .resx. W przypadku wybrania wartości auto albo długiej lub krótkiej postaci przełącznika są używane podstawowe ustawienia regionalne lub rozwiązanie. Możesz użyć krótkiej formy polecenia: /src. |
| /localize | Opcjonalny. Wyodrębnij lub połącz wszystkie resursy tekstowe w plikach .resx. Możesz użyć krótkiej formy polecenia: /loc. Opcja lokalizacji obsługuje udostępnione składniki dla plików resx. Aby uzyskać więcej informacji, zobacz Korzystanie z zasobów internetowych RESX. |
| /SolutionName: <nazwa> | Opcjonalny. Unikatowa nazwa rozwiązania do spakowania lub wyodrębnienia, gdy folder źródłowy zawiera wiele rozwiązań w obszarze solutions/*/solution.yml. Wymagane w przypadku wykrycia więcej niż jednego rozwiązania. Dotyczy tylko formatu kontroli źródła YAML. Możesz użyć krótkiej formy polecenia: /sn. |
| /remapPluginTypeNames | Opcjonalny. Po określeniu w pełni kwalifikowane nazwy typów dodatków plug-in są ponownie mapowane na podstawie zestawów zawartych w rozwiązaniu. Opcja domyślnie włączona w formacie kontroli źródła YAML. Możesz użyć krótkiej formy polecenia: /fp. |
Formaty plików kontroli źródła
SolutionPackager obsługuje dwa układy folderów podczas wyodrębniania i pakowania rozwiązań.
Format XML (starsza wersja)
Oryginalny format. Narzędzie przechowuje metadane rozwiązania w elementach Other\Solution.xml i Other\Customizations.xml. Narzędzie wyodrębnia wszystkie pliki składników do płaskiej hierarchii folderów wraz z tymi plikami. Ten format jest formatem domyślnym podczas wyodrębniania pliku .zip bez dodatkowej konfiguracji.
Format kontroli źródła YAML
Wprowadzony wraz z integracją usługi Dataverse z usługą Git ten format przechowuje metadane rozwiązania jako pliki YAML dystrybuowane w hierarchii folderów strukturalnych. Jest to format zapisywany podczas zatwierdzania rozwiązań przy użyciu natywnej integracji z usługą Git w Power Apps.
Zalety w porównaniu z formatem XML
- Tworzy bardziej czytelne różnice poszczególnych składników w kontroli źródła.
- Obsługuje wiele rozwiązań w jednym folderze repozytorium.
- Pliki Canvas app
.msappi nowoczesne przepływy są obsługiwane tylko w tym formacie. - Ponowne mapowanie nazwy typu wtyczki jest domyślnie włączone.
Wymagana struktura folderów
<rootFolder>/
├── solutions/
│ └── <SolutionUniqueName>/
│ ├── solution.yml (solution metadata)
│ ├── solutioncomponents.yml (paths to all component files)
│ ├── rootcomponents.yml (root-level components)
│ └── missingdependencies.yml (dependency info)
├── publishers/
│ └── <PublisherUniqueName>/
│ └── publisher.yml (publisher definition)
├── entities/ (entity components, if present)
├── workflows/ (classic workflows, if present)
├── modernflows/ (Power Automate cloud flows, if present)
├── canvasapps/ (canvas app .msapp files, if present)
└── [other component folders]/
Ważna
Obecność podfolderu solutions/ zawierającego pliki *solution.yml wskazuje na format YAML.
Jeśli umieścisz pliki manifestu YAML (solution.yml, solutioncomponents.yml i tak dalej) w katalogu głównym folderu, a nie w obszarze solutions/<SolutionUniqueName>/, narzędzie nie wykryje formatu YAML. Narzędzie wraca do ścieżki XML i zgłasza mylący błąd dotyczący brakującego Customizations.xmlelementu . Zobacz Rozwiązywanie problemów , aby uzyskać informacje na temat rozwiązywania tego problemu.
Więcej informacji: Dokumentacja formatu YAML dla systemu kontroli wersji rozwiązania
Formatowanie reguł automatycznego wykrywania
| Warunek | Używany format |
|---|---|
solutions/*/solution.yml found — dokładnie jedno rozwiązanie |
Format YAML, w którym nazwa rozwiązania jest wywnioskowana z folderu |
solutions/*/solution.yml znaleziono — wiele rozwiązań |
Format YAML, w którym /SolutionName argument jest wymagany |
Brak solutions/ podkatalogu |
Format XML (starsza wersja) |
Pakowanie folderu formatu YAML
Następujące polecenie pakuje folder formatu YAML.
SolutionPackager.exe /action:Pack /zipfile:MySolution.zip /folder:C:\repos\myrepo
Pakowanie z folderu zawierającego wiele rozwiązań
Następujące polecenie pakuje określone rozwiązanie w folderze z wieloma rozwiązaniami.
SolutionPackager.exe /action:Pack /zipfile:SolutionA.zip /folder:C:\repos\myrepo /SolutionName:SolutionA
Używanie argumentu polecenia /map
Poniższa dyskusja zawiera szczegółowe informacje na temat użycia argumentu /map w narzędziu SolutionPackager.
Pliki utworzone w zautomatyzowanym systemie kompilacji, na przykład plik .xap i zestawy dodatków plug-in rozwiązania Silverlight, nie są zazwyczaj ewidencjonowane w kontroli źródła. Być może masz już zasoby internetowe objęte kontrolą wersji w lokalizacjach, które nie są bezpośrednio zgodne z narzędziem SolutionPackager. Uwzględniając parametr /map, można skierować narzędzie SolutionPackager do odczytu i spakowania takich plików z alternatywnych lokalizacji zamiast z folderu Extract. Parametr /map musi określać nazwę i ścieżkę do pliku XML zawierającego dyrektywy mapowania. Te dyrektywy instruują program SolutionPackager do dopasowania plików według ich nazwy i ścieżki, oraz wskazują alternatywną lokalizację, w celu znalezienia dopasowanego pliku. Poniższe informacje odnoszą się w równym stopniu do wszystkich dyrektyw.
Można wymienić wiele dyrektyw, w tym te, które odnoszą się do identycznych plików. Dyrektywy wymienione na początku pliku mają pierwszeństwo przed dyrektywami wymienionymi później.
Jeśli plik jest zgodny z dowolną dyrektywą, musi zostać znaleziony w co najmniej jednej alternatywnej lokalizacji. Jeśli nie zostaną znalezione żadne pasujące alternatywy, narzędzie SolutionPackager wyświetla błąd.
Ścieżki folderów i plików mogą być bezwzględne lub względne. Ścieżki względne są zawsze oceniane z folderu określonego przez parametr /folder.
Określ zmienne środowiskowe za pomocą składni
%variable%.Użyj symbolu wieloznacznego
**dla folderu, aby oznaczyć „w dowolnym podfolderze”. Można go używać tylko jako ostatniej części ścieżki, na przykład:c:\folderA\**.Użyj symboli wieloznacznych nazw plików tylko w postaciach
*.extlub*.*. Żaden inny wzorzec nie jest obsługiwany.W poniższej sekcji opisano trzy typy mapowań dyrektyw oraz przykład pokazujący, jak ich używać.
Mapowanie folderów
Poniższa sekcja zawiera szczegółowe informacje dotyczące mapowania folderów.
Format XML
<Folder map="folderA" to="folderB" />
Opis
Ścieżki plików pasujące do „folderA” są przekierowywane do „folderB”.
Hierarchia podfolderów w każdym folderze musi być dokładnie zgodna.
Symbole wieloznaczne folderów nie są obsługiwane.
Nie można określić nazw plików.
Examples
<Folder map="folderA" to="folderB" /> <Folder map="folderA\folderB" to="..\..\folderC\" /> <Folder map="WebResources\subFolder" to="%base%\WebResources" />
Mapowanie pliku do pliku
Poniżej zamieszczono informacje na temat mapowania pliku do pliku.
XML Format
<FileToFile map="path\filename.ext" to="path\filename.ext" />
Opis
Każdy plik zgodny z parametrem map zostanie odczytany z poziomu nazwy i ścieżki określonej w parametrze to.
Dla parametru map :
Określ nazwę pliku. Ścieżka jest opcjonalna. Jeśli nie określisz ścieżki, mapowanie może dopasować pliki z dowolnego folderu.
Symbole wieloznaczne nazw plików nie są obsługiwane.
Symbol wieloznaczny folderu jest obsługiwany.
Dla parametru
to:Określ nazwę pliku i ścieżkę.
Nazwa pliku może różnić się od nazwy w parametrze
map.Symbole wieloznaczne nazw plików nie są obsługiwane.
Symbol wieloznaczny folderu jest obsługiwany.
Examples
<FileToFile map="assembly.dll" to="c:\path\folder\assembly.dll" />
<FileToFile map="PluginAssemblies\**\this.dll" to="..\..\Plugins\**\that.dll" />
<FileToFile map="Webresrouces\ardvark.jpg" to="%SRCBASE%\CrmPackage\WebResources\JPG format\aardvark.jpg" />
<FileToFile
map="pluginpackages\cr886_PluginPackageTest\package\cr886_PluginPackageTest.nupkg"
to="myplg\bin\Debug\myplg.1.0.0.nupkg" />
W poprzednim przykładzie pakietu NuGet nie jest zastępowany, cr886_PluginPackageTest.nupkg jeśli plik już istnieje w określonej lokalizacji.
Mapowanie ścieżki do pliku
Poniższa sekcja zawiera szczegółowe informacje na temat mapowania plików do ścieżki.
XML Format
<FileToPath map="path\filename.ext" to="path" />
Opis
Parametr map określa plik do dopasowania, a to parametr określa ścieżkę do odczytu.
Dla parametru map :
Określ nazwę pliku. Ścieżka jest opcjonalna. Jeśli nie określisz ścieżki, mapowanie może być zgodne z plikami z dowolnego folderu.
Obsługuje symbole wieloznaczne nazw plików.
Symbol wieloznaczny folderu jest obsługiwany.
Dla parametru to :
Określ ścieżkę.
Obsługuje symbol wieloznaczny dla folderów.
Nie określaj nazwy pliku.
Examples
<FileToPath map="assembly.dll" to="c:\path\folder" />
<FileToPath map="PluginAssemblies\**\this.dll" to="..\..\Plugins\bin\**" />
<FileToPath map="*.jpg" to="%SRCBASE%\CrmPackage\WebResources\JPG format\" />
<FileToPath map="*.*" to="..\..\%ARCH%\%TYPE%\drop" />
Przykładowe mapowanie
Poniższy przykładowy kod XML przedstawia kompletny plik mapowania, który umożliwia narzędziu SolutionPackager odczytywanie dowolnego zasobu internetowego i dwóch domyślnych zestawów wygenerowanych z projektu Developer Toolkit o nazwie CRMDevTookitSample.
<?xml version="1.0" encoding="utf-8"?>
<Mapping>
<!-- Match specific named files to an alternate folder -->
<FileToFile map="CRMDevTookitSamplePlugins.dll" to="..\..\Plugins\bin\**\CRMDevTookitSample.plugins.dll" />
<FileToFile map="CRMDevTookitSampleWorkflow.dll" to="..\..\Workflow\bin\**\CRMDevTookitSample.Workflow.dll" />
<!-- Match any file in and under WebResources to an alternate set of subfolders -->
<FileToPath map="WebResources\*.*" to="..\..\CrmPackage\WebResources\**" />
<FileToPath map="WebResources\**\*.*" to="..\..\CrmPackage\WebResources\**" />
</Mapping>
Rozwiązania zarządzane i niezarządzane
Możesz wyeksportować skompresowane rozwiązanie Dataverse (.zip) jako rozwiązanie zarządzane lub niezarządzane.
Rozwiązanie zarządzane
Ukończone rozwiązanie gotowe do zaimportowania do organizacji. Po zaimportowaniu nie można dodawać ani usuwać komponentów, chociaż opcjonalnie można zezwolić na dalsze dostosowywanie. Jest to zalecane, gdy programowanie rozwiązania zostanie zakończone.
Rozwiązanie niezarządzane
Otwarte rozwiązanie bez ograniczeń dotyczących tego, co można dodawać, usuwać ani modyfikować. Opcja zalecana podczas projektowania rozwiązania.
Format skompresowanego pliku rozwiązania będzie inny w zależności od typu rozwiązania: zarządzanego lub niezarządzanego. SolutionPackager może przetwarzać skompresowane pliki rozwiązań dowolnego typu. Jednak narzędzie nie może przekonwertować jednego typu na inny. Jedynym sposobem konwertowania plików rozwiązania na inny typ, na przykład z niezarządzanego do zarządzanego, jest zaimportowanie niezarządzanego rozwiązania .zip pliku do serwera Dataverse, a następnie wyeksportowanie rozwiązania jako rozwiązania zarządzanego.
Pakiet SolutionPackager może przetwarzać niezarządzane i zarządzane pliki rozwiązań .zip jako zestaw połączony przy użyciu parametru /PackageType:Both. Aby wykonać tę operację, należy wyeksportować rozwiązanie dwukrotnie, po jednym razie dla każdego typu. Nazwij pliki .zip w następujący sposób:
Niezarządzany plik ZIP: dowolna_nazwa.zip
Zarządzany plik ZIP: AnyName_managed.zip
Narzędzie zakłada, że zarządzany plik zip znajduje się w tym samym folderze co niezarządzany plik. Wyodrębnia oba pliki do jednego folderu i zachowuje różnice tam, gdzie występują składniki zarządzane i niezarządzane.
Po wyodrębnieniu rozwiązania jako niezarządzanego i zarządzanego można spakować oba typy lub każdy typ oddzielnie z tego pojedynczego folderu. Użyj parametru , /PackageType aby określić typ do utworzenia. Po określeniu obu plików narzędzie tworzy dwa pliki .zip zgodnie z powyższą konwencją nazewnictwa. Jeśli brakuje parametru /PackageType, podczas pakowania z podwójnego folderu rozwiązań zarządzanych i niezarządzanych domyślnie przyjmowany jest jeden plik ZIP rozwiązania niezarządzanego.
Troubleshooting
Komunikat wyświetlany podczas używania Visual Studio do edytowania plików zasobów
Jeśli używasz programu Visual Studio do edytowania plików zasobów utworzonych przez narzędzie Solution Packager, podczas ponownego pakowania może zostać wyświetlony komunikat podobny do następującego: "Failed to determine version id of the resource file <filename>.resx the resource file must be exported from the solutionpackager.exe tool in order to be used as part of the pack process." Ten komunikat jest wyświetlany, ponieważ Visual Studio zastępuje tagi metadanych pliku zasobów tagami danych.
Rozwiązanie
Otwórz plik zasobu w ulubionym edytorze tekstów, a następnie znajdź i zaktualizuj następujące tagi:
<data name="Source LCID" xml:space="preserve"> <data name="Source file" xml:space="preserve"> <data name="Source package type" xml:space="preserve"> <data name="SolutionPackager Version" mimetype="application/x-microsoft.net.object.binary.base64">Zmień nazwę węzła z
<data>na<metadata>.Na przykład taki ciąg:
<data name="Source LCID" xml:space="preserve"> <value>1033</value> </data>Zmienia się na:
<metadata name="Source LCID" xml:space="preserve"> <value>1033</value> </metadata>Dzięki temu narzędzie do tworzenia pakietów rozwiązań może odczytać i zaimportować plik zasobów. Ten problem występuje tylko wtedy, gdy używasz edytora zasobów Visual Studio.
Błąd: "Nie można odnaleźć wymaganego pliku ...\Other\Customizations.xml" z folderem YAML
Ten błąd pojawia się po uruchomieniu pakietu SolutionPackager (lub pac solution pack) względem folderu zawierającego pliki YAML, takie jak solution.yml, ale umieszczasz te pliki w katalogu głównym folderu, a nie wewnątrz wymaganego solutions/<SolutionUniqueName>/ podfolderu.
Przyczyna: Narzędzie wykrywa format kontroli wersji YAML, wyszukując solutions/ podfolder zawierający *solution.yml pliki. Gdy ten katalog jest nieobecny, narzędzie w trybie dyskretnym wraca do formatu XML (starsza wersja) i oczekuje .Other\Customizations.xml Komunikat o błędzie odwołuje się do pliku XML i nie wspomina o yaML, co może być mylące.
Naprawiono: Zorganizuj na nowo folder, aby pliki manifestu YAML znajdowały się w odpowiednich ścieżkach.
<rootFolder>/
solutions/<YourSolutionUniqueName>/ ← move solution.yml here
solution.yml
solutioncomponents.yml
rootcomponents.yml
missingdependencies.yml
publishers/<YourPublisherUniqueName>/
publisher.yml
Jeśli folder został uzyskany podczas procesu zatwierdzania integracji Git lub pac solution clone, struktura folderów powinna być już poprawna. Folder zawierający tylko pliki YAML najwyższego poziomu bez podkatalogu solutions/ reprezentuje niekompletny wyciąg i nie można go bezpośrednio spakować.
Ostrzeżenie: składnik zadeklarowany w rootcomponents.yml nie ma plików źródłowych
Pojawia się ostrzeżenie, gdy składnik, taki jak aplikacja kanwy, jest wymieniony na liście rootcomponents.yml, ale nie ma odpowiednich plików źródłowych w oczekiwanym folderze składnika (na przykład canvasapps/<schema-name>/).
Efekt: działanie narzędzia nadal kończy się powodzeniem (kod zakończenia 0) i tworzy prawidłowy pliki .zip, ale zadeklarowany składnik zostanie pominięty w spakowanym rozwiązaniu.
Przyczyna: Folder został utworzony w wyniku częściowego wyodrębnienia lub pliki źródłowe składnika nie zostały uwzględnione w repozytorium. Na przykład tylko pliki manifestu rozwiązania zostały zatwierdzone, a nie sama aplikacja kanwy.
Naprawić: Upewnij się, że wszystkie składniki zadeklarowane w pliku rootcomponents.yml mają odpowiednie pliki źródłowe obecne w folderze. W przypadku aplikacji kanwy plik .msapp musi istnieć w canvasapps/<schema-name>/. Jeśli brakuje jakichkolwiek plików, ponownie wyeksportuj pełne rozwiązanie z usługi Dataverse i rozpakuj je, lub użyj pac solution clone , aby uzyskać pełne wyodrębnienie.