Wybieranie odpowiedniego pakietu NuGet programu PowerShell dla projektu platformy .NET

  • Artykuł

pwsh Oprócz pakietów wykonywalnych publikowanych w każdej wersji programu PowerShell zespół programu PowerShell utrzymuje również kilka pakietów dostępnych w programie NuGet. Te pakiety umożliwiają określanie wartości docelowej programu PowerShell jako platformy interfejsu API na platformie .NET.

Jako aplikacja .NET, która udostępnia interfejsy API i oczekuje załadowania bibliotek platformy .NET implementujących własne (moduły binarne), ważne jest, aby program PowerShell był dostępny w postaci pakietu NuGet.

Obecnie istnieje kilka pakietów NuGet, które zapewniają pewną reprezentację obszaru powierzchni interfejsu API programu PowerShell. Który pakiet do użycia z konkretnym projektem nie zawsze był jasno określony. W tym artykule omówiono kilka typowych scenariuszy dotyczących projektów platformy .NET przeznaczonych dla programu PowerShell oraz sposób wybierania odpowiedniego pakietu NuGet przeznaczonego dla projektu platformy .NET zorientowanego na program PowerShell.

Hosting a odwoływanie

Niektóre projekty platformy .NET starają się napisać kod, który ma zostać załadowany do istniejącego środowiska uruchomieniowego programu PowerShell (na przykład pwsh, powershell.exezintegrowanej konsoli programu PowerShell lub środowiska ISE), a inne chcą uruchomić program PowerShell we własnych aplikacjach.

  • Odwołanie dotyczy, gdy projekt, zwykle moduł, ma zostać załadowany do programu PowerShell. Należy go skompilować względem interfejsów API udostępnianych przez program PowerShell w celu interakcji z nim, ale implementacja programu PowerShell jest dostarczana przez proces ładowania go przez program PowerShell. W przypadku odwoływania się projekt może używać zestawów odwołań lub rzeczywistych zestawów środowiska uruchomieniowego jako celu kompilacji, ale musi upewnić się, że nie publikuje żadnego z tych zestawów z kompilacją.
  • Hosting polega na tym, że projekt wymaga własnej implementacji programu PowerShell, zwykle dlatego, że jest to autonomiczna aplikacja, która musi uruchamiać program PowerShell. W tym przypadku nie można używać czystych zestawów odwołań. Zamiast tego należy zależeć od konkretnej implementacji programu PowerShell. Ponieważ należy użyć konkretnej implementacji programu PowerShell, należy wybrać określoną wersję programu PowerShell do hostowania; pojedyncza aplikacja hosta nie może obsługiwać wielu docelowych wersji programu PowerShell.

Publikowanie projektów przeznaczonych dla programu PowerShell jako odwołania

Uwaga

Termin publikowania w tym artykule jest używany do odwoływania się do uruchamiania dotnet publishbiblioteki .NET w katalogu ze wszystkimi jego zależnościami, gotowym do wdrożenia w określonym środowisku uruchomieniowym.

Aby zapobiec publikowaniu zależności projektu, które są używane tylko jako elementy docelowe odwołania do kompilacji, zaleca się ustawienie atrybutu PrivateAssets :

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

Jeśli zapomnisz to zrobić i użyjesz zestawu referencyjnego jako docelowego, mogą wystąpić problemy związane z używaniem domyślnej implementacji zestawu referencyjnego zamiast rzeczywistej implementacji. Może to mieć postać elementu NullReferenceException, ponieważ zestawy odwołań często wyśmiewają interfejs API implementacji, po prostu zwracając element null.

Kluczowe rodzaje projektów platformy .NET przeznaczonych dla programu PowerShell

