PowerShellGallery Yayımlama Yönergeleri ve En İyi Yöntemler

  • Makale

Bu makalede, PowerShell Galerisi yayımlanan paketlerin yaygın olarak benimsenmesini sağlamak ve PowerShell Galerisi bildirim verilerini nasıl işlediğine ve çok sayıda PowerShell Galerisi kullanıcıdan gelen geri bildirimlere göre kullanıcılara yüksek değer sağlamak için Microsoft ekipleri tarafından kullanılan önerilen adımlar açıklanmaktadır. Bu yönergelere göre yayımlanan paketlerin yüklenmesi, güvenilir olması ve daha fazla kullanıcı çekmesi daha olasıdır.

Aşağıda, iyi bir PowerShell Galerisi paketi oluşturan, isteğe bağlı Bildirim ayarlarının en önemli olduğu, ilk gözden geçirenlerin ve PowerShell Betik Çözümleyicisi'nin geri bildirimleriyle kodunuzu geliştiren, modülünüzü, belgelerinizi, testlerinizi ve paylaştıklarınızı nasıl kullanacağınıza ilişkin örnekleri içeren yönergeler verilmiştir. Bu belgelerin büyük bölümü , Yüksek Kaliteli DSC Kaynak Modülleri yayımlama yönergelerini izler.

bir paketi PowerShell Galerisi yayımlama mekanizması için bkz. Paket Oluşturma ve Yayımlama.

Bu yönergelerle ilgili geri bildirimler memnuniyetle karşılanır. Geri bildiriminiz varsa lütfen Sorunları GitHub belge depomuzda açın.

Paketleri yayımlamak için en iyi yöntemler

Aşağıdaki en iyi yöntemler, PowerShell Galerisi öğelerinin kullanıcılarının önemli olduğunu söyledikleri ve nominal öncelik sırasına göre listelendiği uygulamalardır. Bu yönergeleri izleyen paketlerin başkaları tarafından indirilip benimsenmiş olma olasılığı çok daha yüksektir.

  • PSScriptAnalyzer kullanma
  • Belgeleri ve örnekleri ekle
  • Geri bildirimlere yanıt verme
  • Betikler yerine modüller sağlama
  • Proje sitesine bağlantılar sağlama
  • Paketinizi uyumlu PSEdition'lar ve platformlarla etiketleme
  • Modüllerinize test ekleme
  • Lisans koşullarını dahil etme ve/veya bağlantı
  • Kodunuzu imzalama
  • Sürüm oluşturma için SemVer yönergelerini izleyin
  • Ortak PowerShell Galerisi etiketleri'nde belgelendiği gibi ortak etiketleri kullanma
  • Yerel depo kullanarak yayımlamayı test etme
  • Yayımlamak için PowerShellGet kullanma

Bunların her biri aşağıdaki bölümlerde kısaca ele alınmıştır.

PSScriptAnalyzer kullanma

PSScriptAnalyzer , PowerShell kodu üzerinde çalışan ücretsiz bir statik kod analizi aracıdır. PSScriptAnalyzer , PowerShell kodunda görülen en yaygın sorunları belirler ve genellikle sorunun nasıl düzeltileceğine ilişkin bir öneri sunar. Araç kullanımı kolaydır ve sorunları Hatalar (ciddi, ele alınmalıdır), Uyarı (gözden geçirilmesi ve ele alınması gerekir) ve Bilgi (en iyi yöntemler için kullanıma değer) olarak kategorilere ayırır. PowerShell Galerisi yayımlanan tüm paketler PSScriptAnalyzer kullanılarak taranır ve hatalar sahibine geri bildirilir ve düzeltilmesi gerekir.

En iyi yöntem ve -Severity Uyarı ile -Recurse çalıştırmaktırInvoke-ScriptAnalyzer.

Sonuçları gözden geçirin ve şunların olduğundan emin olun:

  • Tüm Hatalar belgelerinizde düzeltilir veya giderilir.
  • Tüm Uyarılar gözden geçirilir ve uygun olduğunda ele alınıyor.

