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.
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.
Projenin kök klasöründeki PackageTemplate.cs (ya da PackageImportExtension.cs) dosyasını düzenleyin.
C# dosyasında şunları yapabilirsiniz:
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
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.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. 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.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ındakicrmmigdataimportfile
özniteliğinde belirtilir.Hedef Dataverse örneği veri içermiyorsa veri kontrollerini atlama (OverrideDataImportSafetyChecks = true) etkili olabilir.
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.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ındanGetImportPackageDataFolderName
ö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"; } }
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.
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.
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.
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 = 4RaiseFailEvent(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
veyafalse
şeklinde belirtin. Varsayılanfalse
değeridir.
Bu özelliği yalnızca hedef Dataverse örneği veri içermiyorsatrue
olarak ayarlamalısınız.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.
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 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.