Chociaż dowolna biblioteka lub aplikacja platformy .NET może osadzić program PowerShell, istnieje kilka typowych scenariuszy korzystających z interfejsów API programu PowerShell:

  • Implementowanie modułu binarnego programu PowerShell

    Moduły binarne programu PowerShell to biblioteki platformy .NET ładowane przez program PowerShell, które muszą implementować interfejsy API programu PowerShell, takie jak typy PSCmdlet lub CmdletProvider, aby uwidocznić odpowiednio polecenia cmdlet lub dostawców. Ponieważ są ładowane, moduły starają się skompilować odwołania do programu PowerShell bez publikowania ich w kompilacji. Często zdarza się również, że moduły chcą obsługiwać wiele wersji i platform programu PowerShell, najlepiej z minimalnym obciążeniem miejsca na dysku, złożonością lub powtarzaną implementacją. Aby uzyskać więcej informacji na temat modułów, zobacz about_Modules .

  • Implementowanie hosta programu PowerShell

    Host programu PowerShell udostępnia warstwę interakcji dla środowiska uruchomieniowego programu PowerShell. Jest to konkretna forma hostingu, w której host PSHost jest implementowany jako nowy interfejs użytkownika w programie PowerShell. Na przykład konsola programu PowerShellHost udostępnia interfejs użytkownika terminalu dla plików wykonywalnych programu PowerShell, a host usług Edytora programu PowerShell i host ISE zapewniają częściowo graficzny interfejs użytkownika w edytorze wokół programu PowerShell. Chociaż istnieje możliwość załadowania hosta do istniejącego procesu programu PowerShell, implementacja hosta działa znacznie częściej jako autonomiczna implementacja programu PowerShell, która redystrybuuje aparat programu PowerShell.

  • Wywoływanie programu PowerShell z innej aplikacji .NET

    Podobnie jak w przypadku dowolnej aplikacji, program PowerShell może być wywoływany jako podproces do uruchamiania obciążeń. Jednak jako aplikacja .NET można również wywołać proces programu PowerShell w celu odzyskania pełnych obiektów platformy .NET do użycia w aplikacji wywołującej. Jest to bardziej ogólna forma hostingu, w której aplikacja posiada własną implementację programu PowerShell do użytku wewnętrznego. Przykładem może być usługa lub demon z uruchomionym programem PowerShell do zarządzania stanem komputera lub aplikacją internetową, która uruchamia program PowerShell na żądanie, aby wykonać operacje zarządzania wdrożeniami w chmurze.

  • Testowanie jednostkowe modułów programu PowerShell z platformy .NET

    Moduły i inne biblioteki przeznaczone do uwidaczniania funkcji programu PowerShell powinny być testowane głównie z poziomu programu PowerShell (zalecamy korzystanie z programu Pester), ale czasami konieczne jest przeprowadzenie testów jednostkowych interfejsów API napisanych dla modułu programu PowerShell z platformy .NET. Taka sytuacja obejmuje kod modułu, który próbuje kierować do wielu wersji programu PowerShell, podczas gdy testowanie powinno być uruchamiane w określonych, konkretnych implementacjach.

Pakiety NuGet programu PowerShell w skrócie

W tym artykule omówimy następujące pakiety NuGet, które uwidaczniają interfejsy API programu PowerShell:

  • PowerShellStandard.Library, zestaw referencyjny, który umożliwia tworzenie pojedynczego zestawu, który może być ładowany przez wiele środowisk uruchomieniowych programu PowerShell.
  • Microsoft.PowerShell.SDK — sposób kierowania i ponownego hostowania całego zestawu SDK programu PowerShell
  • Pakiet System.Management.Automation, podstawowa implementacja środowiska uruchomieniowego programu PowerShell i aparatu, który może być przydatny w minimalnych implementacjach hostowanych oraz w scenariuszach określania wersji.
  • Zestawy odwołań programu Windows PowerShell, sposób kierowania i efektywnego ponownego hostowania programu Windows PowerShell (program PowerShell w wersji 5.1 lub nowszej).

Uwaga

Pakiet NuGet programu PowerShell nie jest w ogóle pakietem biblioteki .NET, ale zamiast tego udostępnia globalną implementację narzędzia dotnet programu PowerShell. Nie powinno być ono używane przez żadne projekty, ponieważ udostępnia tylko plik wykonywalny.

PowerShellStandard.Library

