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

  • Makale

Bu makalede, PowerShell Galerisi'nde yayımlanan paketlerin yaygın olarak benimsenmesini sağlamak ve PowerShell Galerisi'nin bildirim verilerini nasıl işlediğine ve çok sayıda PowerShell Galerisi kullanıcısından gelen geri bildirimlere bağlı olarak 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 uygun olarak 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 yapan, isteğe bağlı Bildirim ayarlarının en önemli olduğu, ilk gözden geçirenlerin geri bildirimleriyle kodunuzun geliştirilmesi ve PowerShell Betik Çözümleyicisi, modülünüzün, belgenizin, testlerinizin ve paylaştıklarınızın nasıl kullanılacağına ilişkin örneklerin sürümüne ilişkin yönergeler verilmiştir. Bu belgelerin çoğu,Yüksek Kaliteli DSC Kaynak Modülleri yayımlama yönergelerini izler.

PowerShell Galerisi'nde paket 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 GitHub belge depomuzdasorunları 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önergelere uyan paketlerin indirilip benimsenmeye devam etme olasılığı çok daha yüksektir.

  • PSScriptAnalyzer kullanma
  • Belgeleri ve örnekleri ekle
  • Geri bildirime 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ına ekleme ve/veya bağlantı
  • Kodunuzu imzalama
  • Sürüm oluşturma için SemVer yönergelerini izleyin
  • Ortak PowerShell Galerisi etiketlerinde belgelendiği gibi ortak etiketleri kullanma
  • Yerel depo kullanarak yayımlamayı test edin
  • 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 çözümleme aracıdır. PSScriptAnalyzer, PowerShell kodunda görülen en yaygın sorunları ve genellikle sorunun nasıl düzeltileceğine ilişkin bir öneriyi belirler. Araç kullanımı kolaydır ve sorunları Hatalar (ciddi, ele alınmalıdır), Uyarı (gözden geçirilmeli ve ele alınmalıdır) ve Bilgi (en iyi yöntemler için kullanıma almaya değer) olarak kategorilere ayırır. PowerShell Galerisi'nde yayımlanan tüm paketler PSScriptAnalyzerkullanılarak taranır ve tüm hatalar sahibine geri bildirilir ve bunların giderilmesi gerekir.

En iyi yöntem, Invoke-ScriptAnalyzer-Recurse ve -Severity Uyarısı ile çalıştırmaktır.

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.

PowerShell Galerisi'nden paket indiren kullanıcıların PSScriptAnalyzer çalıştırmaları ve tüm Hataları ve Uyarıları değerlendirmeleri önemle tavsiye edilir. Kullanıcılar, PSScriptAnalyzertarafından bildirilen bir hata olduğunu görürlerse 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'nde yayımlanan paketlere eklenecek en yararlı şeydir. Kullanıcılar genellikle belgeleri olmayan paketleri atlarlar, alternatif olarak paketin ne olduğunu ve nasıl kullanılacağını anlamak için kodu okumaktır. PowerShell paketleriyle belge sağlama hakkında aşağıdakiler de dahil olmak üzere çeşitli makaleler mevcuttur:

  • Yardım sağlamaya yönelik yönergeler Cmdlet'i Yazma Yardımı.
  • Herhangi bir PowerShell betiği, işlevi veya cmdlet'i için en iyi yaklaşım olan cmdlet yardımı oluşturma. Cmdlet yardımı oluşturma hakkında bilgi için cmdlet YardımıIle başlayın. Betik içine yardım eklemek için bkz. açıklama tabanlı yardım hakkındahakkında .
  • Birçok modül, MarkDown dosyaları gibi metin biçiminde belgeler de içerir. Bu özellikle, Markdown'ın yoğun olarak kullanılan bir biçim olduğu GitHub'da bir proje sitesi olduğunda yararlı olabilir. En iyi yöntem GitHub özellikli Markdownkullanmaktır.

Ö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 simülasyonlu gerçekçi kullanım örneğini gösterir ve kod iyi yorumlanır. PowerShell Galerisi'nde yayımlanan modül örnekleri, modül kökü altındaki Örnekler klasöründe olmalıdır.

