about_scripts

主题
    about_Scripts

简短说明
    说明如何在 Windows PowerShell 中编写和运行脚本。

详细说明
    脚本是包含一个或多个 Windows PowerShell 命令的纯文本文件。Windows PowerShell 脚本的文件扩展
    名为 .ps1。

    编写脚本可以保存命令以备将来使用并轻松地与他人共享。更为重要的是,编写脚本后,您只需键入脚本
    路径和文件名即可运行命令。脚本既可以像文件中的单个命令那样简单,也可以像复杂应用程序那样错综复杂。

    脚本具有其他一些功能,例如 #Requires 特殊注释、参数使用、支持 Data 节,以及确保安全的数字签名。
    您还可以为脚本以及脚本中的任何函数编写帮助主题。

 如何编写脚本

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

    若要编写脚本,请打开记事本等文本编辑器或 Windows PowerShell 集成脚本环境 (ISE) 等脚本编辑器。
    请键入命令,并将命令保存在一个具有有效的文件名和 .ps1 文件扩展名的文件中。

    下面的示例是一个简单脚本,可以获取在当前系统上运行的服务,并将其保存到日志文件中。日志文件名根据当前日期创建。

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

    若要创建此脚本,请打开一个文本编辑器或脚本编辑器,键入这些命令,并将它们保存在一个
    名为"ServiceLog.ps1"的文件中。


 如何运行脚本

    在能够运行脚本之前,需要更改默认的 Windows PowerShell 执行策略。默认的执行策略"Restricted"
    会阻止所有脚本运行,包括在本地计算机上编写的脚本。有关详细信息,请参阅 
    about_Execution_Policies。

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

    例如,若要运行 C:\Scripts 目录中的 ServicesLog 脚本,请键入:

        c:\scripts\ServicesLog.ps1

    若要运行当前目录中的脚本,请键入当前目录的路径,或者使用一个圆点表示当前目录,在后面键入路径反斜杠 
    (.\)。

    例如,若要运行本地目录中的 ServicesLog.ps1 脚本,请键入:

        .\ServicesLog.ps1

    作为一种安全功能,当您在 Windows 资源管理器中双击脚本图标时,或键入不带完整路径的脚本名时(即使脚
    本位于当前目录中),Windows PowerShell 不会运行脚本。有关在 Windows PowerShell 中运行命令和
    脚本的详细信息,请参阅 about_Command_Precedence。


 远程运行脚本

    若要在远程计算机上运行脚本,请使用 Invoke-Command cmdlet 的 FilePath 参数。

    将脚本的路径和文件名输入到 Invoke-Command。该脚本必须位于本地计算机上或者本地计算机能够访问的目
    录中。

    以下命令在 Server01 远程计算机上运行 ServicesLog.ps1 脚本。

        invoke-command -computername Server01 -filepath C:\scripts\servicesLog.ps1


 脚本中的参数

    若要在脚本中定义参数,请使用 Param 语句。除了注释和所有的 #requires 语句之外,Param 语句必须是
    脚本中的第一个语句。

    脚本参数的作用类似于函数参数。参数值可供脚本中的所有命令使用。函数形式参数的所有功能(包括 
    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。



 脚本帮助

    Get-Help cmdlet 可获取脚本、cmdlet、提供程序和函数的帮助。若要获取脚本的帮助,
    请键入 Get-Help 和脚本的路径与文件名。如果脚本路径在 Path 环境变量中,则可以省略路径。

    例如,若要获取 ServicesLog.ps1 脚本的帮助,请键入:

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

    可使用以下两种方法当中的任意一种来编写脚本帮助:

    --  基于注释的脚本帮助

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

    --  基于 XML 的脚本帮助

        创建基于 XML 的帮助主题,例如通常为 cmdlet 创建的类型。如果要将帮助主题本地化为多种语言,
        则需要使用基于 XML 的帮助。

        若要将脚本与基于 XML 的帮助主题相关联,请使用 .ExternalHelp 帮助注释关键字。有关 
        ExternalHelp 关键字的详细信息,请参阅 about_Comment_Based_Help。有关基于 XML 的帮助的详
        细信息,请参阅 MSDN (Microsoft Developer Network) 库中的“如何编写 Cmdlet 帮助”。



 脚本作用域和使用点“.”获得来源

    每个脚本都在自己的作用域中运行。在脚本中创建的函数、变量、别名和驱动器仅存在于脚本作用域中,
    不能在运行脚本的作用域中访问这些项或它们的值。

    若要在不同的作用域中运行脚本,可以指定一个作用域(例如全局或本地),或者使用点“.”获得脚本来源。

    借助使用点“.”获得来源这一功能,您可以在当前作用域中(而不是在脚本作用域中)运行脚本。
    运行使用点“.”获得来源的脚本时,脚本中命令的运行方式与您在命令提示符处键入命令时相同。
    脚本所创建的函数、变量、别名和驱动器也将在您正在使用的作用域中创建。脚本运行后,
    可以在会话中使用已创建的项并访问它们的值。

    若要使用点“.”获得脚本来源,请在脚本路径前键入一个圆点 (.) 和一个空格。

    例如:

        . C:\scripts\UtilityFunctions.ps1

    -或 -

        . .\UtilityFunctions.ps1


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

    例如,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 "There is already a $profileName profile on this computer."}
            else
           {new-item -type file -path $profile -force }
        }


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

        C:\PS> .\UtilityFunctions.ps1

        C:\PS> New-Profile
        “new-profile”一词未被识别为 cmdlet、函数、可操作的程序,
        或脚本文件。请验证该词并重试。
        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。



 模块中的脚本

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

    可以将脚本包括在模块中,或者创建一个脚本模块,也就是完全或主要由脚本和支持资源组成的模块。脚本模块
    只是具有 .psm1 文件扩展名的脚本。

    有关模块的详细信息,请参阅 about_modules。



 其他脚本功能

    Windows PowerShell 具有很多可在脚本中使用的有用功能。

    #Requires
        可以使用 #requires 语句以阻止脚本在没有指定的模块或管理单元和指定的 Windows PowerShell 
        版本的情况下运行。有关详细信息,请参阅 about_Requires。

    $MyInvocation
        $MyInvocation 自动变量包含有关当前命令的信息,包括当前脚本。可以使用此变量及其属性在脚本
        运行时获取有关脚本的信息。例如,$MyInvocation.MyCommand.Path 变量包含脚本的路径和文件名。

    Data 节
        在脚本中,可以使用 Data 关键字将数据与逻辑分隔开。
        Data 节还可使本地化变得更加容易。有关详细信息,请参阅
        about_Data_Sections 和 about_Script_Localization。

    脚本签名
        可以为脚本添加数字签名。根据执行策略,可以使用数字签名来限制可能包括不安全命令
        的脚本的运行。有关详细信息,请参阅 about_Execution_Policies 和 about_Signing。



另请参阅
    about_Command_Precedence
    about_Comment_Based_Help
    about_Execution_Policies
    about_Functions
    about_Modules
    about_Profiles
    about_Requires
    about_Scopes
    about_Script_Blocks
    about_Signing
    Invoke-Command