Powershell функции: Функции — PowerShell | Microsoft Docs

Функции — PowerShell | Microsoft Docs

• 06/02/2020
• Чтение занимает 13 мин

В этой статье

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

По возможности я предпочитаю писать функции, потому что они больше ориентированы на работу со средствами. Я могу поместить функции в модуль сценария, отправить этот модуль в $env:PSModulePath и вызвать функции без необходимости физического определения их местонахождения. С помощью модуля PowerShellGet эти модули можно легко запрашивать в репозитории NuGet.

PowerShellGet поставляется с PowerShell версии 5.0 и выше. Он доступен в виде отдельного скачиваемого файла для PowerShell версии 3.0 и более поздних версий.

Не нужно ничего усложнять. Будьте проще и выбирайте самый прямой путь для решения задач. Избегайте псевдонимов и позиционных параметров в любом многократно используемом коде. Отформатируйте код, чтобы сделать его удобочитаемым. Не указывайте значения прямо в коде — используйте параметры и переменные. Не пишите лишний код, даже если это ничему не повредит. Он усложнит ситуацию. При написании кода PowerShell очень важно обращать внимание на детали.

Именование

При именовании функций в PowerShell используйте имя в Регистр Pascal с утвержденным глаголом и существительным в единственном числе. Кроме того, перед существительным рекомендуется добавить префикс. Например:

<ApprovedVerb>-<Prefix><SingularNoun>.

В PowerShell есть конкретный список утвержденных глаголов, которые можно получить, выполнив Get-Verb.

Get-Verb | Sort-Object -Property Verb

Verb        Group
----        -----
Add         Common
Approve     Lifecycle
Assert      Lifecycle
Backup      Data
Block       Security
Checkpoint  Data
Clear       Common
Close       Common
Compare     Data
Complete    Lifecycle
Compress    Data
Confirm     Lifecycle
Connect     Communications
Convert     Data
ConvertFrom Data
ConvertTo   Data
Copy        Common
Debug       Diagnostic
Deny        Lifecycle
Disable     Lifecycle
Disconnect  Communications
Dismount    Data
Edit        Data
Enable      Lifecycle
Enter       Common
Exit        Common
Expand      Data
Export      Data
Find        Common
Format      Common
Get         Common
Grant       Security
Group       Data
Hide        Common
Import      Data
Initialize  Data
Install     Lifecycle
Invoke      Lifecycle
Join        Common
Limit       Data
Lock        Common
Measure     Diagnostic
Merge       Data
Mount       Data
Move        Common
New         Common
Open        Common
Optimize    Common
Out         Data
Ping        Diagnostic
Pop         Common
Protect     Security
Publish     Data
Push        Common
Read        Communications
Receive     Communications
Redo        Common
Register    Lifecycle
Remove      Common
Rename      Common
Repair      Diagnostic
Request     Lifecycle
Reset       Common
Resize      Common
Resolve     Diagnostic
Restart     Lifecycle
Restore     Data
Resume      Lifecycle
Revoke      Security
Save        Data
Search      Common
Select      Common
Send        Communications
Set         Common
Show        Common
Skip        Common
Split       Common
Start       Lifecycle
Step        Common
Stop        Lifecycle
Submit      Lifecycle
Suspend     Lifecycle
Switch      Common
Sync        Data
Test        Diagnostic
Trace       Diagnostic
Unblock     Security
Undo        Common
Uninstall   Lifecycle
Unlock      Common
Unprotect   Security
Unpublish   Data
Unregister  Lifecycle
Update      Data
Use         Other
Wait        Lifecycle
Watch       Common
Write       Communications
   

В предыдущем примере результаты отсортированы по столбцу Verb. Взглянув на столбец Group, вы получите представление о том, как эти глаголы используются. При добавлении функций в модуль важно выбрать утвержденную команду в PowerShell. Если будет выбран неутвержденный глагол, модуль создаст предупреждение во время загрузки. Из-за этого предупреждения ваши функции выглядят непрофессионально. Кроме того, неутвержденные глаголы ограничивают возможности обнаружения функций.

Простая функция

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

function Get-Version {
    $PSVersionTable.PSVersion
}

Показан простой пример функции, возвращающей версию PowerShell.

Get-Version
 

Major  Minor  Build  Revision
-----  -----  -----  --------
5      1      14393  693

Существует большая вероятность возникновения конфликта имен функций, названных примерно как Get-Version, и команд по умолчанию в PowerShell или команд, которые могут написать другие пользователи. Именно поэтому в целях предотвращения конфликтов имен рекомендуется добавлять префикс к части функции, выраженной существительным. В следующем примере используется префикс PS.

function Get-PSVersion {
    $PSVersionTable.PSVersion
}

Эта функция идентична предыдущей, за исключением имени.

Get-PSVersion

Major  Minor  Build  Revision
-----  -----  -----  --------
5      1      14393  693

Даже при добавлении префикса типа PS все равно есть большая вероятность конфликта имен. Обычно перед существительным в имени функции я указываю свои инициалы. Разработайте свой стандарт и придерживайтесь его.

function Get-MrPSVersion {
    $PSVersionTable.PSVersion
}

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

 Get-MrPSVersion

Major  Minor  Build  Revision
-----  -----  -----  --------
5      1      14393  693

Функции, загруженные в память, можно увидеть на PSDrive Function.

Get-ChildItem -Path Function:\Get-*Version

CommandType     Name                                               Version    Source
-----------     ----                                               -------    ------
Function        Get-Version
Function        Get-PSVersion
Function        Get-MrPSVersion

Чтобы удалить эти функции из текущего сеанса, необходимо удалить их из PSDrive

Function или закрыть и повторно открыть PowerShell.

Get-ChildItem -Path Function:\Get-*Version | Remove-Item

Убедитесь, что функции действительно удалены.

Get-ChildItem -Path Function:\Get-*Version

Если функции были загружены в составе модуля, то, чтобы удалить их, можно выгрузить модуль.

Remove-Module -Name <ModuleName>

Командлет Remove-Module удаляет модули из памяти в текущем сеансе PowerShell, но не удаляет их из системы или с диска.

Параметры

Не присваивайте значения статически! Используйте параметры и переменные. Когда дело доходит до именования параметров, по возможности используйте те же имена, что и у командлетов по умолчанию.

function Test-MrParameter {

    param (
        $ComputerName
    )

    Write-Output $ComputerName

}

Почему в качестве имени параметра я использовал ComputerName, а не Computer, ServerName или Host? Потому что я хотел, чтобы мои функции были стандартизированы как стандартные командлеты.

Я создам функцию, которая будет запрашивать все команды в системе и возвращать количество команд с конкретными именами параметров.

function Get-MrParameterCount {
    param (
        [string[]]$ParameterName
    )

    foreach ($Parameter in $ParameterName) {
        $Results = Get-Command -ParameterName $Parameter -ErrorAction SilentlyContinue

        [pscustomobject]@{
            ParameterName = $Parameter
            NumberOfCmdlets = $Results. Count
        }
    }
}

Как видно в приведенных ниже результатах, у 39 команд есть параметр ComputerName. Командлеты с такими параметрами, как Computer, ServerName, Host или Machine

, не найдены.

Get-MrParameterCount -ParameterName ComputerName, Computer, ServerName, Host, Machine

ParameterName NumberOfCmdlets
------------- ---------------
ComputerName               39
Computer                    0
ServerName                  0
Host                        0
Machine                     0

Кроме того, имена параметров рекомендуется указывать в том же регистре, что и имена командлетов по умолчанию. Используйте ComputerName, а не computername. В этом случае функции выглядят и работают как командлеты по умолчанию. Это очень удобно для пользователей, уже знакомых с PowerShell.

