about_Scripts

Краткое описание

Описывает выполнение и запись скриптов в PowerShell.

Длинное описание

Скрипт — это обычный текстовый файл, содержащий одну или несколько команд PowerShell. Скрипты PowerShell имеют расширение .ps1 файла.

Выполнение скрипта очень похоже на выполнение cmdlet. Вы вводите путь и имя файла скрипта и используете параметры для отправки данных и задания параметров. Скрипты можно запускать на компьютере или в удаленном сеансе на другом компьютере.

Написание скрипта сохраняет команду для последующего использования и упрощает совместное использование с другими пользователями. Самое главное, это позволяет выполнять команды, просто введя путь к скрипту и имя файла. Скрипты могут быть простыми, как одна команда в файле, или сложными, как целая программа.

Скрипты имеют дополнительные функции, такие как #Requires специальный комментарий, использование параметров, поддержка разделов данных и цифровая подпись для обеспечения безопасности. Вы также можете написать разделы справки для сценариев и для любых функций в скрипте.

Запуск скрипта

Прежде чем запускать скрипт в Windows, необходимо изменить политику выполнения PowerShell по умолчанию. Политика выполнения не применяется к PowerShell, работающей на платформах, отличных от Windows.

Политика выполнения по умолчанию, Restricted, предотвращает выполнение всех скриптов, включая скрипты, которые записываются на локальном компьютере. Дополнительные сведения см. в about_Execution_Policies.

Политика выполнения сохраняется в реестре, поэтому ее необходимо изменить только один раз на каждом компьютере.

Чтобы изменить политику выполнения, используйте следующую процедуру.

В командной строке введите:

Set-ExecutionPolicy AllSigned

или

Set-ExecutionPolicy RemoteSigned

Изменение действует немедленно.

Чтобы запустить скрипт, введите полное имя и полный путь к файлу скрипта.

Например, чтобы запустить скрипт Get-ServiceLog.ps1 в каталоге C:\Scripts, введите следующее:

C:\Scripts\Get-ServiceLog.ps1

Чтобы запустить скрипт в текущем каталоге, введите путь к текущему каталогу или используйте точку для представления текущего каталога, за которым следует обратная косая черта пути (.\).

Например, чтобы запустить скрипт ServicesLog.ps1 в локальном каталоге, введите следующее:

.\Get-ServiceLog.ps1

Если скрипт имеет параметры, введите параметры и значения параметров после имени файла скрипта.

Например, следующая команда использует параметр ServiceName скрипта Get-ServiceLog для запроса журнала действий службы WinRM.

.\Get-ServiceLog.ps1 -ServiceName WinRM

В качестве функции безопасности PowerShell не запускает скрипты при двойном щелчке значка скрипта в проводнике или при вводе имени скрипта без полного пути, даже если скрипт находится в текущем каталоге. Дополнительную информацию о выполнении команд и сценариев в PowerShell можно найти в about_Command_Precedence.

Запуск с помощью PowerShell

Начиная с PowerShell 3.0, можно запускать сценарии из Проводника Windows.

Чтобы использовать функцию "Запуск с помощью PowerShell", выполните следующие действия.

Запустите проводник, щелкните правой кнопкой мыши имя файла скрипта и выберите команду "Выполнить с помощью PowerShell".

Функция "Запуск с помощью PowerShell" предназначена для выполнения скриптов, которые не имеют необходимых параметров и не возвращают выходные данные в командную строку.

Дополнительные сведения см. в about_Run_With_PowerShell.

Выполнение скриптов на других компьютерах

Чтобы запустить скрипт на одном или нескольких удаленных компьютерах, используйте параметр FilePath командлета Invoke-Command.

Введите путь и имя файла скрипта в качестве значения параметра FilePath. Скрипт должен находиться на локальном компьютере или в каталоге, к которому может получить доступ локальный компьютер.

Следующая команда запускает скрипт Get-ServiceLog.ps1 на удаленных компьютерах с именем Server01 и Server02.