paketleri PowerShell Galerisi indiren kullanıcıların PSScriptAnalyzer'ı çalıştırmaları ve tüm Hataları ve Uyarıları değerlendirmeleri önemle tavsiye edilir. Kullanıcıların , PSScriptAnalyzer tarafından bildirilen bir hata olduğunu görmeleri durumunda paket sahiplerine başvurma olasılığı çok yüksektir. Paketinizin hata olarak işaretlenmiş kodu tutması için cazip bir neden varsa, aynı soruyu birçok kez yanıtlamak zorunda kalmamak için bu bilgileri belgelerinize ekleyin.

Belgeleri ve örnekleri ekle

Belgeler ve örnekler, kullanıcıların paylaşılan kodlardan yararlanabilmesini sağlamanın en iyi yoludur.

Belgeler, PowerShell Galerisi yayımlanan paketlere dahil etmek için en yararlı şeydir. Alternatif olarak, paketin ne olduğunu ve nasıl kullanılacağını anlamak için kodu okumak olduğundan, kullanıcılar genellikle belgeleri olmadan paketleri atlar. PowerShell paketleriyle belge sağlama hakkında aşağıdakiler de dahil olmak üzere çeşitli makaleler mevcuttur:

Örnekler, kullanıcılara paketin nasıl kullanılmaya yönelik olduğunu gösterir. Birçok geliştirici, bir şeyin nasıl kullanılacağını anlamak için belgelerden önce örneklere baktıklarını söyler. En iyi örnek türleri temel kullanımın yanı sıra sanal gerçekçi kullanım örneğini gösterir ve kod iyi yorumlanır. PowerShell Galerisi yayımlanan modüllerin örnekleri, modül kökü altındaki Örnekler klasöründe olmalıdır.

Örnekler için iyi bir desen, klasörün altındaki PSDscResource modülündeExamples\RegistryResource bulunabilir. Her dosyanın en üstünde, nelerin gösterildiğini belgeleyen kısa bir açıklama içeren dört örnek kullanım örneği vardır.

Bağımlılıkları Yönetme

Modül Bildirimi'nde modülünüzün bağımlı olduğu modülleri belirtmek önemlidir. Bu, son kullanıcının sizinkilerin bağımlılık yaptığı modüllerin uygun sürümlerini yükleme konusunda endişelenmesine gerek kalmaz. Bağımlı modülleri belirtmek için modül bildiriminde gerekli modül alanını kullanmanız gerekir. Bu işlem, önceden yüklenmedikleri sürece modülünüzü içeri aktarmadan önce listelenen modülleri genel ortama yükler. Örneğin, bazı modüller farklı bir modül tarafından zaten yüklenmiş olabilir. Ayrıca ModuleVersion alanı yerine RequiredVersion alanını kullanarak yükleneceğini belirli bir sürüm belirtmek de mümkündür. ModuleVersion kullanırken, belirtilen en düşük sürümle kullanılabilen en yeni sürümü yükler. RequiredVersion alanını kullanmadığınızda, belirli bir sürümü belirtmek için gerekli modüldeki sürüm güncelleştirmelerini izlemek önemlidir. Modülünüzdeki kullanıcı deneyimini etkileyebilecek hataya neden olabilecek değişikliklerden haberdar olmak özellikle önemlidir.

Example: RequiredModules = @(@{ModuleName="myDependentModule"; ModuleVersion="2.0"; Guid="cfc45206-1e49-459d-a8ad-5b571ef94857"})

Example: RequiredModules = @(@{ModuleName="myDependentModule"; RequiredVersion="1.5"; Guid="cfc45206-1e49-459d-a8ad-5b571ef94857"})

Geri bildirime yanıt verme

Geri bildirimlere düzgün bir şekilde yanıt veren paket sahipleri topluluk tarafından çok değerlidir. Yapıcı geri bildirim sağlayan kullanıcılar, paketi geliştirmeye yardımcı olmak için paketle yeterince ilgilendikleri için yanıt vermeleri önemlidir.

