可移植的模块Portable Modules

本文内容

Windows PowerShell 面向.NET Framework而为编写的 PowerShell Core .NET Core。可移植的模块是在 Windows PowerShell 和 PowerShell Core 中的模块。虽然.NET Framework 和.NET Core 是高度兼容，有可用的 Api 在两者之间的差异。还有 Api 中的差异在 Windows PowerShell 和 PowerShell Core 中可用。需要注意这些差异的模块应在这两个环境中使用。

移植现有模块Porting an Existing Module

移植 PSSnapInPorting a PSSnapIn

在 PowerShell Core 中不支持 PowerShell 管理单元 (PSSnapIn)。但是，很容易将 PSSnapIn 转换为 PowerShell 模块。通常情况下，PSSnapIn 注册代码处于单个源文件的类派生自PSSnapIn。从生成; 中删除此源文件不再需要它。

使用New-modulemanifest若要创建新的模块清单，即无需 PSSnapIn 注册代码。一些 PSSnapIn （如说明） 中的值可以在模块清单中重复使用。

RootModule模块清单中的属性应设置为实现 cmdlet 的程序集 (dll) 的名称。

.NET 可移植性分析器 (又称 APIPort)The .NET Portability Analyzer (aka APIPort)

为端口模块为 Windows PowerShell，若要使用 PowerShell Core，开始编写.NET 可移植性分析器。对已编译程序集以确定是否与.NET Framework、.NET Core 和其他.NET 运行时兼容的模块中使用的.NET Api 运行此工具。如果它们存在，则该工具建议备用 Api。否则，可能需要添加运行时检查并限制在特定的运行时中不可用的功能。

创建一个新的模块Creating a New Module

如果创建一个新的模块，建议是使用.NET CLI。

安装 PowerShell 标准模块模板Installing the PowerShell Standard Module Template

一旦安装了.NET CLI，安装的模板库生成一个简单的 PowerShell 模块。该模块将与 Windows PowerShell、 PowerShell Core、 Windows、 Linux 和 macOS 兼容。

