เครื่องมือ SolutionPackager

SolutionPackager เป็นเครื่องมือที่สามารถย่อยสลายไฟล์โซลูชันที่บีบอัด Microsoft Dataverse เป็นไฟล์ XML และไฟล์อื่นๆ หลายไฟล์แบบย้อนกลับได้ จากนั้นคุณสามารถจัดการไฟล์เหล่านี้ได้อย่างง่ายดายโดยใช้ระบบควบคุมแหล่งที่มา ส่วนต่อไปนี้แสดงวิธีการเรียกใช้เครื่องมือและวิธีใช้เครื่องมือกับโซลูชันที่มีการจัดการและไม่มีการจัดการ

จะหาเครื่องมือ SolutionPackager ได้ที่ไหน

เครื่องมือ SolutionPackager ถูกแจกจ่ายเป็นส่วนหนึ่งของแพคเกจ Microsoft.CrmSdk.CoreTools NuGet ในการติดตั้งโปรแกรม ให้ทำตามขั้นตอนเหล่านี้

1. ดาวน์โหลดแพคเกจ NuGet
2. เปลี่ยนชื่อนามสกุลไฟล์แพคเกจจาก .nupkg เป็น .zip
3. แตกเนื้อหาของไฟล์ zip ที่บีบอัด

ค้นหาไฟล์ปฏิบัติการ SolutionPackager.exe ในโฟลเดอร์ <extracted-folder-name>/contents/bin/coretools เรียกใช้โปรแกรมจากโฟลเดอร์ coretools หรือเพิ่มโฟลเดอร์นั้นในพาธของคุณ

อาร์กิวเมนต์บรรทัดคำสั่งของ SolutionPackager

SolutionPackager เป็นเครื่องมือบรรทัดคําสั่ง คุณสามารถเรียกใช้ได้โดยใช้พารามิเตอร์ที่อธิบายไว้ในตารางต่อไปนี้

รูปแบบไฟล์ตัวควบคุมแหล่งข้อมูล

SolutionPackager สนับสนุนเค้าโครงโฟลเดอร์สองรายการเมื่อแยกและบรรจุโซลูชัน

รูปแบบ XML (แบบดั้งเดิม)

รูปแบบเดิม เครื่องมือจะจัดเก็บเมตาดาต้าของโซลูชันใน Other\Solution.xml และOther\Customizations.xml เครื่องมือจะแยกไฟล์คอมโพเนนต์ทั้งหมดลงในโครงสร้างโฟลเดอร์แบบชั้นเดียวควบคู่ไปกับไฟล์เหล่านั้น รูปแบบนี้เป็นรูปแบบเริ่มต้นเมื่อคุณแยก .zip ไฟล์โดยไม่มีการกําหนดค่าเพิ่มเติม

รูปแบบตัวควบคุมแหล่งข้อมูล YAML

รูปแบบนี้ถูกแนะนำพร้อมกับการรวม Dataverse Git โดยจัดเก็บเมตาดาต้าของโซลูชันเป็นไฟล์ YAML ที่กระจายอยู่ในลำดับชั้นของโฟลเดอร์ที่มีโครงสร้าง ซึ่งเป็นรูปแบบที่เขียนขึ้นเมื่อคุณคอมมิตโซลูชันโดยใช้การรวม Git ดั้งเดิมใน Power Apps

ข้อดีเหนือรูปแบบ XML

• สร้าง diffs ต่อคอมโพเนนต์ที่สะอาดกว่า และอ่านได้ง่ายขึ้นในซอร์สคอนโทรล
• รองรับโซลูชันหลายรายการในโฟลเดอร์รีโพซิทอรีเดียว
• ไฟล์ Canvas app .msapp และโฟลว์สมัยใหม่ได้รับการสนับสนุนในรูปแบบนี้เท่านั้น
• การแมปชื่อชนิดปลั๊กอินจะเปิดใช้งานตามค่าเริ่มต้น

โครงสร้างโฟลเดอร์ที่จําเป็น

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

ข้อมูลเพิ่มเติม: การอ้างอิงรูปแบบการควบคุมแหล่งข้อมูล YAML ของโซลูชัน

จัดรูปแบบกฎการตรวจหาอัตโนมัติ

