Wybieranie odpowiedniego pakietu NuGet programu PowerShell dla projektu platformy .NET

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

Jako aplikacja .NET, która udostępnia interfejsy API i oczekuje załadowania bibliotek .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 przedstawiono kilka typowych scenariuszy przeznaczonych dla 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 się

Niektóre projekty platformy .NET mają na celu napisanie kodu, 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), podczas gdy inne chcą uruchomić program PowerShell we własnych aplikacjach.

  • Odwoływanie się dotyczy tego, kiedy projekt, zazwyczaj 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 elementu docelowego kompilacji, ale musi upewnić się, że nie opublikuje żadnego z nich w kompilacji.
  • 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 takim przypadku nie można używać czystych zestawów odwołań. Zamiast tego należy polegać na konkretnych implementacjach programu PowerShell. Ponieważ należy użyć konkretnej implementacji programu PowerShell, należy wybrać konkretną 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 publishelementu , który umieszcza bibliotekę .NET w katalogu ze wszystkimi jego zależnościami gotowymi do wdrożenia w określonym środowisku uruchomieniowym.

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

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

Jeśli zapomnisz to zrobić i użyjesz zestawu odniesienia jako celu, mogą wystąpić problemy związane z używaniem domyślnej implementacji zestawu odwołania zamiast rzeczywistej implementacji. Może to mieć postać NullReferenceExceptionelementu , 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, istnieją pewne typowe scenariusze korzystające 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 PSCmdlet lub CmdletProvider , aby uwidocznić odpowiednio polecenia cmdlet lub dostawców. Ponieważ są ładowane, moduły dążą do skompilowania odwołań 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 zapewnia 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, podczas gdy host usług edytora programu PowerShell i host ISE udostępniają 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 każdej aplikacji, program PowerShell może być wywoływany jako podproces w celu 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 maszyny lub aplikacją internetową, która uruchamia program PowerShell na żądanie, aby wykonać podobne czynności, jak zarządzanie wdrożeniami w chmurze.

  • Testowanie jednostkowe modułów programu PowerShell na platformie .NET

    Moduły i inne biblioteki przeznaczone do uwidocznienia funkcji programu PowerShell powinny być testowane głównie z poziomu programu PowerShell (zalecamy korzystanie z programu Pester), jednak czasami konieczne jest przeprowadzenie testów jednostkowych interfejsów API napisanych dla modułu programu PowerShell na platformie .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 na pierwszy rzut oka

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 utworzenie pojedynczego zestawu, który może zostać zał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 i w scenariuszach określania wartości docelowej specyficznych dla wersji.
  • Zestawy odwołań Windows PowerShell, sposób docelowego i efektywnego ponownego hostowania 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 zapewnia globalną implementację narzędzia dotnet programu PowerShell. Nie powinno być ono używane przez żadne projekty, ponieważ zapewnia tylko plik wykonywalny.

PowerShellStandard.Library

Biblioteka programu PowerShell w warstwie Standardowa to zestaw referencyjny, który przechwytuje część wspólną 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 na potrzeby projektów platformy .NET przeznaczonych 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 w warstwie Standardowa nie zawiera samej implementacji, dlatego nie zapewnia żadnych 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 .NET Framework i platformę .NET Core. Dzięki temu pojedyncze środowisko uruchomieniowe może utworzyć pojedynczy zestaw, 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 mieć co najmniej program .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 Windows PowerShell nie oznacza nowszej wersji .NET Framework; Windows PowerShell 5.1 może działać na platformie .NET 4.5.2.
  • Aby pracować z programem PowerShell z systemem .NET Framework 4.7.1 lub nowszym, implementacja biblioteki .NETStandard.Library platformy .NETStandard.Library jest wymagana do zapewnienia netstandard.dll i innych zestawów podkładek w starszych wersjach .NET Framework.

Program PowerShell 6+ udostępnia własne zestawy podkładek dla przekazywania typów z .NET Framework 4.6.1 (i nowszych) do platformy .NET Core. Oznacza to, że tak długo, jak moduł używa tylko interfejsów API istniejących na platformie .NET Core, program PowerShell 6+ może ładować i uruchamiać go, gdy został utworzony dla .NET Framework 4.6.1 (net461cel środowiska uruchomieniowego).

