.NET projeniz için doğru PowerShell NuGet paketini seçme

PowerShell ekibi, her PowerShell sürümüyle birlikte yayınlanan pwsh yürütülebilir paketlerinin yanı sıra NuGet'te kullanılabilen çeşitli paketlere de sahiptir. Bu paketler, PowerShell'in .NET'te bir API platformu olarak hedeflenmesine olanak tanır.

API'ler sağlayan ve kendi (ikili modüller) uygulayan .NET kitaplıklarını yüklemeyi bekleyen bir .NET uygulaması olarak PowerShell'in bir NuGet paketi biçiminde mevcut olması önemlidir.

Şu anda PowerShell API yüzey alanının bazı temsillerini sağlayan birkaç NuGet paketi bulunmaktadır. Belirli bir projede hangi paketin kullanılacağı her zaman netlik kazanmamıştır. Bu makale, PowerShell'i hedefleyen .NET projelerine yönelik birkaç yaygın senaryoya ve PowerShell odaklı .NET projeniz için hedeflenecek doğru NuGet paketinin nasıl seçileceğine ışık tutmaktadır.

Barındırma ve referanslama

Bazı .NET projeleri, önceden var olan bir PowerShell çalışma zamanına (pwsh, powershell.exe, PowerShell Tümleşik Konsolu veya ISE gibi) yüklenecek kod yazmaya çalışır. bazıları ise PowerShell'i kendi uygulamalarında çalıştırmak ister.

• Referanslama, genellikle bir modül olan bir projenin PowerShell'e yüklenmesinin amaçlandığı durumlar içindir. Onunla etkileşim kurmak için PowerShell'in sağladığı API'lere göre derlenmesi gerekir, ancak PowerShell uygulaması onu yükleyen PowerShell işlemi tarafından sağlanır. Referans vermek için bir proje, derleme hedefi olarak referans derlemelerini veya gerçek çalışma zamanı derlemelerini kullanabilir, ancak bunların hiçbirini kendi yapısıyla birlikte yayınlamadığından emin olmalıdır.
• Barındırma, genellikle PowerShell'i çalıştırması gereken bağımsız bir uygulama olması nedeniyle bir projenin kendi PowerShell uygulamasına ihtiyaç duymasıdır. Bu durumda saf referans düzenekleri kullanılamaz. Bunun yerine somut bir PowerShell uygulamasına güvenilmelidir. Somut bir PowerShell uygulamasının kullanılması gerektiğinden, barındırma için belirli bir PowerShell sürümü seçilmelidir; tek bir ana bilgisayar uygulaması PowerShell sürümlerini çoklu hedefleyemez.

Referans olarak PowerShell'i hedefleyen projeleri yayınlama

Yalnızca derleme referans hedefleri olarak kullanılan proje bağımlılıklarının yayınlanmasını önlemek için PrivateAssets niteliğinin ayarlanması önerilir:

<PackageReference Include="PowerShellStandard.Library" Version="5.1.0.0" PrivateAssets="all" />

Bunu yapmayı unutursanız ve hedefiniz olarak bir referans derlemesi kullanırsanız, gerçek uygulama yerine referans derlemenin varsayılan uygulamasını kullanmayla ilgili sorunlar görebilirsiniz. Referans derlemeleri genellikle yalnızca null değerini döndürerek uygulama API'sini taklit ettiğinden, bu bir NullReferenceException biçimini alabilir.

PowerShell'i hedefleyen .NET projelerinin temel türleri

Herhangi bir .NET kitaplığı veya uygulaması PowerShell'i katıştırabilir ancak PowerShell API'lerini kullanan bazı yaygın senaryolar vardır:

• PowerShell ikili modülünü uygulama

  PowerShell ikili modülleri, sırasıyla cmdlet'leri veya sağlayıcıları kullanıma sunmak için PSCmdlet veya CmdletProvider türleri gibi PowerShell API'lerini uygulaması gereken PowerShell tarafından yüklenen .NET kitaplıklarıdır. Yüklendikleri için modüller, yapılarında yayınlamadan PowerShell referanslarına göre derlemeye çalışır. Modüllerin birden fazla PowerShell sürümünü ve platformunu, ideal olarak minimum disk alanı yükü, karmaşıklık veya tekrarlanan uygulama yükü ile desteklemek istemesi de yaygındır. Modüller hakkında daha fazla bilgi için about_Modules'a bakın.

• PowerShell Ana Bilgisayarını Uygulama

  PowerShell Ana Bilgisayarı, PowerShell çalışma zamanı için bir etkileşim katmanı sağlar. Bu, PSHost'un PowerShell'e yeni bir kullanıcı arayüzü olarak uygulandığı özel bir barındırma biçimidir. Örneğin, PowerShell ConsoleHost, PowerShell yürütülebilir dosyaları için bir terminal kullanıcı arabirimi sağlarken, PowerShell Düzenleyici Hizmetleri Ana Bilgisayarı ve ISE Ana Bilgisayarı, PowerShell çevresinde düzenleyiciyle tümleşik kısmen grafiksel bir kullanıcı arabirimi sağlar. Mevcut bir PowerShell işlemine bir ana bilgisayar yüklemek mümkün olsa da, bir ana bilgisayar uygulamasının PowerShell motorunu yeniden dağıtan bağımsız bir PowerShell uygulaması gibi davranması çok daha yaygındır.

• Başka bir .NET uygulamasından PowerShell'e çağrı yapma

  Her uygulamada olduğu gibi PowerShell de iş yüklerini çalıştıran bir alt süreç olarak çağrılabilir. Ancak bir .NET uygulaması olarak, çağıran uygulama içinde kullanılmak üzere tam .NET nesnelerini geri almak için süreç içinde PowerShell'i çağırmak da mümkündür. Bu, uygulamanın dahili kullanım için kendi PowerShell uygulamasını barındırdığı daha genel bir barındırma biçimidir. Bunun örnekleri, makine durumunu yönetmek için PowerShell'i çalıştıran bir hizmet veya arka plan programı veya bulut dağıtımlarını yönetmek gibi bir şey yapmak için istek üzerine PowerShell'i çalıştıran bir web uygulaması olabilir.