การบรรจุโฟลเดอร์รูปแบบ YAML

คําสั่งต่อไปนี้จะแพ็คโฟลเดอร์รูปแบบ YAML

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

การบรรจุจากโฟลเดอร์แบบหลายโซลูชัน

คําสั่งต่อไปนี้แพ็คโซลูชันที่ระบุในโฟลเดอร์หลายโซลูชัน

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

ใช้อาร์กิวเมนต์คำสั่ง /map

การอภิปรายต่อไปนี้มีรายละเอียดการใช้อาร์กิวเมนต์ /map กับเครื่องมือ SolutionPackager

ไฟล์ที่สร้างขึ้นในระบบบิลท์อัตโนมัติ เช่น .xap ไฟล์ Silverlight และแอสเซมบลีปลั๊กอิน มักไม่ถูกเช็คอินเข้าไปในระบบควบคุมซอร์สโค้ด คุณอาจมีทรัพยากรบนเว็บในระบบควบคุมเวอร์ชันอยู่แล้วในตำแหน่งที่ตั้งที่เข้ากันไม่ได้โดยตรงกับเครื่องมือ SolutionPackager ด้วยการรวมพารามิเตอร์ /map คุณสามารถสั่งให้เครื่องมือ SolutionPackager อ่านและแพคเกจไฟล์ดังกล่าวจากตำแหน่งทางเลือกแทนจากภายในโฟลเดอร์แยก พารามิเตอร์ /map ต้องระบุชื่อและพาธไปยังไฟล์ XML ที่มีคำสั่งการแมป คำสั่งเหล่านั้นจะสั่งให้ SolutionPackager จับคู่ไฟล์ตามชื่อและพาธ และระบุตำแหน่งอื่นเพื่อค้นหาไฟล์ที่ตรงกัน ข้อมูลต่อไปนี้ใช้กับคําสั่งทั้งหมดอย่างเท่าเทียมกัน

• คุณสามารถระบุไดเรกทีฟหลายรายการ รวมถึงไดเรกทีฟที่ตรงกับไฟล์ที่เหมือนกันได้ คำสั่งที่ระบุไว้ในไฟล์จะมีความสำคัญมากกว่าคำสั่งที่ระบุไว้ในภายหลัง

• ถ้าไฟล์ตรงกับคําสั่งใด ๆ จะต้องพบไฟล์นั้นในตําแหน่งอื่นอย่างน้อยหนึ่งตําแหน่ง หากไม่พบทางเลือกที่ตรงกัน SolutionPackager จะส่งข้อผิดพลาด

• เส้นทางโฟลเดอร์และไฟล์อาจเป็นแบบสัมบูรณ์หรือแบบสัมพัทธ์ได้ เส้นทางสัมพัทธ์จะได้รับการประเมินจากโฟลเดอร์ที่ระบุโดยพารามิเตอร์ /folder เสมอ

• ระบุตัวแปรสภาพแวดล้อมโดยใช้ไวยากรณ์ %variable%

• ใช้สัญลักษณ์ตัวแทนโฟลเดอร์ ** เพื่อหมายถึง "ในโฟลเดอร์ย่อยใด ๆ" คุณสามารถใช้เป็นส่วนสุดท้ายของเส้นทางได้เท่านั้น ตัวอย่างเช่น: c:\folderA\**

• ใช้สัญลักษณ์ตัวแทนชื่อไฟล์เฉพาะในรูปแบบ *.ext หรือ *.* ไม่รองรับรูปแบบอื่น

  ส่วนต่อไปนี้อธิบายการแมปคําสั่งสามประเภทพร้อมกับตัวอย่างที่แสดงวิธีการใช้งาน

การแมปโฟลเดอร์

ส่วนต่อไปนี้แสดงข้อมูลโดยละเอียดเกี่ยวกับการแมปโฟลเดอร์

รูปแบบ XML

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

คำอธิบาย:

เส้นทางของไฟล์ที่ตรงกับ "folderA" เปลี่ยนเป็น "folderB"

• ลําดับชั้นของโฟลเดอร์ย่อยภายใต้แต่ละโฟลเดอร์ต้องตรงกันทั้งหมด

• ไม่รองรับอักขระตัวแทนในโฟลเดอร์

