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.