SolutionPackager aracı

SolutionPackager, Microsoft Dataverse sıkıştırılmış bir çözüm dosyasını birden çok XML dosyasına ve diğer dosyalara dönüştürebilen bir araçtır. Daha sonra, bu dosyaları bir kaynak denetim sistemi kullanarak kolayca yönetebilirsiniz. Aşağıdaki bölümlerde, aracın nasıl çalıştırılacağı ve aracın yönetilen ve yönetilmeyen çözümlerle nasıl kullanılacağı gösterilmektedir.

Important

SolutionPackager aracı, artık çözümlerin ambalajını kaldırmak ve paketlemek için önerilen bir yol değildir. SolutionPackager aracının özellikleri Power Platform CLI'sına eklenir. komutupac solution, , unpack, packve clone gibi syncSolutionPackager aracının aynı temel özelliklerini içeren birçok fiil içerir.

SolutionPackager aracını nerede bulabilirim?

SolutionPackager aracı Microsoft.CrmSdk.CoreTools NuGet paketinin bir parçası olarak dağıtılır. Programı kurmak için aşağıdaki adımları izleyin.

  1. NuGet paketini indirin.
  2. Paket dosya adı uzantısını .nupkg'den .zip'e değiştirin.
  3. Sıkıştırılmış (zip) dosyasının içeriklerini ayıklayın.

<extracted-folder-name>/contents/bin/coretools klasöründe SolutionPackager.exe yürütülebilir dosyasını bulun. Programı coretools klasöründe çalıştırın veya bu klasörü YOLUNUZA ekleyin.

SolutionPackager komut satırı parametreleri

SolutionPackager bir komut satırı aracıdır. Aşağıdaki tabloda açıklanan parametreleri kullanarak çağırabilirsiniz.

Argument Description
/action: {Çıkart|Paketlemek} Gerekli. Gerçekleştirilecek eylem. Eylem, bir çözüm .zip dosyasını bir klasöre ayıklamak veya bir klasörü bir .zip dosyasına paketlemek olabilir.
/zipfile: <dosya yolu> Gerekli. Çözüm .zip dosyasının yolu ve adı. Ayıklama sırasında dosya mevcut ve okunur olmalıdır. Paketleme sırasında dosya değiştirilir.
/folder: <klasör yolu> Gerekli. Klasörün yolu. Ayıklama sırasında bu klasör oluşturulur ve bileşen dosyalarıyla doldurulur. Paketleme sırasında, bu klasör zaten var olmalı ve önceden çıkarılmış bileşen dosyalarını içermelidir.
/packagetype: {Yönetilmeyen|Yönetilen|Her ikisi de} Optional. İşlenecek paket türü. Varsayılan değer Yönetilmeyen'dir. Araç paket türünü .zip dosyasının veya bileşen dosyalarının içinden okuyabildiğinden çoğu durumda bu bağımsız değişkeni atlayabilirsiniz. Ayıklama sırasında İkisi değeri belirtildiğinde yönetilen ve yönetilmeyen çözüm .zip dosyaları var olmalı ve tek bir klasörde işlenmelidir. Paketleme sırasında ve "Both" değeri belirtildiğinde, yönetilen ve yönetilmeyen çözüm .zip dosyaları tek bir klasörden üretilir. Daha fazla bilgi için bu makalede daha sonra açıklanan yönetilen ve yönetilmeyen çözümlerle çalışma bölümüne bakın.
/allowWrite:{Evet|Hayır} Optional. Varsayılan değer Evet'tir. Bu argümanı yalnızca ayıklama sırasında kullanın. /allowWrite:Hayır belirttiğinizde araç tüm işlemleri gerçekleştirir, ancak hiçbir dosyayı yazmaz veya silmez. Var olan dosyaların üzerine yazmadan veya silmeden ayıklama işlemini güvenle test edebilirsiniz.
/allowDelete:{Evet|Hayır|Komut istemi} Optional. Varsayılan değer İstem'dir. Bu argümanı yalnızca bir çıkarma işlemi sırasında kullanın. /allowDelete:Yes belirttiğinizde, araç /folder parametresiyle belirtilen klasörde bulunan beklenmeyen tüm dosyaları otomatik olarak siler. /allowDelete:Hayır belirttiğinizde araç hiçbir dosyayı silmez. /allowDelete:Prompt belirttiğinizde, kullanıcıya konsol üzerinden tüm silme işlemlerine izin vermesi ya da reddetmesi için istem gösterilir. /allowWrite:Hayır belirtilirse, /allowDelete:Evet ayrıca belirtilmiş olsa bile araç hiçbir dosyayı silmez.
/clobber Optional. Bu argümanı yalnızca ayıklama sırasında kullanın. /clobber belirttiğinizde, araç salt okunur özniteliği ayarlanmış dosyaların üzerine yazar veya siler. Aksi belirtilmedikçe, araç salt okunur özniteliğine sahip dosyaların üzerine yazmaz veya onları silmez.
/errorlevel: {Off|Hata|Uyarı|Bilgi|Ayrıntılı} Optional. Varsayılan değer Bilgi'dir. Bu bağımsız değişken, gönderilecek günlük bilgilerinin düzeyini gösterir.
/map: <dosya yolu> Optional. Dosya eşleme yönergeleri içeren bir .xml dosyasının yolu ve adı. Ayıklama sırasında kullanıldığında, araç genellikle eşleme dosyasında belirtilen alternatif konumlardan /folder parametresi tarafından belirtilen klasörün içinden okunan dosyaları okur. Paket işlemi sırasında araç, yönergelerle eşleşen dosyaları yazmaz.
/nologo Optional. Çalışma zamanında banner'ı gizleyin.
/log: <dosya yolu> Optional. Günlük dosyasının yolu ve adı. Dosya zaten mevcutsa, yeni kayıt bilgileri dosyaya eklenir.
<@ dosya yolu> Optional. Araç için komut satırı bağımsız değişkenleri içeren bir dosyanın yolu ve adı.
/sourceLoc: <dize> Optional. Bu bağımsız değişken, bir şablon kaynak dosyası oluşturur ve yalnızca ayıklama sırasında geçerlidir.

