Aracılığıyla paylaş

Package Deployer aracı için paketler oluşturma

  • Makale

Package Deployer, yöneticilerin paketleri Microsoft Dataverse kurulumlarında dağıtmalarına olanak tanır. Package Deployer paketi aşağıdakilerin herhangi birinden veya tümünden oluşabilir:

  • Bir veya daha fazla Dataverse çözüm dosyası.
  • Düz dosyalar veya Configuration Migration toolndan dışa aktarılan yapılandırma veri dosyası. Araç hakkında Daha fazla bilgi edinmek için bkz. Configuration Migration Tool yapılandırma verilerini kurulumlar ve kuruluşlar arasında taşıma.
  • Paketin Dataverse kurulumuna dağıtılması öncesinde, sırasında veya sonrasında çalışabilen özel kod.
  • Dağıtım işleminin başlangıcında ve sonunda görüntülenebilen pakete özel HTML içeriği. Bu içerik, paket içinde dağıtılan çözümlerin ve dosyaların bir açıklamasını sağlamak için faydalı olabilir.

Not

Eklenti paketi denen başka bir paket türü vardır. Bu tür paketler, eklenti bağımlı derlemeler içindir ve Package Deployer paketleriyle herhangi bir ilişkisi yoktur.

Önkoşullar

  • Pakete eklemek istediğiniz tüm çözümlerin ve diğer dosyaların hazır olduğundan emin olun.
  • Visual Studio 2019 veya üstü ya da Visual Studio Code.

İşlem genel bakışı

Package Deployer paketi oluşturmak için aşağıdaki adımları uygulayın.

  • Visual Studio veya MSBuild projesi oluşturma
  • Projeye çözümler ve diğer dosyalar ekleyin
  • Sağlanan HTML dosyalarını güncelleştirme (isteğe bağlı)
  • Paket için yapılandırma değerlerini belirtin
  • Paket için özel kod tanımlayın
  • Paketi derleyin ve dağıtın

Bu adımlar, makalenin sonraki bölümlerinde ayrıntılı olarak açıklanmıştır.

Paket projesi oluşturma

İlk adım, paket için bir Visual Studio veya MSBuild projesi oluşturmaktır. Bunu yapmak için, geliştirme bilgisayarınızda yüklü iki araç uzantılardan birine sahip olmanız gerekir. Visual Studio Code kullanılıyorsa, Microsoft Power Platform CLI yükleyin. Aksi takdirde, Visual Studio 2019 veya üzerini kullanıyorsanız, Visual Studio için Power Platform tools yükleyin.

İstediğiniz aracın uzantısını kullanarak bir projenin nasıl oluşturulacağını öğrenmek için aşağıdaki uygun sekmeyi seçin. Her iki araç da projeyi benzer biçimde çıktı olarak doldurur.

İlk paketi oluşturmak için pac package init komutunu çalıştırın. Daha fazla bilgi: pac package

pac package init help
pac package init --outputDirectory DeploymentPackage

Ortaya çıkan CLI çıkışı, aşağıda gösterilen klasörleri ve dosyaları içerir. "DeploymentPackage" klasör adı bir örnek olarak burada kullanıldı.

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

Oluşturulan projede PkgAssets klasöründe ImportConfig.xml yapılandırma dosyasını ve PackageImportExtension.cs dosyasını bulun. Bu dosyaları bu makalenin ilerleyen kısımlarında açıklandığı şekilde değiştireceksiniz.

Paket dosyaları ekleme

Bir paket projesi oluşturduktan sonra, o projeye çözümler ve başka dosyalar eklemeye başlayabilirsiniz.

CLı kullanırken, ekle alt komutlarının birini kullanarak paket projenize harici paketler, çözümler ve referanslar ekleyebilirsiniz. Alt komutların listesini görmek için pac package help girin. Paketimize bir çözüm ekleyelim.

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

Paketi yapılandırma

Projede bulunan ImportConfig.xml dosyasına paketiniz hakkında bilgi ekleyerek paket yapılandırmasını tanımlayın. Kullanılacak geçerli öğelerin ve özniteliklerin örnekleri ve açıklamaları için ImportConfig Başvurusu'na bakın.

Özel kod ekleme

Paket bir ortama alınmadan önce, sırasında ve sonrasında yürütülen özel kod ekleyebilirsiniz. Bunu yapmak için aşağıdaki talimatları izleyin.

  1. Projenin kök klasöründeki PackageTemplate.cs (ya da PackageImportExtension.cs) dosyasını düzenleyin.

  2. C# dosyasında şunları yapabilirsiniz:

    1. InitializeCustomExtension geçersiz kılma yöntemi tanımında paket başlatıldığında yürütülecek özel kodu girin.

      Bu yöntem, kullanıcıların bir paketi çalıştırırken çalışma zamanı parametrelerini kullanmalarına olanak tanımak için kullanılabilir. Bir geliştirici olarak, kullanıcı girişine göre işlem yapan bir koda sahip olduğunuz sürece RuntimeSettings özelliğini kullanarak paketinize herhangi bir çalışma zamanı parametresi için destek ekleyebilirsiniz.

      Örneğin, aşağıdaki örnek kod, doğru veya yanlış şeklinde iki olası değeri olan paket için SkipChecks olarak adlandırılan bir çalışma zamanı parametresini etkinleştirir. Örnek kod, kullanıcının Package Deployer'ı çalıştırırken (komut satırı veya PowerShell kullanarak) herhangi bir çalışma zamanı parametresi belirtip belirtmediğini denetler ve ardından bilgileri buna göre işler. Paketi çalıştırırken kullanıcı tarafından çalışma zamanı parametresi belirtilmezse RuntimeSettings özelliğinin değeri null olur.

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

      Bu kod, yöneticinin paketi içeri aktarmak için Package Deployer aracını çalıştırırken güvenlik denetimlerinin atlanıp atlanmayacağını belirtmek için komut satırını veya Import-CrmPackage cmdlet'ini kullanmasına olanak tanır. Daha fazla bilgi: Package Deployer ve Windows PowerShell kullanarak paketleri dağıtma

    2. Hedef Dataverse kurulumunda belirtilen çözümü güncelleştirirken özelleştirmelerin saklanıp saklanmayacağını veya üzerine yazılıp yazılmayacağını ve eklentilerin ve iş akışlarının otomatik olarak etkinleştirilip etkinleştirilmeyeceğini belirlemek için çözümleri PreSolutionImport geçersiz kılma yöntemi tanımında içeri aktarılmadan önce yürütecek özel kodu girin.

    3. Bu yöntem yalnızca içe aktardığınız çözüm halihazırda hedef Dataverse örneğinde mevcutsa çözümünün iki sürümü arasında veri aktarımı veya yükseltmesi gerçekleştirmek üzere RunSolutionUpgradeMigrationStep tanımının geçersiz kılma yöntemini kullanın.

      Bu işlev için aşağıdaki parametreler beklenir:

      Parametre Açıklama
      solutionName Çözümün adı
      oldVersion Eski çözümün sürüm numarası
      newVersion Yeni çözümün sürüm numarası
      oldSolutionId Eski çözümün GUID'si.
      newSolutionId Yeni çözümün GUID'si.

    4. BeforeImportStage yönteminin geçersiz kılma tanımında çözümü içeri aktarma işlemi tamamlanmadan önce yürütecek özel kodu girin. ImportConfig.xml dosyasında belirtilen çözümler için örnek veriler ve bazı düz dosyalar, çözümü içeri aktarma işlemi tamamlanmadan içeri aktarılır.

    5. OverrideConfigurationDataFileLanguage geçersiz kılma yöntemi tanımını kullanarak yapılandırma verilerini içeri aktarmak için şu anda seçili olan dili geçersiz kılın. Belirtilen dilin belirtilen yerel ayar kimliği (LCID) paketteki mevcut diller listesinde bulunamazsa, varsayılan veri dosyası içe aktarılır.

      Yapılandırma verileri için kullanılabilir dilleri ImportConfig.xml dosyasındaki <cmtdatafiles> düğümünde belirtebilirsiniz. Varsayılan yapılandırma verileri içeri aktarma dosyası ImportConfig.xml dosyasındaki crmmigdataimportfile özniteliğinde belirtilir.

      Hedef Dataverse örneği veri içermiyorsa veri kontrollerini atlama (OverrideDataImportSafetyChecks = true) etkili olabilir.

    6. AfterPrimaryImport> yönteminin geçersiz kılma tanımında çözümü içeri aktarma işlemi tamamlandıktan sonra yürütecek özel kodu girin. Çözümün içe aktarımı başlamadan önce daha önce içe aktarılmayan kalan düz dosyalar şimdi içe aktarılıyor.

    7. Paket klasörünüzün varsayılan adını istediğiniz paket adı olarak değiştirin. Bunu yapmak için Çözüm Gezgini bölmesinde PkgFolder (veya PkgAssets) klasörünü yeniden adlandırın ve ardından GetImportPackageDataFolderName özelliği altında dönüş değerini düzenleyin.

      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 özelliğinin altında dönüş değerini düzenleyerek paket adını değiştirin.

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

      Döndürülen bu değer, Dynamics 365 Package Deployer sihirbazındaki paket seçim sayfasında görünen paketinizin adıdır.

    9. GetImportPackageDescriptionText özelliğinin altında dönüş değerini düzenleyerek paket açıklamasını değiştirin.

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

      Döndürülen bu değer, Package Deployer sihirbazında paket seçimi sayfasında paket adının yanında görüntülenen paket tanımı değeridir.

    10. GetLongNameOfImport özelliğinin altında dönüş değerini düzenleyerek paketin uzun adını değiştirin.

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

      Yüklenecek paketi seçtikten sonra paketin uzun adı sonraki sayfada görüntülenir.

  3. Ek olarak, paket için aşağıdaki işlev ve değişkenler de kullanılabilir:

    Ad Tür Açıklama
    CreateProgressItem(String) Function Kullanıcı arabiriminde (UI) yeni bir ilerleme öğesi oluşturmak için kullanılır.
    RaiseUpdateEvent(String, ProgressPanelItemStatus) Function CreateProgressItem(String) çağrısı ile oluşturulan ilerlemeyi güncelleştirmek için kullanılır.

    ProgressPanelItemStatus aşağıdaki değerlere sahip bir numaralandırmadır:

    Çalışıyor = 0
    Tamamlandı = 1
    Başarısız Oldu = 2
    Uyarı = 3
    Bilinmeyen = 4
    RaiseFailEvent(String, Exception) Function Geçerli durum içeri aktarma işlemi bir özel durum iletisiyle başarısız olduğunda kullanılır.
    IsRoleAssoicatedWithTeam(Guid, Guid) Function Rolün belirli bir takımla ilişkilendirilip ilişkilendirilmediğini belirlemek için kullanılır.
    IsWorkflowActive(Guid) Function Belirli bir iş akışının etkin olup olmadığını belirlemek için kullanılır.
    PackageLog Sınıf İşaretçisi Paket için başlatılmış günlük kaydı arabiriminin işaretçisidir. Bu arabirim, bir paket tarafından iletileri ve özel durumları paket günlük dosyasında günlüğe kaydetmek için kullanılır.
    RootControlDispatcher Özellik Denetiminizin paket dağıtımı sırasında kendi kullanıcı arabirimini oluşturmasını sağlamak için kullanılan bir sevkiyatçı arabirimidir. Kullanıcı arabirimi öğelerini veya komutlarını paketlemek için bu arabirimi kullanın. Bir değere ayarlanmamış olabileceğinden, bu değişkeni kullanmadan önce boş değerler açısından kontrol etmek önemlidir.
    CrmSvc Özellik Bir paketin, paket içinden Dynamics 365'e girmesini sağlayan CrmServiceClient sınıfının işaretçisidir. Bu işaretçiyi, SDK yöntemlerini ve geçersiz kılınmış yöntemlerde diğer eylemleri yürütmek için kullanın.
    DataImportBypass Özellik Dynamics 365 Package Deployer'ın Dataverse örnek verilerini, düz dosya verilerini ve Configuration Migration toolndan dışarı aktarılan verileri içeri aktarma gibi tüm veri içeri aktarma işlemlerini atlayıp atlamayacağını belirtin. Doğru veya yanlış şeklinde belirtin. Varsayılan false değeridir.
    OverrideDataImportSafetyChecks Özellik Dynamics 365 Package Deployer içe aktarma performansının iyileştirilmesine yardımcı olacak güvenlik kontrollerinden bazılarını atlayıp atlamadığını belirtin. true veya false şeklinde belirtin. Varsayılan false değeridir.

    Bu özelliği yalnızca hedef Dataverse örneği veri içermiyorsa true olarak ayarlamalısınız.

  4. Projenizi kaydedin. Sonraki adım, paketi derlemektir.