Oznacza to, że moduły binarne korzystające z programu PowerShell Standard przeznaczone dla wielu wersji programu PowerShell z pojedynczą opublikowaną biblioteką DLL mają dwie opcje:

  1. Publikowanie zestawu utworzonego net461 dla docelowego środowiska uruchomieniowego. Obejmuje to:

    • 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 .NET Framework.

Aby utworzyć moduły programu PowerShell lub biblioteki przeznaczone dla starszych wersji .NET Framework, lepszym rozwiązaniem 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 Standard na platformie .NET

Jeśli chodzi o testowanie modułu w modułach uruchamiających testy platformy .NET, takich jak xUnit, pamiętaj, że kontrole czasu kompilacji mogą być przeprowadzane 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ść testowania z platformą .NET Core (z wersją ustawioną tak, aby odpowiadała żądanej wersji programu PowerShell) oraz odpowiednie zestawy odwołań Windows PowerShell z .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 odwołuje się tylko do wszystkich pakietów składników tworzących program PowerShell, 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 jej pomocą 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 zależy obecnie od dostępnego pwsh pliku wykonywalnego, więc nie będzie działać Microsoft.Powershell.SDK domyślnie.

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.

Opublikowanie docelowej 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 dodatek.

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

  • Implementacja hostów programu PowerShell.
  • XUnit testowanie 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 konkretnej wersji programu PowerShell. Należy pamiętać, że zestaw opublikowany dla określonej wersji Microsoft.PowerShell.SDK programu będzie bezpieczny tylko do załadowania i użycia w tej wersji programu PowerShell. Aby kierować wiele wersji programu PowerShell z określonymi interfejsami API, wymagane jest wiele kompilacji, z których każda jest przeznaczona dla własnej wersji programu Microsoft.Powershell.SDK.

Uwaga

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

System.Management.Automation

Pakiet System.Management.Automation jest sercem zestawu POWERShell SDK. Istnieje on przede wszystkim w narzędziu NuGet jako zasób 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 określania 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 dla 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 utworzonej za pomocą metody fabryki CreateDefault2 .

Ponadto jest przydatnym zestawem referencyjnym, System.Management.Automation gdy:

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

zestawy referencyjne Windows PowerShell

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

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

Zamiast rozróżniać wersję, zestawy referencyjne Windows PowerShell mają inny pakiet dla każdej wersji Windows PowerShell:

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

Przykłady w świecie rzeczywistym korzystające z 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 przedstawiono 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 Standard jako zależność, a nie określoną wersję programu PowerShell, a także przeznaczony net461 dla środowiska uruchomieniowego platformy .NET w pliku csproj.

Program PowerShell 6+ udostępnia 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 .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 w programie PowerShell 6 lub nowszym, a jednocześnie zezwalając modułowi na dostarczanie tylko jednego zestawu.

Docelowy element docelowy platformy .NET 4.6.1 oznacza, że Windows PowerShell uruchomione na platformie .NET 4.5.2 i .NET 4.6 nie są jednak obsługiwane.

Usługi edytora programu PowerShell

Usługi Edytora programu PowerShell (PSES) to zaplecze rozszerzenia programu PowerShell dla 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 samym sobie, zapewniając jednocześnie funkcje protokołu usługi językowej i karty debugowania.

Program PSES udostępnia 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 Windows PowerShell 5.1, ale zawiera większość jego logiki w drugim zestawie, który jest przeznaczony netstandard2.0 dla programu 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 on kompilowany w programie PowerShell w warstwie Standardowa, program PSES wymaga implementacji środowiska uruchomieniowego programu PowerShell w celu poprawnego przetestowania. W tym celu testy xUnit 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 poniżej, ale wykonuje sprawdzanie w czasie wykonywania przed wywołaniem któregokolwiek z interfejsów API, które mogą spowodować awarię w niższych środowiskach uruchomieniowych .NET Framework.

PSScriptAnalyzer

PsScriptAnalyzer, linter dla programu PowerShell, musi być przeznaczony dla elementów składniowych wprowadzonych 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ć programu 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 docelowych interfejsów API specyficznych dla wersji
  • Funkcje specyficzne dla wersji, które mają być implementowane bez kosztów środowiska uruchomieniowego
  • Łączna obsługa Windows PowerShell aż do .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 powody, dla których można używać jednego nawzajem.

Jeśli pominięto podsumowanie, niektóre szerokie zalecenia są następujące:

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