PowerShell Galerisi bir geri bildirim yöntemi vardır:

  • Kişi Sahibi: Bu, kullanıcının paket sahibine e-posta göndermesine olanak tanır. Paket sahibi olarak, PowerShell Galerisi paketleriyle kullanılan e-posta adresini izlemek ve ortaya çıkarılan sorunlara yanıt vermek önemlidir. Bu yöntemin bir dezavantajı, yalnızca kullanıcı ve sahibin iletişimi görmesidir, bu nedenle sahibin aynı soruyu birçok kez yanıtlaması gerekebilir.

Geri bildirimlere yapıcı bir şekilde yanıt veren sahipler topluluk tarafından takdir edilir. Daha fazla bilgi istemek için rapordaki fırsatı kullanın. Gerekirse geçici bir çözüm sağlayın veya bir güncelleştirmenin sorunu giderip gidermediğini belirleyin.

Bu iletişim kanallarından herhangi birinde uygunsuz davranış gözlemleniyorsa, Galeri Yöneticilerine başvurmak için PowerShell Galerisi Kötüye Kullanımı Bildir özelliğini kullanın.

Modüller ve Betikler Karşılaştırması

Betiği diğer kullanıcılarla paylaşmak harikadır ve diğer kullanıcılara sahip olabilecekleri sorunların nasıl çözülebileceğine yönelik örnekler sağlar. Sorun, PowerShell Galerisi betiklerin ayrı belgeler, örnekler ve testler içermeyen tek dosyalar olmasıdır.

PowerShell Modülleri, pakete birden çok klasör ve dosyanın eklenmesini sağlayan bir klasör yapısına sahiptir. Modül yapısı, en iyi yöntemler olarak listelediğimiz diğer paketleri de dahil edebilir: cmdlet yardımı, belgeler, örnekler ve testler. En büyük dezavantaj, modülün içindeki bir betiğin kullanıma sunulmalı ve işlev olarak kullanılmalıdır. Modül oluşturma hakkında bilgi için bkz. Windows PowerShell Modülü Yazma.

Betiğin özellikle DSC yapılandırmalarında kullanıcı için daha iyi bir deneyim sağladığı durumlar vardır. DSC yapılandırmaları için en iyi yöntem, yapılandırmayı belgeleri, örnekleri ve testleri içeren bir eşlik eden modülle betik olarak yayımlamaktır. Betik, kullanarak RequiredModules = @(Name of the Module)eşlik eden modülü listeler. Bu yaklaşım herhangi bir betikle kullanılabilir.

Diğer en iyi yöntemleri izleyen tek başına betikler diğer kullanıcılara gerçek değer sağlar. PowerShell Galerisi betik yayımlarken açıklama tabanlı belgeler ve Proje Sitesi bağlantısı sağlanması kesinlikle önerilir.

Proje Sitesi, yayımcının PowerShell Galerisi paketlerinin kullanıcılarıyla doğrudan etkileşim kurabildiği yerdir. Kullanıcılar, paket hakkında daha kolay bilgi almalarını sağladığından bunu sağlayan paketleri tercih eder. PowerShell Galerisi birçok paket GitHub'da geliştirilir, diğerleri ise ayrılmış web varlığı olan kuruluşlar tarafından sağlanır. Bunların her biri bir proje sitesi olarak kabul edilebilir.

Bağlantı ekleme işlemi, bildirimin PSData bölümüne ProjectURI'yi aşağıdaki gibi ekleyerek yapılır:

  # A URL to the main website for this project.
  ProjectUri = 'https://github.com/powershell/powershell'

ProjectURI sağlandığında, PowerShell Galerisi paket sayfasının sol tarafındaki Proje Sitesi'ne bir bağlantı içerir.

Paketinizi uyumlu PSEdition'lar ve platformlarla etiketleme