• คุณไม่สามารถระบุชื่อแฟ้ม

  ตัวอย่าง

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

การแมประหว่างไฟล์

ข้อมูลต่อไปนี้ให้รายละเอียดเพิ่มเติมเกี่ยวกับการแมปไฟล์กับไฟล์

รูปแบบ XML

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

คำอธิบาย:

ไฟล์ใด ๆ ที่ตรงกับ map พารามิเตอร์จะอ่านจากชื่อและเส้นทางที่ระบุในพารามิเตอร์ to

สำหรับพารามิเตอร์ map:

• ระบุชื่อแฟ้ม เส้นทางเป็นทางเลือก ถ้าคุณไม่ได้ระบุเส้นทาง การแมปสามารถจับคู่ไฟล์จากโฟลเดอร์ใด ๆ

• ไม่รองรับสัญลักษณ์แทนชื่อไฟล์

• สนับสนุนสัญลักษณ์ตัวแทนโฟลเดอร์

  สำหรับพารามิเตอร์ to:

• ระบุชื่อไฟล์และเส้นทาง

• ชื่อไฟล์อาจแตกต่างจากชื่อใน map พารามิเตอร์

• ไม่รองรับสัญลักษณ์แทนชื่อไฟล์

• สนับสนุนสัญลักษณ์ตัวแทนโฟลเดอร์

ตัวอย่าง

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

ในตัวอย่างแพคเกจ NuGet ก่อนหน้านี้ cr886_PluginPackageTest.nupkg จะไม่ถูกเขียนทับถ้ามีไฟล์อยู่แล้วในตำแหน่งที่ระบุ

การแมปไปยังเส้นทางไฟล์

ส่วนต่อไปนี้แสดงข้อมูลโดยละเอียดเกี่ยวกับการแมปไฟล์ไปยังเส้นทาง

รูปแบบ XML

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

คำอธิบาย:

พารามิเตอร์ map ระบุไฟล์ที่จะจับคู่ และ to พารามิเตอร์ ระบุเส้นทางที่จะอ่าน

สำหรับพารามิเตอร์ map:

• ระบุชื่อแฟ้ม เส้นทางเป็นทางเลือก ถ้าคุณไม่ได้ระบุเส้นทาง การแมปสามารถจับคู่ไฟล์จากโฟลเดอร์ใด ๆ

• รองรับสัญลักษณ์ตัวแทนชื่อไฟล์

• สนับสนุนสัญลักษณ์ตัวแทนโฟลเดอร์

สำหรับพารามิเตอร์ to:

• ระบุพาธ

• รองรับไวลด์การ์ดของโฟลเดอร์

• อย่าระบุชื่อไฟล์

  ตัวอย่าง

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

ตัวอย่างการแมป

ตัวอย่างโค้ด XML ต่อไปนี้แสดงไฟล์การแมปที่สมบูรณ์ที่ช่วยให้เครื่องมือ SolutionPackager สามารถอ่านทรัพยากรบนเว็บใดๆ และแอสเซมบลีที่สร้างขึ้นเริ่มต้นสองรายการจากโครงการ Developer Toolkit ที่ชื่อ 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>  

โซลูชันที่มีการจัดการและที่ไม่มีการจัดการ

คุณสามารถส่งออกไฟล์โซลูชันที่บีบอัด Dataverse (.zip) เป็นโซลูชันที่มีการจัดการหรือไม่ถูกจัดการ

โซลูชันที่มีการจัดการ
โซลูชันที่เสร็จสมบูรณ์พร้อมที่จะนําเข้าไปยังองค์กร เมื่อนําเข้าแล้ว คุณไม่สามารถเพิ่มหรือลบคอมโพเนนต์ออกได้ แม้ว่าคุณสามารถเลือกที่จะอนุญาตให้มีการปรับแต่งเพิ่มเติมได้ ใช้ชนิดนี้เมื่อการพัฒนาโซลูชันเสร็จสมบูรณ์

โซลูชันที่ไม่ได้รับการจัดการ
โซลูชันแบบเปิดที่ไม่มีข้อจํากัดเกี่ยวกับสิ่งที่คุณสามารถเพิ่ม ลบ หรือปรับเปลี่ยนได้ ใช้ชนิดนี้ในระหว่างการพัฒนาของโซลูชัน