paramОператор позволяет определить один или несколько параметров. Определения параметров разделяются запятой ( , ). Дополнительные сведения см. в разделе about_Functions_Advanced_Parameters.

Расширенные функции

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

Я начну с функции Test-MrParameter, которая использовалась в предыдущем разделе.

function Test-MrParameter {

    param (
        $ComputerName
    )

    Write-Output $ComputerName

}

Хочу обратить ваше внимание на то, что функция Test-MrParameter не имеет общих параметров. Существует несколько различных способов просмотра общих параметров. Один из них — просмотр синтаксиса с помощью Get-Command.

Get-Command -Name Test-MrParameter -Syntax

Test-MrParameter [[-ComputerName] <Object>]

Другой — детализация параметров с помощью Get-Command.

(Get-Command -Name Test-MrParameter).Parameters.Keys

ComputerName

Добавьте CmdletBinding, чтобы преобразовать функцию в расширенную.

function Test-MrCmdletBinding {

    [CmdletBinding()] #<<-- This turns a regular function into an advanced function
    param (
        $ComputerName
    )

    Write-Output $ComputerName

}

При добавлении CmdletBinding общие параметры добавляются автоматически. Для CmdletBinding требуется блок param, но блок param может быть пустым.

Get-Command -Name Test-MrCmdletBinding -Syntax

Test-MrCmdletBinding [[-ComputerName] <Object>] [<CommonParameters>]

Если выполнить детализацию параметров с помощью Get-Command, можно увидеть имена параметров, включая общие параметры.

(Get-Command -Name Test-MrCmdletBinding). Parameters.Keys

ComputerName
Verbose
Debug
ErrorAction
WarningAction
InformationAction
ErrorVariable
WarningVariable
InformationVariable
OutVariable
OutBuffer
PipelineVariable

SupportsShouldProcess

SupportsShouldProcess добавляет параметры WhatIf и Confirm. Они необходимы только для команд, которые вносят изменения.

function Test-MrSupportsShouldProcess {

    [CmdletBinding(SupportsShouldProcess)]
    param (
        $ComputerName
    )

    Write-Output $ComputerName

}

Обратите внимание, что теперь появились параметры WhatIf и Confirm.

Get-Command -Name Test-MrSupportsShouldProcess -Syntax

Test-MrSupportsShouldProcess [[-ComputerName] <Object>] [-WhatIf] [-Confirm] [<CommonParameters>]

Опять же: с помощью Get-Command можно получить список фактических имен параметров, включая общие параметры и WhatIf и Confirm.

(Get-Command -Name Test-MrSupportsShouldProcess).Parameters.Keys

ComputerName
Verbose
Debug
ErrorAction
WarningAction
InformationAction
ErrorVariable
WarningVariable
InformationVariable
OutVariable
OutBuffer
PipelineVariable
WhatIf
Confirm

Проверка параметров

Входные данные следует проверять в самом начале. Для чего продолжать выполнение кода, если это невозможно сделать без допустимых входных данных?

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

function Test-MrParameterValidation {

    [CmdletBinding()]
    param (
        [string]$ComputerName
    )

    Write-Output $ComputerName

}

В предыдущем примере в качестве типа данных для параметра ComputerName указано String. Это означает, что допускается только одно имя компьютера. Если задается несколько имен компьютеров в виде списка с разделителями-запятыми, возникает ошибка.

Test-MrParameterValidation -ComputerName Server01, Server02

Test-MrParameterValidation : Cannot process argument transformation on parameter
'ComputerName'. Cannot convert value to type System.String.
At line:1 char:42
+ Test-MrParameterValidation -ComputerName Server01, Server02
+
    + CategoryInfo          : InvalidData: (:) [Test-MrParameterValidation], ParameterBindingArg
     umentTransformationException
    + FullyQualifiedErrorId : ParameterArgumentTransformationError,Test-MrParameterValidation

Проблема с текущим определением заключается в том, что значение параметра ComputerName можно опустить, но оно требуется для успешного выполнения функции. Именно в таком случае будет полезен атрибут параметра Mandatory.

function Test-MrParameterValidation {

    [CmdletBinding()]
    param (
        [Parameter(Mandatory)]
        [string]$ComputerName
    )

    Write-Output $ComputerName

}

В предыдущем примере используется синтаксис, совместимый с PowerShell версии 3. 0 и более поздними. Чтобы обеспечить совместимость функции с PowerShell версии 2.0 и более поздними, можно указать [Parameter(Mandatory=$true)]. Теперь, когда потребуется значение параметра ComputerName, которое пока не задано, функция выведет соответствующий запрос.

Test-MrParameterValidation

cmdlet Test-MrParameterValidation at command pipeline position 1
Supply values for the following parameters:
ComputerName:

Чтобы разрешить несколько значений для параметра ComputerName, используйте тип данных String, но добавьте к нему открывающие и закрывающие квадратные скобки, позволяющие использовать массив строк.

function Test-MrParameterValidation {

    [CmdletBinding()]
    param (
        [Parameter(Mandatory)]
        [string[]]$ComputerName
    )

    Write-Output $ComputerName

}

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

function Test-MrParameterValidation {

    [CmdletBinding()]
    param (
        [ValidateNotNullOrEmpty()]
        [string[]]$ComputerName = $env:COMPUTERNAME
    )

    Write-Output $ComputerName

}

Даже при задании значения по умолчанию старайтесь не прибегать к статическим значениям. В предыдущем примере в качестве значения по умолчанию используется $env:COMPUTERNAME, которое автоматически преобразуется в имя локального компьютера, если значение не указано.

Подробные выходные данные

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

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

function Test-MrVerboseOutput {

    [CmdletBinding()]
    param (
        [ValidateNotNullOrEmpty()]
        [string[]]$ComputerName = $env:COMPUTERNAME
    )

    foreach ($Computer in $ComputerName) {
        #Attempting to perform some action on $Computer <<-- Don't use
        #inline comments like this, use write verbose instead.
        Write-Output $Computer
    }

}

Лучшим вариантом является использование Write-Verbose вместо встроенных комментариев.

function Test-MrVerboseOutput {

    [CmdletBinding()]
    param (
        [ValidateNotNullOrEmpty()]
        [string[]]$ComputerName = $env:COMPUTERNAME
    )

    foreach ($Computer in $ComputerName) {
        Write-Verbose -Message "Attempting to perform some action on $Computer"
        Write-Output $Computer
    }

}

Если функция вызывается без параметра verbose, подробные выходные данные отображаться не будут.

Test-MrVerboseOutput -ComputerName Server01, Server02

При вызове функции с параметром verbose будут выведены подробные выходные данные.

Test-MrVerboseOutput -ComputerName Server01, Server02 -Verbose

Входные данные конвейера

Если требуется, чтобы функция принимала входные данные конвейера, необходимо написать дополнительный код. Как говорилось ранее в этой книге, команды могут принимать входные данные конвейера по значению (по типу) или по имени свойства. Вы можете писать свои функции так же, как машинные команды, чтобы они принимали один тип входных данных или оба.

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

Входные данные конвейера поступают в один элемент за раз аналогично тому, как элементы обрабатываются в цикле foreach. Если в качестве входных данных принимается массив, для обработки каждого из этих элементов требуется как минимум блок process. Если в качестве входных данных принимается только одно значение, блок process не требуется, но я по-прежнему рекомендую указывать его для обеспечения согласованности.

function Test-MrPipelineInput {

    [CmdletBinding()]
    param (
        [Parameter(Mandatory,
                   ValueFromPipeline)]
        [string[]]$ComputerName
    )

    PROCESS {
        Write-Output $ComputerName
    }

}

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