Kullanıcılara ortamlarıyla hangi paketlerin iyi çalışacağını göstermek için aşağıdaki etiketleri kullanın:

  • PSEdition_Desktop: Windows PowerShell ile uyumlu paketler
  • PSEdition_Core: PowerShell 6 ve üzeri ile uyumlu paketler
  • Windows: Windows İşletim Sistemi ile uyumlu paketler
  • Linux: Linux İşletim Sistemleri ile uyumlu paketler
  • MacOS: Mac İşletim Sistemi ile uyumlu paketler

Paketinizi uyumlu platformlarla etiketleyerek, arama sonuçlarının sol bölmesindeki Galeri arama filtrelerine eklenir. Paketinizi GitHub'da barındırıyorsanız, paketinizi etiketlediğinizde PowerShell Galerisi uyumluluk kalkanlarıuyumluluk kalkanı örneğimizden de yararlanabilirsiniz.

Testleri dahil etme

Testlerin açık kaynak kodla dahil edilmesi, kullanıcılara neyi doğruladığınız konusunda güvence sağladığı ve kodunuzun nasıl çalıştığı hakkında bilgi verdiği için önemlidir. Ayrıca, kodunuzu ortamlarına uyacak şekilde değiştirirlerse kullanıcıların özgün işlevselliğinizi bozmadığından emin olmalarını sağlar.

PowerShell için özel olarak tasarlanmış olan Pester test çerçevesinden yararlanmak için testlerin yazılması kesinlikle önerilir. Pester GitHub, PowerShell Galerisi ve Windows 10, Windows Server 2016, WMF 5.0 ve WMF 5.1 ile birlikte sunulur.

GitHub'daki Pester proje sitesi, başlarken en iyi uygulamalara kadar Pester testleri yazmaya yönelik iyi belgeler içerir.

Test kapsamı hedefleri, %70 birim testi kod kapsamı önerilen Yüksek Kaliteli Kaynak Modülü belgelerinde vurgulanmıştır.

PowerShell Galerisi yayımlanan tüm paketlerin lisans koşullarını belirtmesi veya Sergi A altındaki Kullanım Koşulları'na dahil edilen lisansa bağlı olması gerekir. Farklı bir lisans belirtmeye yönelik en iyi yaklaşım, PSData'dakiLicenseURI'yi kullanarak lisansa bir bağlantı sağlamaktır. Daha fazla bilgi için bkz . Paketler bildirimi ve Galeri kullanıcı arabirimi.

