SolutionPackager-verktøy

SolutionPackager er et verktøy som kan dekomponere en Microsoft Dataverse komprimert løsningsfil til flere XML-filer og andre filer. Du kan deretter enkelt behandle disse filene ved å bruke et kildekontrollsystem. Avsnittene nedenfor viser hvordan du kjører verktøyet og hvordan du bruker verktøyet med administrerte og uadministrerte løsninger.

Hvor finner du SolutionPackager-verktøyet

SolutionPackager-verktøyet distribueres som en del av Microsoft. CrmSdk.CoreTools NuGet-pakke. Følg disse trinnene for å installere programmet.

1. Last ned NuGet-pakken.
2. Endre navnet på pakkefilnavnet fra NUPKG til ZIP.
3. Pakk ut innholdet i komprimerte (zip) filen.

Finn den kjørbare SolutionPackager.exe-filen i mappen <extracted-folder-name>/contents/bin/coretools folder. Kjør programmet fra mappen coretools, eller legg til mappen i PATH.

SolutionPackager kommandolinjeargumenter

SolutionPackager er et kommandolinjeverktøy. Du kan kalle den ved hjelp av parameterne som er beskrevet i tabellen nedenfor.

Filformater for kildekontroll

SolutionPackager støtter to mappeoppsett når du trekker ut og pakker ut løsninger.

XML-format (eldre)

Det opprinnelige formatet. Verktøyet lagrer løsningsmetadata i Other\Solution.xml og Other\Customizations.xml. Verktøyet trekker ut alle komponentfiler i et flatt mappehierarki ved siden av disse filene. Dette formatet er standardformatet når du ekstraherer en .zip-fil uten mer konfigurasjon.

YAML-kildekontrollformat

Dette formatet ble introdusert sammen med Dataverse Git-integrering, og lagrer løsningsmetadata som YAML-filer distribuert på tvers av et strukturert mappehierarki. Det er formatet som skrives når du committer løsninger ved hjelp av opprinnelig Git-integrasjon i Power Apps.

Fordeler med XML-format

• Produserer renere, mer lesbare per komponent diffs i kildekontroll.
• Støtter flere løsninger i én enkelt repository-mappe.
• filer for lerretsapper .msapp og moderne arbeidsflyter støttes bare i dette formatet.
• Omtilordning av navn for programtilleggstype er aktivert som standard.

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

Mer informasjon: Referanse for løsnings-YAML-kildekontrollformat

Formatere regler for automatisk gjenkjenning

Pakking av en mappe i YAML-format

Følgende kommando pakker en YAML-formatmappe.

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

Pakking fra en mappe med flere løsninger

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

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

Bruk kommandoargumentet /map

Følgende diskusjon beskriver bruken av /map-argumentet til SolutionPackager-verktøyet.

Filer som er bygd i et automatisert byggesystem, for eksempel .xap Silverlight-filer og plugin-moduler, er vanligvis ikke sjekket inn i kildekontrollen. Det kan hende at du allerede har nettressurser i kildekontrollen på steder som ikke er direkte kompatible med SolutionPackager-verktøyet. Ved å inkludere /map-parameteren kan du dirigere SolutionPackager-verktøyet til å lese og pakke slike filer fra alternative plasseringer i stedet for fra innsiden av Extract-mappen. Parameteren /map må angi navnet og banen til en XML-fil som inneholder tilordningsdirektiver. Disse direktivene ber SolutionPackager om å samsvare filene etter navn og bane, og angir den alternative plasseringen for å finne den samsvarende filen. Følgende informasjon gjelder for alle direktiver likt.

• Du kan liste opp flere direktiver, inkludert de direktivene som samsvarer med identiske filer. Direktiver som står oppført tidlig i filen, prioriteres foran direktiver som er oppført senere.

• Hvis en fil samsvarer med et direktiv, må den finnes på minst ett alternativt sted. Hvis det ikke blir funnet noen tilsvarende alternativer, vil SolutionPackager sende en feilmelding.

