Hulpprogramma SolutionPackager

SolutionPackager is een hulpprogramma waarmee een Microsoft Dataverse gecomprimeerd oplossingsbestand kan worden omgedraaid in meerdere XML-bestanden en andere bestanden. U kunt deze bestanden vervolgens eenvoudig beheren door gebruik te maken van een bronbeheersysteem. In de volgende secties ziet u hoe u het hulpprogramma uitvoert en hoe u het hulpprogramma gebruikt met beheerde en onbeheerde oplossingen.

Waar vindt u de tool SolutionPackager?

Het hulpprogramma SolutionPackager wordt gedistribueerd als onderdeel van het Microsoft.CrmSdk.CoreTools NuGet-pakket. Voer deze stappen uit om het programma te installeren.

1. Download het NuGet-pakket.
2. Verander de bestandsnaamextensie van het pakket van .nupkg naar .zip.
3. Pak de inhoud van het gecomprimeerde (zip) bestand uit.

Zoek het uitvoerbare bestand SolutionPackager.exe in de map <naam-uitgepakte-map>/contents/bin/coretools. Voer het programma uit vanuit de map coretools of voeg die map toe aan uw PATH.

Argumenten van de opdrachtregel SolutionPackager

SolutionPackager is een opdrachtregelprogramma dat kan worden aangeroepen met de parameters die in de volgende tabel worden geïdentificeerd.

Bestandsindelingen voor broncodebeheer

SolutionPackager ondersteunt twee mapindelingen bij het extraheren en verpakken van oplossingen.

XML-indeling (verouderd)

De oorspronkelijke indeling. nl-NL: Metagegevens van oplossingen worden opgeslagen in Other\Solution.xml en Other\Customizations.xml. Alle onderdeelbestanden worden samen met deze bestanden uitgepakt in een vlakke mappenhiërarchie. Deze indeling is de standaardindeling bij het extraheren van een .zip bestand zonder meer configuratie.

YAML-indeling voor broncodebeheer

Geïntroduceerd samen met Dataverse Git-integratie, slaat deze indeling metagegevens van oplossingen op als YAML-bestanden die zijn verdeeld over een gestructureerde maphiërarchie. Dit is de indeling die is geschreven wanneer u oplossingen doorvoert met behulp van systeemeigen Git-integratie in Power Apps.

Voordelen ten opzichte van XML-indeling

• Produceert schonere, beter leesbare diffs per onderdeel in versiebeheer
• Ondersteunt meerdere oplossingen in één opslagplaatsmap
• Canvas-app-bestanden .msapp en moderne workflows worden alleen ondersteund in dit format
• Hernoemen van plug-in typen is standaard ingeschakeld

Vereiste mapstructuur

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

Meer informatie: Naslaginformatie over de YAML-broncodebeheerindeling van oplossing

Regels voor automatische detectie opmaken

Een bestand met YAML-indeling inpakken

Met de volgende opdracht wordt een map in YAML-indeling ingepakt.

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

Inpakken vanuit een map met meerdere oplossingen

Met de volgende opdracht wordt een opgegeven oplossing in een map met meerdere oplossingen verpakt.

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

Gebruik het argument van de opdracht /map

In de volgende discussie wordt het gebruik van het argument /map voor het hulpprogramma SolutionPackager beschreven.

Bestanden die in een geautomatiseerd buildsysteem worden opgebouwd, zoals Silverlight-bestanden (.xap) en plug-inassemblies, worden meestal niet opgenomen in bronbeheer. Webresources kunnen al aanwezig zijn in bronbeheer op locaties die niet rechtstreeks compatibel zijn met het SolutionPackager-hulpprogramma,. Door de parameter /map op te nemen, kan het hulpprogramma SolutionPackager worden aangestuurd om dergelijke bestanden te lezen en te verpakken vanaf alternatieve locaties en niet vanuit de map Uitpakken, zoals normaal gesproken het geval zou zijn. De parameter /map moet de naam en het pad naar een XML-bestand met toewijzingsrichtlijnen specificeren. Deze richtlijnen instrueren de SolutionPackager om bestanden te matchen op naam en pad, en geven de alternatieve locatie aan om het overeenkomende bestand te vinden. De volgende informatie is in gelijke mate van toepassing op alle richtlijnen.

• Meerdere richtlijnen kunnen worden weergegeven, waaronder richtlijnen die identieke bestanden zoeken. De richtlijnen die vroeg in het bestand staan, krijgen de voorkeur ten opzichte van de richtlijnen die later worden weergegeven.

• Als een bestand overeenkomt met een richtlijn, moet het op ten minste één alternatieve locatie worden gevonden. Als er geen overeenkomende alternatieven worden gevonden, wordt er een fout weergegeven.

