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

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 paketinin ne olduğu, hangi isteğe bağlı Bildirim ayarlarının en önemli olduğu, ilk gözden geçirenlerden ve Powershell Betik Çözümleyicisi'nden gelen geri bildirimlerle kodunuzu geliştirme, modülünüzün sürümünü oluşturma, belgeler, testler ve paylaştıklarınızı nasıl kullanacağınıza ilişkin örnekler ile ilgili yönergeler yer almaktadır. Bu belgelerin çoğu, Yüksek Kaliteli DSC Kaynak Modülleri yayımlama yönergelerini izler.

PowerShell Galerisi'nde paket yayımlama mekaniği için bkz.

Bu yönergelerle ilgili geri bildirimler memnuniyetle karşılanır. Geri bildiriminiz varsa, lütfen GitHub belge depomuzdaki sorunları 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 analiz 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 tanımlar. 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 yayımlanan tüm paketler PSScriptAnalyzer kullanılarak taranır ve tüm hatalar sahibine geri bildirilir ve ele alınmalıdır.

En iyi uygulama 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.

PowerShell Galerisi'nden paket indiren kullanıcıların PSScriptAnalyzer'ı çalıştırmaları ve tüm Hataları ve Uyarıları değerlendirmeleri kesinlikle önerilir. Kullanıcılar, PSScriptAnalyzer tarafından bildirilen bir hata olduğunu görürlerse paket sahipleriyle iletişim kurma 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ğlama yönergeleri Cmdlet Yardımı Yazma bölümündedir.
• 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ı Yazma ile başlayın. Bir komut dosyası içinde yardım eklemek için, bkz: Açıklama Tabanlı Yardım Hakkı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 aromalı Markdown kullanmaktı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, 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ö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ü belirtmek de mümkündür. ModuleVersion kullanırken, belirtilen sürümün en azı ile mevcut en yeni sürümü yükleyecektir. RequiredVersion alanını kullanmadığınızda, belirli bir sürümü belirtmek için gerekli modüle yönelik 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. Komut dosyası, eşlik eden modülü kullanarak RequiredModules = @(Name of the Module)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 sitesine bağlantı sağlama

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 PowerShell Galerisi uyumluluk kalkanları de 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'da ve PowerShell Galerisi'nde mevcuttur ve Windows 10, Windows Server 2016, WMF 5.0 ve WMF 5.1'de gönderilir.

GitHub'daki Pester proje sitesi, başlangıçtan en iyi uygulamalara kadar Pester testleri yazmaya ilişkin iyi belgeler içerir.

Test kapsamı hedefleri, Yüksek Kaliteli Kaynak Modülü belgelerinde belirtilir ve 70% birim test kodu kapsamı önerilir.

Lisans koşullarına ekleme ve/veya bağlantı

PowerShell Galerisi'nde yayımlanan tüm paketler lisans koşullarını belirtmeli veya Ek A altındaki Kullanım Koşulları'nda yer alan lisansa bağlı olmalıdır. 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 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 İmzalamaya 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ın nasıl imzalanacağına ilişkin ayrıntılar İmzalama Hakkında makalesinde ele alınmıştır. Genel bakışta, betik yüklendiğinde PowerShell'in doğruladığı herhangi .PS1 bir dosyaya 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. Bir modülün nasıl imzalanacağı 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 imzanın geçerli olduğundan emin olmak için imzayı denetler ve ardından her paketin karma değerinin katalogdakiyle eşleştiğini onaylar. Save-Module imzayı doğrulamaz. Sistemde modülün önceki bir sürümü kuruluysa, Install-Module yeni sürüm için imzalama yetkisinin daha önce kurulu olanla eşleştiğini onaylar. Install-Module ve Update-Module paket katalog imzalı değilse imzayı bir .PSD1 dosyada 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 kolay yorumlanmasına izin vermek için bir sürümün nasıl yapılandırılacağını ve değiştirileceğini açıklayan genel bir kuraldır. Paketinizin sürümü bildirim verilerine eklenmelidir.

• Sürüm, veya 4.11.192gibi 0.1.1 noktalarla ayrılmış üç sayısal blok olarak yapılandırılmalıdır.
• ile başlayan 0 sürümler, paketin henüz üretime hazır olmadığını gösterir ve ilk sayı yalnızca kullanılan tek sayı buysa ile 0 başlamalıdır.
• İlk sayıdaki (1.9.9999 ila 2.0.0) değişiklikler, sürümler arasındaki büyük ve hataya neden olan değişiklikleri gösterir.
• İkinci sayıda (1.1 ile ) 1.2yapılan değişiklikler, modüle yeni cmdlet'ler ekleme gibi özellik düzeyindeki 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 dizeler 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 değil, özellikle:

• Sürüm numaralarında yayın öncesi dizeleri desteklemez. Bu, bir yayıncı bir sürüm 1.0.0sağ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 ve PowerShellGet cmdlet'lerinin gelecekteki bir sürümünde desteklenecektir.
• PowerShell ve PowerShell Galerisi 1, 2 ve 4 kesimli sürüm dizelerine izin verir. İlk modüllerin çoğu yönergelere uymadı 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 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'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 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, parametresinde -RepositoryPublish-Modulekullandığınız yeni bir depo tanımlamak için kullanınRegister-PSRepository.

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 ve Publish-Script cmdlet'lerini kullanmaları Publish-Module kesinlikle önerilir. PowerShellGet, PowerShell Galerisi'nden yükleme ve PowerShell Galerisi'nde yayımlama ile ilgili önemli ayrıntıları hatırlamaktan kaçınmanıza yardımcı olmak için oluşturulmuştur. Bazen yayımcılar PowerShellGet'i atlamayı ve bunun Publish-Moduleyerine NuGet istemcisini veya PackageManagement cmdlet'lerini kullanmayı seçmiştir. Kolayca kaçırılan bir dizi ayrıntı vardır ve bu da çeşitli destek istekleriyle sonuçlanır.

Kullanamadığınız Publish-Module bir neden varsa veya Publish-Script, lütfen bize bildirin. PowerShellGet GitHub deposunda bir sorun bildirin ve NuGet veya PackageManagement'ı seçmenize neden olan ayrıntıları sağlayın.

Önerilen iş akışı

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 ve PowerShell Betik Çözümleyicisi'nden gelen geri bildirimleri 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 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 hissettiğinizde PowerShell Galerisi'nde bir 1.0.0 sürüm yayımlayın.
• Geri bildirim toplamaya ve kullanıcı girişine göre kodunuz üzerinde yineleme yapmaya devam edin.