รูปแบบของไฟล์โซลูชันที่บีบอัดจะแตกต่างกันขึ้นอยู่กับชนิดของโซลูชันว่าเป็นแบบมีการจัดการหรือไม่มีการจัดการ SolutionPackager สามารถประมวลผลไฟล์โซลูชันที่บีบอัดได้ทั้งสองประเภท อย่างไรก็ตาม เครื่องมือไม่สามารถแปลงชนิดหนึ่งเป็นอีกชนิดหนึ่งได้ วิธีเดียวที่จะแปลงไฟล์โซลูชันเป็นชนิดอื่น เช่น จากแบบไม่มีการจัดการไปเป็นแบบมีการจัดการ คือการนำเข้าไฟล์ .zip ของโซลูชันแบบไม่มีการจัดการไปยังเซิร์ฟเวอร์ Dataverse แล้วส่งออกโซลูชันเป็นโซลูชันแบบมีการจัดการ

SolutionPackager สามารถประมวลผลไฟล์ .zip ของโซลูชันแบบ unmanaged และ managed เป็นชุดรวมได้โดยใช้พารามิเตอร์ /PackageType:Both เมื่อต้องดําเนินการนี้ คุณจําเป็นต้องส่งออกโซลูชันของคุณสองครั้ง อย่างละ 1 ครั้งสำหรับแต่ละประเภท ตั้งชื่อไฟล์ .zip ดังนี้:

เครื่องมือจะถือว่าไฟล์ zip ที่มีการจัดการอยู่ในโฟลเดอร์เดียวกันกับไฟล์ที่ไม่มีการจัดการ ซึ่งจะแยกไฟล์ทั้งสองลงในโฟลเดอร์เดียว และเก็บรักษาความแตกต่างไว้ในส่วนที่มีคอมโพเนนต์แบบมีการจัดการและแบบไม่มีการจัดการ

หลังจากที่คุณแตกไฟล์โซลูชันเป็นทั้งแบบไม่มีการจัดการและแบบมีการจัดการแล้ว คุณสามารถบรรจุได้ทั้งสองชนิดหรือแต่ละชนิดแยกกันจากโฟลเดอร์เดียวนั้น /PackageTypeใช้พารามิเตอร์ เพื่อระบุชนิดที่จะสร้าง เมื่อคุณระบุทั้งสองไฟล์ เครื่องมือจะสร้างไฟล์ .zip สองไฟล์โดยใช้แบบแผนการตั้งชื่อก่อนหน้านี้ หากคุณไม่รวมพารามิเตอร์ /PackageType เมื่อบรรจุจากโฟลเดอร์แบบคู่ที่เป็นแบบมีการจัดการและไม่มีการจัดการ ค่าเริ่มต้นคือการสร้างไฟล์ .zip แบบไม่มีการจัดการเพียงไฟล์เดียว

การแก้ไขปัญหา

ข้อความที่แสดงขึ้นเมื่อใช้ Visual Studio เพื่อแก้ไขไฟล์ทรัพยากร

ถ้าคุณใช้ Visual Studio เพื่อแก้ไขไฟล์ทรัพยากรที่สร้างขึ้นโดยตัวแพคเกจโซลูชัน คุณอาจเห็นข้อความเมื่อคุณบรรจุใหม่คล้ายกับสิ่งนี้: "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." ข้อความนี้ปรากฏขึ้นเนื่องจาก Visual Studio แทนที่แท็กเมตาดาต้าของไฟล์ทรัพยากรด้วยแท็กข้อมูล

วิธีการแก้ไข

1. เปิดไฟล์ทรัพยากรในตัวแก้ไขข้อความโปรดของคุณ จากนั้นค้นหาและอัปเดตแท็กต่อไปนี้:

   <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. เปลี่ยนชื่อโหนดจาก <data> เป็น <metadata>

   ตัวอย่าง สตริงนี้:

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

   เปลี่ยนเป็น:

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

   การเปลี่ยนแปลงนี้ช่วยให้ตัวแพคเกจโซลูชันสามารถอ่าน และนําเข้าไฟล์ทรัพยากร ปัญหานี้เกิดขึ้นเฉพาะเมื่อคุณใช้ตัวแก้ไขทรัพยากร Visual Studio

