แชร์ผ่าน

สร้างแพคเกจสำหรับเครื่องมือ Package Deployer

  • บทความ

Package Deployer ช่วยให้ผู้ดูแลสามารถปรับใช้แพคเกจบนอินสแตนซ์ Microsoft Dataverse แพคเกจe Package Deployer สามารถประกอบด้วยรายการต่อไปนี้หนึ่งรายการหรือทั้งหมด:

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

หมายเหตุ

มีแพคเกจอีกประเภทที่เรียกว่า แพคเกจปลั๊กอิน แพคเกจประเภทนั้นมีไว้สำหรับส่วนประกอบที่อิงกับปลั๊กอินและไม่มีความสัมพันธ์กับแพคเกจ Package Deployer

ข้อกำหนดเบื้องต้น

  • ตรวจสอบให้แน่ใจว่าคุณมีโซลูชันและไฟล์อื่นๆ ทั้งหมดที่คุณต้องการรวมไว้ในแพคเกจ
  • Visual Studio 2019 หรือที่ใหม่กว่า หรือ Visual Studio Code

ภาพรวมของกระบวนการ

หากต้องการสร้างแพคเกจ Package Deployer ให้ดำเนินการห้าขั้นตอนต่อไปนี้

  • สร้างโครงการ Visual Studio หรือ MSBuild
  • เพิ่มโซลูชันและไฟล์อื่นๆ ในโครงการ
  • อัปเดตไฟล์ HTML ที่ให้มา (ไม่บังคับ)
  • ระบุค่าการกำหนดค่าสำหรับแพคเกจ
  • กำหนดโค้ดที่กำหนดเองสำหรับแพคเกจ
  • สร้างและปรับใช้งานแพคเกจ

ขั้นตอนเหล่านี้จะมีคำอธิบายโดยละเอียดในบทความนี้

สร้างโครงการแพคเกจ

ขั้นตอนแรกคือการสร้างโครงการ Visual Studio หรือ MSBuild สำหรับแพคเกจ ในการทำเช่นนั้น คุณต้องมีหนึ่งในสองส่วนขยายเครื่องมือที่พร้อมใช้งานติดตั้งบนคอมพิวเตอร์สำหรับการพัฒนาของคุณ หากใช้ Visual Studio Code ให้ติดตั้ง Microsoft Power Platform CLI มิฉะนั้น หากใช้ Visual Studio 2019 หรือใหม่กว่า ให้ติดตั้ง Power Platform Tools สำหรับ Visual Studio

เลือกแท็บที่เหมาะสมด้านล่างเพื่อค้นหาวิธีสร้างโครงการโดยใช้ส่วนขยายเครื่องมือที่ต้องการ เครื่องมือทั้งสองจะส่งออกโครงการในรูปแบบที่คล้ายคลึงกัน

เรียกใช้คำสั่ง pac package init เพื่อสร้างแพคเกจเริ่มต้น ข้อมูลเพิ่มเติม: pac package

pac package init help
pac package init --outputDirectory DeploymentPackage

เอาต์พุต CLI ที่เป็นผลลัพธ์ประกอบด้วยโฟลเดอร์และไฟล์ที่แสดงด้านล่าง ชื่อโฟลเดอร์ "DeploymentPackage" มีการใช้ที่นี่เป็นตัวอย่าง

C:.
└───DeploymentPackage
    │   DeploymentPackage.csproj
    │   PackageImportExtension.cs
    │
    └───PkgAssets
            ImportConfig.xml
            manifest.ppkg.json

ในโครงการที่สร้างขึ้น ให้ค้นหาไฟล์การกำหนดค่า ImportConfig.xml ในโฟลเดอร์ PkgAssets และไฟล์ PackageImportExtension.cs คุณจะแก้ไขไฟล์เหล่านี้ตามที่อธิบายไว้ในบทความนี้

เพิ่มไฟล์แพคเกจ

หลังจากที่คุณสร้างโครงการแพคเกจ คุณสามารถเริ่มเพิ่มโซลูชันและไฟล์อื่นๆ ในโครงการนั้นได้

เมื่อใช้ CLI คุณสามารถเพิ่มแพคเกจภายนอก โซลูชัน และข้อมูลอ้างอิงในโครงการแพคเกจของคุณโดยใช้คำสั่งย่อย เพิ่ม ป้อน pac package help เพื่อดูรายการคำสั่งย่อย มาเพิ่มโซลูชันลงในแพคเกจของเรากัน

