about_Scripts

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

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

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

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

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

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

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

Чтобы использовать функцию "Запуск с Помощью 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 операторов.

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

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

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

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

• XML-Based справка по сценариям

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

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

• $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_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