function Test-MrPipelineInput {

    [CmdletBinding()]
    param (
        [Parameter(Mandatory,
                   ValueFromPipelineByPropertyName)]
        [string[]]$ComputerName
    )

    PROCESS {
            Write-Output $ComputerName
    }

}

Блоки BEGIN и END являются необязательными. BEGIN указывается перед блоком PROCESS и используется для выполнения всех начальных задач до получения элементов из конвейера. Разобраться с этим очень важно. Переданные значения недоступны в блоке BEGIN. Блок END указывается после блока PROCESS и используется для очистки после обработки всех переданных элементов.

Обработка ошибок

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

function Test-MrErrorHandling {

    [CmdletBinding()]
    param (
        [Parameter(Mandatory,
                   ValueFromPipeline,
                   ValueFromPipelineByPropertyName)]
        [string[]]$ComputerName
    )

    PROCESS {
        foreach ($Computer in $ComputerName) {
            Test-WSMan -ComputerName $Computer
        }
    }

}

В PowerShell существует несколько различных способов обработки ошибок. Более современным является Try/Catch.

function Test-MrErrorHandling {

    [CmdletBinding()]
    param (
        [Parameter(Mandatory,
                   ValueFromPipeline,
                   ValueFromPipelineByPropertyName)]
        [string[]]$ComputerName
    )

    PROCESS {
        foreach ($Computer in $ComputerName) {
            try {
                Test-WSMan -ComputerName $Computer
            }
            catch {
                Write-Warning -Message "Unable to connect to Computer: $Computer"
            }
        }
    }

}

Хотя функция, показанная в предыдущем примере, использует обработку ошибок, она также выдает необработанное исключение, так как команда не создает неустранимую ошибку. Разобраться с этим очень важно! Перехватываются только устранимые ошибки. Чтобы преобразовать неустранимую ошибку в устранимую, укажите параметр ErrorAction со значением Stop.

function Test-MrErrorHandling {

    [CmdletBinding()]
    param (
        [Parameter(Mandatory,
                   ValueFromPipeline,
                   ValueFromPipelineByPropertyName)]
        [string[]]$ComputerName
    )

    PROCESS {
        foreach ($Computer in $ComputerName) {
            try {
                Test-WSMan -ComputerName $Computer -ErrorAction Stop
            }
            catch {
                Write-Warning -Message "Unable to connect to Computer: $Computer"
            }
        }
    }

}

Не изменяйте глобальную переменную $ErrorActionPreference, если в этом нет крайней необходимости. Если вы используете нечто вроде .NET непосредственно в функции PowerShell, параметр ErrorAction невозможно указать в самой команде. В этом случае может потребоваться изменить глобальную переменную $ErrorActionPreference, но, если вы измените ее, верните ее к исходному виду сразу же после того, как попробуете запустить команду.

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

function Get-MrAutoStoppedService {

<#
.SYNOPSIS
    Returns a list of services that are set to start automatically, are not
    currently running, excluding the services that are set to delayed start.

.DESCRIPTION
    Get-MrAutoStoppedService is a function that returns a list of services from
    the specified remote computer(s) that are set to start automatically, are not
    currently running, and it excludes the services that are set to start automatically
    with a delayed startup.

.PARAMETER ComputerName
    The remote computer(s) to check the status of the services on.

.PARAMETER Credential
    Specifies a user account that has permission to perform this action.  The default
    is the current user.

.EXAMPLE
     Get-MrAutoStoppedService -ComputerName 'Server1', 'Server2'

.EXAMPLE
     'Server1', 'Server2' | Get-MrAutoStoppedService

.EXAMPLE
     Get-MrAutoStoppedService -ComputerName 'Server1' -Credential (Get-Credential)

.INPUTS
    String

.OUTPUTS
    PSCustomObject

.NOTES
    Author:  Mike F Robbins
    Website: http://mikefrobbins.com
    Twitter: @mikefrobbins
#>

    [CmdletBinding()]
    param (

    )

    #Function Body

}

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

Весь синтаксис написания функции в PowerShell может показаться слишком объемным и перегруженным, особенно для тех, кто только начинает работу с этой оболочкой. Часто, если я не могу вспомнить какой-то синтаксис, я открываю вторую копию ISE на отдельном мониторе, просматриваю фрагмент «Cmdlet (расширенная функция) — Complete» и одновременно ввожу код для функции. В интегрированной среде сценариев PowerShell доступ к фрагментам кода можно получить с помощью сочетания клавиш CTRL+J.

Сводка

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

Просмотр

1. Как получить список утвержденных глаголов в PowerShell?
2. Как преобразовать функцию PowerShell в расширенную функцию?
3. Когда следует добавлять параметры WhatIf и Confirm в функции PowerShell?
4. Как преобразовать неустранимую ошибку в устранимую?
5. Для чего нужно добавлять справку на основе комментариев к функциям?

Рекомендуем прочесть

о функциях — PowerShell | Microsoft Docs

• 000Z» data-article-date-source=»ms.date»>2/27/2019
• Чтение занимает 10 мин

В этой статье

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

Описание создания и использования функций в PowerShell.

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

Функция — это список операторов PowerShell с назначенным именем. При запуске функции необходимо ввести имя функции. Инструкции в списке выполняются так, как если бы вы вводили их в командной строке.

Функции могут быть простыми:

function Get-PowerShellProcess { Get-Process PowerShell }

Функция также может быть сложной в качестве командлета или программы приложения.

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

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

Список операторов функции может содержать различные типы списков операторов с ключевыми словами Begin , Process и End . Эти списки инструкций обработают входные данные из конвейера по-разному.

Фильтр — это специальный тип функции, который использует Filter ключевое слово.

Функции также могут действовать как командлеты. Можно создать функцию, которая работает так же, как командлет, без использования C# программирования. Дополнительные сведения см. в разделе about_Functions_Advanced.

Синтаксис

Ниже приведен синтаксис функции.

function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])]
{
  param([type]$parameter1 [,[type]$parameter2])
  dynamicparam {<statement list>}
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
}

Функция включает следующие элементы:

• FunctionКлючевое слово
• Область (необязательно)
• Выбранное имя
• Любое количество именованных параметров (необязательно)
• Одна или несколько команд PowerShell, заключенных в фигурные скобки {}

Дополнительные сведения о Dynamicparam ключевом слове и динамических параметрах в функциях см. в разделе about_Functions_Advanced_Parameters.

Простые функции

Функции не обязательно должны быть очень сложными. Простейшие функции имеют следующий формат:

function <function-name> {statements}

Например, следующая функция запускает PowerShell с параметром Запуск от имени администратора.

function Start-PSAdmin {Start-Process PowerShell -Verb RunAs}

Чтобы использовать функцию, введите: Start-PSAdmin

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

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

function Get-NewPix
{
  $start = Get-Date -Month 1 -Day 1 -Year 2010
  $allpix = Get-ChildItem -Path $env:UserProfile\*.jpg -Recurse
  $allpix | Where-Object {$_.LastWriteTime -gt $Start}
}

Вы можете создать панель элементов с полезными небольшими функциями. Добавьте эти функции в профиль PowerShell, как описано в about_Profiles и далее в этом разделе.

Имена функций

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

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

Функции должны использовать стандартные команды, которые были утверждены для всех команд PowerShell. Эти команды помогают нам упростить, согласовать и легко понимать имена команд.

Дополнительные сведения о стандартных командах PowerShell см. в разделе утвержденные команды в документация Майкрософт.

Функции с параметрами

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

именованных параметров

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

Параметры внутри фигурных скобок можно определить с помощью Param ключевого слова, как показано в следующем примере синтаксиса:

function <name> {
  param ([type]$parameter1[,[type]$parameter2])
  <statement list>
}

Можно также определить параметры за пределами фигурных скобок без Param ключевого слова, как показано в следующем примере синтаксиса:

function <name> [([type]$parameter1[,[type]$parameter2])] {
  <statement list>
}

Ниже приведен пример альтернативного синтаксиса.

Function Add-Numbers($one, $two) {
    $one + $two
}

Хотя первый метод является предпочтительным, разница между этими двумя методами отсутствует.

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

В следующем примере показана функция с именем Get-SmallFiles . Эта функция имеет $Size параметр. Функция отображает все файлы, размер которых меньше значения $Size параметра, и исключает каталоги.

function Get-SmallFiles {
  Param($Size)
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

В функции можно использовать $Size переменную, которая является именем, определенным для параметра.

Чтобы использовать эту функцию, введите следующую команду:

Get-SmallFiles -Size 50

Можно также ввести значение для именованного параметра без имени параметра. Например, следующая команда дает тот же результат, что и команда, которая присваивает имя параметру size :

Get-SmallFiles 50

Чтобы определить значение по умолчанию для параметра, введите знак равенства и значение после имени параметра, как показано в следующем варианте Get-SmallFiles примера:

function Get-SmallFiles ($Size = 100) {
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

Если ввести Get-SmallFiles без значения, функция присваивает 100 значение $size . Если указать значение, то функция использует это значение.

При необходимости можно указать краткую строку справки, описывающую значение параметра по умолчанию, добавив атрибут псдефаултвалуе в описание параметра и указав свойство Help объекта псдефаултвалуе. Чтобы предоставить строку справки, описывающую значение по умолчанию (100) параметра size в Get-SmallFiles функции, добавьте атрибут псдефаултвалуе , как показано в следующем примере.

function Get-SmallFiles {
  param (
      [PSDefaultValue(Help = '100')]
      $Size = 100
  )
}

Дополнительные сведения о классе атрибута псдефаултвалуе см. в разделе псдефаултвалуе Attribute Members.

Параметры позиционирования

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

При использовании позиционированных параметров введите одно или несколько значений после имени функции. Значения позиционированных параметров присваиваются $args переменной массива. Значение, следующее за именем функции, присваивается первой положению в $args массиве, $args[0] .

Следующая Get-Extension функция добавляет .txt расширение имени файла к указанному имени файла:

function Get-Extension {
  $name = $args[0] + ".txt"
  $name
}

Get-Extension myTextFile

myTextFile.txt

Параметры переключателя

Переключатель — это параметр, который не требует значения. Вместо этого введите имя функции, за которым следует имя параметра переключателя.

Чтобы определить параметр переключателя, укажите тип [switch] перед именем параметра, как показано в следующем примере:

function Switch-Item {
  param ([switch]$on)
  if ($on) { "Switch on" }
  else { "Switch off" }
}

При вводе On параметра Switch после имени функции функция отображает параметр on. Без параметра Switch отображается значение «Отключить выключение».

Switch-Item -on

Switch on

Switch-Item

Switch off

При выполнении функции можно также присвоить логическое значение параметру, как показано в следующем примере:

Switch-Item -on:$true

Switch on

Switch-Item -on:$false

Switch off

Использование Сплаттинг для представления параметров команды

Сплаттинг можно использовать для представления параметров команды. Эта функция появилась в Windows PowerShell 3,0.

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

Следующий пример функции вызывает Get-Command командлет. Команда использует @Args для представления параметров Get-Command .

function Get-MyCommand { Get-Command @Args }

Get-CommandПри вызове функции можно использовать все параметры Get-MyCommand . Параметры и значения параметров передаются в команду с помощью команды @Args .

Get-MyCommand -Name Get-ChildItem

CommandType     Name                ModuleName
-----------     ----                ----------
Cmdlet          Get-ChildItem       Microsoft.PowerShell.Management

Эта @Args функция использует $Args Автоматический параметр, представляющий необъявленные параметры и значения командлета из оставшихся аргументов.

Дополнительные сведения о Сплаттинг см. в разделе about_Splatting.

Передача объектов в функции

Любая функция может принимать входные данные из конвейера. Можно контролировать, как функция обрабатывает входные данные из конвейера с помощью Begin Process End ключевых слов, и. В следующем образце синтаксиса показаны три ключевых слова:

function <name> {
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
}

BeginСписок инструкций выполняется только один раз в начале функции.

Важно!

Если функция определяет Begin блок, то Process End весь код должен находиться внутри этих блоков. Код не будет располагаться за пределами блоков, если определены какие либо блоки.

ProcessСписок инструкций выполняется один раз для каждого объекта в конвейере. Во время Process выполнения блока каждый объект конвейера назначается $_ автоматической переменной, по одному объекту конвейера за раз.

После того как функция получит все объекты в конвейере, End список инструкций будет выполняться один раз. Если не Begin Process End используются ключевые слова, или, все инструкции рассматриваются как End список инструкций.

Следующая функция использует Process ключевое слово. Функция отображает примеры из конвейера:

function Get-Pipeline
{
  process {"The value is: $_"}
}

Чтобы продемонстрировать эту функцию, введите список чисел, разделенных запятыми, как показано в следующем примере:

1,2,4 | Get-Pipeline

The value is: 1
The value is: 2
The value is: 4

При использовании функции в конвейере объекты, переданный функции, назначаются $input автоматической переменной. Функция выполняет инструкции с Begin ключевым словом перед тем, как все объекты поступают из конвейера. Функция выполняет инструкции с End ключевым словом после того, как все объекты были получены из конвейера.

В следующем примере показана $input Автоматическая переменная с Begin End ключевыми словами и.

function Get-PipelineBeginEnd
{
  begin {"Begin: The input is $input"}
  end {"End:   The input is $input" }
}

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

1,2,4 | Get-PipelineBeginEnd

Begin: The input is
End:   The input is 1 2 4

При Begin выполнении инструкции функция не имеет входных данных из конвейера. EndИнструкция выполняется после того, как функция применяет значения.

Если у функции есть Process ключевое слово, каждый объект в удаляется $input из $input и присваивается $_ . В следующем примере содержится Process список операторов:

function Get-PipelineInput
{
  process {"Processing:  $_ " }
  end {"End:   The input is: $input" }
}

В этом примере каждый объект, передаваемый функции, отправляется в Process список инструкций. ProcessИнструкции выполняются для каждого объекта, по одному объекту за раз. $inputАвтоматическая переменная пуста, если функция достигает End ключевого слова.

1,2,4 | Get-PipelineInput

Processing:  1
Processing:  2
Processing:  4
End:   The input is:

Дополнительные сведения см. в разделе Использование перечислителей .

Фильтры

Фильтр — это тип функции, которая выполняется для каждого объекта в конвейере. Фильтр напоминает функцию со всеми ее операторами в Process блоке.

Синтаксис фильтра выглядит следующим образом:

filter [<scope:>]<name> {<statement list>}

Следующий фильтр принимает записи журнала из конвейера, а затем отображает всю запись или только часть сообщения в записи:

filter Get-ErrorLog ([switch]$message)
{
  if ($message) { Out-Host -InputObject $_.Message }
  else { $_ }
}

Область действия функции

Функция существует в области, в которой она была создана.

Если функция является частью скрипта, функция доступна для инструкций внутри этого скрипта. По умолчанию функция в скрипте недоступна в командной строке.

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

function global:Get-DependentSvs {
  Get-Service | Where-Object {$_.DependentServices}
}

Если функция находится в глобальной области, ее можно использовать в скриптах, функциях и в командной строке.

Обычно функции создают область. Элементы, созданные в функции, такие как переменные, существуют только в области видимости функции.

Дополнительные сведения об области действия в PowerShell см. в разделе about_Scopes.

Поиск функций и управление ими с помощью диска Function:

Все функции и фильтры в PowerShell автоматически сохраняются на Function: диске. Этот диск предоставляется поставщиком функций PowerShell.

При обращении к Function: диску введите двоеточие после функции, как при обращении к C диску или на D диске компьютера.

Следующая команда отображает все функции в текущем сеансе PowerShell:

Get-ChildItem function:

Команды в функции хранятся в виде блока скрипта в свойстве определения функции. Например, чтобы отобразить команды в функции справки, поставляемой с PowerShell, введите:

(Get-ChildItem function:help).Definition

Можно также использовать следующий синтаксис.

$function:help

Дополнительные сведения о Function: диске см. в разделе справки по поставщику функций . Введите Get-Help Function.

Повторное использование функций в новых сеансах

При вводе функции в командной строке PowerShell функция станет частью текущего сеанса. Он доступен до завершения сеанса.

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

Можно также сохранить функцию в файле сценария PowerShell. Введите функцию в текстовом файле, а затем сохраните файл с .ps1 расширением имени файла.

Написание справки для функций

Get-HelpКомандлет возвращает справку по функциям, а также к командлетам, поставщикам и скриптам. Чтобы получить справку по функции, введите, Get-Help за которым следует имя функции.

Например, чтобы получить справку по Get-MyDisks функции, введите:

Get-Help Get-MyDisks

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

• Comment-Based справки по функциям

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

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

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

  Чтобы связать функцию с разделом справки на основе XML, используйте .ExternalHelp ключевое слово справки на основе комментариев. Без этого ключевого слова Get-Help не удается найти раздел справки по функциям и вызовы для Get-Help функции, возвращающие только автоматически созданную справку.

  Дополнительные сведения о ExternalHelp ключевом слове см. в разделе about_Comment_Based_Help. Дополнительные сведения о справке на основе XML см. в разделе как написать справку по командлетам.

См. также

about_Automatic_Variables

about_Comment_Based_Help

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_Advanced_Parameters

about_Functions_CmdletBindingAttribute

about_Functions_OutputTypeAttribute

about_Parameters

about_Profiles

about_Scopes

about_Script_Blocks

about_Function_provider

PowerShell. Пользовательские функции для пользователей / Хабр

Привет! Довольно часто в своей работе приходиться пользоваться самостоятельно написанными функциями и таскать куски кода между разными скриптами. На Хабре уже есть довольно хорошая статья про

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

от

Mroff

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

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

Function TestPath ([String]$Path)
        {
                Return(Test-Path $Path)
        }

В общем то ничего сложного, как и в других языках задали имя TestPath, в круглых скобках через запятую скормили переменные $Path, выполнили в теле функции необходимые действия и при необходимости вернули Return() значение. А как быть, когда нужно работать с несколькими переменными? Выходов всегда больше одного – постоянно давать мнемонические коды или делать описание переменной, давайте рассмотрим, как это делается:

Function TestPath
        {
                PARAM (
                [PARAMETER(Mandatory=$True,Position=0,HelpMessage = "Путь до проверяемого ресурса",ParameterSetName='Path')]$Path
                )
                Return(Test-Path $Path)
        }

Сложности никакой нет, но появились дополнительные параметры, которые нам упрощают жизнь:

Mandatory – Принимает два значения True обязательный для заполнения и False необязательный;
HelpMessage – Справка по переменной;
ParameterSetName – Имя переменной к которой относятся данные параметры;
Position – Позиция переменной при вызове функции;

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

((Get-Command TestPath).ParameterSets.Parameters | Where-Object Name -eq Path).HelpMessage

PowerShell ответит нам одной строкой в которой будет написано: Путь до проверяемого ресурса.

В какой-то степени удобно, но если мы привыкли работать с PowerShell, то знаем команду Get-Help которая выводит подробную информацию о функции с примерами ее использования и переменными, которые необходимо передавать.

Немного усложним задачу и подготовим функцию информация о которой по запросу Get-Help будет выводиться в полном объеме:

Function WriteToLog {
    <#
    .SYNOPSIS
        Вывод сообщения в консоль и в файл лога.
    .DESCRIPTION
        Данная функция выводит переданную строку в лог файл и в консоль PowerShell
    .EXAMPLE
        #WriteToLog -Str "Данное сообщение будет выведено в консоль красным цветом и в файл C:\Log\log.txt" -FileName 'C:\Log\log.txt' -Color Red
    .EXAMPLE
        #WriteToLog -Str "Данное сообщение будет выведено в консоль цветом по умолчанию (White) и в файл C:\Log\log.txt" -FileName 'C:\Log\log.txt'
    .PARAMETER Str
        Строка, которую необходимо вывести (обязательный параметр)
    .PARAMETER FileName
        Имя файла лога (обязательный параметр)
    .PARAMETER Color
        Цвет текста сообщения в консоли PowerShell (По умолчанию цвет текста белый (White))
    #>
    param (
        [PARAMETER(Mandatory=$True,Position=0)][String]$Str,
        [PARAMETER(Mandatory=$True,Position=1)][String]$FileName,
        [PARAMETER(Mandatory=$False,Position=2)][String]$Color='White'
        )
        Write-Host $Str -ForegroundColor $Color
        If ((Test-Path $FileName) -eq $True)
            {
                Add-Content -Path $FileName -Value $Str
            }
        Else
            {
                Set-Content -Path $FileName -Value $Str
            }
    }

После выполнения данного кода команда Get-Help ‘WriteToLog’ -ShowWindow выведет нам следующее окно.

Давайте разберем что же мы такого написали:

<##> – В данном блоке написаны параметры для справки PowerShell.
.SYNOPSIS – блок для краткого описание функции
.DESCRIPTION – блок для полного описание функции
.EXAMPLE – блок для примера использования функции, может быть несколько
.PARAMETR Имя параметра – блок для описания переменной, для каждой переменной свой блок.

Как вы могли заметить текстовый комментарий начинается со следующей строки после ключевого названия раздела и может быть многострочным. Окончанием комментария считается закрывающий тег #> или следующий блок.

param () – блок для описания переменных, в котором мы указали их порядок и необходимость передачи параметров при вызове функции. Для переменной $Color мы присвоили значение по умолчанию’White’.

Теперь все пользовательские функции можно использовать централизованно и вам не придется вспоминать какой параметр за что отвечает, а также какой тип данных использует та или иная переменная.

Спасибо что дочитали до конца.

Использование функций

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

Функции — это тип команд в Windows PowerShell. Для запуска функции введите ее имя, точно так же, как и для командлета. Как и командлеты, функции могут иметь параметры. Как и командлеты, функции могут использовать объекты .NET в качестве источника ввода и выводить объекты .NET. Фактически функции обладают теми же возможностями, что и командлеты.

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

Функции являются командами, и поэтому для поиска функций используйте командлет Get-Command.

Например, чтобы найти все функции текущего сеанса, введите команду:

get-command -CommandType function

Кроме того, в Windows PowerShell имеется диск Function:, содержащий все функции текущего сеанса. Для просмотра диска Function: используйте те же методы, что и для просмотра дисков файловой системы.

Чтобы открыть диск функций, введите:

Чтобы вывести функции с диска функций, введите:

Для запуска функции нужно просто ввести ее имя. Например, для запуска функции Clear-Host введите следующую команду:

В консоли Windows PowerShell функция Clear-Host служит для удаления всего текста из окна консоли. В других приложениях эта функция может иметь другое действие или не иметь никакого действия.

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

Например, функция Help, выводящая разделы справки постранично, имеет те же параметры, что и командлет Get-Help. Чтобы использовать функцию Help для вывода только примеров из раздела справки для командлета Get-Service, введите следующую команду:

help -name get-service -examples

Для функций могут существовать разделы справки. Чтобы найти раздел справки для функции, используйте командлет Get-Help. Это тот же командлет, что используется для получения справки по командлетам.

Например, для получения справки по функции Disable-PSRemoting, введите следующую команду:

get-help Disable-PSRemoting

Для получения справки по функциям можно использовать любые параметры командлета Get-Help. Например, чтобы получить примеры из раздела справки для функции Disable-PSRemoting, введите следующую команду:

get-help Disable-PSRemoting -example

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

function <name> { <commands> }

Введите ключевое слово function и имя функции и заключите команды в фигурные скобки ({ }).

Например, если какая-то команда, например, get-help get-member -examples, используется часто, для экономии времени можно написать функцию, исполняющую эту команду. Следующая функция с именем GMEX исполняет эту команду.

function GMEX {get-help get-member -examples}

После ввода в командной строке Windows PowerShell (или после копирования и вставки из этого раздела) и нажатия клавиши ENTER эту функцию можно будет использовать в текущем сеансе. Для исполнения функции введите команду GMEX.

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

Дополнительные сведения о написании функций см. в разделах about_Functions, about_Comment_Based_Help и about_Functions_Advanced.

При запуске Windows PowerShell открывается ее сеанс. Сеанс длится, пока не закрывается окно Windows PowerShell (или пока сеанс не завершается с помощью команды Exit). Элементы, созданные во время сеанса, удаляются при его закрытии, если они не сохранены в файле на диске или в реестре.

Для использования функций в будущих сеансах Windows PowerShell нужно создать профиль Windows PowerShell и сохранить эти функции в нем.

Дополнительную информацию см. в разделе about_Profiles.

Функции в Windows PowerShell | вебисторий

В предыдущей статье мы говорили о командлетах в Windows PowerShell. Теперь поговорим о следующем типе команд — функциях.

Функции — это блоки кода на языке PowerShell, имеющие название и находящиеся в памяти до завершения текущего сеанса командной оболочки. Функции в PowerShell это не совсем то же самое, что функции в языках программирования.

Создадим простейшую функцию Primer, которая просто выводит сообщение. Для этого введем в PowerShell

Function Primer{"Это пример функции."}

Таким образом мы задали имя функции и выполняемое действие. Теперь, для того, чтобы исполнить функцию, нам достаточно написать её имя.

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

Изменим нашу функцию Primer, добавив в неё переменную $Args.

Function Primer{"Это пример $Args."}

Тогда при вызове функции нам необходимо будет прописать аргумент или аргументы. Внимательно посмотрите на скриншот ниже.

Пример функции с аргументами в PowerShell

В данном случае «функции», «с» и «аргументами» — три элемента массива $Args. Как видим, они выводятся через пробел. Для того, чтобы убедиться, что это именно три отдельных элемента, введем разделитель в виде точки с помощью специальной переменной $OFS.

Function Primer{
>> $OFS="."
>> "Это пример $Args."}
>>

 Смотрим результат.

Использование переменной $OFS

Второй способ обработки аргументов функций в Windows PowerShell это использование формальных параметров. Формальные параметры указываются в круглых скобках после имени функции.

Продолжим наш пример с выводом сообщения. Снова изменим функцию Primer, приведя её к следующему виду

Function Primer ($a, $b, $c) {"Это пример $a $b $c."}

Результат будет тем же самым.

Использование формальных параметров

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

Создадим функцию Summa, которая складывала бы значения двух аргументов.

Function Summa ($a, $b) {$a+$b}

Мы можем задать значения параметров сразу. Если все значения уже заданы, функции не нужны дополнительные аргументы. Мы также вольны называть параметры по собственному усмотрению.

Видоизменим функцию Summa.

Function Summa ($chislo1=15,$chislo2=20) {$chislo1+$chislo2}

Мы обозначили параметры как $chislo1 и $chislo2, задав им значения соответственно 15 и 20. Поскольку значения всех параметров здесь указаны, аргументы нам не нужны. Но, если мы всё-таки запустим эту функцию с дополнительным аргументом, то он заменит собой значение $chislo1, а $chislo2 останется без изменений.

PowerShell также позволяет указывать тип параметра функции. Например, тип [int] это целые числа, [string] — текст, а [boolean] — логический тип данных.

Вот следующий пример.

Использование типов данных в Windows PowerShell

Как видим, в результате деления $a на $b должно было получиться 1,15. Но, поскольку мы указали интерпретатору воспринимать все параметры функции как целые числа, дробные значения были округлены до целых. Обратите внимание на округления, которые представлены ниже.

Они не совсем соответствуют тем законам математики, к которым мы привыкли.

Среди типов параметров есть так называемые «параметры-переключатели» обозначающиеся типом [Switch]. Их смысл состоит в логическом выборе, а сами параметры могут принимать только значения $True или $False.

Создадим функцию с таким переключателем.

Function Vybor ([Switch] $a) {
>> if ($a) {
>> "Это первый вариант."
>> }
>> else { "Это второй вариант."
>> }
>> }
>>

В данном случае, если мы запустим функцию Vybor с параметром -a (аналогично, как мы запускали dir с параметрами -recurse и -filter в прошлой статье), то нам выйдет одно сообщение, а если без параметра, то другое.

Использование переключателя Switch в Windows PowerShell

На этом с функциями пока всё. Далее мы продолжим изучать типы команд в Windows PowerShell.

Переменные и функции

Security Controls поддерживает использование ряда переменных и функций PowerShell для выполнения каждого сценария. Все имена переменных начинаются с «ST_». Все имена функций начинаются с «ST-«. Вы можете использовать эти переменные и функции в своих сценариях.

Переменные PowerShell могут иметь другие области действия:

•Global: Доступна в текущем сеансе PowerShell.

•Script: Используется в сценарии (вне функций) и локально для этого сценария.

•Закрытая: Используется в функции и локально для этой функции.

•Local: Текущая область действия, которая может быть глобальной, сценарием или закрытой.

Переменные, используемые с Security Controls, имеют общую область действия. Так как каждый целевой компьютер выполняет собственный сеанс PowerShell, это равносильно использованию области действия сценария.

Переменные выполнения

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

ST_OutputDirectory	Полный путь к базовому каталогу вывода. Для выполнения будет создан подкаталог. [Только чтение]
ST_RunDirectory	Полный путь к каталогу выполнения вывода. [Только чтение]
ST_RunErrorFile	Полный путь к файлу ошибок выполнения вывода. В этом файле должны быть представлены ошибки, не относящиеся к конкретному компьютеру. Этот файл также будет содержать сообщения о компьютерах, для которых не удалось определить IP-адрес, и о компьютерах, на которых не будут созданы соответствующие им вложенные папки. [Только чтение]
ST_RunName	Имя выполнения, указанное в пользовательском интерфейсе во время запуска вручную или по расписанию с добавленным временем выполнения. По умолчанию используется имя сценария или шаблона. [Только чтение]
ST_RunOnConsole	Установите значение $false, если в сценарии используется удаленное подключение PowerShell, а в противном случае — $true. [Только чтение]
ST_RunOutputFile	Полный путь к стандартному файлу вывода выполнения вывода. В этом файле будут присутствовать все данные вывода, отображаемые на консоли во время запуска из командной строки. [Только чтение]
ST_RunResult	Это краткий результат выполнения, отображаемый в Мониторе операций. Он ограничен 100 символами. Если вы не введете эту переменную явно в своем сценарии, она будет установлена для указания количества компьютеров, на которых были обнаружены ошибки, и количество ошибок обнаружения компьютеров.

Переменные компьютера

В следующей таблице перечислены переменные для каждого компьютера. Значения этих переменных могут отличаться для каждого целевого компьютера. Не изменяйте значения переменных, отмеченных как [Только чтение].

ST_ComputerName	Имя целевого компьютера. [Только чтение]
ST_Credential	Объект PSCredential, содержащий имя пользователя и пароль SecureString, используемые для подключения к целевому компьютеру. Эту переменную можно передать в любую команду, которая поддерживает параметр Credential. [Только чтение]
ST_DomainName	Имя домена или рабочей группы целевого компьютера. [Только чтение]
ST_MachineDirectory	Полный путь к каталогу компьютера. Обычно это имя компьютера, однако, если имя компьютера содержит символы, недопустимые в именах папок, эти символы будут заменены символами подчеркивания. [Только чтение]
ST_MachineError	Логическое значение, указывающее, что во время выполнения этого сценария на конкретном компьютере, обнаружена одна или несколько ошибок.
ST_MachineErrorFile	Полный путь к файлу ошибок компьютера. Если во время выполнения сценария будут обнаружены ошибки, они будут записаны в этот файл. [Только чтение]
ST_MachineOutputFile	Полный путь к файлу вывода компьютера. В этом файле будут представлены данные вывода, созданные сценарием для стандартного вывода.
ST_MachineResult	Это краткий результат для компьютера, отображаемый в Мониторе операций. Он ограничен 100 символами. Если вы не укажете эту переменную явно в своем сценарии, для нее будет установлено значение «Успешно» в случае отсутствия ошибок на компьютере, или сообщение первой ошибки, обнаруженной для этого компьютера. Используйте функцию ST-SetMachineResult для явной установки значения этой переменной.
ST_MachineResultSet	Логическое значение, указывающее, что сценарий установил переменную ST_MachineResult. Используйте функцию ST-SetMachineResult для явной установки значения ST_MachineResult и этой переменной.

Функции

Security Controls содержит набор функций, доступных для каждого создаваемого вами сценария. Они перечислены в следующей таблице.

ST-GetTargetOS	Эта функция выполняет попытку подключения к целевой системе, опрашивая WMI и получая объект Win32_OperatingSystem.
ST-SetMachineResult	Эта функция использует строковый параметр. Она устанавливает переменную ST_MachineResult для передачи строки и устанавливает для переменной ST_MachineResultSet значение $true.
ST-SetMachineError	Эта функция использует строковый аргумент в качестве параметра. Она устанавливает переменную ST_MachineResult для передачи строки. Она также устанавливает для переменных ST_MachineResultSet и ST_MachineError значение $true.
ST-SendMessage	Эта функция использует строковый параметр. Эта строка будет отображаться в Мониторе операций. Используйте эту функцию для отслеживания выполнения долговременных сценариев. После выполнения сценария строка в ST_MachineResult будет отображена в Мониторе операций. За исключением процесса отладки вы должны избегать вызова этого метода в быстро выполняемых сценариях. Строка будет усечена до 100 символов, если будет передана строка длиннее этого значения.
ST-CreateMachineDirectory	Обычно каталог компьютера не создается до записи выводных данных. Если ваш сценарий создает файлы в каталоге компьютера, перед записью в каталоге вы должны вызвать эту функцию для создания каталога. Вызов этой функции более одного раза не имеет отрицательного эффекта.
ST-CreateRunDirectory	Обычно каталог выполнения не создается до тех пор, пока во время выполнения не будут записаны любые выходные данные. Если ваш сценарий создает файлы в каталоге выполнения, перед записью в каталоге вы должны вызвать эту функцию для создания каталога. Вызов этой функции более одного раза не имеет отрицательного эффекта.
ST-ComputerAndCredential	Эта функция возвращает для целевого компьютера соответствующие значения для использования в параметрах ComputerName и Credential. Для получения информации см. раздел Использование параметров ComputerName и Credential.
ST-SubCC	Эта функция принимает строковый параметр, который является допустимым для команд PowerShell. Эта функция заменяет параметр «$ST_CC» в этой командной строке соответствующими значениями для использования параметров ComputerName и Credential. Затем она выполняет полученную команду и возвращает результаты выполнения. Для получения информации см. раздел Использование параметров ComputerName и Credential.

powershell — Как передать несколько параметров в функцию в PowerShell?

Здесь есть несколько хороших ответов, но я хотел бы отметить пару других вещей. Параметры функций — это место, где светит PowerShell. Например, вы можете иметь именованные или позиционные параметры в расширенных функциях, например:

function Get-Something
{
    Param
    (
         [Parameter(Mandatory=$true, Position=0)]
         [string] $Name,
         [Parameter(Mandatory=$true, Position=1)]
         [int] $Id
    )
}

Затем вы можете либо вызвать его, указав имя параметра, либо просто использовать позиционные параметры, поскольку вы явно их определили. Так что любой из них будет работать:

Get-Something -Id 34 -Name "Blah" 
Get-Something "Blah" 34

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

PowerShell также имеет возможность определять наборы параметров. Это использует это вместо перегрузки метода, и снова довольно полезно:

function Get-Something
{
    [CmdletBinding(DefaultParameterSetName='Name')]
    Param
    (
         [Parameter(Mandatory=$true, Position=0, ParameterSetName='Name')]
         [string] $Name,
         [Parameter(Mandatory=$true, Position=0, ParameterSetName='Id')]
         [int] $Id
    )
}

Теперь функция будет либо принимать имя, либо идентификатор, но не оба. Вы можете использовать их по месту или по имени. Так как они другого типа, PowerShell поймет это.Some.*’)] [string] $Name, [Parameter(Mandatory=$true, Position=1)] [ValidateRange(10,100)] [int] $Id ) }

