About_function_provider

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

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

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

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

Дополнительные сведения о стандартных командах PowerShell см. в разделе Утвержденные команды.

Создание базового модуля PowerShell

Ниже описано, как создать модуль PowerShell.

1. Сохраните скрипт PowerShell с расширением . Используйте то же имя для скрипта и каталога, в котором сохраняется скрипт.

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

   Пример скрипта PowerShell, который имеет право , доступен в конце этой статьи.

2. Чтобы управлять доступом пользователей к определенным функциям или переменным, вызовите Export-ModuleMember в конце скрипта.

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

   Вы можете ограничить импортированные данные с помощью манифеста модуля. Дополнительные сведения см. в статье «Импорт модуля PowerShell » и «Создание манифеста модуля PowerShell».

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

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

4. Чтобы описать модуль в системе справки PowerShell, можно использовать стандартные комментарии справки в файле или создать дополнительный файл справки.

5. Если у вас есть дополнительные модули, XML-файлы или другое содержимое, которое вы хотите упаковать с помощью модуля, можно использовать манифест модуля.

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

6. Чтобы установить и запустить модуль, сохраните модуль в одном из соответствующих путей PowerShell и используйте его.

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

   Примечание

   Начиная с PowerShell 3.0, если модуль помещен в один из путей модуля PowerShell, его не нужно импортировать явным образом. Модуль автоматически загружается при вызове функции пользователем. Дополнительные сведения о пути модуля см. в статье «Импорт модуля PowerShell » и about_PSModulePath.

7. Чтобы удалить модуль из активной службы в текущем сеансе PowerShell, используйте Remove-Module.

   Примечание

   Удаляет модуль из текущего сеанса PowerShell, но не удаляет модуль или не удаляет файлы модуля.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

При вводе без значения функция присваивает значение 100 . Если указать значение, функция использует это значение.

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

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

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

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

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

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

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

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

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

При вводе параметра switch после имени функции функция отображает . Без параметра switch отображается .

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

Создание нестандартных объектов из хэш-таблиц

Хэш-таблицы также можно использовать для создания объектов для нестандартных классов. При создании объекта для нестандартного класса требуется имя типа с указанием пространства имен, хотя можно опустить любой исходный компонент пространства имен System .

Например, следующая команда создает объект параметра сеанса.

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

Функцию хэш-таблицы можно также использовать при установке значений параметров. Например, значение параметра SessionOption объекта .
Командлет может быть хэш-таблицей.

Работа со свойствами

Иногда требуется список всех имен свойств объекта.

Его можно также получить из свойства .

Динамический доступ к свойствам

Я уже упоминал, что доступ к значениям свойств можно получить напрямую.

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

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

Я знаю, что выглядит это странно, но это работает.

Преобразование PSCustomObject в хэш-таблицу

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

Проверка свойств

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

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

Навигация по диску функции

Поставщик функции предоставляет хранилище данных на диске. Для работы с функциями можно изменить расположение на диск (). Вы также можете работать с другого диска PowerShell. Чтобы ссылаться на функцию из другого расположения, используйте имя диска () в пути.

Чтобы вернуться к диску файловой системы, введите имя диска. Например, введите:

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

Примечание

PowerShell использует псевдонимы, чтобы обеспечить привычный способ работы с путями поставщика. Такие команды, как и , теперь являются псевдонимами для Get-ChildItem, являются псевдонимами для Set-Location. и является псевдонимом get-Location.

Использование DefaultPropertySet (длинный способ)

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

Теперь, когда объект оказался в оболочке, для него по умолчанию будут отображаться только эти свойства.

Update-TypeData с DefaultPropertySet

Это удобный способ, но недавно при просмотре видео о PowerShell 2016 с участием Джеффри Сновера и Дона Джонса я узнал, что есть еще более удобный вариант. Чтобы указать свойства по умолчанию, Джеффри использовал Update-TypeData.

Это так просто, что я бы даже запомнил этот способ, если бы у меня не было под рукой этой публикации для справки. Теперь я могу легко создавать объекты с большим количеством свойств, которые будут выглядеть все так же аккуратно и понятно при просмотре из оболочки. Если мне нужно получить доступ к другим свойствам или просмотреть их, они всегда под рукой.

Update-TypeData со ScriptProperty

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

Его можно применить как до создания объекта, так и после, и все равно все получится. Этим данный подход и отличается от использования со свойством скрипта. При использовании (этот способ я описал ранее) свойство существует только в данном конкретном экземпляре объекта. Это относится ко всем объектам с таким значением .

Получение функций

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

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

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

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

Получение выбранных функций

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

Работа с путями поставщика функций

Обе команды получают функцию с именем . Первую команду можно использовать на любом диске. Вторая команда используется на диске. Поскольку имя функции оканчивается двоеточием, то есть имеет синтаксис имени диска, необходимо указать в пути имя диска. На диске можно использовать любой формат. Во второй команде точка () представляет текущее расположение.

Создание PSCustomObject

Мне нравится использовать в PowerShell. Создать пригодный к использованию объект просто, как никогда.
Вот почему я опущу все остальные способы создания объекта

Однако обратите внимание, что большинство из этих примеров для PowerShell версии 3.0 и более поздних

Этот метод хорошо мне подходит, поскольку я практически везде использую хэш-таблицы. Но иногда мне хочется, чтобы в PowerShell работа с хэш-таблицами была больше похожа на работу с объектами. Первое различие становится заметно, когда вы хотите использовать или и понимаете, что хэш-таблица — это просто коллекция пар «ключ — значение».

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

Преобразование хэш-таблицы

Хотя мне не следует отступать от темы, возможно, не все знают о следующей возможности.

Я предпочитаю создавать объект с самого начала, но иногда сначала приходится работать с хэш-таблицей. Этот пример работает, поскольку конструктор принимает хэш-таблицу в качестве значения свойств объекта

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

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