Biblioteka programu PowerShell w warstwie Standardowa to zestaw referencyjny, który przechwytuje skrzyżowanie interfejsów API programu PowerShell w wersji 7, 6 i 5.1. Zapewnia to powierzchnię interfejsu API sprawdzaną w czasie kompilacji w celu skompilowania kodu platformy .NET, dzięki czemu projekty platformy .NET będą przeznaczone dla programu PowerShell w wersji 7, 6 i 5.1 bez ryzyka wywołania interfejsu API, który nie będzie dostępny.

Program PowerShell Standard jest przeznaczony do pisania modułów programu PowerShell lub innego kodu przeznaczonego tylko do uruchomienia po załadowaniu go do procesu programu PowerShell. Ponieważ jest to zestaw referencyjny, program PowerShell Standard nie zawiera samej implementacji, dlatego nie zapewnia funkcji dla aplikacji autonomicznych.

Używanie programu PowerShell w warstwie Standardowa z różnymi środowiskami uruchomieniowymi platformy .NET

Program PowerShell Standard jest przeznaczony dla docelowego środowiska uruchomieniowego platformy .NET Standard 2.0 , który jest środowiskiem uruchomieniowym fasady zaprojektowanym w celu zapewnienia wspólnego obszaru powierzchni współużytkowanego przez platformy .NET Framework i platformę .NET Core. Pozwala to na utworzenie pojedynczego środowiska uruchomieniowego w celu utworzenia pojedynczego zestawu, który będzie działać z wieloma wersjami programu PowerShell, ale ma następujące konsekwencje:

  • Program PowerShell ładujący moduł lub bibliotekę musi działać co najmniej na platformie .NET 4.6.1; .NET 4.6 i .NET 4.5.2 nie obsługują platformy .NET Standard. Należy pamiętać, że nowsza wersja programu Windows PowerShell nie oznacza nowszej wersji programu .NET Framework; Program Windows PowerShell 5.1 może działać na platformie .NET 4.5.2.
  • Aby pracować z programem PowerShell z uruchomionym programem .NET Framework 4.7.1 lub nowszym, implementacja biblioteki .NETStandard.Library platformy .NET 4.6.1 jest wymagana do zapewnienia netstandard.dll i innych zestawów podkładek w starszych wersjach programu .NET Framework.

Program PowerShell 6+ udostępnia własne zestawy podkładek do przekazywania typów z programu .NET Framework 4.6.1 (i nowszych) do platformy .NET Core. Oznacza to, że jeśli moduł używa tylko interfejsów API istniejących na platformie .NET Core, program PowerShell 6+ może załadować i uruchomić go po utworzeniu net461 dla programu .NET Framework 4.6.1 (celu środowiska uruchomieniowego).

Oznacza to, że moduły binarne używające programu PowerShell Standard do kierowania wielu wersji programu PowerShell z pojedynczą opublikowaną biblioteką DLL mają dwie opcje:

  1. Publikowanie zestawu utworzonego net461 dla docelowego środowiska uruchomieniowego. Ten proces obejmuje następujące czynności:

    • Publikowanie projektu dla środowiska uruchomieniowego net461
    • Ponadto kompilowanie względem netstandard2.0 środowiska uruchomieniowego (bez używania danych wyjściowych kompilacji), aby upewnić się, że wszystkie używane interfejsy API są również obecne na platformie .NET Core.

  2. Publikowanie kompilacji zestawu dla netstandard2.0 docelowego środowiska uruchomieniowego. Wymaga to:

    • Publikowanie projektu dla środowiska uruchomieniowego netstandard2.0
    • net461 Pobranie zależności biblioteki NETStandard.Library i skopiowanie ich do lokalizacji publikowania zestawu projektu w taki sposób, aby zestaw został poprawiony przez typ w programie .NET Framework.

Aby utworzyć moduły lub biblioteki programu PowerShell przeznaczone dla starszych wersji programu .NET Framework, preferowane może być kierowanie wielu środowisk uruchomieniowych platformy .NET. Spowoduje to opublikowanie zestawu dla każdego docelowego środowiska uruchomieniowego, a prawidłowy zestaw będzie musiał zostać załadowany w czasie ładowania modułu (na przykład z małym psm1 jako modułem głównym).