> pac package add-solution help

Commands:
Usage: pac package add-solution --path [--import-order] [--skip-validation] [--publish-workflows-activate-plugins] [--overwrite-unmanaged-customizations] [--import-mode] [--missing-dependency-behavior] [--dependency-overrides]

> cd .\DeploymentPackage\
> pac package add-solution --path ..\TestSolution_1_0_0_1_managed.zip

The item was added successfully.

กำหนดค่าแพคเกจ

กำหนดการกำหนดค่าแพคเกจโดยเพิ่มข้อมูลเกี่ยวกับแพคเกจของคุณในไฟล์ ImportConfig.xml ในโครงการ โปรดดู การอ้างอิง ImportConfig สำหรับตัวอย่างและคำอธิบายขององค์ประกอบ และแอตทริบิวต์ที่ถูกต้องที่จะใช้

เพิ่มโค้ดแบบกำหนดเอง

คุณสามารถเพิ่มโค้ดแบบกำหนดเองที่ดำเนินการก่อน ระหว่าง และหลังจากที่นำเข้าแพคเกจลงในสภาพแวดล้อม เมื่อต้องการทำเช่นนั้น ให้ทำตามคำแนะนำเหล่านี้

  1. แก้ไขไฟล์ PackageTemplate.cs (หรือ PackageImportExtension.cs) ในโฟลเดอร์รากของโครงการ

  2. ในไฟล์ C# คุณสามารถ:

    1. ป้อนรหัสที่กำหนดเองเพื่อดำเนินการ เมื่อมีการเริ่มต้นแพคเกจในนิยามวิธีการแทนที่ของ InitializeCustomExtension

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

      ตัวอย่างเช่น รหัสตัวอย่างต่อไปนี้เปิดใช้งานพารามิเตอร์รันไทม์ที่เรียกว่า SkipChecks สำหรับแพคเกจที่มีค่าสองค่าที่เป็นไปได้: จริงหรือเท็จ รหัสตัวอย่างตรวจสอบว่าผู้ใช้ระบุพารามิเตอร์รันไทม์ใดๆ ขณะทำงาน Package Deployer หรือไม่ (โดยใช้บรรทัดคำสั่งหรือ PowerShell) จากนั้นจึงประมวลผลข้อมูล หากไม่มีการระบุพารามิเตอร์รันไทม์โดยผู้ใช้ขณะรันแพกเกจ ค่าของคุณสมบัติ RuntimeSettings จะเป็นโมฆะ

      public override void InitializeCustomExtension()  
{  
// Do nothing.  

// Validate the state of the runtime settings object.  
if (RuntimeSettings != null)  
{  
PackageLog.Log(string.Format("Runtime Settings populated.  Count = {0}", RuntimeSettings.Count));  
foreach (var setting in RuntimeSettings)  
{  
PackageLog.Log(string.Format("Key={0} | Value={1}", setting.Key, setting.Value.ToString()));  
}  

// Check to see if skip checks is present.  
if ( RuntimeSettings.ContainsKey("SkipChecks") )  
{  
bool bSkipChecks = false;  
if (bool.TryParse((string)RuntimeSettings["SkipChecks"], out bSkipChecks))  
OverrideDataImportSafetyChecks = bSkipChecks;  
}  
}  
else  
PackageLog.Log("Runtime Settings not populated");  
}

      โค้ดนี้ทำให้ผู้ดูแลระบบใช้บรรทัดคำสั่งหรือ Import-CrmPackage cmdlet เพื่อระบุว่าจะข้ามการตรวจสอบความปลอดภัยในขณะใช้งานเครื่องมือ Package Deployer เพื่อที่จะนำเข้าแพคเกจหรือไม่ ข้อมูลเพิ่มเติม: ปรับใช้งานแพคเกจโดยใช้ Package Deployer และ Windows PowerShell

    2. ป้อนรหัสที่กำหนดเองเพื่อดำเนินการก่อนที่โซลูชันจะถูกนำเข้าในข้อกำหนดวิธีการแทนที่ของ PreSolutionImport เพื่อระบุว่าจะเก็บหรือเขียนทับการกำหนดเองขณะที่อัปเดตโซลูชันที่ระบุในอินสแตนซ์ Dataverse เป้าหมายหรือไม่ และจะเปิดใช้งานปลั๊กอินและเวิร์กโฟลว์โดยอัตโนมัติหรือไม่

    3. ใช้ข้อกำหนดวิธีการแทนที่ของ RunSolutionUpgradeMigrationStep เพื่อทำการแปลงข้อมูลหรืออัปเกรดระหว่างสองเวอร์ชันของโซลูชัน วิธีนี้เรียกใช้เฉพาะเมื่อโซลูชันที่คุณนำเข้ามีอยู่แล้วในอินสแตนซ์ Dataverse เป้าหมาย

      ฟังก์ชันนี้ต้องการพารามิเตอร์ต่อไปนี้:

      พารามิเตอร์ คำอธิบาย
      solutionName ชื่อของโซลูชัน
      oldVersion หมายเลขรุ่นของโซลูชันเก่า
      newVersion หมายเลขรุ่นของโซลูชันใหม่
      oldSolutionId GUID ของโซลูชันเก่า
      newSolutionId GUID ของโซลูชันใหม่

    4. ป้อนรหัสที่กำหนดเองเพื่อดำเนินการก่อนที่โซลูชันจะนำเข้าสำเร็จในนิยามแทนที่ของวิธี BeforeImportStage ข้อมูลตัวอย่างและไฟล์คงที่บางตัวสำหรับโซลูชันที่ระบุในไฟล์ ImportConfig.xml จะถูกนำเข้าก่อนที่การนำเข้าโซลูชันจะเสร็จสิ้น

    5. แทนที่ภาษาที่เลือกในปัจจุบันสำหรับการนำเข้าข้อมูลการกำหนดค่าโดยใช้ข้อกำหนดวิธีการแทนที่ของ OverrideConfigurationDataFileLanguage หากไม่พบรหัสตำแหน่งที่ตั้ง (LCID) ของภาษาที่ระบุในรายการภาษาที่มีในแพคเกจ ไฟล์ข้อมูลเริ่มต้นจะถูกนำเข้า

      คุณระบุภาษาที่มีสำหรับข้อมูลการกำหนดค่าในโหนด <cmtdatafiles> ในไฟล์ ImportConfig.xml ไฟล์การนำเข้าข้อมูลการกำหนดค่าเริ่มต้นถูกระบุในแอตทริบิวต์ crmmigdataimportfile ในไฟล์ ImportConfig.xml

      ข้ามการตรวจสอบข้อมูล (OverrideDataImportSafetyChecks = จริง) สามารถมีผลได้ที่นี่ หากคุณแน่ใจว่าอินสแตนซ์ Dataverse เป้าหมายนั้นไม่มีข้อมูลใด ๆ

    6. ป้อนรหัสที่กำหนดเองเพื่อดำเนินการหลังนำเข้าสำเร็จในนิยามแทนที่ของวิธี AfterPrimaryImport> วิธี ไฟล์คงที่ที่เหลือที่ไม่ได้นำเข้าก่อนหน้านี้ ก่อนการนำเข้าโซลูชันจะเริ่มต้น จะถูกนำเข้าตอนนี้

    7. เปลี่ยนชื่อเริ่มต้นของโฟลเดอร์แพคเกจของคุณเป็นชื่อแพคเกจที่คุณต้องการ หากต้องการทำเช่นนั้น ให้เปลี่ยนชื่อโฟลเดอร์ PkgFolder (หรือ PkgAssets) ในบานหน้าต่าง ตัวสำรวจโซลูชัน และแก้ไขค่าที่ส่งคืนภายใต้คุณสมบัติ GetImportPackageDataFolderName

      public override string GetImportPackageDataFolderName  
{  
get  
{  
// WARNING this value directly correlates to the folder name in the Solution Explorer where the ImportConfig.xml and sub content is located.  
// Changing this name requires that you also change the correlating name in the Solution Explorer  
return "PkgFolder";  
}  
}

    8. เปลี่ยนชื่อแพคเกจโดยแก้ไขค่าส่งกลับภายใต้คุณสมบัติ GetNameOfImport

      public override string GetNameOfImport(bool plural)  
{  
return "Package Short Name";  
}

      ค่าที่ส่งคืนนี้เป็นชื่อของแพคเกจของคุณที่ปรากฏบนหน้าการเลือกแพคเกจในตัวช่วยสร้าง Dynamics 365 Package Deployer

    9. เปลี่ยนคำอธิบายแพคเกจโดยแก้ไขค่าส่งกลับภายใต้คุณสมบัติ GetImportPackageDescriptionText

      