Derleme ve dağıtma

Aşağıdaki bölümlerde bir paketin nasıl oluşturulacağı ve dağıtılacağı açıklanmaktadır.

Derleme

Paketinizi oluşturmak, kullandığınız araca bağlı olarak aşağıda açıklanmıştır.

CLI ile oluşturulmuş bir paket oluşturmak için .csproj dosyasını Visual Studio'a yükleyebilirsiniz ancak bunun yerine dotnet komutunu ve MSBuild'ı kullanacağız. Aşağıdaki örnekte çalışma dizininde *.csproj dosyasının bulunduğu varsayılmaktadır.

> dotnet publish

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

İsteğe bağlı olarak, oluşturulan paketin ayrıntılarına bakabilirsiniz.

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

Paketiniz <Project>\Bin\Debug klasörü altında aşağıdaki dosyalardır.

  • <PackageName> klasörü: Klasör adı, bu Özel kod ekleme bölümünde adım 2.g'de paket klasör adı olarak değiştirdiğiniz adla aynıdır. Bu klasörde tüm çözümler, yapılandırma verileri, düz dosyalar ve paketinizin içeriği bulunur.

Not

Pdpublish klasörü içeren bir .NET klasörü (ör. net472) görebilirsiniz. DLL'niz ve diğer proje dosyalarınız bu pdpublish klasöründe bulunur.

  • <PackageName>.dll: Derlemede paketinizin özel kodu vardır. Varsayılan olarak, derleme adı proje adıyla aynıdır.

Dağıt

Paket oluşturduktan sonra, Package Deployer aracını veya Windows PowerShell'i ya da CLI komutunu kullanarak paketi Dataverse kurulumunda dağıtabilirsiniz.

En iyi yöntemler

Aşağıda, Package Deployer paketlerle çalışırken izlenecek en iyi uygulama ipuçları aşağıda listelenmektedir.

Paket oluşturma

Paketler oluştururken, geliştiriciler:

  • Paket derlemelerinin imzalandığından emin olun.

Paket dağıtma

Paket dağıtırken, Dataverse yöneticilerinin aşağıdakileri yapması gerekir:

  • Bir derlemeyi kaynağına kadar izleyebilmek için imzalı bir pakette ısrar etmeleri.
  • Paketi bir üretim öncesi örneğinde, tercihen üretim kurulumu'nin ayna görüntüsünde, üretim kurulumu üzerinde çalıştırmadan önce test edin.
  • Paketi dağıtmadan önce üretim kurulumunu yedeklemeleri.

Ayrıca bkz.

Çözüm Paketi Oluşturucu aracı