Testowanie projektów programu PowerShell w warstwie Standardowa na platformie .NET

Jeśli chodzi o testowanie modułu w modułach uruchamiających testy platformy .NET, takich jak xUnit, pamiętaj, że sprawdzanie czasu kompilacji może być możliwe tylko do tej pory. Moduł należy przetestować na odpowiednich platformach programu PowerShell.

Aby przetestować interfejsy API utworzone przy użyciu programu PowerShell Standard na platformie .NET, należy dodać Microsoft.Powershell.SDK ją jako zależność testową z platformą .NET Core (z ustawioną wersją zgodną z żądaną wersją programu PowerShell) i odpowiednimi zestawami referencyjnymi programu Windows PowerShell za pomocą programu .NET Framework.

Aby uzyskać więcej informacji na temat programu PowerShell w warstwie Standardowa i używania go do pisania modułu binarnego działającego w wielu wersjach programu PowerShell, zobacz ten wpis w blogu. Zobacz również repozytorium Programu PowerShell w warstwie Standardowa w witrynie GitHub.

Microsoft.PowerShell.SDK

Microsoft.PowerShell.SDK to metapakiet, który łączy wszystkie składniki zestawu SDK programu PowerShell w jeden pakiet NuGet. Samodzielna aplikacja .NET może używać zestawu Microsoft.PowerShell.SDK do uruchamiania dowolnych funkcji programu PowerShell bez względu na zewnętrzne instalacje lub biblioteki programu PowerShell.

Uwaga

Zestaw SDK programu PowerShell odnosi się tylko do wszystkich pakietów składników tworzących program PowerShell i które mogą być używane do programowania na platformie .NET za pomocą programu PowerShell.

Dana Microsoft.Powershell.SDK wersja zawiera konkretną implementację tej samej wersji aplikacji programu PowerShell. Wersja 7.0 zawiera implementację programu PowerShell 7.0 i uruchamianie poleceń lub skryptów za pomocą niego będzie w dużej mierze zachowywać się jak uruchamianie ich w programie PowerShell 7.0.

Uruchamianie poleceń programu PowerShell z zestawu SDK jest w większości, ale nie całkowicie takie samo jak uruchamianie ich z poziomu pwsh. Na przykład zadanie uruchamiania obecnie zależy od dostępnego pwsh pliku wykonywalnego, więc nie będzie domyślnie działać Microsoft.Powershell.SDK .

Określanie wartości docelowej Microsoft.Powershell.SDK z poziomu aplikacji .NET umożliwia integrację ze wszystkimi zestawami implementacji programu PowerShell, takimi jak System.Management.Automation, Microsoft.PowerShell.Managementi inne zestawy modułów.

Publikowanie elementów docelowych Microsoft.Powershell.SDK aplikacji będzie zawierać wszystkie te zestawy, a wszystkie zależności wymagają programu PowerShell. Będzie również zawierać inne zasoby wymagane przez program PowerShell w swojej kompilacji, takie jak manifesty modułów dla Microsoft.PowerShell.* modułów i ref katalog wymagany przez add-type.

Biorąc pod uwagę kompletność elementu Microsoft.Powershell.SDK, najlepiej nadaje się do:

  • Implementacja hostów programu PowerShell.
  • Testowanie xUnit bibliotek przeznaczonych dla zestawów odwołań programu PowerShell.
  • Wywoływanie programu PowerShell w procesie z poziomu aplikacji .NET.

Microsoft.PowerShell.SDK może być również używany jako element docelowy odwołania, gdy projekt platformy .NET ma być używany jako moduł lub w inny sposób ładowany przez program PowerShell, ale zależy od interfejsów API obecnych tylko w określonej wersji programu PowerShell. Należy pamiętać, że zestaw opublikowany w określonej wersji Microsoft.PowerShell.SDK programu będzie bezpieczny tylko do załadowania i użycia w tej wersji programu PowerShell. Aby kierować do wielu wersji programu PowerShell z określonymi interfejsami API, wymagane jest wiele kompilacji, z których każda jest przeznaczona dla własnej wersji Microsoft.Powershell.SDKprogramu .