Устаревший подход

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

Этот метод медленнее, но он может оказаться лучшим вариантом для ранних версий PowerShell.

Сохранение в папке

Самый лучший способ сохранить хэш-таблицу в файл — использовать формат JSON. Вы можете импортировать ее обратно в .

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

Статический метод new()

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

Чтобы просмотреть конструкторы для типа, укажите имя метода после имени типа и нажмите клавишу .

Теперь можно создать System.Uri , указав соответствующий конструктор.

С помощью следующего примера можно определить, какие типы .NET загружены для создания экземпляра.

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

Например, поставщик FileSystem в PowerShell добавляет шесть значений NoteProperty в объект DirectoryInfo, возвращаемый .

При непосредственном создании объекта DirectoryInfo у него нет этих шести значений NoteProperty .

Дополнительные сведения о системе расширенных типов см. в разделе about_Types.ps1xml.

Эта функция была добавлена в PowerShell 5.0

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

Параметры переключателя — это параметры, которые не принимают значения параметра. Вместо этого они передают логическое значение true-or-false через их присутствие или отсутствие, чтобы при наличии параметра switch у него было истинное значение, а при отсутствии — ложное значение.

Например, параметр Recurse является параметром switch.

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

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

Параметры switch просты в использовании и предпочтительнее логических параметров, которые имеют менее естественный синтаксис для PowerShell.

Например, чтобы использовать параметр switch, пользователь вводит параметр в команде .

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

При создании параметров коммутатора тщательно выберите имя параметра. Убедитесь, что имя параметра сообщает пользователю о действии параметра.
Избегайте неоднозначных терминов, таких как Filter или Maximum , которые могут означать обязательное значение.

Рекомендации по проектированию параметров коммутатора

• Параметры переключения не должны присваиваться значениям по умолчанию. По умолчанию всегда должно быть false.

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

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

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

• Явно задать переключатель из логического можно с помощью и в сплаттинге с помощью .

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

  Нет необходимости писать

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

В следующем примере кода показано, как использовать параметры учетных данных. В этом примере демонстрируется функция с именем , которая приведена в книге The Pester Book. Эта функция определяет параметр учетных данных с помощью техник, описанных в предыдущем разделе. Функция вызывает с помощью переменной , создаваемой функцией. Это позволяет вам изменить пользователя, выполняющего . Так как для значения по умолчанию используются пустые учетные данные, функцию можно выполнять без предоставления учетных данных.

В следующих разделах приведены различные методы по предоставлению учетных данных функции .

Запрос учетных данных

Использование может сделать код громоздким. Обычно при использовании параметра Credential только с именем пользователя командлет автоматически запрашивает пароль. Такое поведение обеспечивается атрибутом .

Примечание

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

Указание учетных данных в переменной

Вы также можете предварительно указать переменную учетных данных и передать ее параметру Credential функции . Используйте этот метод с инструментами непрерывной интеграции и непрерывного развертывания (CI/CD), такими как Jenkins, TeamCity и Octopus Deploy. Пример использования Jenkins можно найти в записи блога Hodge Автоматизация с помощью Jenkins и PowerShell в Windows — часть 2.

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

Для этого примера защищенная строка создается с использованием пароля в формате открытого текста. Все упомянутые ранее инструменты CI/CD предоставляют защищенный метод для указания пароля во время выполнения. При использовании таких инструментов замените пароль в формате обычного текста переменной, определенной в используемом инструменте CI/CD.

Выполнение без учетных данных

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

Атрибуты завершения аргументов

Атрибут ArgumentCompletions

Атрибут ArgumentCompletions позволяет добавлять значения завершения табуляции в определенный параметр. Атрибут ArgumentCompletions должен быть определен для каждого параметра, требующего завершения табуляции. Атрибут ArgumentCompletions аналогичен Атрибуту ValidateSet. Оба атрибута принимают список значений, которые будут представлены, когда пользователь нажимает клавишу TAB после имени параметра.
Однако, в отличие от ValidateSet, значения не проверяются.

Этот атрибут появился в PowerShell 6.0.

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

Атрибут ArgumentCompleter

Атрибут ArgumentCompleter позволяет добавлять значения завершения табуляции в определенный параметр. Атрибут ArgumentCompleter должен быть определен для каждого параметра, требующего завершения табуляции. Как и DynamicParameters, доступные значения вычисляются во время выполнения, когда пользователь нажимает клавишу TAB после имени параметра.

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

Динамические параметры

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

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

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

Динамические параметры могут быть полезны, но используйте их только при необходимости, так как их может быть трудно обнаружить пользователям. Чтобы найти динамический параметр, пользователь должен находиться в пути поставщика, использовать параметр ArgumentList командлета или параметр Path объекта .

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

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

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

В следующем примере показана функция со стандартными параметрами с именами Name и Path и необязательным динамическим параметром с именем KeyCount. Параметр KeyCount находится в наборе параметров и имеет тип . Параметр KeyCount доступен в функции, только если значение параметра Path начинается с , указывая, что он используется на диске реестра.

Дополнительные сведения см. в документации по типу RuntimeDefinedParameter .

Добавление параметра учетных данных

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

В следующем примере демонстрируется блок параметра для функции с именем . Она имеет два параметра: и .

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

• Добавьте атрибут проверки , чтобы проверить значение, передаваемое параметру Credential. Если параметр имеет значение NULL, этот атрибут предотвратит выполнение функции с недопустимыми учетными данными.

• Добавьте . Это позволяет передать имя пользователя в формате строки и запросить пароль через интерактивный ввод.

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

Совет

Некоторые командлеты, которые принимают параметр учетных данных, не поддерживают . Временное решение см. в разделе .