• .NET'ten PowerShell modüllerini birim testi

  İşlevselliği PowerShell'e sunmak için tasarlanan modüller ve diğer kitaplıkların öncelikle PowerShell'den test edilmesi gerekirken (Pester'ı öneririz), bazen .NET'ten bir PowerShell modülü için yazılan birim test API'lerinin test edilmesi gerekebilir. Bu durum, modül kodunun bir dizi PowerShell sürümünü hedeflemeye çalışmasını içerirken testin onu belirli, somut uygulamalarda çalıştırması gerekir.

Bir bakışta PowerShell NuGet paketleri

Bu makalede PowerShell API'lerini kullanıma sunan aşağıdaki NuGet paketlerini ele alacağız:

• PowerShellStandard.Library, birden fazla PowerShell çalışma zamanı tarafından yüklenebilen tek bir derleme oluşturmaya olanak tanıyan bir referans derlemesidir.
• Microsoft.PowerShell.SDK, PowerShell SDK'nın tamamını hedeflemenin ve yeniden barındırmanın yolu
• Minimum düzeyde barındırılan uygulamalarda ve sürüme özel hedefleme senaryolarında yararlı olabilecek temel PowerShell çalışma zamanı ve motor uygulaması olan System.Management.Automation paketi.
• Windows PowerShell referans derlemeleri, Windows PowerShell'i (PowerShell sürüm 5.1 ve altı) hedeflemenin ve etkili bir şekilde yeniden barındırmanın yolu.

PowerShellStandard.Library

PowerShell Standart kitaplığı, PowerShell sürüm 7, 6 ve 5.1'in API'lerinin kesişimini yakalayan bir referans derlemesidir. Bu, .NET kodunu derlemek için derleme zamanı denetlenen bir API yüzeyi sağlar ve .NET projelerinin, orada olmayacak bir API'yi çağırma riski olmadan PowerShell sürüm 7, 6 ve 5,1'i hedeflemesine olanak tanır.

PowerShell Standardı, PowerShell modüllerini veya yalnızca bir PowerShell işlemine yüklendikten sonra çalıştırılması amaçlanan diğer kodları yazmak için tasarlanmıştır. Bir referans derlemesi olduğundan, PowerShell Standard'ın kendisi herhangi bir uygulama içermediğinden bağımsız uygulamalar için hiçbir işlevsellik sağlamaz.

PowerShell Standard'ı farklı .NET çalışma zamanlarıyla kullanma

PowerShell Standard, .NET Framework ve .NET Core tarafından paylaşılan ortak bir yüzey alanı sağlamak üzere tasarlanmış bir cephe çalışma zamanı olan .NET Standard 2,0 hedef çalışma zamanını hedefler. Bu, birden fazla PowerShell sürümüyle çalışacak tek bir derleme oluşturmak için tek bir çalışma zamanının hedeflenmesine olanak tanır, ancak aşağıdaki sonuçlara yol açar:

• Modülü veya kitaplığı yükleyen PowerShell'in en az .NET 4.6.1 sürümünü çalıştırması gerekir; .NET 4.6 ve .NET 4.5.2, .NET Standard'ı desteklemez. Daha yeni bir Windows PowerShell sürümünün daha yeni bir .NET Framework sürümü anlamına gelmediğini unutmayın; Windows PowerShell 5.1, .NET 4.5.2'de çalışabilir.
• .NET Framework 4.7.1 veya daha düşük bir sürümünü çalıştıran bir PowerShell ile çalışmak için, eski .NET Framework sürümlerinde netstandard.dll ve diğer dolgu derlemelerini sağlamak üzere .NET 4.6.1 NETStandard.Library uygulaması gereklidir.

PowerShell 6+, .NET Framework 4.6.1'den (ve üzeri) .NET Core'a tür aktarımı için kendi dolgu derlemelerini sağlar. Bu, bir modül yalnızca .NET Core'da bulunan API'leri kullandığı sürece PowerShell 6+, .NET Framework 4.6.1 (net461 çalışma zamanı hedefi) için oluşturulduğunda onu yükleyebilir ve çalıştırabilir. ).

Bu, yayınlanan tek bir DLL ile birden fazla PowerShell sürümünü hedeflemek için PowerShell Standardı kullanan ikili modüllerin iki seçeneğe sahip olduğu anlamına gelir:

1. net461 hedef çalışma zamanı için oluşturulmuş bir derleme yayımlanıyor. Bu şunları içerir:

   • Projeyi net461 çalışma zamanı için yayınlama
   • Ayrıca, kullanılan tüm API'lerin .NET Core'da da mevcut olduğundan emin olmak için netstandard2.0 çalışma zamanına göre derleme (derleme çıktısını kullanmadan).

2. netstandard2.0 hedef çalışma zamanı için bir derleme yapısı yayımlanıyor. Bu şunları gerektirir:

   • Projeyi netstandard2.0 çalışma zamanı için yayınlama
   • NETStandard.Library'nin net461 bağımlılıklarını almak ve bunları proje derlemesinin yayınlama konumuna kopyalamak, böylece derlemenin .NET Framework'te tür iletilmesi düzeltilmiştir.

Eski .NET Framework sürümlerini hedefleyen PowerShell modülleri veya kitaplıkları oluşturmak için birden fazla .NET çalışma zamanını hedeflemek tercih edilebilir. Bu, her hedef çalışma zamanı için bir derleme yayınlayacaktır ve modül yükleme zamanında doğru derlemenin yüklenmesi gerekecektir (örneğin, kök modül olarak küçük bir psm1 ile).

.NET'te PowerShell Standard projelerini test etme

Modülünüzü xUnit gibi .NET test çalıştırıcılarında test etmeye gelince, derleme zamanı kontrollerinin ancak bu kadar ileri gidebileceğini unutmayın. Modülünüzü ilgili PowerShell platformlarına göre test etmelisiniz.

.NET'te PowerShell Standardına göre oluşturulan API'leri test etmek için, .NET Core (sürüm istenen PowerShell sürümüyle eşleşecek şekilde ayarlanmış) ve uygun .NET Framework ile Windows PowerShell başvuru derlemeleri.

PowerShell Standardı ve bunu birden çok PowerShell sürümünde çalışan bir ikili modül yazmak için kullanma hakkında daha fazla bilgi için bu blog gönderisine bakın. Ayrıca GitHub'daki PowerShell Standard deposuna bakın.

Microsoft.PowerShell.SDK

Microsoft.PowerShell.SDK, PowerShell SDK'nın tüm bileşenlerini tek bir NuGet paketinde bir araya getiren bir meta pakettir. Bağımsız bir .NET uygulaması, herhangi bir harici PowerShell kurulumuna veya kitaplığına bağlı olmadan isteğe bağlı PowerShell işlevselliğini çalıştırmak için Microsoft.PowerShell.SDK'yi kullanabilir.

Belirli bir Microsoft.Powershell.SDK sürümü, PowerShell uygulamasının aynı sürümünün somut uygulamasını içerir; sürüm 7.0, PowerShell 7.0'ın uygulamasını içerir ve komutları veya komut dosyalarını onunla çalıştırmak, büyük ölçüde bunları PowerShell 7.0'da çalıştırmak gibi davranacaktır.

PowerShell komutlarını SDK'dan çalıştırmak tamamen olmasa da çoğunlukla pwsh'dan çalıştırmakla aynıdır. Örneğin, Start-Job şu anda pwsh yürütülebilir dosyasının mevcut olmasına bağlıdır ve bu nedenle varsayılan olarak Microsoft.Powershell.SDK ile çalışmaz.

Bir .NET uygulamasından Microsoft.Powershell.SDK'yi hedeflemek, System.Management.Automation, Microsoft.PowerShell gibi tüm PowerShell uygulama derlemeleriyle entegrasyon yapmanıza olanak tanır .Yönetim ve diğer modül derlemeleri.

Microsoft.Powershell.SDK'yi hedefleyen bir uygulamanın yayımlanması, tüm bu derlemeleri ve PowerShell'in gerektirdiği tüm bağımlılıkları içerecektir. Ayrıca Microsoft.PowerShell.* modülleri için modül bildirimleri ve Add-Type'ın gerektirdiği ref dizini gibi PowerShell'in yapısında ihtiyaç duyduğu diğer varlıkları da içerecektir.

Microsoft.Powershell.SDK'nin eksiksizliği göz önüne alındığında, aşağıdakiler için en uygunudur:

• PowerShell ana bilgisayarlarının uygulanması.
• PowerShell referans derlemelerini hedefleyen kitaplıkların xUnit testi.
• Bir .NET uygulamasından süreç içinde PowerShell'i çağırma.

Microsoft.PowerShell.SDK ayrıca bir .NET projesinin modül olarak kullanılması veya PowerShell tarafından başka şekilde yüklenmesi amaçlandığında referans hedefi olarak kullanılabilir, ancak yalnızca belirli bir sürümde bulunan API'lere bağlıdır. PowerShell. Belirli bir Microsoft.PowerShell.SDK sürümüne karşı yayınlanan bir derlemenin yalnızca PowerShell'in bu sürümünde yüklenmesinin ve kullanılmasının güvenli olacağını unutmayın. Belirli API'lere sahip birden çok PowerShell sürümünü hedeflemek için, her biri kendi Microsoft.Powershell.SDK sürümünü hedefleyen birden çok derleme gerekir.

System.Management.Automation