Uwaga

Zestaw POWERShell SDK jest dostępny tylko dla programu PowerShell w wersji 6 i nowszej. Aby zapewnić równoważne funkcje programu Windows PowerShell, użyj zestawów referencyjnych programu Windows PowerShell opisanych poniżej.

System.Management.Automation

Pakiet System.Management.Automation jest sercem zestawu PowerShell SDK. Istnieje on przede wszystkim w rozwiązaniu NuGet jako element zawartości do Microsoft.Powershell.SDK ściągnięcia. Można go jednak również używać bezpośrednio jako pakietu dla mniejszych scenariuszy hostingu i modułów przeznaczonych dla wersji.

W szczególności System.Management.Automation pakiet może być preferowanym dostawcą funkcji programu PowerShell, gdy:

  • Chcesz używać tylko funkcji języka programu PowerShell (w System.Management.Automation.Language przestrzeni nazw), takiej jak analizator programu PowerShell, AST i interfejsy API odwiedzających AST (na przykład na potrzeby statycznej analizy programu PowerShell).
  • Chcesz wykonać tylko określone polecenia z modułu Microsoft.PowerShell.Core i wykonać je w stanie sesji utworzonym za pomocą metody fabryki CreateDefault2 .

Ponadto jest przydatnym zestawem referencyjnym w System.Management.Automation następujących przypadkach:

  • Docelowe interfejsy API, które są obecne tylko w określonej wersji programu PowerShell
  • Nie będziesz zależeć od typów występujących poza zestawem System.Management.Automation (na przykład typów eksportowanych przez polecenia cmdlet w Microsoft.PowerShell.* modułach).

Zestawy referencyjne programu Windows PowerShell

W przypadku programu PowerShell w wersji 5.1 lub starszej (Windows PowerShell) nie ma zestawu SDK do zapewnienia implementacji programu PowerShell, ponieważ implementacja programu Windows PowerShell jest częścią systemu Windows.

Zamiast tego zestawy odwołań środowiska Windows PowerShell udostępniają obiekty docelowe odwołań i sposób ponownego hostowania programu Windows PowerShell, działając tak samo jak zestaw SDK programu PowerShell dla wersji 6 i nowszych.

Zamiast rozróżniać wersję, zestawy odwołań programu Windows PowerShell mają inny pakiet dla każdej wersji programu Windows PowerShell:

Informacje na temat korzystania z zestawów referencyjnych programu Windows PowerShell można znaleźć w zestawie SDK programu Windows PowerShell.

Rzeczywiste przykłady użycia tych pakietów NuGet

Różne projekty narzędzi programu PowerShell są przeznaczone dla różnych pakietów NuGet programu PowerShell w zależności od ich potrzeb. Poniżej wymieniono kilka godnych uwagi przykładów.

PSReadLine

PSReadLine, moduł programu PowerShell, który zapewnia wiele rozbudowanego środowiska konsoli programu PowerShell, jest przeznaczony dla programu PowerShell w warstwie Standardowa jako zależność, a nie określoną wersję programu PowerShell i jest przeznaczony dla net461 środowiska uruchomieniowego platformy .NET w pliku csproj.

Program PowerShell 6+ dostarcza własne zestawy podkładek, które umożliwiają biblioteki DLL przeznaczone net461 dla środowiska uruchomieniowego "po prostu pracę" podczas ładowania (przez przekierowanie powiązania do programu .NET Framework mscorlib.dll do odpowiedniego zestawu platformy .NET Core).

Upraszcza to znacznie układ modułu i dostarczanie modułu PSReadLine, ponieważ program PowerShell Standard zapewnia, że jedyne używane interfejsy API będą obecne zarówno w programie PowerShell 5.1, jak i programie PowerShell 6 lub nowszym, a jednocześnie umożliwia dostarczanie modułu tylko z jednym zestawem.

Docelowy program .NET 4.6.1 oznacza, że program Windows PowerShell uruchomiony na platformie .NET 4.5.2 i .NET 4.6 nie jest jednak obsługiwany.

