SolutionPackager-værktøj

SolutionPackager er et værktøj, der kan omdanne en Microsoft Dataverse komprimeret løsningsfil til flere XML-filer og andre filer. Du kan derefter nemt administrere disse filer ved hjælp af et kildekontrolsystem. I følgende afsnit kan du se, hvordan du kører værktøjet, og hvordan du bruger værktøjet med administrerede og ikke-administrerede løsninger.

Hvor finder du SolutionPackager-værktøjet

SolutionPackager-værktøjet distribueres som en del af NuGet-pakken Microsoft.CrmSdk.CoreTools . Følg denne fremgangsmåde for at installere programmet.

1. Download NuGet-pakken.
2. Omdøb filtypenavnet for pakken fra .nupkg til .zip.
3. Udpak indholdet i den komprimerede fil (zip).

Find den SolutionPackager.exe eksekverbare i mappen <extracted-folder-name>/contents/bin/coretools. Kør programmet fra mappen coretools, eller føj mappen til STIEN.

SolutionPackager kommandolinjeargumenter

SolutionPackager er et kommandolinjeværktøj. Du kan aktivere den ved hjælp af de parametre, der er beskrevet i følgende tabel.

Filformater for kildekontrol

SolutionPackager understøtter to mappelayout ved udpakning og pakning af løsninger.

XML-format (ældre)

Det oprindelige format. Værktøjet gemmer løsningsmetadata i Other\Solution.xml og Other\Customizations.xml. Værktøjet udtrækker alle komponentfiler til et fladt mappehierarki sammen med disse filer. Dette format er standardformatet, når du udtrækker en .zip fil uden mere konfiguration.

YAML-kildekontrolformat

Dette format blev introduceret sammen med Dataverse Git-integration og gemmer løsningsmetadata som YAML-filer, der distribueres på tværs af et struktureret mappehierarki. Det er det format, der skrives, når du committer løsninger ved hjælp af oprindelig Git-integration i Power Apps.

Fordele i forhold til XML-format

• Giver renere og mere læsbare diff'er pr. komponent i versionsstyring.
• Understøtter flere løsninger i en enkelt repositorymappe.
• Canvas-appfiler .msapp og moderne flow understøttes kun i dette format.
• Omdirigering af plug-in-typenavne er som standard aktiveret.

Påkrævet mappestruktur

<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]/

Flere oplysninger: Reference til YAML-kildekontrolformat for løsning

Formatér regler for automatisk registrering

Pakning af en YAML-formatmappe

Følgende kommando pakker en YAML-formatmappe.

SolutionPackager.exe /action:Pack /zipfile:MySolution.zip /folder:C:\repos\myrepo

Pakning fra en mappe med flere løsninger

Følgende kommando pakker en angivet løsning i en mappe med flere løsninger.

SolutionPackager.exe /action:Pack /zipfile:SolutionA.zip /folder:C:\repos\myrepo /SolutionName:SolutionA

Brug kommandoargumentet /map

Følgende diskussion beskriver brugen af argumentet /map til værktøjet SolutionPackager.

Filer, der bygges i et automatiseret buildsystem, f.eks. .xap Silverlight-filer og plug-in-assemblies, tjekkes normalt ikke ind i versionsstyringen. Du har muligvis allerede webressourcer i kildestyring på placeringer, der ikke er direkte kompatible med SolutionPackager-værktøjet. Ved at inkludere parameteren /map kan du få værktøjet SolutionPackager til at læse og pakke sådanne filer fra alternative placeringer i stedet for inde fra mappen Extract. Parameteren /map skal angive navnet og stien til en XML-fil, der indeholder tilknytningsparameteren. Disse parametre giver SolutionPackager besked om at matche filerne efter navn og sti og at angive, hvilken alternativ placering den matchede fil skal findes på. Følgende oplysninger gælder for alle direktiver på samme måde.

• Du kan opføre flere direktiver, herunder de direktiver, der svarer til identiske filer. Parametrene, der står tidligt i filen, går forud for de parametre, der er angivet senere.

• Hvis en fil er matchet med et direktiv, skal den findes på mindst én alternativ placering. Hvis der ikke findes nogen tilsvarende alternativer, udsender SolutionPackager en fejl.

• Mappe- og filstier kan være absolutte eller relative. Relative stier evalueres altid fra den mappe, der er angivet af parameteren /folder.

• Angiv miljøvariabler ved hjælp af en %variable% syntaks.

