Chia sẻ qua

Tạo các gói cho công cụ Package Deployer

  • Bài viết

Package Deployer cho phép quản trị viên triển khai gói trên phiên bản Microsoft Dataverse. Một gói Package Deployer có thể bao gồm bất kỳ hoặc tất cả những điều sau đây:

  • Một hoặc nhiều Dataverse tệp giải pháp.
  • Tệp mỏng hoặc tệp dữ liệu cấu hình được xuất từ Configuration Migration Tool. Để biết thông tin về công cụ này, hãy xem Di chuyển dữ liệu cấu hình giữa các phiên bản và tổ chức với Configuration Migration Tool.
  • Mã tùy chỉnh có thể chạy trước, trong hoặc sau khi các gói phần mềm được triển khai đến phiên bản Dataverse.
  • Nội dung HTML cụ thể cho các gói phần mềm mà có thể hiển thị ở đầu và cuối của quá trình triển khai. Nội dung này có thể hữu ích để cung cấp một mô tả về các giải pháp và tệp đã được triển khai trong gói.

Lưu ý

Có một loại gói khác gọi là gói phần bổ trợ. Loại gói đó dành cho các tổ hợp phụ thuộc phần bổ trợ và không có mối quan hệ nào với các gói Package Deployer.

Điều kiện tiên quyết

  • Đảm bảo rằng bạn có tất cả các giải pháp và tệp khác sẵn sàng mà bạn muốn đưa vào trong gói.
  • Visual Studio 2019 trở lên hoặc Visual Studio Mã.

Tổng quan về quy trình

Để tạo gói Package Deployer , hãy thực hiện các bước sau.

  • Tạo một dự án Visual Studio hoặc MSBuild
  • Thêm giải pháp và các tệp khác vào dự án
  • Cập nhật tệp HTML được cung cấp (tùy chọn)
  • Chỉ định các giá trị cấu hình cho gói
  • Xác định mã tùy chỉnh cho gói
  • Xây dựng và triển khai gói

Các bước này được mô tả chi tiết trong bài viết này.

Tạo dự án theo gói

Bước đầu tiên là tạo dự án Visual Studio hoặc MSBuild cho gói. Để làm điều đó, bạn phải cài đặt một trong hai tiện ích mở rộng công cụ có trên máy tính phát triển của mình. Nếu sử dụng Visual Studio Code, hãy cài đặt Microsoft Power Platform CLI. Ngược lại, nếu sử dụng Visual Studio 2019 trở lên, hãy cài đặt công cụ Power Platform cho Visual Studio.

Chọn tab thích hợp bên dưới để tìm hiểu cách tạo dự án bằng tiện ích mở rộng công cụ mong muốn. Cả hai công cụ đều xuất dự án ở định dạng tương tự nhau.

Chạy lệnh pac package init để tạo gói ban đầu. Thông tin khác: pac package

pac package init help
pac package init --outputDirectory DeploymentPackage

Kết quả đầu ra CLI chứa các thư mục và tệp hiển thị bên dưới. Tên thư mục "DeploymentPackage" đã được sử dụng ở đây làm ví dụ.

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

Trong dự án đã tạo, tìm tệp cấu hình ImportConfig.xml trong thư mục PkgAssets và tệp PackageImportExtension.cs. Bạn sẽ sửa đổi các tệp này như được mô tả ở phần sau của bài viết này.

Thêm tệp gói

Sau khi đã tạo dự án trọn gói, bạn có thể bắt đầu thêm giải pháp và các tệp khác vào dự án đó.

Khi sử dụng CLI, bạn có thể thêm các gói, giải pháp và tham chiếu bên ngoài vào dự án trọn gói của mình bằng cách sử dụng một trong các lệnh con add. Nhập pac package help để xem danh sách các lệnh con. Hãy thêm một giải pháp cho gói của chúng tôi.

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

Đặt cấu hình gói

Xác định cấu hình gói bằng cách thêm thông tin về gói của bạn vào tệp ImportConfig.xml trong dự án. Hãy tham khảo Tham khảo ImportConfig để biết ví dụ và mô tả về các thành phần và thuộc tính hợp lệ sẽ sử dụng.