• Mappe- og filbaner kan være absolutte eller relative. Relative baner evalueres alltid fra mappen som er angitt av parameteren /folder.

• Angi miljøvariabler ved hjelp av en %variable% syntaks.

• Bruk et mappe-jokertegn ** til å bety «i en hvilken som helst undermappe». Du kan bare bruke den som den siste delen av en bane, for eksempel: c:\folderA\**.

• Bruk filnavn-jokertegn bare i formene *.ext eller *.*. Ingen andre mønstre støttes.

  Den følgende delen beskriver de tre typene direktivtilordninger, sammen med et eksempel som viser deg hvordan du bruker dem.

Mappekartlegging

Avsnittet nedenfor inneholder detaljert informasjon om mappetilordning.

XML-format

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

beskrivelse

Filbaner som samsvarer med «folderA», byttes til «folderB».

• Hierarkiet for undermapper under hver mappe må samsvare nøyaktig.

• Støtter ikke mappe-jokertegn.

• Du kan ikke angi filnavn.

  Eksempler

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

Fil-til-fil-mapping

Nedenfor finner du mer detaljert informasjon om fil til fil-tilordning.

XML-format

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

beskrivelse

Alle filer som samsvarer med parameteren map, leses med navnet og banen som er angitt i parameteren to.

For map-parameteren:

• Angi et filnavn. Banen er valgfri. Hvis du ikke angir en bane, kan tilordningen samsvare med filer fra en hvilken som helst mappe.

• Støtter ikke jokertegn for filnavn.

• Støtter mappe-jokertegnet.

  For to-parameteren:

• Angi et filnavn og en sti.

• Filnavnet kan avvike fra navnet i parameteren map.

• Støtter ikke jokertegn for filnavn.

• Støtter mappe-jokertegnet.

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-pakkeeksempelet blir ikke cr886_PluginPackageTest.nupkg overskrevet hvis filen allerede finnes på den angitte plasseringen.

Fil-til-sti-tilordning

Følgende avsnitt inneholder detaljert informasjon om tilordning fra fil til bane.

XML-format

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

beskrivelse

Parameteren map angir filen som skal samsvare, og parameteren to angir stien som skal leses fra.

For map-parameteren:

• Angi et filnavn. Banen er valgfri. Hvis du ikke angir en bane, kan tilordningen samsvare med filer fra en hvilken som helst mappe.

• Støtter filnavn-jokertegn.

• Støtter jokertegn for mapper.

For to-parameteren:

• Angi en sti.

• Støtter mappe-jokertegnet.

• Ikke angi 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å kartlegging

Følgende XML-kodeeksempel viser en fullstendig tilordningsfil som gjør det mulig for SolutionPackager-verktøyet å lese en hvilken som helst webressurs og de to standardgenererte samlingene fra et Developer Toolkit-prosjekt kalt 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>  

Administrerte og uadministrerte løsninger

Du kan eksportere en Dataverse-komprimert løsningsfil (.zip) som enten en administrert eller uadministrert løsning.

Administrert løsning
En fullført løsning klar til å importeres til en organisasjon. Når du har importert, kan du ikke legge til eller fjerne komponenter, selv om du eventuelt kan tillate ytterligere tilpassing. Bruk denne typen når utviklingen av løsningen er fullført.

Uadministrert løsning
En åpen løsning uten begrensninger på hva du kan legge til, fjerne eller endre. Bruk denne typen under utvikling av en løsning.

Formatet til en komprimert løsningspakkefil varierer basert på typen, enten administrert eller uadministrert. SolutionPackager kan behandle komprimerte løsningsfiler av begge typer. Verktøyet kan imidlertid ikke konvertere én type til en annen. Den eneste måten å konvertere løsningsfiler til en annen type, for eksempel fra uadministrert til administrert, er ved å importere den uadministrerte løsningen .zip-filen til en Dataverse-server og deretter eksportere løsningen som en administrert løsning.

SolutionPackager kan behandle uadministrerte og administrerte løsninger .zip filer som et kombinert sett ved hjelp av parameteren /PackageType:Both . Hvis du vil utføre denne operasjonen, må du eksportere løsningen to ganger, én gang for hver type. Gi .zip-filene navn på følgende måte:

Verktøyet antar at den administrerte ZIP-filen er i samme mappe som den uadministrerte filen. Den pakker ut begge filene i én enkelt mappe og bevarer forskjellene der administrerte og uadministrerte komponenter finnes.

Når du har eksportert en løsning både som uadministrert og administrert, kan du pakke begge typene eller hver type individuelt fra den ene mappen. Bruk /PackageType-parameteren til å angi hvilken type som skal opprettes. Når du angir begge filene, produserer verktøyet to .zip filer ved hjelp av den foregående navnekonvensjonen. Hvis du ikke inkluderer parameteren /PackageType når du pakker fra en mappe med både administrert og uadministrert innhold, er standarden å produsere én enkelt uadministrert .zip-fil.

Feilsøking

Melding som vises når du bruker Visual Studio til å redigere ressursfiler

Hvis du bruker Visual Studio til å redigere ressursfiler som er opprettet av løsningspakkeren, kan det hende du ser en melding når du pakker på nytt på samme måte som denne: "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 meldingen vises fordi Visual Studio erstatter metadatakodene for ressursfilen med datakoder.

Løsning

1. Åpne ressursfilen i tekstredigeringsprogrammet du foretrekker, og finn og oppdater følgende koder:

   <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. Endre nodenavnet fra <data> til <metadata>.

   For eksempel denne strengen:

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

   Endringer i:

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

   Denne endringen gjør det mulig for løsningspakkeren å lese og importere ressursfilen. Dette problemet oppstår bare når du bruker ressursredigereren i Visual Studio.

Feil: «Finner ikke nødvendig fil ...\Other\Customizations.xml» med en YAML-mappe

Denne feilen vises når du kjører SolutionPackager (eller pac solution pack) mot en mappe som inneholder YAML-filer, for eksempel solution.yml, men du plasserer disse filene ved roten av mappen i stedet for i den nødvendige solutions/<SolutionUniqueName>/ undermappen.

Forårsake: Verktøyet oppdager YAML-kildekontrollformatet ved å se etter en solutions/ undermappe som inneholder *solution.yml filer. Når denne katalogen er fraværende, faller verktøyet stille tilbake til XML-formatet (eldre) og forventer Other\Customizations.xml. Feilmeldingen refererer til en XML-fil og nevner ikke YAML, noe som kan være forvirrende.

Fikse: Omorganiser mappen slik at YAML-manifestfilene er under riktige baner:

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

Hvis du hentet mappen fra en commit fra Git-integrering eller pac solution clone, er mappestrukturen allerede riktig. En mappe som bare inneholder YAML-filer på øverste nivå uten underkatalogen solutions/ , representerer en ufullstendig utpakking og kan ikke pakkes direkte.

Advarsel! Komponent deklarert i rootcomponents.yml har ingen kildefiler

Denne advarselen vises når en komponent, for eksempel en lerretsapp, er oppført i rootcomponents.yml , men det finnes ingen tilsvarende kildefiler i den forventede komponentmappen (for eksempel canvasapps/<schema-name>/).

Effekt: Verktøyet lykkes fortsatt (avslutt kode 0) og produserer en gyldig .zip fil, men den deklarerte komponenten utelates fra den pakkede løsningen.

Forårsake: Mappen ble produsert av en delvis uttrekking, eller komponentens kildefiler ble ikke inkludert i repositoriet. Bare løsningsmanifestfilene ble for eksempel utført, og ikke selve lerretsappen.

Fikse: Sørg for at alle komponenter deklarert i rootcomponents.yml har tilsvarende kildefiler i mappen. Filen må finnes under .msappfor lerretsappercanvasapps/<schema-name>/. Hvis noen filer mangler, eksporterer du den fullstendige løsningen fra Datavers og pakker den ut på nytt, eller bruker pac solution clone den til å hente en fullstendig utpakking.

Se også

• Bruke kildekontroll med løsningsfiler
• Løsningskonsepter