• Brug et jokertegn for mapper ** til at angive "i en hvilken som helst undermappe". Du kan kun bruge den som den sidste del af en sti, f.eks.: c:\folderA\**.

• Brug kun jokertegn for filnavn i formerne *.ext eller *.*. Der understøttes ikke andet mønster.

  I følgende afsnit beskrives de tre typer direktivtilknytninger sammen med et eksempel, der viser, hvordan du bruger dem.

Mappetilknytning

Følgende afsnit indeholder detaljerede oplysninger om mappetilknytning.

XML-format

<Folder map="folderA" to="folderB" />

Beskrivelse

Filstier, der svarer til "folderA", skifter til "folderB".

• Hierarkiet for undermapper under hver mappe skal stemme nøjagtigt overens.

• Mappejokertegn understøttes ikke.

• Du kan ikke angive filnavne.

  Eksempler

  <Folder map="folderA" to="folderB" />  
  <Folder map="folderA\folderB" to="..\..\folderC\" />  
  <Folder map="WebResources\subFolder" to="%base%\WebResources" />  
  

Fil-til-fil-mapping

Følgende oplysninger indeholder flere detaljer om fil til fil-tilknytning.

XML-format

<FileToFile map="path\filename.ext" to="path\filename.ext" />

Beskrivelse

Alle filer, der matcher map-parameteren, læses fra det navn og den sti, der er angivet i to-parameteren.

Angående parameteren map :

• Angiv et filnavn. Stien er valgfri. Hvis du ikke angiver en sti, kan mappingen matche filer fra en hvilken som helst mappe.

• Jokertegn understøttes ikke i filnavne.

• Understøtter jokertegn for mapper.

  Angående parameteren to :

• Angiv et filnavn og sti.

• Filnavnet kan være forskelligt fra navnet i map parameteren.

• Jokertegn understøttes ikke i filnavne.

• Understøtter mappejokertegn.

Eksempler

  <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" /> 

I det foregående NuGet-pakkeeksempel overskrives cr886_PluginPackageTest.nupkg ikke, hvis filen allerede findes på den angivne placering.

Fil-til-sti-mapping

Følgende afsnit indeholder detaljerede oplysninger om tilknytning af filer til stier.

XML-format

<FileToPath map="path\filename.ext" to="path" />

Beskrivelse

Parameteren map angiver den fil, der skal matches med, og parameteren to angiver den sti, der skal læses fra.

Angående parameteren map :

• Angiv et filnavn. Stien er valgfri. Hvis du ikke angiver en sti, kan mappingen matche filer fra en hvilken som helst mappe.

• Understøtter jokertegn for filnavne.

• Understøtter jokertegn for mapper.

Angående parameteren to :

• Angiv en sti.

• Understøtter jokertegn for mapper.

• Angiv ikke et filnavn.

  Eksempler

  <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" />  

Eksempel på kortlægning

Følgende XML-kodeeksempel viser en komplet tilknytningsfil, der gør det muligt for SolutionPackager-værktøjet at læse en hvilken som helst webressource og de to standardgenererede assemblies fra et Developer Toolkit-projekt med navnet 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>  

Administrerede og ikke-administrerede løsninger

Du kan eksportere en Dataverse-komprimeret løsningsfil (.zip) som enten en administreret eller uadministreret løsning.

Administreret løsning
En fuldført løsning, der er klar til at blive importeret til en organisation. Når den er importeret, kan du ikke tilføje eller fjerne komponenter, selvom du eventuelt kan tillade yderligere tilpasning. Brug denne type, når udviklingen af løsningen er fuldført.

Ikke-administreret løsning
En åben løsning uden begrænsninger for, hvad du kan tilføje, fjerne eller ændre. Brug denne type under udvikling af en løsning.

Formatet af en komprimeret løsningsfil varierer afhængigt af typen, enten administreret eller uadministreret. SolutionPackager kan behandle komprimerede løsningsfiler af begge typer. Værktøjet kan dog ikke konvertere én type til en anden. Den eneste måde at konvertere løsningsfiler til en anden type, f.eks. fra en ikke-administreret løsning til en administreret løsning, er ved at importere den ikke-administrerede løsnings .zip-fil til en Dataverse-server og derefter eksportere løsningen som en administreret løsning.

SolutionPackager kan behandle ikke-administrerede og administrerede løsnings-.zip-filer som et kombineret sæt ved hjælp af parameteren /PackageType:Both. Hvis du vil udføre denne handling, skal du eksportere løsningen to gange, én gang for hver type. Navngiv de .zip filer på følgende måde:

Værktøjet forudsætter, at den administrerede zip-fil er i samme mappe som den ikke-administrerede fil. Den udtrækker begge filer til en enkelt mappe og bevarer forskellene, hvor der findes administrerede og ikke-administrerede komponenter.

Når du har ekstraheret en løsning som både ikke-administreret og administreret, kan du pakke begge typer eller hver type individuelt fra den samme mappe. /PackageType Brug parameteren til at angive, hvilken type der skal oprettes. Når du angiver begge filer, opretter værktøjet to .zip filer ved hjælp af den foregående navngivningskonvention. Hvis du ikke medtager parameteren /PackageType, når du pakker fra et administreret/ikke-administreret mappepar, er standarden at oprette en enkelt ikke-administreret .zip-fil.

Fejlfinding

Meddelelse, der vises, når du bruger Visual Studio til at redigere ressourcefiler

Hvis du bruger Visual Studio til at redigere de ressourcefiler, der er oprettet af løsningspakkeren, får du muligvis vist en meddelelse, når du pakker igen i stil med dette: "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." Denne meddelelse vises, fordi Visual Studio erstatter ressourcefilens metadatakoder med datakoder.

Løsning

1. Åbn ressourcefilen i din foretrukne teksteditor, og find og opdater derefter følgende tags:

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

2. Skift nodenavnet fra <data> til <metadata>.

   For eksempel denne streng:

   <data name="Source LCID" xml:space="preserve">  
     <value>1033</value>  
   </data>  
   
   

   Ændringer til:

   <metadata name="Source LCID" xml:space="preserve">  
     <value>1033</value>  
   </metadata>  
   
   

   Denne ændring gør det muligt for løsningspakkeren at læse og importere ressourcefilen. Problemet opstår kun, når du bruger Visual Studio Resource Editor.

Fejl! "Den nødvendige fil ...\Other\Customizations.xml" blev ikke fundet med en YAML-mappe

Denne fejl vises, når du kører SolutionPackager (eller pac solution pack) på en mappe, der indeholder YAML-filer, f.eks solution.yml. , men du placerer disse filer i roden af mappen i stedet for i den påkrævede solutions/<SolutionUniqueName>/ undermappe.

Forårsage: Værktøjet registrerer YAML-kildekontrolformatet ved at søge efter en solutions/ undermappe, der indeholder *solution.yml filer. Når mappen ikke findes, går værktøjet automatisk tilbage til XML-formatet (ældre) og forventer Other\Customizations.xml. Fejlmeddelelsen refererer til en XML-fil og nævner ikke YAML, hvilket kan være forvirrende.

Lave: Omorganiser mappen, så YAML-manifestfilerne er under de korrekte stier:

<rootFolder>/
  solutions/<YourSolutionUniqueName>/   ← move solution.yml here
    solution.yml
    solutioncomponents.yml
    rootcomponents.yml
    missingdependencies.yml
  publishers/<YourPublisherUniqueName>/
    publisher.yml

Hvis du har hentet mappen fra en Git-integrations-commit eller pac solution clone, er mappestrukturen allerede korrekt. En mappe, der kun indeholder YAML-filer på øverste niveau uden solutions/ undermappen, repræsenterer en ufuldstændig udtrækning og kan ikke pakkes direkte.

Advarsel! Komponenten, der er erklæret i rootcomponents.yml, har ingen kildefiler

Denne advarsel vises, når en komponent, f.eks. en lærredsapp, er angivet i rootcomponents.yml , men der ikke findes tilsvarende kildefiler i den forventede komponentmappe (f.eks. canvasapps/<schema-name>/).

Effekt: Værktøjet lykkes stadig (afslutningskode 0) og opretter en gyldig .zip fil, men den angivne komponent udelades fra den pakkede løsning.

Forårsage: Mappen blev oprettet ved en delvis udtrækning, eller komponentens kildefiler blev ikke inkluderet i lageret. Det er f.eks. kun løsningsmanifestfilerne, der blev bekræftet, og ikke selve lærredsappen.

Lave: Kontrollér, at alle komponenter, der er erklæret i rootcomponents.yml , har tilsvarende kildefiler i mappen. Filen .msapp skal findes under canvasapps/<schema-name>/ for lærredsapps. Hvis der mangler filer, skal du eksportere hele løsningen fra Dataverse igen og pakke den ud igen eller bruge pac solution clone til at få et komplet uddrag.

Se også

• Brug af kildekontrol med løsningsfiler
• Løsningskoncepter