В первом примере ValidatePattern принимает регулярное выражение, которое гарантирует, что предоставленный параметр соответствует ожидаемому. Если это не так, выдается интуитивно понятное исключение, которое говорит вам, что именно не так. Таким образом, в этом примере «Something» будет работать нормально, но «Summer» не пройдет проверку.

ValidateRange гарантирует, что значение параметра находится в диапазоне, который вы ожидаете для целого числа. Таким образом, 10 или 99 сработают, но 101 сгенерирует исключение.

Еще одним полезным является ValidateSet, который позволяет явно определять массив допустимых значений. Если будет введено что-то еще, будет сгенерировано исключение. Есть и другие, но, вероятно, самый полезный один из них — ValidateScript. Это берет блок скрипта, который должен иметь значение $ true, поэтому пределом является небо. Например:

function Get-Something
{
    Param
    (
         [Parameter(Mandatory=$true, Position=0)]
         [ValidateScript({ Test-Path $_ -PathType 'Leaf' })]
         [ValidateScript({ (Get-Item $_ | select -Expand Extension) -eq ".csv" })]
         [string] $Path
    )
}

В этом примере мы уверены, что не только $ Path существует, но и что это файл (в отличие от каталога) и имеет расширение .csv. ($ _ относится к параметру, находящемуся внутри вашего скриптового блока.) Вы также можете передать гораздо большие многострочные скриптовые блоки, если требуется этот уровень, или использовать несколько скриптовых блоков, как я сделал здесь. Это чрезвычайно полезно, и делает для Nice чистые функции и интуитивно понятные исключения.