Örnekler için iyi bir desen, Examples\RegistryResource klasörünün altındaki PSDscResource modülünde 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önet

Modül Bildirimi'nde modülünüzün bağımlı olduğu modülleri belirtmek önemlidir. Bu, son kullanıcının sizinkinin 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, modülünüzü içeri aktarmadan önce listelenen tüm modülleri önceden yüklenmediği sürece genel ortama yükler. Örneğin, bazı modüller farklı bir modül tarafından zaten yüklenmiş olabilir. ModuleVersion alanı yerine RequiredVersion alanını kullanarak yüklenecek belirli bir sürüm de belirtebilirsiniz. ModuleVersionkullanı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ın, paketi geliştirmeye yardımcı olmak için yeterince ilgilendikleri için yanıt vermesi önemlidir.

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

  • İlgili 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 bir geçici çözüm sağlayın veya güncelleştirmenin bir 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'nin Uygunsuz Kullanımı Bildir özelliğini kullanın.

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

Bir 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'ndeki 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 eder: cmdlet yardımı, belgeler, örnekler ve testler. En büyük dezavantaj, modül 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.

Bir 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 modülle betik olarak yayımlamaktır. Betik, RequiredModules = @(Name of the Module)kullanarak birlikte gelen 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'nde betik yayımlarken açıklama tabanlı belgeler ve Proje Sitesi bağlantısı sağlanması kesinlikle önerilir.

Proje Sitesi, bir yayımcının PowerShell Galerisi paketlerinin kullanıcıları ile doğrudan etkileşim kurabildiği yerdir. Kullanıcılar, paket hakkında daha kolay bilgi almalarına olanak sağladığından bunu sağlayan paketleri tercih eder. PowerShell Galerisi'ndeki birçok paket GitHub'da geliştirilmiştir, diğerleri ise ayrılmış web varlığı olan kuruluşlar tarafından sağlanır. Bunların her biri 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'

Bir 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,uyumluluk kalkanı örneğimiz PowerShell Galerisi uyumluluk kalkanlarımızdan da yararlanabilirsiniz.

Testleri dahil et

Açık kaynak koduna sahip testlerin 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, kullanıcıların kodunuzu ortamlarına uyacak şekilde değiştirmeleri durumunda özgün işlevselliğinizi bozmadığından emin olmalarını sağlar.

Özellikle PowerShell için tasarlanmış olan Pester test çerçevesinden yararlanmak için testlerin yazılması kesinlikle önerilir. Pester GitHub, PowerShell Galleryve Windows 10, Windows Server 2016, WMF 5.0 ve WMF 5.1'de sunulur.

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

Test kapsamı hedefleri,Yüksek Kaliteli Kaynak Modülü belgelerinde vurgulanır ve 70% birim testi kod kapsamı önerilir.

PowerShell Galerisi'nde yayımlanan tüm paketlerin lisans koşullarını belirtmesi veya Kullanım KoşullarıSergile altında yer alan lisansa bağlı olması gerekir. Farklı bir lisans belirtmeye yönelik en iyi yaklaşım, PSDataiçindeki LicenseURI kullanarak lisansa bağlantı sağlamaktır. Daha fazla bilgi için bkz. Paketleri 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 yüksek düzeyde güvence sağlar ve aldıkları kodun kopyasının tam olarak yayımcı tarafından yayımlanan kod olduğunu gösterir. Genel olarak kod imzalama hakkında daha fazla bilgi edinmek için bkz. kod imzalamaya giriş. PowerShell, iki birincil yaklaşım aracılığıyla kod imzalama doğrulamasını destekler:

  • betik dosyalarını imzalama
  • Modül imzalama kataloğu

PowerShell dosyalarının imzalanması, 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, betik yüklendiğinde PowerShell'in doğrulediği herhangi bir .PS1 dosyasına imza eklenebilir. PowerShell, imzalı betiklerin kullanılmasını sağlamak için Yürütme İlkesi cmdlet'leri kullanılarak kısıtlanabilir.