• Map- en bestandspaden kunnen absoluut of relatief zijn. Relatieve paden worden altijd geëvalueerd vanuit de map die is opgegeven door de parameter /map.

• Omgevingsvariabelen kunnen worden gespecificeerd met behulp van een %variable% syntaxis.

• Een mapjokerteken '**' kan worden gebruikt om aan te geven dat het 'in een willekeurige submap' is. Het kan alleen worden gebruikt als het laatste deel van een pad, bijvoorbeeld: 'c:\folderA\**'.

• Jokertekens voor bestandsnaam mogen alleen worden gebruikt in de formulieren *.ext of *.*. Er wordt geen ander patroon ondersteund.

  De drie types richtlijnentoewijzingen worden hier beschreven, samen met een voorbeeld dat toont hoe u deze kunt gebruiken.

Maptoewijzing

De volgende informatie bevat gedetailleerde gegevens over maptoewijzing.

Xml-indeling

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

Beschrijving

Bestandspaden die overeenkomen met 'folderA' worden overgeschakeld naar 'folderB'.

• De hiërarchie van submappen onder elk ervan moet precies overeenkomen.

• Mapjokertekens worden niet ondersteund.

• Er mogen geen bestandsnamen worden opgegeven.

  Voorbeelden

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

Bestand naar bestandtoewijzing

De volgende informatie toont meer details over de bestand-naar-bestandtoewijzing.

Xml-indeling

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

Beschrijving

Elk bestand dat overeenstemt met de parameter map wordt gelezen vanaf de naam en het pad in de opgegeven parameter to.

Voor de map parameter:

• Er moet een bestandsnaam worden opgegeven. Het pad is optioneel. Als er geen pad is opgegeven, kunnen bestanden uit elke map worden gevonden.

• Bestandsnaamjokertekens worden niet ondersteund.

• Het mapjokerteken wordt ondersteund.

  Voor de to parameter:

• Er moet een bestandsnaam en pad worden opgegeven.

• De bestandsnaam kan afwijken van de naam in de map parameter.

• Bestandsnaamjokertekens worden niet ondersteund.

• Het mapjokerteken wordt ondersteund.

Voorbeelden

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

In het bovenstaande NuGet-pakketvoorbeeld wordt cr886_PluginPackageTest.nupkg niet overschreven als het bestand al bestaat op de opgegeven locatie.

Bestand naar padtoewijzing

De volgende tabel toont gedetailleerde informatie over de bestand-naar-padtoewijzing.

Xml-indeling

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

Beschrijving

Elk bestand dat overeenkomt met de map parameter, wordt gelezen van het pad dat in de to parameter is opgegeven.

Voor de map parameter:

• Er moet een bestandsnaam worden opgegeven. Het pad is optioneel. Als er geen pad is opgegeven, kunnen bestanden uit elke map worden gevonden.

• Jokertekens voor bestandsnamen worden ondersteund.

• Het mapjokerteken wordt ondersteund.

Voor de to parameter:

• Er moet een pad worden opgegeven.

• Het mapjokerteken wordt ondersteund.

• Er mag geen bestandsnaam worden opgegeven.

  Voorbeelden

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

Voorbeeld van toewijzing

In het volgende voorbeeld van een XML-code ziet u een volledig toewijzingsbestand waarmee het hulpprogramma SolutionPackager alle webresources en de twee standaard gegenereerde assembly's kan lezen van een Developer Toolkit-project met de naam 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>  

Beheerde en onbeheerde oplossingen

Een bestand met een gecomprimeerde Dataverse-oplossing (.zip) kan worden geëxporteerd in een of twee types, zoals hier getoond.

Beheerde oplossing
Een voltooide oplossing die klaar is om in een organisatie te worden geïmporteerd. Na het importeren kunnen onderdelen niet worden toegevoegd of verwijderd, hoewel ze eventueel verdere aanpassingen kunnen toestaan. Dit wordt aanbevolen wanneer de ontwikkeling van de oplossing is voltooid.

Onbeheerde oplossing
Een open oplossing zonder beperkingen op wat kan worden toegevoegd, verwijderd of gewijzigd. Dit wordt aanbevolen tijdens de ontwikkeling van een oplossing.

De indeling van een gecomprimeerd oplossingsbestand verschilt op basis van het type, beheerd of onbeheerd. De SolutionPackager kan gecomprimeerde oplossingsbestanden van beide typen verwerken. Het hulpprogramma kan het ene type echter niet converteren naar een ander type. De enige manier om oplossingsbestanden om te zetten naar een ander type, bijvoorbeeld van onbeheerd naar beheerd, is door het onbeheerde oplossingsbestand (.zip) te importeren in een Dataverse-server en vervolgens de oplossing te exporteren als een beheerde oplossing.