System.Management.Automation paketi PowerShell SDK'nın kalbidir. NuGet'te öncelikle Microsoft.Powershell.SDK'nin kullanabileceği bir varlık olarak bulunur. Ancak daha küçük barındırma senaryoları ve sürüm hedefleme modülleri için doğrudan bir paket olarak da kullanılabilir.

Özellikle System.Management.Automation paketi şu durumlarda tercih edilen bir PowerShell işlevselliği sağlayıcısı olabilir:

• Yalnızca PowerShell ayrıştırıcısı, AST ve AST ziyaretçi API'leri (örneğin PowerShell'in statik analizi için) gibi PowerShell dil işlevlerini (System.Management.Automation.Language ad alanında) kullanmayı düşünüyorsunuz.
• Yalnızca Microsoft.PowerShell.Core modülünden belirli komutları yürütmek istiyorsunuz ve bunları CreateDefault2 fabrika yöntemiyle oluşturulan bir oturum durumunda yürütebilirsiniz.

Ayrıca System.Management.Automation şu durumlarda yararlı bir referans derlemesidir:

• Yalnızca belirli bir PowerShell sürümünde bulunan API'leri hedeflemek istiyorsunuz
• System.Management.Automation derlemesinin dışında oluşan türlere bağlı olmayacaksınız (örneğin, Microsoft.PowerShell.* modüllerindeki cmdlet'ler tarafından dışa aktarılan türler).

Windows PowerShell başvuru derlemeleri

PowerShell sürüm 5,1 ve daha eski sürümler için (Windows PowerShell), Windows PowerShell uygulaması Windows'un bir parçası olduğundan PowerShell uygulamasını sağlayacak bir SDK yoktur.

Bunun yerine, Windows PowerShell referans derlemeleri hem referans hedefleri hem de Windows PowerShell'i yeniden barındırmanın bir yolunu sağlar ve PowerShell SDK'nın sürüm 6 ve üzeri için yaptığı gibi davranır.

Windows PowerShell referans derlemeleri, sürüme göre farklılaştırılmak yerine, Windows PowerShell'in her sürümü için farklı bir pakete sahiptir:

• PowerShell 5.1
• PowerShell 4
• PowerShell 3

Windows PowerShell başvuru derlemelerinin nasıl kullanılacağına ilişkin bilgiler Windows PowerShell SDK'sında bulunabilir.

Bu NuGet paketlerini kullanan gerçek dünyadan örnekler

Farklı PowerShell araç projeleri, ihtiyaçlarına bağlı olarak farklı PowerShell NuGet paketlerini hedefler. Burada bazı dikkate değer örnekler listelenmiştir.

PSReadLine

PowerShell'in zengin konsol deneyiminin çoğunu sağlayan PowerShell modülü PSReadLine, belirli bir PowerShell sürümü yerine bağımlılık olarak PowerShell Standard'ı hedefler ve csproj'unda net461 .NET çalışma zamanını hedefler.

PowerShell 6+, net461 çalışma zamanını hedefleyen bir DLL dosyasının yüklendiğinde "sadece çalışmasına" olanak tanıyan kendi ayar düzeneklerini sağlar (bağlamayı .NET Framework'ün mscorlib.dll dosyasına yeniden yönlendirerek) ilgili .NET Core derlemesi).

Bu, PSReadLine'ın modül düzenini ve dağıtımını önemli ölçüde basitleştirir; çünkü PowerShell Standard, kullanılan yalnızca API'lerin hem PowerShell 5.1 hem de PowerShell 6+'da mevcut olmasını sağlarken aynı zamanda modülün yalnızca tek bir derlemeyle gönderilmesine de olanak tanır.

.NET 4.6.1 hedefi, .NET 4.5.2 ve .NET 4.6 üzerinde çalışan Windows PowerShell'in desteklenmediği anlamına gelir.

PowerShell Düzenleyici Hizmetleri

PowerShell Düzenleyici Hizmetleri (PSES), Visual Studio Code için PowerShell uzantısının arka ucudur ve aslında bir PowerShell yürütülebilir dosyası tarafından yüklenen ve daha sonra PowerShell'i kendi içinde yeniden barındırmak için bu işlemi devralan ve aynı zamanda Dil Hizmeti Protokolü sağlayan bir PowerShell modülü biçimidir. ve Hata Ayıklama Adaptörü özellikleri.

PSES, PowerShell 6+ sürümünü hedeflemek için netcoreapp2.1 (PowerShell 7'nin netcoreapp3.1 çalışma zamanı geriye dönük olarak uyumlu olduğundan) ve net461 sürümünü hedeflemek için somut uygulama hedefleri sağlar. Windows PowerShell 5.1'i hedefler ancak mantığının çoğunu netstandard2.0 ve PowerShell Standard'ı hedefleyen ikinci bir derlemede içerir. Bu, .NET Core ve .NET Framework platformları için gereken bağımlılıkları almasına olanak tanırken aynı zamanda kod tabanının çoğunu tek tip bir soyutlamanın arkasında basitleştirmeye devam eder.

PowerShell Standardına göre oluşturulduğundan PSES, doğru şekilde test edilebilmesi için PowerShell'in çalışma zamanı uygulamasını gerektirir. Bunu yapmak için, PSES'in xUnit testleri, test ortamında bir PowerShell uygulaması sağlamak amacıyla Microsoft.PowerShell.SDK ve Microsoft.PowerShell.5.ReferenceAssemblies'ı alır.

PSReadLine'da olduğu gibi, PSES de .NET 4.6 ve altını destekleyemez, ancak daha düşük .NET Framework çalışma zamanlarında çökmeye neden olabilecek API'lerden herhangi birini çağırmadan önce çalışma zamanında bir kontrol gerçekleştirir.

PSScript Analizörü

PowerShell'in linter'ı olan PSScriptAnalyzer, yalnızca PowerShell'in belirli sürümlerinde sunulan sözdizimsel öğeleri hedeflemelidir. Bu sözdizimsel öğelerin tanınması bir AstVisitor2 uygulanarak gerçekleştirildiğinden, PowerShellStandard'ı kullanmak ve ayrıca daha yeni PowerShell sözdizimleri için AST ziyaretçi yöntemlerini uygulamak mümkün değildir.

Bunun yerine PSScriptAnalyzer, her PowerShell sürümünü bir yapı yapılandırması olarak hedefler ve her biri için ayrı bir DLL üretir. Bu, yapı boyutunu ve karmaşıklığını artırır ancak aşağıdakilere olanak tanır:

• Sürüme özel API hedefleme
• Temel olarak hiçbir çalışma zamanı maliyeti olmadan uygulanacak sürüme özel işlevsellik
• .NET Framework 4.5.2'ye kadar Windows PowerShell için tam destek

Özet

Bu makalede, PowerShell kullanan bir .NET projesini uygularken hedeflenebilecek NuGet paketlerini ve bunların birini diğerine tercih etmenizin olası nedenlerini listeleyip tartıştık.

Özete atladıysanız bazı genel öneriler şunlardır:

• PowerShell modülleri, yalnızca farklı PowerShell sürümleri için ortak API'ler gerektiriyorsa PowerShell Standardına göre derlenmelidir.
• PowerShell'i dahili olarak çalıştırması gereken PowerShell ana bilgisayarları ve uygulamaları, PowerShell 6+ için PowerShell SDK'sını veya Windows PowerShell için ilgili Windows PowerShell referans derlemelerini hedeflemelidir.
• Sürüme özel API'lere ihtiyaç duyan PowerShell modülleri, gerekli PowerShell sürümleri için PowerShell SDK'sını veya Windows PowerShell referans derlemelerini hedeflemeli ve bunları referans derlemeleri olarak kullanmalıdır (yani, PowerShell bağımlılıklarını yayınlamamalıdır).