about_Scripts

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

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

Подробное описание

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

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

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

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

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

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

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

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

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

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

Set-ExecutionPolicy AllSigned

or

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, можно запускать сценарии из проводник.

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

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

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

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

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

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

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

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

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

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

Командлет 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 должен быть первым оператором в скрипте, за исключением комментариев и любых #Require инструкций.

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

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

В следующем примере показан 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.

Справка по написанию скриптов

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

• Справка на основе комментариев для сценариев

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

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

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

Чтобы связать скрипт с разделом справки на основе XML, используйте раздел справки. Ключевое слово комментария externalHelp Help. Дополнительные сведения о ключевом слове ExternalHelp см. в about_Comment_Based_Help. Дополнительные сведения о справке на основе XML см. в статье "Создание справки по командлетам".

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

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

or

. .\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 }
}

При запуске скрипта в собственной области New-Profile скрипта UtilityFunctions.ps1 функция и $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 В отличие от и автоматических переменных, которые содержат сведения о текущем скрипте, свойства $MyInvocation PSCommandPath и $PSScriptRoot PSScriptRoot переменной содержат сведения о скрипте, который называется текущим скриптом.

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

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

См. также

• about_Command_Precedence
• about_Comment_Based_Help
• about_Execution_Policies
• about_Functions
• about_Modules
• about_Profiles
• about_Requires
• about_Run_With_PowerShell
• about_Scopes
• about_Script_Blocks
• about_Signing
• Invoke-Command