De SolutionPackager kan onbeheerde en beheerde oplossings- .zip bestanden verwerken als een gecombineerde set via de parameter /PackageType:Both. Om deze bewerking uit te voeren, is het noodzakelijk om uw oplossing twee keer als elk type te exporteren, waarbij de .zip bestanden als volgt worden genoemd.

De tool gaat ervan uit dat het beheerde zip-bestand zich in dezelfde map bevindt als het onbeheerde bestand en pakt beide bestanden uit in één map, waarbij de verschillen tussen beheerde en onbeheerde componenten behouden blijven.

Nadat een oplossing is uitgetrokken als zowel onbeheerd als beheerd, is het mogelijk vanuit die ene map beide typen, of elk type afzonderlijk, in te pakken met behulp van de parameter /PackageType om op te geven welk type moet worden gemaakt. Bij het opgeven van beide bestanden, worden er twee zipbestanden gemaakt met de naamconventie zoals hierboven. Als de parameter /PackageType ontbreekt bij het inpakken vanuit een dubbele beheerde en onbeheerde map, is de standaardinstelling het produceren van één onbeheerd .zip bestand.

Probleemoplossing

Bericht weergegeven wanneer u Visual Studio gebruikt om resourcebestanden te bewerken

Als u Visual Studio gebruikt om resource fsiles te bewerken die zijn gemaakt door de oplossingspakketer, ontvangt u mogelijk een bericht wanneer u deze opnieuw inpakt: "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." Dit gebeurt omdat Visual Studio de metagegevenstags van het resourcebestand vervangt door gegevenstags.

Oplossing

1. Open het bronbestand in uw favoriete teksteditor en zoek en werk de volgende tags bij:

   <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. Wijzig de naam van het knooppunt van <data> in <metadata>.

   Bijvoorbeeld, deze string:

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

   Wijzigt in:

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

   Hierdoor kan de oplossingsverpakker het bronbestand lezen en importeren. Dit probleem is alleen waargenomen bij het gebruik van de Visual Studio Resource-editor.

Fout: "Kan vereist bestand …\Other\Customizations.xml niet vinden" met een YAML-map

Deze fout wordt weergegeven wanneer u SolutionPackager (of pac solution pack) uitvoert op een map die YAML-bestanden bevat, zoals solution.yml, maar deze bestanden worden in de hoofdmap van de map geplaatst in plaats van in de vereiste solutions/<SolutionUniqueName>/ submap.

Oorzaak: Het hulpprogramma detecteert de YAML-broncodebeheerindeling door te zoeken naar een solutions/ submap met *solution.yml bestanden. Wanneer die map afwezig is, valt het hulpprogramma terug naar de XML-indeling (legacy) en verwacht Other\Customizations.xml. Het resulterende foutbericht verwijst naar een XML-bestand en vermeldt geen YAML, wat misleidend is.

Fix: De map opnieuw indelen zodat de YAML-manifestbestanden zich onder de juiste paden bevinden:

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

Als u de map hebt verkregen van een Git-integratiedoorvoering of pac solution clone, moet de mapstructuur al correct zijn. Een map die alleen de YAML-bestanden op het hoogste niveau bevat zonder de solutions/ submap, vertegenwoordigt een onvolledig extract en kan niet rechtstreeks worden verpakt.

Waarschuwing: het onderdeel dat is gedeclareerd in rootcomponents.yml geen bronbestanden bevat

Deze waarschuwing wordt weergegeven wanneer een onderdeel, zoals een canvas-app, wordt vermeld in rootcomponents.yml maar er geen bijbehorende bronbestanden bestaan in de verwachte onderdeelmap (bijvoorbeeld canvasapps/<schema-name>/).

Effect: Het hulpprogramma slaagt nog steeds (afsluitcode 0) en produceert een geldig .zip bestand, maar het gedeclareerde onderdeel wordt weggelaten uit de verpakte oplossing.

Oorzaak: De map is geproduceerd door een gedeeltelijk extract of de bronbestanden van het onderdeel zijn niet opgenomen in de opslagplaats. Alleen de manifestbestanden van de oplossing zijn bijvoorbeeld doorgevoerd en niet de canvas-app zelf.

Fix: Zorg ervoor dat alle onderdelen die zijn gedeclareerd, rootcomponents.yml overeenkomende bronbestanden in de map hebben. Voor canvas-apps moet het .msapp bestand bestaan onder canvasapps/<schema-name>/. Als er bestanden ontbreken, exporteert u de volledige oplossing opnieuw uit Dataverse en pakt u deze opnieuw uit of gebruikt pac solution clone u deze om een volledig extract te verkrijgen.

Zie ook

• Broncodebeheer gebruiken met oplossingsbestanden
• sOplossingsconcepten