PrivateData = @{
    PSData = @{

        # Tags applied to this module. These help with module discovery in online galleries.
        Tags = @('.net','acl','active-directory')

        # A URL to the license for this module.
        LicenseUri = 'http://www.apache.org/licenses/LICENSE-2.0'

Kodunuzu imzalama

Kod imzalama, kullanıcılara paketi kimin yayımladığı konusunda en üst düzeyde güvence sağlar ve aldıkları kodun kopyasının yayımcının yayımladığı kopya olduğunu gösterir. Kod imzalama hakkında genel olarak daha fazla bilgi edinmek için bkz. Kod İmzalama'ya giriş. PowerShell, iki birincil yaklaşım aracılığıyla kod imzalama doğrulamasını destekler:

  • İmzalama betiği dosyaları
  • Modül katalog imzalama

PowerShell dosyalarını imzalama, yürütülen kodun güvenilir bir kaynak tarafından oluşturulduğundan ve değiştirilmediğinden emin olmak için iyi oluşturulmuş bir yaklaşımdır. PowerShell betik dosyalarını imzalama hakkındaki ayrıntılar İmzalama Hakkında makalesinde ele alınmıştır. Genel bakış bölümünde, PowerShell'in betik yüklendiğinde doğrulediği herhangi bir .PS1 dosyaya imza eklenebilir. PowerShell, imzalı betiklerin kullanıldığından emin olmak için Yürütme İlkesi cmdlet'leri kullanılarak kısıtlanabilir.

Katalog imzalama modülleri, Sürüm 5.1'de PowerShell'e eklenen bir özelliktir. Modül imzalama, Katalog Cmdlet'leri makalesinde ele alınmıştır. Genel bakış açısından katalog imzalama işlemi, modüldeki her dosya için karma değeri içeren bir katalog dosyası oluşturup bu dosyayı imzalayarak gerçekleştirilir.

PowerShellGetPublish-Module, Install-Moduleve Update-Module cmdlet'leri geçerli olduğundan emin olmak için imzayı denetler, ardından her paketin karma değerinin katalogdaki değerle eşleşip eşleşmediğini onaylar. Save-Module bir imzayı doğrulamaz. Sistemde modülün önceki bir sürümü yüklüyse, Install-Module yeni sürüm için imzalama yetkilisinin daha önce yüklenmiş olanla eşleşeceğini onaylar. Install-Module ve Update-Module paket katalog imzalı değilse bir .PSD1 dosyada imzayı kullanır. Katalog imzalama ile çalışır ancak imzalama betik dosyalarının yerini almaz. PowerShell, modül yükleme zamanında katalog imzalarını doğrulamaz.

Sürüm oluşturma için SemVer yönergelerini izleyin

SemVer , değişikliklerin kolayca yorumlanmasını sağlamak için bir sürümün nasıl yapılandırıldığını ve değiştirildiğini açıklayan genel bir kuraldır. Paketinizin sürümü bildirim verilerine eklenmelidir.

  • Sürüm, veya 4.11.192gibi noktalarla ayrılmış üç sayısal blok olarak 0.1.1 yapılandırılmalıdır.
  • ile 0 başlayan sürümler paketin henüz üretime hazır olmadığını gösterir ve ilk sayı yalnızca kullanılan tek sayıysa ile 0 başlamalıdır.
  • İlk sayıdaki değişiklikler (1.9.9999 için 2.0.0) sürümler arasındaki büyük ve hataya neden olan değişiklikleri gösterir.
  • İkinci sayıya yapılan değişiklikler (1.1 için ) bir modüle 1.2yeni cmdlet'ler ekleme gibi özellik düzeyindeki değişiklikleri gösterir.
  • Üçüncü sayıda yapılan değişiklikler yeni parametreler, güncelleştirilmiş örnekler veya yeni testler gibi hataya neden olmayan değişiklikleri gösterir.
  • Sürümleri listelerken PowerShell sürümleri dize olarak sıralar, bu nedenle 1.01.0 değerinden 1.001.0büyük olarak değerlendirilir.

PowerShell, SemVer yayımlanmadan önce oluşturulmuştur, bu nedenle SemVer'in çoğu için destek sağlar ancak SemVer'in tüm öğeleri için özellikle destek sağlamaz:

  • Sürüm numaralarındaki yayın öncesi dizeleri desteklemez. Bu, bir yayımcı sürümü sağladıktan 1.0.0sonra yeni bir ana sürümün önizleme sürümünü sunmak istediğinde kullanışlıdır. Bu, PowerShell Galerisi ve PowerShellGet cmdlet'lerinin gelecek sürümlerinde desteklenecektir.
  • PowerShell ve PowerShell Galerisi 1, 2 ve 4 segmentli sürüm dizelerine izin verir. İlk modüllerin birçoğu yönergeleri izlemedi ve Microsoft'un ürün sürümleri derleme bilgilerini 4. sayı bloğu olarak içerir (örneğin 5.1.14393.1066). Sürüm oluşturma açısından bu farklar yoksayılır.

Yerel depo kullanarak test edin

PowerShell Galerisi, yayımlama işlemini test etmek için hedef olarak tasarlanmamıştır. PowerShell Galerisi yayımlama işlemini uçtan uca test etmenin en iyi yolu kendi yerel deponuzu ayarlamak ve kullanmaktır. Bu, aşağıdakiler de dahil olmak üzere birkaç yolla yapılabilir:

  • GitHub'daki PS Özel Galeri projesini kullanarak yerel bir PowerShell Galerisi örneği ayarlayın. Bu önizleme projesi, denetleyebileceğiniz ve testleriniz için kullanabileceğiniz bir PowerShell Galerisi örneği ayarlamanıza yardımcı olur.
  • bir iç Nuget deposu ayarlayın. Bunun ayarlanması için daha fazla çalışma gerekir, ancak gereksinimlerin birkaçını daha doğrulama, özellikle api anahtarının kullanımını doğrulama ve yayımladığınızda hedefte bağımlılıkların bulunup bulunmadığını doğrulama avantajına sahip olursunuz.
  • Test deposu olarak bir dosya paylaşımı ayarlayın. Bunu ayarlamak kolaydır, ancak bu bir dosya paylaşımı olduğundan, yukarıda belirtilen doğrulamalar gerçekleşmez. Bu durumda, dosya paylaşımının gerekli API anahtarını denetlememesi, dolayısıyla PowerShell Galerisi yayımlamak için kullandığınız anahtarın aynısını kullanabilmeniz olasıdır.

Bu çözümlerden herhangi biriyle, parametresinde -Repository kullandığınız yeni bir depo tanımlamak için Publish-ModulekullanınRegister-PSRepository.

Test yayımlama hakkında ek bir nokta: PowerShell Galerisi yayımladığınız hiçbir paket, yayımlamak istediğiniz pakete bağlı olmadığını onaylayan operasyon ekibinin yardımı olmadan silinemez. Bu nedenle test hedefi olarak PowerShell Galerisi desteklemiyoruz ve bunu yapan herhangi bir yayımcıyla iletişime geçeceğiz.

Yayımlamak için PowerShellGet kullanma

Yayımcıların PowerShell Galerisi çalışırken ve Publish-Script cmdlet'lerini kullanması Publish-Module kesinlikle önerilir. PowerShellGet, PowerShell Galerisi yükleme ve PowerShell Galerisi yayımlama hakkındaki önemli ayrıntıları hatırlamamanıza yardımcı olmak için oluşturulmuştur. Bazen, yayımcılar PowerShellGet'i atlamayı ve yerine NuGet istemcisini veya PackageManagement cmdlet'lerini kullanmayı seçti.Publish-Module Kolayca gözden kaçırılan bir dizi ayrıntı vardır ve bu da çeşitli destek isteklerine neden olur.

veya Publish-Scriptöğesini kullanamamanıza Publish-Module neden olan bir neden varsa lütfen bize bildirin. PowerShellGet GitHub deposunda bir sorun oluşturun ve NuGet veya PackageManagement'ı seçmenize neden olan ayrıntıları sağlayın.

PowerShell Galerisi yayımlanan paketler için bulduğumuz en başarılı yaklaşım şudur:

  • İlk geliştirmeyi açık kaynak proje sitesinde yapın. PowerShell Ekibi GitHub kullanır.
  • Kodu kararlı duruma getirmek için gözden geçirenlerin ve PowerShell Betik Çözümleyicisi'nin geri bildirimlerini kullanın.
  • Başkalarının çalışmanızı nasıl kullanacağınızı bilmesi için belgeleri ekleyin.
  • Yerel depo kullanarak yayımlama eylemini test edin.
  • Belgeleri ve proje sitenizin bağlantısını eklediğinizden emin olarak PowerShell Galerisi kararlı veya Alfa sürümü yayımlayın.
  • Geri bildirim toplayın ve proje sitenizdeki kodu yineleyin, ardından PowerShell Galerisi kararlı güncelleştirmeler yayımlayın.
  • Projenize ve modülünüze örnekler ve Pester testleri ekleyin.
  • Paketinizi kodla imzalamak isteyip istemediğinize karar verin.
  • Projenin üretim ortamında kullanıma hazır olduğunu düşünüyorsanız, PowerShell Galerisi bir 1.0.0 sürüm yayımlayın.
  • Geri bildirim toplamaya ve kullanıcı girişine göre kodunuzu yinelemeye devam edin.