关于脚本

简短描述

描述如何在 PowerShell 中运行和编写脚本。

详细描述

脚本是一种纯文本文件，其中包含一个或多个 PowerShell 命令。 PowerShell 脚本具有 .ps1 文件扩展名。

运行脚本很像运行 cmdlet。您键入脚本的路径和文件名，并使用参数提交数据和设置选项。您可以在您的计算机上运行脚本，也可以在另一台计算机上的远程会话中运行脚本。

编写脚本可以保存命令以供以后使用，并可以轻松与他人共享。最重要的是，它允许您只需输入脚本路径和文件名即可运行命令。脚本可以像文件中的单个命令一样简单，也可以像复杂的程序一样广泛。

脚本具有附加功能，例如#Requires 特殊注释、参数的使用、对数据部分的支持以及用于安全的数字签名。您还可以为脚本和脚本中的任何函数编写帮助主题。

如何运行脚本

在 Windows 上运行脚本之前，您需要更改默认的 PowerShell 执行策略。执行策略不适用于在非 Windows 平台上运行的 PowerShell。

默认执行策略Restricted 会阻止所有脚本运行，包括您在本地计算机上编写的脚本。有关更多信息，请参阅 about_Execution_Policies。

执行策略保存在注册表中，因此您只需在每台计算机上更改一次。

要更改执行策略，请使用以下过程。

在命令提示符处，键入：

Set-ExecutionPolicy AllSigned

或者

Set-ExecutionPolicy RemoteSigned

该变更立即生效。

要运行脚本，请键入脚本文件的全名和完整路径。

例如，要运行 C:\Scripts 目录中的 Get-ServiceLog.ps1 脚本，请键入：

C:\Scripts\Get-ServiceLog.ps1

要在当前目录中运行脚本，请键入当前目录的路径，或使用点表示当前目录，后跟路径反斜杠 (.\)。

例如，要运行本地目录中的 ServicesLog.ps1 脚本，请键入：

.\Get-ServiceLog.ps1

如果脚本有参数，请在脚本文件名后键入参数和参数值。

例如，以下命令使用 Get-ServiceLog 脚本的 ServiceName 参数来请求 WinRM 服务活动的日志。

.\Get-ServiceLog.ps1 -ServiceName WinRM

作为一项安全功能，当您双击文件资源管理器中的脚本图标或键入不带完整路径的脚本名称时，即使脚本位于当前目录中，PowerShell 也不会运行脚本。有关在 PowerShell 中运行命令和脚本的更多信息，请参阅 about_Command_Precedence。

使用 PowerShell 运行

从 PowerShell 3.0 开始，您可以从文件资源管理器运行脚本。

要使用“使用 PowerShell 运行”功能：

运行文件资源管理器，右键单击脚本文件名，然后选择“使用 PowerShell 运行”。

“使用 PowerShell 运行”功能旨在运行没有必需参数且不会将输出返回到命令提示符的脚本。

有关详细信息，请参阅 about_Run_With_PowerShell。

在其他计算机上运行脚本

要在一台或多台远程计算机上运行脚本，请使用 Invoke-Command cmdlet 的 FilePath 参数。

输入脚本的路径和文件名作为 FilePath 参数的值。该脚本必须驻留在本地计算机上或本地计算机可以访问的目录中。

以下命令在名为 Server01 和 Server02 的远程计算机上运行 Get-ServiceLog.ps1 脚本。

