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, чтобы запросить журнал действия службы удаленного управления Windows.

.\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 справки по сценариям

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

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

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

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

Область скрипта и источники с точкой

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

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

Функция «с точкой» позволяет запускать скрипт в текущей области, а не в области скрипта. При запуске скрипта, который имеет точку с точкой, команды в скрипте выполняются так, будто были введены в командной строке. Функции, переменные, псевдонимы и диски, создаваемые сценарием, создаются в области, в которой выполняется работа. После выполнения скрипта можно использовать созданные элементы и получить доступ к их значениям в сеансе.

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

Пример:

. 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 . Переменная Микомманд. path содержит путь и имя файла скрипта. $MyInvocation. Строка содержит команду, которая запустила скрипт, включая все параметры и значения.

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

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

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

    В отличие от $PSCommandPath и $PSScriptRoot автоматических переменных, содержащих сведения о текущем скрипте, свойства пскоммандпас и 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