Thêm mã tùy chỉnh

Bạn có thể thêm mã tùy chỉnh thực thi trước, trong và sau khi gói được nhập vào một môi trường. Để làm điều này, hãy làm theo các hướng dẫn sau.

  1. Chỉnh sửa tệp PackageTemplate.cs (hoặc PackageImportExtension.cs) trong thư mục gốc của dự án.

  2. Trong tệp C#, bạn có thể:

    1. Nhập mã tùy chỉnh để thực thi khi gói được khởi tạo trong định nghĩa phương thức ghi đè của InitializeCustomExtension.

      Phương pháp này có thể được sử dụng để cho phép người dùng sử dụng các tham số thời gian chạy trong khi chạy gói. Là nhà phát triển, bạn có thể thêm hỗ trợ cho bất kỳ tham số thời gian chạy nào vào gói của mình bằng cách sử dụng thuộc tính RuntimeSettings miễn là bạn có mã để xử lý nó dựa trên đầu vào của người dùng.

      Ví dụ, mã mẫu sau cho phép tham số thời gian chạy được gọi là SkipChecks cho gói có hai giá trị có thể: true hoặc false. Mã mẫu kiểm tra xem người dùng có chỉ định bất kỳ tham số thời gian chạy nào trong khi chạy Package Deployer không (bằng cách sử dụng dòng lệnh hoặc PowerShell), sau đó xử lý thông tin. Nếu không có tham số thời gian chạy nào được chỉ định bởi người dùng trong khi chạy gói, giá trị của thuộc tính RuntimeSettings sẽ là null.

      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");  
}

      Mã này cho phép quản trị viên sử dụng dòng lệnh hoặc lệnh ghép ngắn Import-CrmPackage để chỉ định có bỏ qua kiểm tra an toàn trong khi chạy công cụ Package Deployer để nhập gói hay không. Thông tin thêm: Triển khai các gói bằng Package Deployer và Windows PowerShell

    2. Nhập mã tùy chỉnh để thực thi trước khi các giải pháp được nhập trong định nghĩa phương thức ghi đè của PreSolutionImport để chỉ định nên duy trì hay ghi đè các tùy chỉnh trong khi cập nhật giải pháp đã chỉ định trong phiên bản Dataverse đích, và có tự động kích hoạt phần bổ trợ và quy trình công việc hay không.

    3. Sử dụng định nghĩa phương thức ghi đè của RunSolutionUpgradeMigrationStep để thực hiện chuyển đổi hoặc nâng cấp dữ liệu giữa hai phiên bản của một giải pháp. Phương thức này chỉ được gọi nếu giải pháp bạn đang nhập đã có trong mục tiêu Dataverse ví dụ.

      Hàm này mong đợi các tham số sau:

      Tham số Mô tả
      solutionName Tên giải pháp
      oldVersion Số phiên bản của giải pháp cũ
      newVersion Số phiên bản của giải pháp mới
      oldSolutionId GUID của giải pháp cũ.
      newSolutionId GUID của giải pháp mới.

    4. Nhập mã tùy chỉnh để thực thi trước khi quá trình nhập giải pháp hoàn tất trong định nghĩa ghi đè của phương thứcBeforeImportStage. Dữ liệu mẫu và một số tệp phẳng cho các giải pháp được chỉ định trong tệp ImportConfig.xml được nhập trước khi nhập giải pháp hoàn tất.

    5. Ghi đè ngôn ngữ hiện được chọn để nhập dữ liệu cấu hình bằng cách sử dụng định nghĩa phương thức ghi đè của OverrideConfigurationDataFileLanguage. Nếu không tìm thấy ID ngôn ngữ đã chỉ định (LCID) của ngôn ngữ đã chỉ định trong danh sách các ngôn ngữ có sẵn trong gói thì tệp dữ liệu mặc định sẽ được nhập.

      Bạn chỉ định ngôn ngữ có sẵn cho dữ liệu cấu hình trong nút <cmtdatafiles> trong tệp ImportConfig.xml. Tệp nhập dữ liệu cấu hình mặc định được chỉ định trong thuộc tính crmmigdataimportfile trong tệp ImportConfig.xml.

      Bỏ qua việc kiểm tra dữ liệu (OverrideDataImportSafetyChecks = true) có thể có hiệu quả ở đây nếu bạn chắc chắn rằng phiên bản đích Dataverse không chứa bất kỳ dữ liệu nào.

    6. Nhập mã tùy chỉnh để thực thi sau khi quá trình nhập hoàn tất trong định nghĩa ghi đè của phương thức AfterPrimaryImport>. Các tệp phẳng còn lại chưa được nhập trước đó trước khi quá trình nhập giải pháp bắt đầu sẽ được nhập ngay bây giờ.

    7. Thay đổi tên mặc định của thư mục gói của bạn thành tên gói mà bạn muốn. Để làm như vậy, hãy đổi tên thư mục PkgFolder (hoặc PkgAssets) trong ngăn Trình khám phá giải pháp rồi chỉnh sửa giá trị trả về trong thuộc tính 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. Thay đổi tên gói bằng cách chỉnh sửa giá trị trả về trong thuộc tính GetNameOfImport.

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

      Giá trị trả về này là tên gói của bạn xuất hiện trên trang chọn gói trong trình hướng dẫn Dynamics 365 Package Deployer .

    9. Thay đổi phần mô tả gói bằng cách chỉnh sửa giá trị trả về trong thuộc tính GetImportPackageDescriptionText.

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

      Giá trị được trả về này là mô tả gói xuất hiện cùng với tên gói trên trang chọn gói trong trình hướng dẫn Package Deployer .

    10. Thay đổi tên dài của gói bằng cách chỉnh sửa giá trị trả về trong thuộc tính GetLongNameOfImport.

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

      Tên dài của gói xuất hiện trên trang tiếp theo sau khi bạn đã chọn gói để cài đặt.

  3. Ngoài ra, các hàm và biến sau đây có sẵn cho gói:

    Tên Loại Mô tả
    CreateProgressItem(String) Hàm Được sử dụng để tạo một mục tiến trình mới trong giao diện người dùng (UI).
    RaiseUpdateEvent(String, ProgressPanelItemStatus) Hàm Được sử dụng để cập nhật tiến trình được tạo bởi lệnh gọi đến CreateProgressItem(String).

    ProgressPanelItemStatus là kiểu liệt kê với các giá trị sau:

    Đang hoạt động = 0
    Hoàn thành = 1
    Không thành công = 2
    Cảnh báo = 3
    Không xác định = 4
    RaiseFailEvent(String, Exception) Hàm Được sử dụng để không nhập trạng thái hiện tại với một thông báo ngoại lệ.
    IsRoleAssoicatedWithTeam(Guid, Guid) Hàm Được sử dụng để xác định xem một vai trò có được liên kết với một nhóm được chỉ định hay không.
    IsWorkflowActive(Guid) Hàm Được sử dụng để xác định xem một quy trình công việc có được chỉ định là đang hoạt động hay không.
    PackageLog Con trỏ lớp Một con trỏ đến giao diện ghi nhật ký khởi tạo cho gói. Giao diện này được sử dụng bởi một gói để ghi nhật ký tin nhắn và ngoại lệ cho tệp nhật ký gói.
    RootControlDispatcher Thuộc tính Một giao diện người điều vận được sử dụng để cho phép điều khiển của bạn hiển thị giao diện người dùng của chính nó trong quá trình triển khai gói. Sử dụng giao diện này để bọc bất kỳ thành phần UI hoặc lệnh nào. Điều quan trọng là phải kiểm tra biến này để tìm giá trị null trước khi sử dụng vì nó có thể không được đặt thành giá trị.
    CrmSvc Thuộc tính Một con trỏ tới lớp CrmServiceClient cho phép gói xử lý Dynamics 365 từ trong gói. Sử dụng con trỏ này để thực thi các phương thức SDK và các hành động khác trong các phương thức được ghi đè.
    DataImportBypass Thuộc tính Chỉ định xem Package Deployer của Dynamics 365 có bỏ qua tất cả các hoạt động nhập dữ liệu như nhập dữ liệu mẫu Dataverse, dữ liệu tệp phẳng và dữ liệu được xuất từ Configuration Migration Tool hay không. Chỉ định true hoặc false. Mặc định là false.
    OverrideDataImportSafetyChecks Thuộc tính Chỉ định xem Dynamics 365 Package Deployer có bỏ qua một số kiểm tra an toàn hay không, điều này giúp cải thiện hiệu suất nhập. Chỉ định true hoặc false. Mặc định là false.

    Bạn chỉ nên đặt thuộc tính này thành true nếu phiên bản đích Dataverse không chứa bất kỳ dữ liệu nào.

  4. Lưu dự án của bạn. Bước tiếp theo là tạo gói.