Invoke-Command -ComputerName Server01,Server02 -FilePath `
  C:\Scripts\Get-ServiceLog.ps1

获取脚本帮助

Get-Help cmdlet 获取脚本以及 cmdlet 和其他类型命令的帮助主题。要获取脚本的帮助主题，请键入 Get-Help，后跟脚本的路径和文件名。如果脚本路径位于 Path 环境变量中，则可以省略该路径。

例如，要获取 ServicesLog.ps1 脚本的帮助，请键入：

get-help C:\admin\scripts\ServicesLog.ps1

如何编写脚本

脚本可以包含任何有效的 PowerShell 命令，包括单个命令、使用管道、函数和控制结构（例如 If 语句和 For 循环）的命令。

要编写脚本，请在文本编辑器中打开一个新文件，键入命令，然后将它们保存在具有有效文件名和 .ps1 文件扩展名的文件中。

以下示例是一个简单的脚本，它获取当前系统上运行的服务并将它们保存到日志文件中。日志文件名是从当前日期创建的。

$date = (get-date).dayofyear
get-service | out-file "$date.log"

要创建此脚本，请打开文本编辑器或脚本编辑器，键入这些命令，然后将它们保存在名为 ServiceLog.ps1 的文件中。

脚本中的参数

要在脚本中定义参数，请使用 Param 语句。 Param 语句必须是脚本中的第一个语句，注释和任何 #Require 语句除外。

脚本参数的工作方式与函数参数类似。参数值可用于脚本中的所有命令。函数参数的所有功能（包括 Parameter 属性及其命名参数）在脚本中也有效。

运行脚本时，脚本用户在脚本名称后键入参数。

以下示例显示了一个具有 ComputerName 参数的 Test-Remote.ps1 脚本。这两个脚本函数都可以访问 ComputerName 参数值。

param ($ComputerName = $(throw "ComputerName parameter is required."))

function CanPing {
   $error.clear()
   $tmp = test-connection $computername -erroraction SilentlyContinue

   if (!$?)
       {write-host "Ping failed: $ComputerName."; return $false}
   else
       {write-host "Ping succeeded: $ComputerName"; return $true}
}

function CanRemote {
    $s = new-pssession $computername -erroraction SilentlyContinue

    if ($s -is [System.Management.Automation.Runspaces.PSSession])
        {write-host "Remote test succeeded: $ComputerName."}
    else
        {write-host "Remote test failed: $ComputerName."}
}

if (CanPing $computername) {CanRemote $computername}

要运行此脚本，请在脚本名称后键入参数名称。例如：

C:\PS> .\test-remote.ps1 -computername Server01

Ping succeeded: Server01
Remote test failed: Server01

有关 Param 语句和函数参数的更多信息，请参阅 about_Functions 和 about_Functions_Advanced_Parameters。

编写脚本帮助

您可以使用以下两种方法之一为脚本编写帮助主题：

• 基于注释的脚本帮助

  通过在评论中使用特殊关键字创建帮助主题。要为脚本创建基于注释的帮助，注释必须放置在脚本文件的开头或结尾。有关基于注释的帮助的详细信息，请参阅 about_Comment_Based_Help。

• 基于 XML 的脚本帮助

  创建基于 XML 的帮助主题，例如通常为 cmdlet 创建的类型。如果您要将帮助主题翻译成多种语言，则需要基于 XML 的帮助。

要将脚本与基于 XML 的帮助主题相关联，请使用 .ExternalHelp 帮助注释关键字。有关ExternalHelp 关键字的详细信息，请参阅about_Comment_Based_Help。有关基于 XML 的帮助的详细信息，请参阅如何编写 Cmdlet 帮助。

返回退出值

默认情况下，脚本结束时不会返回退出状态。您必须使用 exit 语句从脚本返回退出代码。默认情况下，exit 语句返回 0。您可以提供一个数值来返回不同的退出状态。非零退出代码通常表示失败。

在 Windows 上，允许 [int]::MinValue 和 [int]::MaxValue 之间的任何数字。

在 Unix 上，仅允许 [byte]::MinValue (0) 和 [byte]::MaxValue (255) 之间的正数。 -1 到 -255 范围内的负数会通过添加 256 自动转换为正数。例如，-2 为转换为 254。

在 PowerShell 中，exit 语句设置 $LASTEXITCODE 变量的值。在 Windows 命令外壳 (cmd.exe) 中，exit 语句设置 %ERRORLEVEL% 环境变量的值。

任何非数字或超出平台特定范围的参数都会转换为 0 值。

脚本范围和点来源

每个脚本都在其自己的范围内运行。在脚本中创建的函数、变量、别名和驱动器仅存在于脚本范围内。您无法在脚本运行的范围内访问这些项目或其值。

要在不同的范围内运行脚本，您可以指定一个范围，例如全局或本地，也可以点源该脚本。

点源功能允许您在当前范围而不是脚本范围中运行脚本。当您运行点源脚本时，脚本中的命令将像您在命令提示符处键入它们一样运行。脚本创建的函数、变量、别名和驱动器是在您工作的范围内创建的。脚本运行后，您可以使用创建的项目并在会话中访问它们的值。

要以点为来源的脚本，请在脚本路径前键入一个点 (.) 和一个空格。

例如：

. C:\scripts\UtilityFunctions.ps1

或者

. .\UtilityFunctions.ps1

UtilityFunctions.ps1 脚本运行后，该脚本创建的函数和变量将添加到当前作用域。

例如，UtilityFunctions.ps1 脚本创建 New-Profile 函数和 $ProfileName 变量。

#In UtilityFunctions.ps1

function New-Profile
{
  Write-Host "Running New-Profile function"
  $profileName = split-path $profile -leaf

  if (test-path $profile)
    {write-error "Profile $profileName already exists on this computer."}
  else
    {new-item -type file -path $profile -force }
}

如果您在自己的脚本作用域中运行 UtilityFunctions.ps1 脚本，则 New-Profile 函数和 $ProfileName 变量仅在该脚本运行时存在正在运行。当脚本退出时，函数和变量将被删除，如以下示例所示。

C:\PS> .\UtilityFunctions.ps1

C:\PS> New-Profile
The term 'new-profile' is not recognized as a cmdlet, function, operable
program, or script file. Verify the term and try again.
At line:1 char:12
+ new-profile <<<<
   + CategoryInfo          : ObjectNotFound: (new-profile:String) [],
   + FullyQualifiedErrorId : CommandNotFoundException

C:\PS> $profileName
C:\PS>

当您获取脚本并运行它时，脚本会在您的作用域内的会话中创建 New-Profile 函数和 $ProfileName 变量。脚本运行后，您可以在会话中使用 New-Profile 函数，如以下示例所示。

C:\PS> . .\UtilityFunctions.ps1

C:\PS> New-Profile

    Directory: C:\Users\juneb\Documents\WindowsPowerShell

    Mode    LastWriteTime     Length Name
    ----    -------------     ------ ----
    -a---   1/14/2009 3:08 PM      0 Microsoft.PowerShellISE_profile.ps1

C:\PS> $profileName
Microsoft.PowerShellISE_profile.ps1

有关范围的更多信息，请参阅 about_Scopes。

模块中的脚本

模块是一组可以作为一个单元进行分发的相关 PowerShell 资源。您可以使用模块来组织脚本、函数和其他资源。您还可以使用模块将代码分发给其他人，并从可信来源获取代码。

您可以在模块中包含脚本，也可以创建脚本模块，该模块完全或主要由脚本和支持资源组成。脚本模块只是一个带有 .psm1 文件扩展名的脚本。

有关模块的更多信息，请参阅 about_Modules。

其他脚本功能

PowerShell 具有许多可以在脚本中使用的有用功能。

• #Requires - 您可以使用 #Requires 语句来防止脚本在没有指定模块或管理单元以及指定版本的 PowerShell 的情况下运行。有关详细信息，请参阅 about_Requires。

• $PSCommandPath - 包含正在运行的脚本的完整路径和名称。该参数在所有脚本中都有效。 PowerShell 3.0 中引入了此自动变量。

• $PSScriptRoot - 包含运行脚本的目录。在 PowerShell 2.0 中，此变量仅在脚本模块 (.psm1) 中有效。从 PowerShell 3.0 开始，它在所有脚本中都有效。

• $MyInvocau - $MyInvocau 自动变量包含有关当前脚本的信息，包括有关如何启动或“调用”脚本的信息。您可以使用此变量及其属性来获取有关脚本运行时的信息。例如，$MyInitation.MyCommand.Path 变量包含脚本的路径和文件名。 $MyInspiration.Line 包含启动脚本的命令，包括所有参数和值。

  从 PowerShell 3.0 开始，$MyInspiration 有两个新属性，提供有关调用或调用当前脚本的脚本的信息。仅当调用者或调用者是脚本时才会填充这些属性的值。

  • PSCommandPath 包含调用或调用当前脚本的脚本的完整路径和名称。

• PSScriptRoot 包含调用或调用当前脚本的脚本的目录。

与包含当前脚本信息的 $PSCommandPath 和 $PSScriptRoot 自动变量不同，PSCommandPath 和 PSScriptRoot $MyInspiration 变量的属性包含有关调用当前脚本的脚本的信息。

参见

• about_Command_Precedence
• about_Comment_Based_Help
• about_Execution_Policies
• about_函数
• about_模块
• about_个人资料
• 关于_需要
• about_Run_With_PowerShell
• about_范围
• about_Script_Blocks
• about_签名
• Invoke-Command