Katalog imzalama modülleri, PowerShell'e sürüm 5.1'de eklenen bir özelliktir. Modülü imzalama Katalog Cmdlet'leri makalesinde ele alınmıştır. Genel bakış bölümünde katalog imzalama işlemi, modüldeki her dosya için bir 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 paket için karma değerinin katalogdakiyle eşleşip eşleşmediğini onaylar. Save-Module imzayı doğrulamaz. Modülün önceki bir sürümü sistemde 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 .PSD1 dosyasında imzayı kullanır. Katalog imzalama ile çalışır, ancak imzalama betiği 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ılıp değiştirildiğini açıklayan genel bir kuraldır. Paketinizin sürümü bildirim verilerine eklenmelidir.

  • Sürüm, 0.1.1 veya 4.11.192gibi noktalarla ayrılmış üç sayısal blok olarak yapılandırılmalıdır.
  • 0 ile 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 0 ile başlamalıdır.
  • İlk sayıdaki değişiklikler (2.0.01.9.9999) sürümler arasındaki önemli ve önemli değişiklikleri gösterir.
  • İkinci sayıdaki (1.11.2) yapılan değişiklikler, modüle yeni cmdlet'ler ekleme gibi özellik düzeyinde değişiklikleri gösterir.
  • Üçüncü numaradaki 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.01.001.0'den bü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 değil, özellikle:

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

Yerel depo kullanarak test edin

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

  • GitHub'da PS Özel Galeri projesi 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 avantajına sahip olursunuz; özellikle bir API anahtarının kullanımını doğrulama ve yayımladığınızda hedefte bağımlılıkların bulunup bulunmadığını belirleme.
  • test deposu olarak bir dosya paylaşımı ayarlayın. Bu kolayca ayarlanabilir, ancak bu bir dosya paylaşımı olduğundan, yukarıda belirtilen doğrulamalar gerçekleşmez. Bu durumda olası bir avantaj, dosya paylaşımının gerekli API anahtarını denetlememesidir, bu nedenle PowerShell Galerisi'nde yayımlamak için kullandığınız anahtarın aynısını kullanabilirsiniz.

Bu çözümlerden herhangi biriyle, Publish-Moduleiçin -Repository parametresinde kullandığınız yeni bir deposutanımlamak için Register-PSRepository kullanın.

Test yayımlama hakkında ek bir nokta: PowerShell Galerisi'nde yayımladığınız herhangi bir paket, yayımlamak istediğiniz pakete bağımlı olmadığını onaylayan operasyon ekibinin yardımı olmadan silinemez. Bu nedenle, test hedefi olarak PowerShell Galerisi'ni desteklemiyoruz ve bunu yapan herhangi bir yayımcıya başvuracağız.

Yayımlamak için PowerShellGet kullanma

Yayımcıların PowerShell Galerisi ile çalışırken Publish-Module ve Publish-Script cmdlet'lerini kullanması kesinlikle önerilir. PowerShell Galerisi'nden yükleme ve PowerShell Galerisi'nde yayımlamayla ilgili önemli ayrıntıları anımsamanıza yardımcı olmak için PowerShellGet oluşturuldu. Bazen, yayımcılar PowerShellGet atlamayı ve yerine NuGet istemcisini veya PackageManagement cmdlet'lerini kullanmayı seçti. Kolayca kaçırılan bir dizi ayrıntı vardır ve bu da çeşitli destek istekleriyle sonuçlanır.

Publish-Module veya Publish-Scriptkullanamamanıza neden olan bir neden varsa lütfen bize bildirin. PowerShellGet GitHub deposunda bir sorun oluşturun ve NuGet veya PackageManagementseçmenize neden olan ayrıntıları sağlayın.

PowerShell Galerisi'nde 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çirenlerden gelen geri bildirimleri kullanın ve PowerShell Betik Çözümleyicisi .
  • 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 eklediğinizden ve proje sitenize bağlantı eklediğinizden emin olarak PowerShell Galerisi'nde kararlı veya Alfa sürümü yayımlayın.
  • Geri bildirim toplayın ve proje sitenizdeki kod üzerinde yineleme yapın, ardından kararlı güncelleştirmeleri PowerShell Galerisi'nde 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'nde 1.0.0 bir sürüm yayımlayın.
  • Geri bildirim toplamaya ve kullanıcı girişine göre kodunuz üzerinde yineleme yapmaya devam edin.