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

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

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

โน้ต

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

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

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

ภาพรวมกระบวนการ

หากต้องการสร้างแพคเกจ Package Deployer ให้ทําตามขั้นตอนต่อไปนี้:

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

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

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

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

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

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

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 คุณสามารถเพิ่มแพคเกจภายนอก โซลูชัน และการอ้างอิงลงในโปรเจ็กต์แพคเกจของคุณได้ด้วยการใช้คำสั่งย่อย add คำสั่งใดคำสั่งหนึ่ง ป้อน 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. ป้อนรหัสที่กําหนดเองที่จะทำงานเมื่อแพคเกจเริ่มต้นในคำนิยามเมธอด override ของ InitializeCustomExtension

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

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

      public override void InitializeCustomExtension()  
{
  // 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");
  }  
}

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

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

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

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

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

    4. แทนที่เมธอด OverrideSolutionImportDecision เพื่อส่งคืนค่า enum UserRequestedImportAction ที่ควบคุมว่าจะข้าม อัปเดต หรืออัปเกรดการนําเข้าโซลูชัน (ค่าเริ่มต้น)

      public override UserRequestedImportAction OverrideSolutionImportDecision(
  string solutionUniqueName, Version organizationVersion,
  Version packageSolutionVersion, Version inboundSolutionVersion,
  Version deployedSolutionVersion, ImportAction systemSelectedImportAction )
{
  return systemSelectedImportAction == 
      ImportAction.Import ? UserRequestedImportAction.ForceUpdate
      : base.OverrideSolutionImportDecision(solutionUniqueName, organizationVersion,
      packageSolutionVersion, inboundSolutionVersion, deployedSolutionVersion,
      systemSelectedImportAction);
}

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

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

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

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

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

    8. เปลี่ยนชื่อเริ่มต้นของโฟลเดอร์แพคเกจของคุณเป็นชื่อแพคเกจที่คุณต้องการ เมื่อต้องการทําเช่นนั้น ให้เปลี่ยนชื่อโฟลเดอร์ PkgFolder หรือ PkgAssets ในบานหน้าต่าง Solution Explorer จากนั้นแก้ไขค่าที่ส่งกลับภายใต้คุณสมบัติ GetImportPackageDataFolderName

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

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

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

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

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

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

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

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

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

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

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

    ชื่อ ชนิด รายละเอียด
    CreateProgressItem(String) ฟังก์ชัน สร้างรายการความคืบหน้าใหม่ในอินเทอร์เฟซผู้ใช้ (UI)
    RaiseUpdateEvent(String, ProgressPanelItemStatus) ฟังก์ชัน ปรับปรุงความคืบหน้าที่สร้างขึ้นโดยการเรียกใช้ CreateProgressItem(String)

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

    กำลังทำงาน = 0
    เสร็จสมบูรณ์ = 1
    ไม่สำเร็จ = 2
    คำเตือน = 3
    ไม่รู้จัก = 4
    RaiseFailEvent(String, Exception) ฟังก์ชัน นําเข้าสถานะปัจจุบันล้มเหลวด้วยข้อความข้อยกเว้น
    IsRoleAssociatedWithTeam(Guid, Guid) ฟังก์ชัน กําหนดว่าบทบาทเชื่อมโยงกับทีมที่ระบุหรือไม่
    IsWorkflowActive(Guid) ฟังก์ชัน กําหนดว่าเวิร์กโฟลว์ที่ระบุใช้งานอยู่หรือไม่
    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 โฟลเดอร์:

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

โน้ต

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

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

ปรับใช้งาน

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

  • หากต้องการปรับใช้โดยใช้เครื่องมือ Package Deployer ก่อนอื่นให้ดาวน์โหลดเครื่องมือตามที่อธิบายไว้ใน เครื่องมือการพัฒนา Dataverse ถัดไป ทําตามข้อมูลโดยละเอียดเกี่ยวกับการปรับใช้แพคเกจในบทความแพคเกจ Deploy โดยใช้ 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 ต้อง:

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

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

เครื่องมือ Solution Packager

  • อัปเดตล่าสุดเมื่อ