ข้อผิดพลาด: "ไม่พบไฟล์ที่จําเป็น ...\Other\Customizations.xml" ด้วยโฟลเดอร์ YAML

ข้อผิดพลาดนี้ปรากฏขึ้นเมื่อคุณเรียกใช้ SolutionPackager (หรือ pac solution pack) กับโฟลเดอร์ที่ประกอบด้วยไฟล์ YAML เช่น solution.yml แต่คุณวางไฟล์เหล่านั้นไว้ที่รากของโฟลเดอร์แทนที่จะอยู่ภายในโฟลเดอร์ย่อย solutions/<SolutionUniqueName>/ ที่จำเป็น

สาเหตุ: เครื่องมือนี้ตรวจหารูปแบบตัวควบคุมแหล่งข้อมูล YAML โดยการค้นหา solutions/ โฟลเดอร์ย่อยที่มี *solution.yml ไฟล์ เมื่อไม่มีไดเรกทอรี เครื่องมือจะถอยกลับไปยังรูปแบบ XML (แบบดั้งเดิม) และ ต้องการOther\Customizations.xml ข้อความแสดงข้อผิดพลาดอ้างอิงถึงไฟล์ XML และไม่กล่าวถึง YAML ซึ่งอาจสร้างความสับสนได้

แก้ไข: จัดระเบียบโฟลเดอร์ใหม่เพื่อให้ไฟล์รายชื่อแฟ้ม YAML อยู่ในเส้นทางที่ถูกต้อง:

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

ถ้าคุณได้รับโฟลเดอร์จากคอมมิตจากการผสานรวม Git หรือ pac solution clone โครงสร้างโฟลเดอร์ก็ถูกต้องแล้ว โฟลเดอร์ที่มีเฉพาะไฟล์ YAML ระดับบนสุดที่ไม่มี solutions/ ไดเรกทอรีย่อยแสดงถึงการแยกที่ไม่สมบูรณ์และไม่สามารถบรรจุได้โดยตรง

คําเตือน: คอมโพเนนต์ที่ประกาศใน rootcomponents.yml ไม่มีแฟ้มต้นฉบับ

คําเตือนนี้ปรากฏขึ้นเมื่อคอมโพเนนต์ เช่นแอปพื้นที่ทํางานแสดงอยู่ใน rootcomponents.yml แต่ไม่มีไฟล์แหล่งข้อมูลที่สอดคล้องกันอยู่ในโฟลเดอร์คอมโพเนนต์ที่คาดไว้ (ตัวอย่างเช่น canvasapps/<schema-name>/)

ผล: เครื่องมือนี้ยังคงประสบความสําเร็จ (ออกจากรหัส 0) และสร้างไฟล์ที่ถูกต้อง .zip แต่คอมโพเนนต์ที่ประกาศถูกเว้นไว้จากโซลูชันแพคเกจ

สาเหตุ: โฟลเดอร์ถูกสร้างขึ้นโดยการแยกบางส่วน หรือไฟล์ต้นฉบับของคอมโพเนนต์ไม่ได้รวมอยู่ในที่เก็บ ตัวอย่างเช่น เฉพาะไฟล์รายการโซลูชันเท่านั้นที่ได้รับการบันทึกและไม่ใช่ตัวแอปพื้นที่ทํางานเอง

แก้ไข: ตรวจสอบให้แน่ใจว่าคอมโพเนนต์ทั้งหมดที่ประกาศใน rootcomponents.yml มีไฟล์แหล่งข้อมูลที่สอดคล้องกันอยู่ในโฟลเดอร์ สำหรับแอปประเภท Canvas ไฟล์.msappต้องมีอยู่ภายใต้canvasapps/<schema-name>/ หากไฟล์ใด ๆ หายไป ให้ส่งออกโซลูชันแบบเต็มจาก Dataverse และยกเลิกการบรรจุอีกครั้ง หรือใช้ pac solution clone เพื่อรับการแยกที่สมบูรณ์

ดูเพิ่มเติมที่

• ใช้การควบคุมแหล่งที่มากับไฟล์โซลูชัน
• แนวคิดของโซลูชัน