public override string GetImportPackageDescriptionText  
{  
get { return "Package Description"; }  
}

      ค่าที่ส่งคืนนี้เป็นคำอธิบายของแพคเกจที่ปรากฏข้างชื่อแพคเกจบนหน้าการเลือกแพคเกจในตัวช่วยสร้าง Package Deployer

    10. เปลี่ยนชื่อเต็มแพคเกจโดยแก้ไขค่าส่งกลับภายใต้คุณสมบัติ GetLongNameOfImport

      
public override string GetLongNameOfImport  
{  
get { return "Package Long Name"; }  
}

      ชื่อเต็มของแพคเกจจะปรากฏในหน้าถัดไป หลังจากคุณเลือกแพคเกจที่จะติดตั้ง

  3. นอกจากนี้ ยังมีฟังก์ชันและตัวแปรต่อไปนี้สำหรับแพคเกจ:

    ชื่อ ชนิด คำอธิบาย
    CreateProgressItem(String) Function ใช้เพื่อสร้างรายการความคืบหน้าใหม่ในส่วนต่อประสานผู้ใช้ (UI)
    RaiseUpdateEvent(String, ProgressPanelItemStatus) Function ใช้เพื่ออัปเดตความคืบหน้าที่สร้างโดยการโทรไป CreateProgressItem(String)

    ProgressPanelItemStatus เป็น enum ที่มีค่าดังต่อไปนี้:

    กำลังทำงาน = 0
    เสร็จสมบูรณ์ = 1
    ไม่สำเร็จ = 2
    คำเตือน = 3
    ไม่รู้จัก = 4
    RaiseFailEvent(String, Exception) Function ใช้เพื่อยกเลิกการนำเข้าสถานะปัจจุบันด้วยข้อความข้อยกเว้น
    IsRoleAssoicatedWithTeam(Guid, Guid) Function ใช้เพื่อกำหนดว่าบทบาทเชื่อมโยงกับทีมที่ระบุหรือไม่
    IsWorkflowActive(Guid) Function ใช้เพื่อกำหนดว่าเวิร์กโฟลว์ที่ระบุนั้นใช้งานอยู่หรือไม่
    PackageLog ตัวชี้ระดับ ตัวชี้ไปยังส่วนติดต่อการบันทึกที่เตรียมใช้งานแล้วสำหรับแพคเกจ ส่วนติดต่อนี้ถูกใช้โดยแพคเกจ เพื่อบันทึกข้อความและข้อยกเว้นไปยังไฟล์บันทึกแพคเกจ
    RootControlDispatcher คุณสมบัติ ส่วนติดต่อผู้มอบหมายงานที่ใช้เพื่อให้การควบคุมของคุณแสดงผล UI ของตัวเองในระหว่างการปรับใช้แพคเกจ ใช้ส่วนติดต่อนี้เพื่อครอบองค์ประกอบ UI หรือคำสั่งใดๆ คุณจำเป็นต้องตรวจสอบตัวแปรนี้สำหรับค่า Null ก่อนที่จะใช้ เนื่องจากอาจมีการตั้งค่าเป็นค่าหรือไม่ก็ได้
    CrmSvc คุณสมบัติ ตัวชี้ไปยังคลาส CrmServiceClient ที่อนุญาตให้แพคเกจกำหนด Dynamics 365 จากภายในแพคเกจ ใช้ตัวชี้นี้เพื่อดำเนินการวิธีการ SDK และการดำเนินการอื่นๆ ในวิธีการแทนที่
    DataImportBypass คุณสมบัติ ระบุว่า Dynamics 365 Package Deployer ข้ามการดำเนินการนำเข้าข้อมูลทั้งหมดหรือไม่ เช่น การนำเข้า Dataverse ข้อมูลตัวอย่าง ข้อมูลไฟล์คงที่ และข้อมูลที่ส่งออกจากเครื่องมือย้ายการกำหนดค่า ระบุว่าเป็น true หรือ false ค่าเริ่มต้นเป็น false
    OverrideDataImportSafetyChecks คุณสมบัติ ระบุว่า Dynamics 365 Package Deployer ข้ามการตรวจสอบความปลอดภัย ซึ่งจะช่วยในการปรับปรุงประสิทธิภาพการนำเข้าหรือไม่ ระบุว่า true หรือ false ค่าเริ่มต้นเป็น false

    คุณควรตั้งค่าคุณสมบัตินี้เป็น true เฉพาะในกรณีที่อินสแตนซ์ Dataverse เป้าหมายไม่มีข้อมูลใด ๆ

  4. บันทึกโครงการของคุณ ขั้นตอนต่อไปคือการสร้างแพคเกจ

สร้างและปรับใช้งาน

ส่วนต่อไปนี้อธิบายวิธีการสร้างและปรับใช้แพคเกจ

รุ่น

การสร้างแพคเกจของคุณมีคำอธิบายอยู่ด้านล่างนี้ ขึ้นอยู่กับเครื่องมือที่คุณใช้

หากต้องการสร้างแพคเกจที่สร้างด้วย CLI คุณสามารถโหลดไฟล์ .csproj ลงใน Visual Studio ได้ แต่เราจะใช้คำสั่ง dotnet และ MSBuild แทน ตัวอย่างด้านล่างถือว่าไดเรกทอรีการทำงานมีไฟล์ *.csproj

> dotnet publish

DeploymentPackage -> C:\Users\peter\Downloads\DeploymentPackage\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip

คุณสามารถเลือกดูรายละเอียดของแพคเกจที่สร้างขึ้นได้

> pac package show --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip

แพคเกจของคุณประกอบด้วยไฟล์ต่อไปนี้ภายใต้โฟลเดอร์ <Project>\Bin\Debug

  • <ชื่อแพ็คเกจ> โฟลเดอร์ : ชื่อโฟลเดอร์จะเหมือนกับชื่อโฟลเดอร์แพ็คเกจที่คุณเปลี่ยนแปลงใน ขั้นตอน 2.g ของส่วนนี้ เพิ่มโค้ดที่กำหนดเอง - โฟลเดอร์นี้ประกอบด้วยโซลูชัน ข้อมูลการกำหนดค่า ไฟล์คงที่ และเนื้อหาทั้งหมดสำหรับแพคเกจของคุณ