Olası değerler, dışarı aktarmak istediğiniz dil için auto veya LCID/ISO kodudur. Bu bağımsız değişkeni kullandığınızda, araç verilen yerel ayar dili/bölge ayarından dize kaynaklarını nötr bir .resx dosyası olarak ayıklar. auto ya da yalnızca anahtarın uzun veya kısa biçimini belirtirseniz, temel yerel ayar veya çözüm kullanılır. Komutun kısa biçimini kullanabilirsiniz: /src.
/localize Optional. Tüm dize kaynaklarını .resx dosyalarına çıkarın veya birleştirin. Komutun kısa formunu kullanabilirsiniz: /loc. Yerelleştir seçeneği, .resx dosyaları için paylaşılan bileşenleri destekler. Daha fazla bilgi için bkz. RESX web kaynaklarını kullanma.
/ÇözümAdı: <name> Optional. Kaynak klasör altında birden çok çözüm olduğunda paketleme veya ayıklama yapılacak çözümün benzersiz adı solutions/*/solution.yml. Birden fazla çözüm algılandığında gereklidir. Yalnızca YAML kaynak denetimi biçimi için geçerlidir. Komutun kısa biçimini kullanabilirsiniz: /sn.
/remapPluginTypeNames Optional. Belirtildiğinde araç, çözüme dahil edilen derlemelere göre eklenti tam nitelikli tür adlarını yeniden eşler. YAML kaynak denetimi biçiminde varsayılan olarak etkindir. Komutun kısa biçimini kullanabilirsiniz: /fp.

Kaynak denetim dosyası biçimleri

SolutionPackager, çözümleri ayıklama ve paketleme sırasında iki klasör düzenini destekler.

XML biçimi (eski)

Özgün biçim. Araç, çözüm meta verilerini Other\Customizations.xml ve Other\Solution.xml içinde depolar. Araç, tüm bileşen dosyalarını bu dosyaların yanında düz bir klasör hiyerarşisine çıkarır. Bu biçim, daha fazla yapılandırma olmadan bir .zip dosyayı dışa çıkardığınızda varsayılan biçimdir.

YAML kaynak denetimi biçimi

Dataverse Git tümleştirmesi ile birlikte sunulan bu biçim, çözüm meta verilerini yapılandırılmış klasör hiyerarşisi arasında dağıtılan YAML dosyaları olarak depolar. Bu, Power Apps yerel Git tümleştirmesini kullanarak çözümleri kaydederken yazılan biçimdir.

XML biçimine göre avantajlar

  • Kaynak denetiminde daha temiz, bileşen başına daha okunabilir farklar üretir.
  • Tek bir depo klasöründe birden çok çözümü destekler.
  • Canvas uygulaması .msapp dosyaları ve modern akışlar yalnızca bu biçimde desteklenir.
  • Eklenti türü adı yeniden eşlemesi varsayılan olarak etkindir.

Gerekli klasör yapısı

<rootFolder>/
├── solutions/
│   └── <SolutionUniqueName>/
│       ├── solution.yml              (solution metadata)
│       ├── solutioncomponents.yml    (paths to all component files)
│       ├── rootcomponents.yml        (root-level components)
│       └── missingdependencies.yml   (dependency info)
├── publishers/
│   └── <PublisherUniqueName>/
│       └── publisher.yml             (publisher definition)
├── entities/                         (entity components, if present)
├── workflows/                        (classic workflows, if present)
├── modernflows/                      (Power Automate cloud flows, if present)
├── canvasapps/                       (canvas app .msapp files, if present)
└── [other component folders]/

Important

solutions/ dosyaları içeren bir *solution.yml alt klasörün varlığı YAML biçimini gösterir. YAML bildirim dosyalarınızı (solution.yml, solutioncomponents.ymlvb.) altında solutions/<SolutionUniqueName>/değil klasörün köküne yerleştirirseniz, araç YAML biçimini algılamaz. Araç XML yoluna geri döner ve eksik Customizations.xml ile ilgili yanıltıcı bir hata raporlar. Bu sorunu giderme hakkında bilgi için bkz. Sorun giderme .

Daha fazla bilgi: Çözüm YAML kaynak denetimi biçimi başvurusu

Otomatik algılama kurallarını biçimlendirme

Condition Kullanılan biçim
solutions/*/solution.yml bulundu — tam olarak bir çözüm ÇÖZÜM adının klasörden çıkarıldığı YAML biçimi
solutions/*/solution.yml bulundu — birden çok çözüm YAML biçiminde /SolutionName argümanının gerekli olduğu durumlar
Alt dizin mevcut değil solutions/ XML biçimi (eski)

YAML biçim klasörünü paketleme

Aşağıdaki komut bir YAML biçim klasörü paketler.

SolutionPackager.exe /action:Pack /zipfile:MySolution.zip /folder:C:\repos\myrepo

Çok çözümlü bir klasörden paketleme

Aşağıdaki komut, belirtilen çözümü çok çözümlü bir klasörde paketler.

SolutionPackager.exe /action:Pack /zipfile:SolutionA.zip /folder:C:\repos\myrepo /SolutionName:SolutionA

/map komutunun bağımsız değişkenini kullanın

Aşağıdaki açıklamada, /map bağımsız değişkeninin SolutionPackager aracında kullanımı ayrıntılı olarak açıklamaktadır.

Silverlight dosyaları ve eklenti derlemeleri gibi .xap otomatik bir derleme sisteminde oluşturulan dosyalar genellikle kaynak denetimine eklenmez. SolutionPackager aracıyla doğrudan uyumlu olmayan konumlarda kaynak denetiminde zaten web kaynaklarınız olabilir. /map parametresini ekleyerek SolutionPackager aracını Ayıkla klasörünün içinden değil alternatif konumlardan bu tür dosyaları okumaya ve paketlemeye yönlendirebilirsiniz. /map parametresi, eşleme yönergeleri içeren bir XML dosyasının adını ve yolunu belirtmelidir. Bu yönergeler, dosyaları adlarıyla yoluna göre eşleştirmek için SolutionPackager'a yönlendirir ve eşleştirilen dosyayı bulmak için alternatif konumu gösterir. Aşağıdaki bilgiler tüm direktifler için eşit olarak geçerlidir.

  • Aynı dosyalarla eşleşen yönergeler de dahil olmak üzere birden çok yönergeyi listeleyebilirsiniz. Dosyanın başında listelenen yönergeler, daha sonra listelenen yönergelere göre önceliklidir.

  • Dosya herhangi bir yönerge ile eşleşiyorsa en az bir alternatif konumda bulunmalıdır. Eşleşen alternatif bulunmazsa SolutionPackager bir hata verir.

  • Klasör ve dosya yolları mutlak veya göreli olabilir. Göreli yollar her zaman /folder parametresi tarafından belirtilen klasörden değerlendirilir.

  • Ortam değişkenlerini %variable% söz dizimini kullanarak belirtin.

  • "Herhangi bir alt klasörde" anlamına gelen bir klasör joker karakteri ** kullanın. Bunu yalnızca yolun son bölümü olarak kullanabilirsiniz, örneğin: c:\folderA\**.

  • Dosya adı joker karakterlerini yalnızca *.ext veya *.* biçimlerinde kullanın. Başka bir desen desteklenmez.

    Aşağıdaki bölümde, yönerge eşlemelerinin üç türü açıklanmakta ve bunların nasıl kullanılacağını gösteren bir örnek verilmektedir.

Klasör eşleme

Aşağıdaki bölümde klasör eşlemesi hakkında ayrıntılı bilgiler sağlanmaktadır.

XML Biçimi

<Folder map="folderA" to="folderB" />

Tanım

"folderA" ile eşleşen dosya yolları "folderB"ye geçer.

  • Her klasörün altındaki alt klasör hiyerarşisi tam olarak eşleşmelidir.

  • Klasör joker karakterleri desteklenmez.

  • Dosya adlarını belirtemezsiniz.

    Examples

    <Folder map="folderA" to="folderB" />  
<Folder map="folderA\folderB" to="..\..\folderC\" />  
<Folder map="WebResources\subFolder" to="%base%\WebResources" />

Dosyadan dosyaya eşleme

Aşağıdaki bilgiler, dosyadan dosyaya eşleme hakkında ayrıntılı bilgi sağlar.

XML Biçimi

<FileToFile map="path\filename.ext" to="path\filename.ext" />

Tanım

map parametresiyle eşleşen tüm dosyalar, to parametresinde belirtilen ad ve yoldan okunur.

map parametresi için:

  • Bir dosya adı belirtin. Yol isteğe bağlı. Yol belirtmezseniz, eşleme herhangi bir klasördeki dosyalarla eşleşebilir.

  • Dosya adı joker karakterleri desteklenmez.

  • Klasör joker karakterlerini destekler.

    to parametresi için:

  • Bir dosya adı ve yol belirtin.

  • Dosya adı, map parametresindeki addan farklı olabilir.

  • Dosya adı joker karakterleri desteklenmez.

  • Klasör joker karakterini destekler.

Examples

  <FileToFile map="assembly.dll" to="c:\path\folder\assembly.dll" />  
  <FileToFile map="PluginAssemblies\**\this.dll" to="..\..\Plugins\**\that.dll" />  
  <FileToFile map="Webresrouces\ardvark.jpg" to="%SRCBASE%\CrmPackage\WebResources\JPG format\aardvark.jpg" />  

  <FileToFile
    map="pluginpackages\cr886_PluginPackageTest\package\cr886_PluginPackageTest.nupkg"
    to="myplg\bin\Debug\myplg.1.0.0.nupkg" />

Yukarıdaki NuGet paketi örneğinde, cr886_PluginPackageTest.nupkg dosya belirtilen konumda zaten varsa üzerine yazılmaz.

Dosya-yol eşlemesi

Aşağıdaki bölümde dosya-yol eşlemesi hakkında ayrıntılı bilgiler sağlanmaktadır.

XML Biçimi

<FileToPath map="path\filename.ext" to="path" />

Tanım

map parametresi eşleşecek dosyayı, to parametresi ise okunacak yolu belirtir.

map parametresi için:

  • Bir dosya adı belirtin. Yol isteğe bağlı. Yol belirtmezseniz, eşleme herhangi bir klasördeki dosyalarla eşleşebilir.

  • Dosya adı joker karakterlerini destekler.

  • Klasör joker karakterini destekler.

to parametresi için:

  • Bir dosya yolu belirtin.

  • Klasör joker karakterini destekler.

  • Dosya adı belirtmeyin.

    Examples

  <FileToPath map="assembly.dll" to="c:\path\folder" />  
  <FileToPath map="PluginAssemblies\**\this.dll" to="..\..\Plugins\bin\**" />  
  <FileToPath map="*.jpg" to="%SRCBASE%\CrmPackage\WebResources\JPG format\" />  
  <FileToPath map="*.*" to="..\..\%ARCH%\%TYPE%\drop" />

Örnek eşleme

Aşağıdaki XML kod örneği, SolutionPackager aracının herhangi bir web kaynağını ve CRMDevTookitSample adlı bir Geliştirici Araç Seti projesinden varsayılan olarak oluşturulan iki derlemeyi okumasını sağlayan eksiksiz bir eşleme dosyasını gösterir.

<?xml version="1.0" encoding="utf-8"?>  
<Mapping>  
       <!-- Match specific named files to an alternate folder -->  
       <FileToFile map="CRMDevTookitSamplePlugins.dll" to="..\..\Plugins\bin\**\CRMDevTookitSample.plugins.dll" />  
       <FileToFile map="CRMDevTookitSampleWorkflow.dll" to="..\..\Workflow\bin\**\CRMDevTookitSample.Workflow.dll" />  
       <!-- Match any file in and under WebResources to an alternate set of subfolders -->  
       <FileToPath map="WebResources\*.*" to="..\..\CrmPackage\WebResources\**" />  
       <FileToPath map="WebResources\**\*.*" to="..\..\CrmPackage\WebResources\**" />  
</Mapping>

Yönetilen ve yönetilmeyen çözümler

Dataverse sıkıştırılmış çözümü (.zip) dosyasını yönetilen veya yönetilmeyen bir çözüm olarak dışarı aktarabilirsiniz.

Yönetilen çözüm
Bir kuruluşa içeri aktarmaya hazır tamamlanmış bir çözüm. İçeri aktarıldıktan sonra bileşen ekleyemez veya kaldıramazsınız, ancak isteğe bağlı olarak daha fazla özelleştirmeye izin verebilirsiniz. Çözümün geliştirilmesi tamamlandığında bu türü kullanın.

Yönetilmeyen çözüm
Neleri ekleyebileceğin, kaldırabileceğin veya değiştirebileceğin konusunda hiçbir kısıtlama olmayan açık bir çözüm. Çözüm geliştirme sırasında bu türü kullanın.

Sıkıştırılmış çözüm dosyasının biçimi, yönetilen veya yönetilmeyen türüne göre farklılık gösterir. SolutionPackager, her iki türdeki sıkıştırılmış çözüm dosyalarını işleyebilir. Ancak araç bir türü başka bir türe dönüştüremez. Çözüm dosyalarını yönetilmeyenden yönetilene gibi farklı bir türe dönüştürmenin tek yolu, yönetilmeyen çözüm .zip dosyasını Dataverse sunucusuna içeri aktarmak ve ardından çözümü yönetilen çözüm olarak dışarı aktarmaktır.

SolutionPackager, /PackageType:Both parametresini kullanarak yönetilmeyen ve yönetilen çözüm .zip dosyalarını birleştirilmiş bir küme olarak işleyebilir. Bu işlemi gerçekleştirmek için çözümünüzü her bir tür olarak birer kez dışa aktarmanız gerekir. .zip dosyalarını aşağıdaki gibi adlandırın:

Yönetilmeyen .zip dosyası: AnyName.zip

Yönetilen .zip dosyası: AnyName_managed.zip

Araç, yönetilen zip dosyasının yönetilmeyen dosyayla aynı klasörde olduğunu varsayar. Her iki dosyayı da tek bir klasöre çıkarır ve yönetilen ve yönetilmeyen bileşenler arasındaki farkları korur.

Bir çözümü hem yönetilmeyen hem de yönetilen olarak dışarı aktardıktan sonra, tek bir klasörden her iki türü veya her türü ayrı ayrı paketleyebilirsiniz. Oluşturulacak türü belirtmek için /PackageType parametresini kullanın. Her iki dosyayı da belirttiğinizde, araç önceki adlandırma kuralını kullanarak iki .zip dosyası oluşturur. Çift yönetilen ve yönetilmeyen bir klasörden paketleme yaparken /PackageType parametresini eklemezseniz, varsayılan değer tek bir yönetilmeyen .zip dosyası oluşturmaktır.

Sorun giderme

Kaynak dosyalarını düzenlemek için Visual Studio kullanılırken görüntülenen ileti

Çözüm paketleyicisi tarafından oluşturulan kaynak dosyalarını düzenlemek için Visual Studio kullanırsanız, şuna benzer bir ileti görebilirsiniz: "Failed to determine version id of the resource file <filename>.resx the resource file must be exported from the solutionpackager.exe tool in order to be used as part of the pack process." Bu ileti görüntülenir çünkü Visual Studio kaynak dosyasının meta veri etiketlerini veri etiketleriyle değiştirir.

Workaround

  1. Kaynak dosyasını sık kullandığınız metin düzenleyicisinde açın ve aşağıdaki etiketleri bulun ve güncelleştirin:

    <data name="Source LCID" xml:space="preserve">  
<data name="Source file" xml:space="preserve">  
<data name="Source package type" xml:space="preserve">  
<data name="SolutionPackager Version" mimetype="application/x-microsoft.net.object.binary.base64">

  2. <data> olan düğüm adını <metadata> olarak değiştirin.

    Örneğin, bu dize:

    <data name="Source LCID" xml:space="preserve">  
  <value>1033</value>  
</data>

    Şu şekilde değişir:

    <metadata name="Source LCID" xml:space="preserve">  
  <value>1033</value>  
</metadata>

    Bu değişiklik, çözüm paketleyicinin kaynak dosyasını okumasına ve içeri aktarmasına olanak tanır. Bu sorun yalnızca Visual Studio Kaynak düzenleyicisini kullandığınızda oluşur.

Hata: YAML klasörüyle "Gerekli dosya ...\Other\Customizations.xmlbulunamıyor"

SolutionPackager'ı (veya pac solution pack ile) solution.yml YAML dosyalarını içeren bir klasörde çalıştırdığınızda, ancak bu dosyaları gerekli solutions/<SolutionUniqueName>/ alt klasörün içine değil klasörün köküne yerleştirdiğinizde bu hata görüntülenir.

Neden: Araç, dosyaları içeren bir solutions/ alt klasör arayarak YAML kaynak denetimi biçimini algılar *solution.yml . Bu dizin olmadığında, araç sessizce XML (eski) biçimine geri döner ve bekler Other\Customizations.xml. Hata iletisi bir XML dosyasına başvurur ve YAML'den bahsetmez ve bu kafa karıştırıcı olabilir.

Düzeltmek: YAML bildirim dosyalarının doğru yolların altında olması için klasörü yeniden düzenleme:

<rootFolder>/
  solutions/<YourSolutionUniqueName>/   ← move solution.yml here
    solution.yml
    solutioncomponents.yml
    rootcomponents.yml
    missingdependencies.yml
  publishers/<YourPublisherUniqueName>/
    publisher.yml

Klasörü bir Git tümleştirmesi commit’inden veya pac solution clone’dan aldıysanız, klasör yapısı zaten doğrudur. Üst düzey YAML dosyalarını içeren ancak solutions/ alt dizini bulunmayan bir klasör, eksik bir ayıklamayı temsil eder ve doğrudan paketlenemez.

Uyarı: rootcomponents.yml'de bildirilen bileşenin kaynak dosyası yok

Bu uyarı, tuval uygulaması gibi bir bileşen içinde rootcomponents.yml listelendiğinde ancak beklenen bileşen klasöründe karşılık gelen kaynak dosya bulunmadığında (örneğin, canvasapps/<schema-name>/) görüntülenir.

Etkisi: Araç yine başarılı olur (çıkış kodu 0) ve geçerli .zip bir dosya oluşturur, ancak bildirilen bileşen paketlenmiş çözümden atlanır.

Neden: Klasör kısmi bir ayıklama tarafından oluşturuldu veya bileşenin kaynak dosyaları depoya dahil edilmedi. Örneğin, yalnızca çözüm bildirim dosyaları işlendi, tuval uygulaması ise işlenmedi.

Düzeltmek: içinde rootcomponents.yml bildirilen tüm bileşenlerin klasörde karşılık gelen kaynak dosyaları olduğundan emin olun. Tuval uygulamaları için .msapp dosyasının canvasapps/<schema-name>/ altında bulunması gerekir. Eksik dosyalar varsa, tam çözümü Dataverse'ten yeniden dışa aktarın ve yeniden paketinden çıkarın veya tam bir ayıklama elde etmek için pac solution clone kullanın.

Ayrıca bakınız

  • Son güncelleştirme: