SolutionPackager-verktyget

SolutionPackager är ett verktyg som kan återställa en Microsoft Dataverse komprimerad lösningsfil till flera XML-filer och andra filer. Du kan då enkelt hantera dessa filer med hjälp av ett källkontrollsystem. I följande avsnitt lär du dig hur du kör verktyget och hur du använder verktyget med hanterade och icke-hanterade lösningar.

Här hittar du verktyget SolutionPackager

SolutionPackager-verktyget distribueras som en del av Microsoft. CrmSdk.CoreTools NuGet-paket. Följ de här stegen för att installera appen.

1. Ladda ned NuGet-paketet.
2. Byt namn på filnamnstillägget för paketet från .nupkg till .zip.
3. Extrahera innehållet i den komprimerade (zip) filen.

Leta upp den körbara filen SolutionPackager.exe i mappen <extracted-folder-name>/contents/bin/coretools. Kör programmet från mappen coretools eller lägg till mappen i PATH.

Kommandoradargument för SolutionPackager

SolutionPackager är ett kommandoradsverktyg som kan startas med de parametrar som anges i följande tabell.

Filformat för källkontroll

SolutionPackager stöder två mappstrukturer när du extraherar och packar lösningar.

XML-format (äldre)

Det ursprungliga formatet. Lösningsmetadata lagras i Other\Solution.xml och Other\Customizations.xml, och alla komponentfiler extraheras till en platt mapphierarki tillsammans med dessa filer. Det här formatet är standardformatet när du extraherar en .zip fil utan mer konfiguration.

YAML-källkontrollformat

Det här formatet introducerades tillsammans med Dataverse Git-integrering och lagrar lösningsmetadata som YAML-filer som distribueras över en strukturerad mapphierarki. Det är formatet som skrivs när du genomför lösningar med inbyggd Git-integrering i Power Apps.

Fördelar jämfört med XML-format

• Producerar renare, mer läsbara diff per komponent i källkontrollen
• Stöder flera lösningar i en enda lagringsplatsmapp
• Canvas app-filer .msapp och moderna flöden stöds endast i det här formatet
• Ommappning av plugin-typnamn är aktiverat som standard

Nödvändig mappstruktur

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

Mer information: Referens för yaml-källkontrollformat för lösning

Formatera regler för automatisk identifiering

Packning av en YAML-formatmapp

Följande kommando packar en YAML-formatmapp.

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

Paketering från en mapp med flera lösningar

Följande kommando packar en angiven lösning i en mapp med flera lösningar.

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

Använda kommandoargumentet /map

I följande diskussion beskrivs hur du använder argumentet /map med verktyget SolutionPackager.

Filer som är inbyggda i ett automatiserat versionssystem, t. ex. xap Silverlight-filer och plugin-programpaket, kontrolleras som regel inte i källkontrollen. Webbresurser kanske redan finns i källkontrollen på platser som inte är direkt kompatibla med verktyget SolutionPackager. Om du inkluderar parametern /map kan verktyget SolutionPackager användas för att läsa och paketera sådana filer från alternativa platser och inte som vanligt från insidan av extraheringsmappen. I parametern /map måste namnet och sökvägen till en XML-fil med mappning anges. De uppger att SolutionPackager ska matcha filernas namn och sökväg och ange en alternativ plats för att hitta den matchande filen. Följande information gäller lika för alla direktiv.

• Flera direktiv kan visas, inklusive de direktiv som överensstämmer med identiska filer. Direktiv som visas tidigt i filen har högre prioritet än de direktiv som visas i listan senare.

• Om en fil matchas mot ett annat direktiv måste den finnas på minst en alternativ plats. Om det inte finns några matchande alternativ kommer SolutionPackager att utfärda ett fel.

• Mapp- och filsökvägar kan vara absoluta eller relativa. Relativa sökvägar utvärderas alltid från den mapp som anges med parametern /folder.

• Miljövariabler kan anges med syntaxen %variable%.

• Jokertecknet för mappar "**" används för att beteckna "i alla undermappar". Den kan bara användas som den sista delen av en sökväg, till exempel: "c:\folderA\**".

• Jokertecken för filnamn får endast användas i formulären "*.ext" eller "*.*". Inget annat mönster stöds.

  De tre typerna av direktivmappningar beskrivs här tillsammans med ett exempel som visar hur du använder dem.

Mapphantering

Nedan finns detaljerad information om mapp-mappning.

XML-format

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

Description

Filsökvägar som matchar "folderA" växlas till "folderB".

• Mapphierarkin för undermappar under varje måste matcha exakt.

• Jokertecken för mappar stöds inte.

• Inga filnamn kan anges.

  Exempel

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

Fil-till-fil-mappning

Nedan finns detaljerad information om mappning fil till fil.

XML-format

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

Description

Alla filer som matchar map-parametern kommer att läsas från namnet och sökvägen som anges i to-parametern.

För map-parametern:

• Ett filnamn måste anges. Sökvägen är valfri. Om ingen sökväg anges kan filer från alla mappar matchas.

• Jokertecken för filnamn stöds inte.

• Jokertecknet för mappen stöds.

  För to-parametern:

• Ett filnamn och en sökväg måste anges.

• Filnamnet kan skilja sig från namnet i map-parametern.

• Jokertecken för filnamn stöds inte.

• Jokertecknet för mappen stöds.

Exempel

  <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 NuGet-paketexemplet ovan, skrivs cr886_PluginPackageTest.nupkg inte över om filen redan finns på den angivna platsen.

Mappning av fil till sökväg

Nedan finns detaljerad information om mappning fil till sökväg.

XML-format

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

Description

Alla filer som matchar map-parametern kommer att läsas från sökvägen som anges i to-parametern.

För map-parametern:

• Ett filnamn måste anges. Sökvägen är valfri. Om ingen sökväg anges kan filer från alla mappar matchas.

• Jokertecken för filnamn stöds.

• Jokertecknet för mappen stöds.

För to-parametern:

• En sökväg måste anges.

• Jokertecknet för mappen stöds.

• Ett filnamn ska inte anges.

  Exempel

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

Exempel på mappning

Följande XML-kodexempel visar en fullständig mappningsfil som gör att SolutionPackager-verktyget kan läsa alla webbresurser och de två standardgenererade sammansättningarna från ett Utvecklare Toolkit-projekt kallat 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>  

Hanterade och icke-hanterade lösningar

Du kan exportera en Dataverse komprimerad lösningsfil (zip) i en av de två typer som visas här.

Hanterad lösning
En slutförd lösning som kan importeras till en organisation. När komponenterna har importerats kan de inte läggas till eller tas bort, även om de kan tillåta ytterligare anpassning. Detta rekommenderas när utvecklingen av lösningen har slutförts.

Ohanterad lösning
En öppen lösning utan begränsningar för vad som kan läggas till, tas bort eller ändras. Detta rekommenderas i samband med utveckling av en lösning.

Formatet för en komprimerad lösningsfil varierar beroende på typ, antingen hanterad eller icke-hanterad. Med SolutionPackager kan du bearbeta komprimerade lösningsfiler av bägge typer. Verktyget kan dock inte konvertera en typ till en annan. Det enda sättet att konvertera lösningsfiler till en annan typ, t.ex. från icke-hanterad till hanterad, är att importera den icke-hanterade lösningsfilen i zip-format till en Dataverse-server och sedan exportera lösningen som en hanterad lösning.

SolutionPackager kan bearbeta icke-hanterade och hanterade lösningsfiler i zip-format som en sammanlagd uppsättning via parametern "/PackageType:Both". Om du vill utföra den här åtgärden måste du exportera lösningen två gånger för respektive typ och namnge zip-filerna enligt följande:

Verktyget förutsätter förekomst av den hanterade zip-filen i samma mapp som den icke-hanterade filen och extraherar båda filer till en enda mapp som bevarar skillnaderna där såväl hanterade som icke-hanterade komponenter förekommer.

När en lösning har extraherats både som icke-hanterad och hanterad är det möjligt att från denna enda mapp paketera båda typer (eller respektive typ individuellt) med hjälp av parametern/PackageType i syfte att ange vilken typ som ska skapas. När båda filer anges kommer två zip-filer att produceras enligt namngivningskonventionen ovan. Om parametern /PackageType saknas när du packar från en dubbel hanterad och icke-hanterad mapp är standardvärdet att skapa en enkel, icke-hanterad zip-fil.

Felsökning

Meddelande som visas när du använder Visual Studio för att redigera resursfiler

Om du använder Visual Studio för att redigera resursfiler som skapats av lösningspaketeraren kan du få ett meddelande när du packar om så här: "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." Detta beror på att Visual Studio ersätter resursfilens metadatataggar med datataggar.

Lösning

1. Öppna resursfilen i din favorittextredigerare och sök efter samt uppdatera följande taggar:

   <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. Ändra nodnamnet från <data> till <metadata>.

   Till exempel följande sträng:

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

   Ändras till:

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

   Detta gör att lösningspaketeraren kan läsa och importera resursfilen. Det här problemet har bara observerats när du använder Visual Studio Resursredigeraren.

Fel: "Det går inte att hitta nödvändig fil ...\Other\Customizations.xml" med en YAML-mapp

Det här felet visas när du kör SolutionPackager (eller pac solution pack) mot en mapp som innehåller YAML-filer som solution.yml, men dessa filer placeras i mappens rot i stället för inuti den nödvändiga solutions/<SolutionUniqueName>/ undermappen.

Orsaka: Verktyget identifierar YAML-källkontrollformatet genom att leta efter en solutions/ undermapp som innehåller *solution.yml filer. När katalogen saknas återgår verktyget tyst till XML-formatet (äldre) och förväntar sig Other\Customizations.xml. Det resulterande felmeddelandet refererar till en XML-fil och nämner inte YAML, vilket är missvisande.

Fixa: Ordna om mappen så att YAML-manifestfilerna finns under rätt sökvägar:

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

Om du har hämtat mappen från en Git-integreringsincheckning eller pac solution clonebör mappstrukturen redan vara korrekt. En mapp som bara innehåller YAML-filerna på den översta nivån utan underkatalogen solutions/ representerar ett ofullständigt extraheringsextrakt och kan inte packas direkt.

Varning! Komponenten som deklareras i rootcomponents.yml har inga källfiler

Den här varningen visas när en komponent, till exempel en arbetsyteapp, visas i rootcomponents.yml men det inte finns några motsvarande källfiler i den förväntade komponentmappen (till exempel canvasapps/<schema-name>/).

Effekt: Verktyget lyckas fortfarande (slutkod 0) och skapar en giltig .zip fil, men den deklarerade komponenten utelämnas från den paketerade lösningen.

Orsaka: Mappen producerades av ett partiellt extraheringsextrakt, eller så inkluderades inte komponentens källfiler i lagringsplatsen. Till exempel har endast lösningsmanifestfilerna lagts till och inte själva canvas-appen.

Fixa: Kontrollera att alla komponenter som deklareras i rootcomponents.yml har motsvarande källfiler i mappen. För canvas-appar måste filen finnas under canvasapps/<schema-name>/. Om några filer saknas, exportera hela lösningen från Dataverse på nytt och packa upp igen, eller använd pac solution clone för att hämta en komplett extrahering.

Se även

• Använda källkontroll med lösningsfiler
• sLösningsbegrepp