$invokeCommandSplat = @{
    ComputerName = 'Server01', 'Server02'
    FilePath = 'C:\Scripts\Get-ServiceLog.ps1'
}
Invoke-Command @invokeCommandSplat

Получение справки по скриптам

Командлет Get-Help получает разделы справки для скриптов, командлетов и других типов команд. Чтобы получить раздел справки для скрипта, введите 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 должен быть первым оператором в скрипте, за исключением комментариев и любых операторов #Requires.

Параметры скрипта работают как параметры функции. Значения параметров доступны для всех команд в скрипте. Все функции параметров функции, включая атрибут "Параметр" и его именованные аргументы, также допустимы в скриптах.

При запуске скрипта пользователи вводят параметры после его имени.

В следующем примере показан скрипт Test-Remote.ps1 с параметром ComputerName. Обе функции скрипта могут получить доступ к значению параметра 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.

Помощь в написании скриптов

Вы можете написать раздел справки для скрипта с помощью одного из двух следующих методов:

• справка Comment-Based для сценариев

  Создайте раздел справки с помощью специальных ключевых слов в комментариях. Чтобы создать справку на основе комментариев для скрипта, комментарии должны размещаться в начале или конце файла скрипта. Дополнительные сведения о помощи на основе комментариев см. в about_Comment_Based_Help.

• XML-Based Справка для сценариев

  Создайте раздел справки на основе XML, например тип, который обычно создается для командлетов. Справка в формате XML необходима, если вы переводите разделы справки на несколько языков.

Чтобы связать скрипт с разделом справки на основе XML, используйте ключевое слово .EXTERNALHELP справки. Дополнительные сведения можно найти здесь

• about_Comment_Based_Help
• Как написать справку по командлетам

Возврат значения выхода

По умолчанию скрипты не возвращают состояние выхода при завершении скрипта. Для возврата кода выхода из скрипта необходимо использовать инструкцию 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) оператор выхода задает значение переменной среды %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, он действителен во всех сценариях.

• $MyInvocation — автоматическая переменная $MyInvocation содержит сведения о текущем скрипте, включая сведения о том, как оно было запущено или "вызвано". Эту переменную и ее свойства можно использовать для получения сведений о скрипте во время его выполнения. Например, $MyInvocation. Переменная MyCommand.Path содержит путь и имя файла скрипта. $MyInvocation. Строка содержит команду, которая запустила скрипт, включая все параметры и значения.

  Начиная с PowerShell 3.0, $MyInvocation имеет два новых свойства, которые предоставляют сведения о скрипте, который вызвал или запустил текущий скрипт. Значения этих свойств устанавливаются только в том случае, если вызывающий объект — скрипт.

  • PSCommandPath содержит полный путь и имя скрипта, который вызвал или инициировал текущий скрипт.

  • PSScriptRoot содержит каталог скрипта, который вызвал текущий скрипт.

  В отличие от $PSCommandPath и $PSScriptRoot автоматических переменных, которые содержат сведения о текущем скрипте, PSCommandPath и PSScriptRoot свойства переменной $MyInvocation содержат сведения о скрипте, который называется текущим скриптом.

• Разделы данных. Ключевое слово Data можно использовать для разделения данных из логики в скриптах. Разделы данных также могут упростить локализацию. Дополнительные сведения см. в разделе about_Data_Sections и about_Script_Internationalization.

• Подписывание скрипта. Вы можете добавить цифровую подпись в скрипт. В зависимости от политики выполнения можно использовать цифровые подписи для ограничения выполнения сценариев, которые могут включать небезопасные команды. Дополнительные сведения см. в разделах о about_Execution_Policies и о about_Signing.

См. также

• о_приоритете_команд
• about_Comment_Based_Help
• about_Execution_Policies
• о_функциях
• о_модулях
• о_профилях
• about_Requires
• about_Запуск_С_помощью_PowerShell
• about_Scopes
• about_Script_Blocks
• about_Signing
• Invoke-Command