Package Deployer aracı için paketler oluşturma

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.

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

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.

pac package init help
pac package init --outputDirectory DeploymentPackage

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

C:.
│   Deployment-package.csproj
│   Deployment-package.sln
│   GettingStarted.html
│   PackageTemplate.cs
│
├───PkgFolder
│   │   ImportConfig.xml
│   │
│   └───Content

Paket dosyaları ekleme

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

> 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 sabit listesidir: Ç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.

> 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

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ününadım 2.g bölümünde paket klasör adınız için 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.

• <PackageName.DLL>: Derleme, paketiniz için özel kodu içerir. 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.

• Package Deployer aracını kullanarak dağıtmak için öncelikle Dataverse geliştirme araçları bölümünde açıklandığı üzere aracı indirin. Daha sonra, Paketleri Package Deployer veya Windows PowerShell kullanarak dağıtma makalesindeki paket dağıtımıyla ilgili ayrıntılı bilgileri izleyin.

• CLI kullanarak dağıtmak için pac package deploy komutunu kullanın.

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

  Not

  Paketi CLI kullanarak hedef ortama dağıtmak için önce bir kimlik doğrulaması profili ayarlamanız ve bir organizasyon seçmeniz gerekir. Daha fazla bilgi: pac auth oluşturma, pac org seçme

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 izleyebilmeniz için imzalı paket derlemelerinde ısrar edin.
• Paketi, bir üretim kurulumu üzerinde çalıştırmadan önce, tercihen üretim kurulumunun ayna görüntüsü olan bir üretim öncesi örnekte test edin.
• Paketi dağıtmadan önce üretim kurulumunu yedekleyin.

Ayrıca bkz.

Çözüm Paketleyici aracı