หมายเหตุ

คุณอาจเห็นโฟลเดอร์ .NET (เช่น net472) ที่มีโฟลเดอร์ pdpublish ไฟล์ DLL และไฟล์โครงการอื่นๆ จะอยู่ในโฟลเดอร์ pdpublish นั้น

  • <ชื่อแพ็คเกจ> .DLL :แอสเซมบลีประกอบด้วยโค้ดที่กำหนดเองสำหรับแพ็คเกจของคุณ โดยค่าเริ่มต้น ชื่อของแอสเซมบลีจะเหมือนกับชื่อโครงการของคุณ

ปรับใช้งาน

หลังจากที่คุณสร้างแพคเกจ คุณสามารถปรับใช้งานบนอินสแตนซ์ Dataverse โดยใช้เครื่องมือ Package Deployer, Windows PowerShell หรือคำสั่ง CLI

  • ในการปรับใช้งานโดยใช้เครื่องมือ Package Deployer ก่อนอื่น ให้ดาวน์โหลดเครื่องมือตามที่อธิบายไว้ใน เครื่องมือการพัฒนา Dataverse จากนั้น ปฏิบัติตามข้อมูลโดยละเอียดเกี่ยวกับการปรับใช้งานแพคเกจในบทความ ปรับใช้งานแพคเกจโดยใช้ Package Deployer หรือ Windows PowerShell

  • ในการปรับใช้งานโดยใช้ CLI ให้ใช้คำสั่ง pac package deploy

    > pac package deploy --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip

    หมายเหตุ

    ในการปรับใช้งานแพคเกจกับสภาพแวดล้อมเป้าหมายโดยใช้ CLI คุณต้องตั้งค่าโปรไฟล์การรับรองความถูกต้องก่อนแล้วเลือกองค์กร ข้อมูลเพิ่มเติม: pac auth create, pac org select

แนวทางปฏิบัติ

รายการที่แสดงด้านล่างเป็นเคล็ดลับแนวทางปฏิบัติที่ดีที่สุดบางประการที่ควรปฏิบัติตามเมื่อทำงานกับแพค Package Deployer

การสร้างแพคเกจ

เมื่อสร้างแพคเกจ นักพัฒนาต้อง:

  • ตรวจสอบให้แน่ใจว่าชุดประกอบแพ็คเกจได้รับการลงนาม -

การปรับใช้งานแพคเกจ

เมื่อปรับใช้งานแพคเกจ ผู้ดูแลระบบ Dataverse ต้อง:

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

ดูเพิ่มเติม

เครื่องมือแพ็คเกจโซลูชัน