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.

Finne 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.

Kommandolinjeargumenter for SolutionPackager

SolutionPackager er et kommandolinjeverktøy som kan startes med parameterne som identifiseres 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. Løsningsmetadata lagres i Other\Solution.xml og Other\Customizations.xml, og alle komponentfiler pakkes ut i et flatt mappehierarki sammen med disse filene. Dette formatet er standardformatet når du trekker ut 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 utfører løsninger ved hjelp av opprinnelig Git-integrasjon i Power Apps.

Fordeler med XML-format

• Produserer renere, mer lesbare forskjeller per komponent i kildekontrollen
• Støtter flere løsninger i én enkelt repositoriummappe
• Lerretsappfiler .msapp og moderne flyter støttes bare i dette formatet
• Tilordning av navn på programtilleggstype er aktivert som standardinnstilling

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

Bruke kommandoargumentet /map

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

Filer som er bygd inn i et automatisk Build-system, for eksempel .xap Silverlight-filer og programtilleggssamlinger, blir vanligvis ikke sjekket inn i kildekontrollen. Det kan hende at nettressurser allerede finnes i kildekontrollen på steder som ikke er direkte kompatible med SolutionPackager-verktøyet. Ved å inkludere /map-parameteren kan du angitt at SolutionPackager-verktøyet skal lese og pakke slike filer fra andre steder, og ikke fra i utpakkingsmappen slik det vanligvis vil bli gjort. 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.

• Det kan hende at flere direktiver vises, inkludert 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 i minst ett alternativt sted. Hvis det ikke blir funnet noen tilsvarende alternativer, vil SolutionPackager sende en feilmelding.

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

• Miljøvariabler kan spesifiseres ved å bruke en %variabel%-syntaks.

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

• Filnavn-jokertegn kan bare brukes i skjemaene *.ext eller *.*. Ingen andre mønstre støttes.

  De tre typene direktiver er beskrevet her, sammen med et eksempel som viser hvordan du bruker dem.

Mappetilordning

Nedenfor finner du detaljert informasjon om mappetilordning.

Xml-format

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

Beskrivelse

Filbaner som samsvarer med «folderA» byttes til «mappeB».

• Hierarkiet i undermapper under hver 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-tilordning

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 map-parameteren, leses fra navnet og banen som er angitt i to-parameteren.

For map-parameteren:

• Et filnavn må angis. Banen er valgfri. Hvis det ikke er angitt en bane, kan det hende at filer fra alle mapper samsvares.

• Støtter ikke jokertegn for filnavn.

• Mappe-jokertegnet støttes.

  For to-parameteren:

• Et filnavn og bane må angis.

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

• Støtter ikke jokertegn for filnavn.

• Mappe-jokertegnet støttes.

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

Fil til bane-tilordning

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

Xml-format

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

Beskrivelse

Alle filer som samsvarer med map-parameteren, leses fra banen som er angitt i to-parameteren.

For map-parameteren:

• Et filnavn må angis. Banen er valgfri. Hvis det ikke er angitt en bane, kan det hende at filer fra alle mapper samsvares.

• Støtter jokertegn for filnavn.

• Mappe-jokertegnet støttes.

For to-parameteren:

• Det må være angitt en bane.

• Mappe-jokertegnet støttes.

• Et filnavn må ikke angis.

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

Tilordningseksempel

Følgende eksempel på XML-kode viser en fullstendig tildelingsfil som gjør det mulig for SolutionPackager-verktøyet å lese alle nettressurser og de to standardsamlingene som er generert av et utviklerverktøyprosjekt 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>  

Administrerte og uadministrerte løsninger

En komprimert Dataverse-løsning (zip-fil) kan eksporteres i én av to typer som vises her.

Administrert løsning
En fullstendig løsning som er klar til å importeres til en organisasjon. Når de er importert, kan ikke komponenter legges til eller fjernes, selv om de eventuelt kan tillate ytterligere tilpassing. Dette anbefales når utviklingen av løsningen er fullført.

Uadministrert løsning
En åpen løsning uten begrensninger for hva som kan legges til, fjernes eller endres. Dette anbefales under utvikling av en løsning.

Formatet til en komprimert løsningsfil vil være forskjellig avhengig av 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 å importere den zip-filen med den uadministrerte løsningen til en Dataverse-server og deretter eksportere løsningen som et administrert løsning.

SolutionPackager kan behandle uadministrerte og administrerte løsnings .zip-filer som et kombinert sett via parameteren /PackageType:Both For å kunne utføre denne operasjonen er det nødvendig å eksportere løsningen to ganger som hver type, og navngi zip-filene som følger.

Verktøyet forutsetter at den administrerte zip-filen er i samme mappe brukes som den uadministrerte filen, og pakker ut begge filene i én enkelt mappe som beholder forskjellene der administrerte og uadministrerte komponenter finnes.

Når en løsning er pakket ut både som uadministrert og administrert, er det mulig å pakke begge fra denne enkeltmappen, eller hver type enkeltvis, ved hjelp av /PackageType-parameteren for å angi hvilken type som skal opprettes. Når du angir begge filene, lages det to .zip-filer ved hjelp av navnekonvensjonen som ovenfor. Hvis /PackageType-parameteren mangler når du pakker fra en dobbelt administrert og uadministrert mappe, er standardvalget å 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 ressurs-fsiles opprettet av løsningspakkeren, kan det hende du får en melding når du pakker på nytt på samme måte som 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." Dette skjer fordi Visual Studio erstatter metadatakodene for ressursfilen med datakoder.

Løsning

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

   <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 navnet på noden 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>  
   
   

   Dette gjør at løsningspakkeprogrammet kan lese og importere ressursfilen. Dette problemet er bare observert når du bruker Visual Studio Ressursredigering.

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 disse filene plasseres 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. Den resulterende feilmeldingen refererer til en XML-fil og nevner ikke YAML, noe som er misvisende.

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 Git-integrering eller pac solution clone, bør mappestrukturen allerede være 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å

• Bruk kildekontroll med løsningsfiler
• sLøsningskonsepter