Tạo và triển khai

Các phần sau đây mô tả cách xây dựng và triển khai một gói.

Bản dựng

Việc xây dựng gói của bạn được mô tả bên dưới tùy thuộc vào công cụ bạn đang sử dụng.

Để xây dựng một gói được tạo bằng CLI, bạn có thể tải tệp .csproj vào Visual Studio, nhưng thay vào đó chúng ta sẽ sử dụng lệnh dotnet và MSBuild. Ví dụ bên dưới giả sử thư mục làm việc có chứa tệp *.csproj.

> dotnet publish

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

Bạn có thể tùy ý xem thông tin chi tiết của gói đã xây dựng.

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

Gói của bạn được làm từ các tệp sau trong thư mục <Project>\Bin\Debug.

  • <PackageName> thư mục: Tên thư mục giống với tên bạn đã thay đổi cho tên thư mục gói của mình trong bước 2.g của phần này Thêm mã tùy chỉnh. Thư mục này chứa tất cả giải pháp, dữ liệu cấu hình, tệp phẳng và các nội dung cho gói của bạn.

Lưu ý

Bạn có thể thấy thư mục .NET (ví dụ: net472) chứa thư mục pdpublish. DLL của bạn và các tệp dự án khác nằm trong thư mục pdpublish đó.

  • <PackageName>.dll: Cụm có chứa mã tùy chỉnh cho gói của bạn. Theo mặc định, tên của cụm chính là tên dự án của bạn.