下面的示例演示如何安装模板：

  1. dotnet new -i Microsoft.PowerShell.Standard.Module.Template
  1.   Restoring packages for C:\Users\Steve\.templateengine\dotnetcli\v2.1.302\scratch\restore.csproj...
  2.   Installing Microsoft.PowerShell.Standard.Module.Template 0.1.3.
  3.   Generating MSBuild file C:\Users\Steve\.templateengine\dotnetcli\v2.1.302\scratch\obj\restore.csproj.nuget.g.props.
  4.   Generating MSBuild file C:\Users\Steve\.templateengine\dotnetcli\v2.1.302\scratch\obj\restore.csproj.nuget.g.targets.
  5.   Restore completed in 1.66 sec for C:\Users\Steve\.templateengine\dotnetcli\v2.1.302\scratch\restore.csproj.
  7. Usage: new [options]
  9. Options:
  10.   -h, --help          Displays help for this command.
  11.   -l, --list          Lists templates containing the specified name. If no name is specified, lists all templates.
  12.   -n, --name          The name for the output being created. If no name is specified, the name of the current directory is used.
  13.   -o, --output        Location to place the generated output.
  14.   -i, --install       Installs a source or a template pack.
  15.   -u, --uninstall     Uninstalls a source or a template pack.
  16.   --nuget-source      Specifies a NuGet source to use during install.
  17.   --type              Filters templates based on available types. Predefined values are "project", "item" or "other".
  18.   --force             Forces content to be generated even if it would change existing files.
  19.   -lang, --language   Filters templates based on language and specifies the language of the template to create.
  22. Templates                                         Short Name         Language          Tags
  23. ----------------------------------------------------------------------------------------------------------------------------
  24. Console Application                               console            [C#], F#, VB      Common/Console
  25. Class library                                     classlib           [C#], F#, VB      Common/Library
  26. PowerShell Standard Module                        psmodule           [C#]              Library/PowerShell/Module
  27. ...

创建新的模块项目Creating a New Module Project

安装模板后，可以创建使用该模板的新 PowerShell 模块项目。在此示例中，示例模块是名为 myModule。

  1. PS> mkdir myModule
  3.     Directory: C:\Users\Steve
  5. Mode LastWriteTime Length Name
  6. ---- ------------- ------ ----
  7. d----- 8/3/2018 2:41 PM myModule
  9. PS> cd myModule
  10. PS C:\Users\Steve\myModule> dotnet new psmodule
  12. The template "PowerShell Standard Module" was created successfully.
  14. Processing post-creation actions...
  15. Running 'dotnet restore' on C:\Users\Steve\myModule\myModule.csproj...
  16.   Restoring packages for C:\Users\Steve\myModule\myModule.csproj...
  17.   Installing PowerShellStandard.Library 5.1.0.
  18.   Generating MSBuild file C:\Users\Steve\myModule\obj\myModule.csproj.nuget.g.props.
  19.   Generating MSBuild file C:\Users\Steve\myModule\obj\myModule.csproj.nuget.g.targets.
  20.   Restore completed in 1.76 sec for C:\Users\Steve\myModule\myModule.csproj.
  22. Restore succeeded.

生成模块Building the Module

使用标准.NET CLI 命令来生成项目。

  1. dotnet build
  1. PS C:\Users\Steve\myModule> dotnet build
  2. Microsoft (R) Build Engine version 15.7.179.6572 for .NET Core
  3. Copyright (C) Microsoft Corporation. All rights reserved.
  5.   Restore completed in 76.85 ms for C:\Users\Steve\myModule\myModule.csproj.
  6.   myModule -> C:\Users\Steve\myModule\bin\Debug\netstandard2.0\myModule.dll
  8. Build succeeded.
  9.     0 Warning(s)
  10.     0 Error(s)
  12. Time Elapsed 00:00:05.40

测试模块Testing the Module

在生成该模块之后, 可以将其导入并执行示例 cmdlet。

  1. ipmo .\bin\Debug\netstandard2.0\myModule.dll
  2. Test-SampleCmdlet -?
  3. Test-SampleCmdlet -FavoriteNumber 7 -FavoritePet Cat
  1. PS C:\Users\Steve\myModule> ipmo .\bin\Debug\netstandard2.0\myModule.dll
  2. PS C:\Users\Steve\myModule> Test-SampleCmdlet -?
  4. NAME
  5.     Test-SampleCmdlet
  7. SYNTAX
  8.     Test-SampleCmdlet [-FavoriteNumber] <int> [[-FavoritePet] {Cat | Dog | Horse}] [<CommonParameters>]
  11. ALIASES
  12.     None
  15. REMARKS
  16.     None
  19. PS C:\Users\Steve\myModule> Test-SampleCmdlet -FavoriteNumber 7 -FavoritePet Cat
  21. FavoriteNumber FavoritePet
  22. -------------- -----------
  23.              7 Cat

以下各节详细说明某些使用此模板的技术。

.NET 标准库.NET Standard Library

.NET standard是所有.NET 实现中可用的.NET Api 的正式规范。管理面向.NET Standard 适用于与该版本的.NET Standard 兼容的.NET Framework 和.NET Core 版本的代码。

备注

虽然 API 可能存在于.NET Standard，.NET Core 中的 API 实现可能会引发PlatformNotSupportedException在运行时，因此若要验证与 Windows PowerShell 和 PowerShell Core，兼容性的最佳做法是为你的模块在这两个环境中运行测试。如果你的模块是要将跨平台还在 Linux 和 macOS 上运行测试。

面向.NET Standard 可帮助确保，随着该模块后，不兼容的 Api 不会意外地获取引入到模块。在编译时，而不是运行时发现不兼容问题。

但是，它不需要以面向.NET Standard 的模块使用 Windows PowerShell 和 PowerShell Core，只要使用兼容的 Api。中间语言 (IL) 是两个运行时之间兼容。你可以面向.NET Framework 4.6.1，这是与.NET Standard 2.0 兼容。如果不使用.NET Standard 2.0 之外的 Api，然后在模块的工作原理与 PowerShell Core 6 无需重新编译。

PowerShell 标准库PowerShell Standard Library

PowerShell 标准库是所有的 PowerShell 版本大于或等于该标准的版本中提供的 PowerShell Api 的正式规范。

例如， PowerShell Standard 5.1兼容 Windows PowerShell 5.1 和 PowerShell Core 6.0 或更高版本。

我们建议你使用 PowerShell 标准库模块编译。该库可确保 Api 的可用性和在 Windows PowerShell 和 PowerShell Core 6 中实现。PowerShell 标准旨在始终是向前兼容。使用 PowerShell 标准库 5.1 构建的模块将始终与将来版本的 PowerShell 兼容。

模块清单Module Manifest

指示使用 Windows PowerShell 和 PowerShell Core 的兼容性Indicating Compatibility With Windows PowerShell and PowerShell Core

在验证之后，您的模块中适用于 Windows PowerShell 和 PowerShell Core，模块清单应显式指示兼容性通过使用CompatiblePSEditions属性。值为Desktop意味着该模块是使用 Windows PowerShell，而值兼容Core意味着该模块与 PowerShell Core 兼容。包括Desktop和Core意味着该模块是使用 Windows PowerShell 和 PowerShell Core 兼容。

备注

Core 并不意味着该模块适用于 Windows、 Linux 和 macOS。CompatiblePSEditions PowerShell v5 中引入了属性。模块清单，使用CompatiblePSEditions属性无法加载 PowerShell v5 之前的版本中。

指示操作系统兼容性Indicating OS Compatibility

首先，请验证您的模块中适用于 Linux 和 macOS。接下来，指示与在模块清单中的这些操作系统的兼容性。这使用户更轻松地找到你的模块时发布到其操作系统PowerShell 库。

在模块清单中，PrivateData属性具有PSData子属性。可选Tags属性的PSData采用 PowerShell 库中显示的值的数组。PowerShell 库支持以下兼容性值：

标记说明
PSEdition_Core与 PowerShell Core 6 兼容
PSEdition_Desktop使用 Windows PowerShell 的兼容
Windows与 Windows 兼容
Linux与 Linux （没有特定发行版） 兼容
macOS与 macOS 兼容

例如：

  1. @{
  2.     GUID = "4ae9fd46-338a-459c-8186-07f910774cb8"
  3.     Author = "Microsoft Corporation"
  4.     CompanyName = "Microsoft Corporation"
  5.     Copyright = "(C) Microsoft Corporation. All rights reserved."
  6.     HelpInfoUri = "https://go.microsoft.com/fwlink/?linkid=855962"
  7.     ModuleVersion = "1.2.4"
  8.     PowerShellVersion = "3.0"
  9.     ClrVersion = "4.0"
  10.     RootModule = "PackageManagement.psm1"
  11.     Description = 'PackageManagement (a.k.a. OneGet) is a new way to discover and install software packages from around the web.
  12.  It is a manager or multiplexer of existing package managers (also called package providers) that unifies Windows package management with a single Windows PowerShell interface. With PackageManagement, you can do the following.
  13.   - Manage a list of software repositories in which packages can be searched, acquired and installed
  14.   - Discover software packages
  15.   - Seamlessly install, uninstall, and inventory packages from one or more software repositories'
  17.     CmdletsToExport = @(
  18.         'Find-Package',
  19.         'Get-Package',
  20.         'Get-PackageProvider',
  21.         'Get-PackageSource',
  22.         'Install-Package',
  23.         'Import-PackageProvider'
  24.         'Find-PackageProvider'
  25.         'Install-PackageProvider'
  26.         'Register-PackageSource',
  27.         'Set-PackageSource',
  28.         'Unregister-PackageSource',
  29.         'Uninstall-Package'
  30.         'Save-Package'
  31.     )
  33.     FormatsToProcess  = @('PackageManagement.format.ps1xml')
  35.     PrivateData = @{
  36.         PSData = @{
  37.             Tags = @('PackageManagement', 'PSEdition_Core', 'PSEdition_Desktop', 'Windows', 'Linux', 'macOS')
  38.             ProjectUri = 'https://oneget.org'
  39.         }
  40.     }
  41. }