如何编写 PowerShell 脚本模块

脚本模块是保存在 .psm1 扩展名中的任何有效 PowerShell 脚本。此扩展允许 PowerShell 引擎在您的文件上使用规则和模块 cmdlet。大多数功能都可以帮助您在其他系统上安装代码以及管理范围。您还可以使用模块清单文件，它描述了更复杂的安装和解决方案。

编写 PowerShell 脚本模块

要创建脚本模块，请将有效的 PowerShell 脚本保存到 .psm1 文件中。脚本和存储它的目录必须使用相同的名称。例如，名为 MyPsScript.psm1 的脚本存储在名为 MyPsScript 的目录中。

模块的目录需要位于 $env:PSModulePath 中指定的路径中。模块的目录可以包含运行脚本所需的任何资源，以及向 PowerShell 描述模块如何工作的模块清单文件。

创建基本的 PowerShell 模块

以下步骤描述了如何创建 PowerShell 模块。

1. 使用 .psm1 扩展名保存 PowerShell 脚本。脚本和保存脚本的目录使用相同的名称。

   使用 .psm1 扩展名保存脚本意味着您可以使用模块 cmdlet，例如 Import-Module。模块 cmdlet 的存在主要是为了将代码导入和导出到其他用户的系统。替代解决方案是将代码加载到其他系统上，然后将其点源到活动内存中，这不是一个可扩展的解决方案。有关详细信息，请参阅了解 Windows PowerShell 模块。默认情况下，当用户导入 .psm1 文件时，脚本中的所有函数都可以访问，但变量则不能。

   本文末尾提供了一个名为 Show-Calendar 的示例 PowerShell 脚本。

   function Show-Calendar {
   param(
       [DateTime] $start = [DateTime]::Today,
       [DateTime] $end = $start,
       $firstDayOfWeek,
       [int[]] $highlightDay,
       [string[]] $highlightDate = [DateTime]::Today.ToString('yyyy-MM-dd')
       )
   
       #actual code for the function goes here see the end of the topic for the complete code sample
   }
   

2. 要控制用户对某些函数或变量的访问，请在脚本末尾调用 Export-ModuleMember。

   本文底部的示例代码只有一个函数，默认情况下会公开该函数。但是，建议您显式调用您希望公开的函数，如以下代码中所述：

   function Show-Calendar {
         }
   Export-ModuleMember -Function Show-Calendar
   

   您可以使用模块清单限制导入的内容。有关详细信息，请参阅导入 PowerShell 模块和如何编写 PowerShell 模块清单。

3. 如果您有自己的模块需要加载的模块，则可以使用模块顶部的 Import-Module。

   Import-Module cmdlet 将目标模块导入到系统中，并且可以在稍后的过程中使用来安装您自己的模块。本文底部的示例代码不使用任何导入模块。但如果确实如此，它们将列在文件的顶部，如以下代码所示：

   Import-Module GenericModule
   

4. 要向 PowerShell 帮助系统描述您的模块，您可以在文件中使用标准帮助注释，也可以创建额外的帮助文件。

   本文底部的代码示例在注释中包含帮助信息。您还可以编写包含附加帮助内容的扩展 XML 文件。有关详细信息，请参阅编写 Windows PowerShell 模块的帮助。

5. 如果您有其他模块、XML 文件或其他想要与模块一起打包的内容，则可以使用模块清单。

   模块清单是一个包含其他模块的名称、目录布局、版本号、作者数据和其他信息的文件。 PowerShell 使用模块清单文件来组织和部署您的解决方案。有关详细信息，请参阅如何编写 PowerShell 模块清单。

6. 要安装并运行模块，请将模块保存到适当的 PowerShell 路径之一，然后使用 Import-Module。

   您可以安装模块的路径位于 $env:PSModulePath 全局变量中。例如，在系统上保存模块的常见路径为 %SystemRoot%/users//Documents/PowerShell/Modules/