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. De volgende secties laten zien hoe u dit hulpprogramma uitvoert en hoe u het hulpprogramma gebruikt met beheerde en onbeheerde oplossingen.

Waar het SolutionPackager-hulpprogramma te zoeken

Het hulpprogramma SolutionPackager wordt gedistribueerd als onderdeel van de 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 met de parameters in de volgende tabel kan 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 opdrachtargument /map

De volgende discussie bespreekt het gebruik van het argument /map naar het hulpprogramma SolutionPackager.

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 /mao op te nemen, kan het SolutionPackager-hulpprogramma worden opgedragen om dergelijke bestanden te lezen en in te pakken vanaf andere locaties en niet vanuit de map Extract zoals gebruikelijk. 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 geldt evenveel voor 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 aan een richtlijn wordt gekoppeld, moet het op ten minste één andere 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 /folder.

• Omgevingvariabelen kunnen worden opgegeven met een a %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 de bestanden van elke map worden afgestemd.

• Bestandsnaamjokertekens worden niet ondersteund.

• Het mapjokerteken wordt ondersteund.

  Voor de to parameter:

• Er moet een bestandsnaam en pad worden opgegeven.

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

• 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 overeenstemt met de parameter map wordt gelezen vanaf 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 de bestanden van elke map worden afgestemd.

• Bestandsnaamjokertekens 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

Het volgende XML-codevoorbeeld toont een volledig toewijzingsbestand dat ervoor zorgt dat het SolutionPackager-hulpprogramma elke webresource en twee standaard gegenereerde assemblies kan lezen vanuit Developer Toolkit-projecten 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, klaar 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 is aanbevolen wanneer de ontwikkeling voor de oplossing is voltooid.

Onbeheerde oplossing
Een open oplossing zonder beperkingen over wat kan worden toegevoegd, verwijderd, of aangepast. Dit is aanbevolen tijdens de ontwikkeling van een oplossing.

De indeling van een gecomprimeerd oplossingbestand is verschillend volgens type, beheerd of onbeheerd. SolutionPackager kan gecomprimeerde oplossingsbestanden van elk type 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.

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

Het hulpprogramma veronderstelt de aanwezigheid van het beheerde zipbestand in dezelfde map als het onbeheerde bestand en pakt beide bestanden uit in één map, waarbij de verschillen worden behouden tussen beheerde en onbeheerde onderdelen.

Nadat een oplossing is uitgepakt als beheerd en onbeheerd, is het mogelijk om vanuit die map beide in te pakken, of elk type afzonderlijk, met de parameter /PackageType om het type te selecteren dat u wilt maken. Bij het opgeven van beide bestanden, worden er twee zipbestanden gemaakt met de naamconventie zoals hierboven. Als de parameter /PackageType ontbreekt wanneer u inpakt vanuit een dubbele beheerde en onbeheerde map, wordt standaard één onbeheerd zipbestand gemaakt.

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 tekstverwerker en zoek en bewerk de volgende labels:

   <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 knooppuntnaam van <data> naar <metadata>.

   Deze tekenreeks bijvoorbeeld:

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

• Bronbeheer gebruiken met oplossingsbestanden
• sOplossingsconcepten