Aracılığıyla paylaş

Package Deployer aracı için paketler oluşturma

Paket Dağıtıcı, yöneticilerin paketleri Microsoft Dataverse örneklerde dağıtması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.
  • Paket Dataverse kurulumuna dağıtılmadan önce, dağıtılırken veya dağıtıldıktan sonra çalışabilecek ö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.

Ön koşullar

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

İşlem genel bakışı

Bir 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ıyorsanız Microsoft Power Platform CLI yükleyin. Aksi takdirde, Visual Studio 2019 veya üzerini kullanıyorsanız Visual Studio için Power Platform araçlarını 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()  
{
  // 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çe aktarmak için Package Deployer aracını çalıştırırken güvenlik kontrollerini atlayıp atlamayacağını belirtmek için komut satırını veya Import-CrmPackage cmdlet'ini kullanmasını sağlar. Daha fazla bilgi: Package Deployer ve Windows PowerShell kullanarak paketleri dağıtın

    2. Hedef Dataverse kurulumunda belirtilen çözümü güncelleştirirken özelleştirmelerin korunması mı yoksa üzerine yazılması mı gerektiğini ve eklentiler ile iş akışlarının otomatik olarak etkinleştirilip etkinleştirilmeyeceğini belirtmek için PreSolutionImport geçersiz kalma yöntemi tanımında çözümler içeri aktarılmadan önce çalıştırılacak özel kodu girin.

    3. Veri dönüşümünü gerçekleştirmek veya çözümü ikinci bir sürüme yükseltmek için RunSolutionUpgradeMigrationStep geçersiz kılma yöntemi tanımını kullanın. Bu yöntem, yalnızca içeri aktardığınız çözümün hedef Dataverse kurulumunda zaten var olması durumunda çağırılır.

      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. Çözümün içeri aktarılmasının atlanıp atlanmayacağını, güncelleştirileceğini veya yükseltileceğini (varsayılan) denetleyecek bir OverrideSolutionImportDecision sabit listesi döndürmek için yöntemini geçersiz kılın.

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

    6. 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 <cmtdatafiles> dosyasındaki ImportConfig.xml düğümünde belirtebilirsiniz. Varsayılan yapılandırma verileri içeri aktarma dosyası crmmigdataimportfile dosyasındaki ImportConfig.xml özniteliğinde belirtilir.

      Hedef Dataverse kurulumunda hiç veri bulunmadığından eminseniz burada veri denetimlerini atlamak (OverrideDataImportSafetyChecks = true) etkili olabilir.

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

    8. Paket klasörünüzün varsayılan adını istediğiniz paket adı olarak değiştirin. Bunu yapmak için PkgFolder bölmesindeki (veya PkgAssets) klasörünü yeniden adlandırın ve 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 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 ö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";  
}

      Bu döndürülen değer, Dynamics 365 Paket Dağıtıcı sihirbazındaki paket seçimi sayfasında görüntülenen paketinizin adıdır.

    10. 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ındaki paket seçim sayfasında paket adının yanında görünen paket açıklamasıdır.

    11. 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) İşlev Kullanıcı arabiriminde (UI) yeni bir ilerleme öğesi oluşturmak için kullanılır.
    RaiseUpdateEvent(String, ProgressPanelItemStatus) İşlev 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) İşlev Geçerli durum içeri aktarma işlemi bir özel durum iletisiyle başarısız olduğunda kullanılır.
    IsRoleAssociatedWithTeam(Guid, Guid) İşlev Rolün belirli bir takımla ilişkilendirilip ilişkilendirilmediğini belirlemek için kullanılır.
    IsWorkflowActive(Guid) İşlev 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 CrmServiceClient sınıfına yönelik, paketin paketin içinden Dynamics 365 adreslemesini sağlayan bir işaretçi. 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 Paket Dağıtıcı'nın Dataverse örnek verilerini içeri aktarma, düz dosya verileri ve Yapılandırma Geçişi aracından dışarı aktarılan veriler 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 Paket Dağıtıcısının, içeri aktarma performansını artırmaya yardımcı olacak bazı güvenlik denetimlerini atlayıp atlamayacağını belirtin. Şunu belirtin: true veya false. Varsayılan false değeridir.

    Bu özelliği yalnızca hedef Dataverse örneği herhangi bir 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şturulan bir paket oluşturmak için .csproj dosyasını Visual Studio yükleyebilirsiniz, ancak bunun yerine dotnet komutunu ve MSBuild'i 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ü (örneğin, 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ğıtma

Bir paket oluşturduktan sonra, Paket Dağıtıcı aracını, Windows PowerShell'i veya CLI komutunu kullanarak dataverse örneğine dağıtabilirsiniz.

  • Package Deployer aracını kullanarak dağıtım yapmak için öncelikle aracı Dataverse geliştirme araçları bölümünde açıklandığı gibi indirin. Ardından Paketi Dağıtıcı veya Windows PowerShell kullanarak paket dağıtımı yapma konusundaki Paketleri Dağıt Paket Dağıtıcı veya Windows PowerShell kullanarak başlıklı makaledeki 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

Paketleri dağıtırken Dataverse yöneticilerinin şunları 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ı

  • Last updated on