функций — PowerShell | Документы Microsoft

• 02.06.2020
• 14 минут на чтение

В этой статье

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

По возможности, я предпочитаю писать функции, потому что они больше ориентированы на инструменты. Я могу поставить функции в модуле сценария, поместите этот модуль в $ env: PSModulePath и вызовите функции без необходимости физически определять, где они сохранены. Используя модуль PowerShellGet, это просто для совместного использования этих модулей в репозитории NuGet. PowerShellGet поставляется с PowerShell версии 5.0 и выше. Он доступен для отдельной загрузки для PowerShell версии 3.0 и выше.

Не усложняйте слишком много. Сохраняйте простоту и используйте самый простой способ достичь задача. Избегайте псевдонимов и позиционных параметров в любом коде, который вы повторно используете. Отформатируйте свой код для читаемость. Не кодируйте значения жестко; использовать параметры и переменные. Не пишите ненужный код даже если это ничего не повредит. Это добавляет ненужной сложности. Внимание к деталям идет долго способ при написании любого кода PowerShell.

Именование

При именовании ваших функций в PowerShell используйте регистр Pascal с утвержденным глаголом и существительное в единственном числе.Я также рекомендую ставить перед существительным префикс. Например: - .

В PowerShell есть специальный список утвержденных глаголов, который можно получить, запустив Get-Verb .

  Get-Verb | Sort-Object -Property Глагол
  

  Verb Group