Triển khai

Sau khi tạo gói, bạn có thể triển khai gói đó trên phiên bản Dataverse bằng công cụ Package Deployer, Windows PowerShell hoặc lệnh CLI.

  • Để triển khai bằng công cụ Package Deployer, trước tiên hãy tải xuống công cụ như được mô tả trong Dataverse công cụ phát triển. Tiếp theo, hãy theo dõi thông tin chi tiết về triển khai gói trong bài viết Triển khai các gói bằng Package Deployer hoặc Windows PowerShell.

  • Để triển khai bằng CLI, hãy sử dụng lệnh pac package deploy.

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

    Lưu ý

    Để triển khai một gói cho môi trường đích bằng CLI, trước tiên bạn phải thiết lập cấu hình xác thực và chọn một tổ chức. Thông tin thêm: pac auth create, pac org select

Thực tiễn tốt nhất

Dưới đây là một số mẹo thực hành tốt nhất để làm theo khi làm việc với các gói Package Deployer.

Tạo gói

Khi tạo các gói, nhà phát triển phải:

  • Đảm bảo các cụm gói được ký.

Triển khai gói

Khi triển khai gói, quản trị viên Dataverse phải:

  • Nhấn mạnh vào một cụm gói đã ký để bạn có thể theo dõi một cụm về nguồn của nó.
  • Kiểm tra gói trên phiên bản tiền sản xuất, tốt nhất là hình ảnh phản chiếu của phiên bản sản xuất, trước khi chạy gói trên phiên bản sản xuất.
  • Sao lưu phiên bản sản xuất trước khi triển khai gói đó.

Xem thêm

Công cụ Gói giải pháp