Usługi edytora programu PowerShell

Usługi edytora programu PowerShell (PSES) to zaplecze rozszerzenia programu PowerShell dla programu Visual Studio Code i jest w rzeczywistości formą modułu programu PowerShell, który jest ładowany przez plik wykonywalny programu PowerShell, a następnie przejmuje ten proces w celu ponownego hostowania programu PowerShell w obrębie samego siebie, zapewniając jednocześnie funkcje protokołu usługi językowej i karty debugowania.

Program PSES zapewnia konkretne cele implementacji dla netcoreapp2.1 programu PowerShell 6+ (ponieważ środowisko uruchomieniowe programu PowerShell 7 netcoreapp3.1 jest zgodne z poprzednimi wersjami) i net461 docelowe środowisko Windows PowerShell 5.1, ale zawiera większość jego logiki w drugim zestawie przeznaczonym netstandard2.0 dla programu PowerShell i programie PowerShell Standard. Dzięki temu można ściągać zależności wymagane dla platform .NET Core i .NET Framework, jednocześnie upraszczając większość bazy kodu za jednolitą abstrakcję.

Ponieważ jest ona oparta na programie PowerShell w warstwie Standardowa, program PSES wymaga implementacji środowiska uruchomieniowego programu PowerShell w celu poprawnego przetestowania. W tym celu testy xUnit programu PSES są ściągane Microsoft.PowerShell.SDK i Microsoft.PowerShell.5.ReferenceAssemblies w celu zapewnienia implementacji programu PowerShell w środowisku testowym.

Podobnie jak w przypadku programu PSReadLine program PSES nie może obsługiwać platformy .NET 4.6 i nowszych, ale wykonuje sprawdzanie w czasie wykonywania przed wywołaniem dowolnego z interfejsów API, które mogą spowodować awarię w niższych środowiskach uruchomieniowych programu .NET Framework.

PSScriptAnalyzer

PSScriptAnalyzer, linter dla programu PowerShell, musi być przeznaczony dla elementów składniowych tylko w niektórych wersjach programu PowerShell. Ponieważ rozpoznawanie tych elementów składniowych jest realizowane przez zaimplementowanie biblioteki AstVisitor2, nie można użyć klasy PowerShellStandard, a także zaimplementować metody odwiedzających AST dla nowszych składni programu PowerShell.

Zamiast tego program PSScriptAnalyzer jest przeznaczony dla każdej wersji programu PowerShell jako konfiguracji kompilacji i tworzy oddzielną bibliotekę DLL dla każdego z nich. Zwiększa to rozmiar kompilacji i złożoność, ale umożliwia:

  • Określanie wartości docelowej interfejsu API specyficznego dla wersji
  • Funkcje specyficzne dla wersji, które mają być implementowane bez kosztów środowiska uruchomieniowego
  • Łączna obsługa programu Windows PowerShell aż do programu .NET Framework 4.5.2

Podsumowanie

W tym artykule wymieniono i omówiliśmy pakiety NuGet dostępne do kierowania podczas implementowania projektu platformy .NET korzystającego z programu PowerShell oraz przyczyny, które mogą być konieczne w przypadku używania ich nawzajem.

Jeśli pominięto podsumowanie, niektóre szerokie zalecenia to:

  • Moduły programu PowerShell powinny być kompilowane w programie PowerShell w warstwie Standardowa, jeśli wymagają tylko interfejsów API wspólnych dla różnych wersji programu PowerShell.
  • Hosty i aplikacje programu PowerShell, które muszą uruchamiać program PowerShell wewnętrznie, powinny być przeznaczone dla zestawu PowerShell SDK dla programu PowerShell 6 lub nowszych lub odpowiednich zestawów odwołań programu Windows PowerShell dla programu Windows PowerShell.
  • Moduły programu PowerShell, które wymagają interfejsów API specyficznych dla wersji, powinny być przeznaczone dla zestawów odwołań programu PowerShell lub środowiska Windows PowerShell dla wymaganych wersji programu PowerShell, używając ich jako zestawów referencyjnych (czyli nie publikowania zależności programu PowerShell).