---- -----
Добавить общий
Утвердить жизненный цикл
Жизненный цикл утверждения
Резервные данные
Блокировать безопасность
Данные контрольной точки
Очистить общий
Закрыть общий
Сравнить данные
Полный жизненный цикл
Сжать данные
Подтвердить жизненный цикл
Подключить коммуникации
Конвертировать данные
Конвертировать из данных
Преобразовать в данные
Копировать Common
Диагностика отладки
Запретить жизненный цикл
Отключить жизненный цикл
Отключить связь
Снять данные
Редактировать данные
Включить жизненный цикл
Введите общий
Выход из общего
Развернуть данные
Экспорт данных
Найти общий
Формат Общий
Общайся
Обеспечение безопасности
Групповые данные
Скрыть общее
Импортировать данные
Инициализировать данные
Установить жизненный цикл
Вызов жизненного цикла
Присоединяйтесь к Common
Ограничить данные
Замок Общий
Измерение диагностики
Объединить данные
Смонтировать данные
Переместить общий
Новый Common
Открытый общий
Оптимизировать Общие
Выходные данные
Ping Diagnostic
Поп-Коммон
Защитить безопасность
Опубликовать данные
Нажмите Common
Читать сообщения
Получать сообщения
Повторить Common
Жизненный цикл регистрации
Удалить общие
Переименовать общий
Диагностика ремонта
Жизненный цикл запроса
Сбросить общий
Изменить размер общего
Разрешить диагностику
Перезапустить жизненный цикл
Восстановить данные
Продолжить жизненный цикл
Отменить безопасность
Сохранять данные
Общий поиск
Выберите Common
Отправить сообщения
Установить общий
Показать общие
Пропустить Common
Разделить общий
Начать жизненный цикл
Шаг Общий
Остановить жизненный цикл
Отправить жизненный цикл
Приостановить жизненный цикл
Коммутатор Общий
Синхронизировать данные
Диагностический тест
Диагностика трассировки
Разблокировать безопасность
Отменить общее
Жизненный цикл удаления
Разблокировать Common
Снять защиту безопасности
Отменить публикацию данных
Отменить регистрацию жизненного цикла
Обновить данные
Использовать другое
Ждать жизненный цикл
Смотреть общие
Написать сообщение
  

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

Простая функция

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

  function Get-Version {
    $ PSVersionTable.PSVersion
}
  

Показанная функция представляет собой простой пример, возвращающий версию PowerShell.

  Get-версия
  

  Major Minor Build Revision
----- ----- ----- --------
5 1 14393 693
  

Существует большая вероятность конфликта имен с функциями, названными чем-то вроде Get-Version и default. команды в PowerShell или команды, которые могут писать другие.Вот почему я рекомендую ставить перед существительным префикс часть ваших функций, чтобы помочь предотвратить конфликты имен. В следующем примере я буду использовать приставка «PS».

  function Get-PSVersion {
    $ PSVersionTable.PSVersion
}
  

За исключением названия, эта функция идентична предыдущей.

  Get-PSVersion
  

  Major Minor Build Revision
----- ----- ----- --------
5 1 14393 693
  

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

  function Get-MrPSVersion {
    $ PSVersionTable.PSVersion
}
  

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

  Get-MrPSVersion
  

  Major Minor Build Revision
----- ----- ----- --------
5 1 14393 693
  

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

  Get-ChildItem -Path Функция: \ Get- * Версия
  

  CommandType Имя Версия Источник
----------- ---- ------- ------
Функция Get-Version
Функция Get-PSVersion
Функция Get-MrPSVersion
  

Если вы хотите удалить эти функции из текущего сеанса, вам придется удалить их из Функция PSDrive или закрыть и снова открыть PowerShell.

  Get-ChildItem -Path Функция: \ Get- * Version | Убрать предмет
  

Убедитесь, что функции действительно были удалены.

  Get-ChildItem -Path Функция: \ Get- * Версия
  

Если функции были загружены как часть модуля, модуль можно выгрузить, чтобы удалить их.

  Remove-Module -Name 
  

Командлет Remove-Module удаляет модули из памяти в текущем сеансе PowerShell. не удаляет их из вашей системы или с диска.

Параметры

Не присваивать значения статически! Используйте параметры и переменные. Когда дело доходит до наименования вашего параметры, по возможности используйте то же имя, что и командлеты по умолчанию для имен параметров.

  function Test-MrParameter {

    парам (
        $ ComputerName
    )

    Запись-вывод $ ComputerName

}
  

Почему я использовал ComputerName , а не Computer , ServerName или Host для моего параметра название? Это потому, что я хотел, чтобы моя функция была стандартизирована, как командлеты по умолчанию.

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

  function Get-MrParameterCount {
    парам (
        [строка []] $ ParameterName
    )

    foreach ($ Parameter в $ ParameterName) {
        $ Results = Get-Command -ParameterName $ Parameter -ErrorAction SilentlyContinue

        [pscustomobject] @ {
            ParameterName = $ Parameter
            NumberOfCmdlets = $ Results.Count
        }
    }
}
  

Как видно из результатов, показанных ниже, 39 команд имеют параметр ComputerName .Там нет командлетов с такими параметрами, как Computer , ServerName , Host или Станок .

  Get-MrParameterCount -ParameterName ComputerName, Computer, ServerName, Host, Machine
  

  ParameterName NumberOfCmdlets
------------- ---------------
ComputerName 39
Компьютер 0
ServerName 0
Хост 0
Машина 0
  

Я также рекомендую использовать тот же регистр для имен параметров, что и для командлетов по умолчанию.Использовать Имя компьютера , а не имя компьютера . Это заставляет ваши функции выглядеть и чувствовать себя как по умолчанию командлеты. Люди, которые уже знакомы с PowerShell, будут чувствовать себя как дома.

Оператор param позволяет определить один или несколько параметров. Определения параметров: через запятую (, ). Для получения дополнительной информации см. About_Functions_Advanced_Parameters.

Расширенные функции

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

Я начну с функции Test-MrParameter , которая использовалась в предыдущем разделе.

  function Test-MrParameter {

    парам (
        $ ComputerName
    )

    Запись-вывод $ ComputerName

}
  

Я хочу, чтобы вы заметили, что функция Test-MrParameter не имеет общего параметры.Есть несколько разных способов увидеть общие параметры. Один из них — просмотр синтаксис с использованием Get-Command .

  Get-Command -Name Test-MrParameter -Syntax
  

  Test-MrParameter [[-ComputerName]