Создание командлета без параметров

Статья
03/25/2025

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

Примечание.

Помните, что при написании командлетов эталонные сборки Windows PowerShell® загружаются на диск (по умолчанию в C:\Program Files\Reference Assemblies\Microsoft\WindowsPowerShell\v1.0). Они не установлены в глобальном кэше сборок (GAC).

Именование командлета

Имя командлета состоит из команды, указывающей действие, выполняемое командлетом, и существительное, указывающее элементы, на которые выполняется командлет. Так как этот пример Get-Proc командлет получает объекты процесса, он использует команду Get, определенную перечислением System.Management.Automation.VerbsCommon, и существительное "Proc", чтобы указать, что командлет работает над элементами процесса.

При именовании командлетов не используйте следующие символы: # , () {} [] & - /\ $ ; : " '<> | ? @ ` .

Выбор существительного

Вы должны выбрать существительное, определенное. Лучше всего использовать префикс единственного существительного с сокращенной версией имени продукта. Пример имени командлета этого типа — "Get-SQLServer".

Выбор команды

Следует использовать команду из набора утвержденных имен командлетов. Дополнительные сведения о утвержденных командлетах см. в разделе Имена командлетов.

Определение класса командлета

Выбрав имя командлета, определите класс .NET для реализации командлета. Ниже приведено определение класса для этого примера командлета Get-Proc:

[Cmdlet(VerbsCommon.Get, "Proc")]
  public class GetProcCommand : Cmdlet

<Cmdlet(VerbsCommon.Get, "Proc")> _
Public Class GetProcCommand
    Inherits Cmdlet

Обратите внимание, что до определения класса атрибут System.Management.Automation.КомандлетAttribute с синтаксисом [Cmdlet(verb, noun, ...)]используется для идентификации этого класса в качестве командлета. Это единственный обязательный атрибут для всех командлетов, и он позволяет среде выполнения Windows PowerShell правильно вызывать их. При необходимости можно задать ключевые слова атрибутов для дальнейшего объявления класса. Помните, что объявление атрибута для нашего примера класса GetProcCommand объявляет только имена существительных и глаголов для командлета Get-Proc.

Примечание.

Для всех классов атрибутов Windows PowerShell ключевые слова, которые можно задать, соответствуют свойствам класса атрибутов.

При именовании класса командлета рекомендуется отразить имя командлета в имени класса. Для этого используйте форму "VerbNounCommand" и замените "Verb" и "Noun" глаголом и существительным, используемым в имени командлета. Как показано в предыдущем определении класса, пример командлета Get-Proc определяет класс GetProcCommand, производный от базового класса System.Management.Automation.Командлет.

Это важно

Если вы хотите определить командлет, который обращается непосредственно к среде выполнения Windows PowerShell, класс .NET должен быть производным от базового класса System.Management.Automation.PSCmdlet. Дополнительные сведения об этом классе см. в создании командлета, определяющего наборы параметров.

Примечание.

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

Windows PowerShell использует Microsoft.PowerShell.Commands пространство имен для классов командлетов. Рекомендуется разместить классы командлетов в пространстве имен Commands пространства имен API, например xxx.PS. Команды.

Переопределение метода обработки входных данных

Класс System.Management.Automation.Командлет предоставляет три основных метода обработки входных данных, по крайней мере один из которых командлет должен переопределить. Дополнительные сведения о том, как windows PowerShell обрабатывает записи, см. в windows PowerShell.

Для всех типов входных данных среда выполнения Windows PowerShell вызывает System.Management.Automation.Командлет.BeginProcessing для включения обработки. Если командлет должен выполнить предварительную обработку или настройку, это можно сделать, переопределив этот метод.

Примечание.

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

Если командлет принимает входные данные конвейера, он должен переопределить метод System.Management.Automation.Automation.ProcessRecord и при необходимости метод System.Management.Automation.Командлет.EndProcessing. Например, командлет может переопределить оба метода, если он собирает все входные данные с помощью System.Management.Automation.Командлет.ProcessRecord, а затем работает над входными данными в целом, а не с одним элементом за раз, так как командлет Sort-Object выполняется.

Если командлет не принимает входные данные конвейера, он должен переопределить метод System.Management.Automation.Командлет.EndProcessing. Помните, что этот метод часто используется вместо System.Management.Automation.Cmdlet.BeginProcessing, если командлет не может работать с одним элементом одновременно, как и для командлета сортировки.

Так как этот пример командлета Get-Proc должен получать входные данные конвейера, он переопределяет метод System.Management.Automation.Cmdlet.ProcessRecord и использует реализации по умолчанию для System.Management.Automation.Командлет.BeginProcessing и System.Management.Automation.Командлет.EndProcessing. System.Management.Automation.Command.ProcessRecord переопределяет процессы и записывает их в командную строку с помощью метода System.Management.Automation.Command.WriteObject.

protected override void ProcessRecord()
{
  // Get the current processes
  Process[] processes = Process.GetProcesses();

  // Write the processes to the pipeline making them available
  // to the next cmdlet. The second parameter of this call tells
  // PowerShell to enumerate the array, and send one process at a
  // time to the pipeline.
  WriteObject(processes, true);
}

Protected Overrides Sub ProcessRecord()

    '/ Get the current processes.
    Dim processes As Process()
    processes = Process.GetProcesses()

    '/ Write the processes to the pipeline making them available
    '/ to the next cmdlet. The second parameter of this call tells
    '/ PowerShell to enumerate the array, and send one process at a
    '/ time to the pipeline.
    WriteObject(processes, True)

End Sub 'ProcessRecord

Сведения о обработке входных данных

Источник по умолчанию для входных данных — это явный объект (например, строка), предоставленный пользователем в командной строке. Дополнительные сведения см. в статье Создание командлета для обработки входныхкомандной строки.
Метод обработки входных данных также может получать входные данные от выходного объекта вышестоящего командлета в конвейере. Дополнительные сведения см. в статье Создание командлета для обработки входных данных конвейера. Помните, что командлет может получать входные данные из сочетания источников командной строки и конвейера.
Подчиненный командлет может не возвращаться в течение длительного времени или вообще не возвращать. По этой причине метод обработки входных данных в командлете не должен содержать блокировки во время вызовов System.Management.Automation.Cmdlet.WriteObject, особенно блокировки, для которых область выходит за рамки экземпляра командлета.

Это важно

Командлеты никогда не должны вызывать System.Console.Writeline* или его эквивалент.

Командлет может иметь переменные объекта для очистки после завершения обработки (например, если он открывает дескриптор файла в методе system.Management.Automation.Automation.BeginProcessing и сохраняет дескриптор открытым для использования с помощью System.Management.Automation.Командлет.ProcessRecord). Важно помнить, что среда выполнения Windows PowerShell не всегда вызывает метод System.Management.Automation.Командлет.EndProcessing, который должен выполнять очистку объектов.

Например, System.Management.Automation.Командлет.EndProcessing может не вызываться, если командлет отменен по середине пути или если в любой части командлета возникает завершающая ошибка. Таким образом, командлет, требующий очистки объекта, должен реализовать полный шаблон System.IDisposable, включая средство завершения, чтобы среда выполнения мог вызывать как System.Management.Automation.Automation.Командлет.EndProcessing, так и System.IDisposable.Dispose* в конце обработки.

Пример кода

Полный пример кода C# см. в разделе GetProcessSample01 sample.

Определение типов объектов и форматирования

Windows PowerShell передает сведения между командлетами с помощью объектов .NET. Следовательно, командлету может потребоваться определить собственный тип, или командлету может потребоваться расширить существующий тип, предоставленный другим командлетом. Дополнительные сведения об определении новых типов или расширении существующих типов см. в расширении типов объектов и форматировании.

Создание командлета

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

Тестирование командлета

После регистрации командлета в Windows PowerShell его можно протестировать, выполнив его в командной строке. Код для нашего примера Get-Proc командлета мал, но он по-прежнему использует среду выполнения Windows PowerShell и существующий объект .NET, который достаточно, чтобы сделать его полезным. Давайте протестируем его, чтобы лучше понять, что Get-Proc может делать и как его выходные данные можно использовать. Дополнительные сведения об использовании командлетов из командной строки см. в Windows PowerShell.

Запустите Windows PowerShell и получите текущие процессы, выполняемые на компьютере.

Get-Proc

Отображаются следующие выходные данные.

Handles  NPM(K)  PM(K)  WS(K)  VS(M)  CPU(s)  Id   ProcessName
-------  ------  -----  -----  -----  ------  --   ----------
254      7       7664   12048  66     173.75  1200  QCTRAY
32       2       1372   2628   31       0.04  1860  DLG
271      6       1216   3688   33       0.03  3816  lg
27       2       560    1920   24       0.01  1768  TpScrex
...

Назначьте переменную результатам командлета для упрощения манипуляции.
```
$p=Get-Proc
```
Получение количества процессов.
```
$p.Length
```
Отображаются следующие выходные данные.
```
63
```

Получение определенного процесса.

$p[6]

Отображаются следующие выходные данные.

Handles  NPM(K)  PM(K)  WS(K)  VS(M)  CPU(s)  Id    ProcessName
-------  ------  -----  -----  -----  ------  --    -----------
1033     3       2400   3336   35     0.53    1588  rundll32

Получите время начала этого процесса.
```
$p[6].StartTime
```
Отображаются следующие выходные данные.
```
Tuesday, July 26, 2005 9:34:15 AM
```
```
$p[6].StartTime.DayOfYear
```
```
207
```

Получите процессы, для которых число дескрипторов больше 500, и отсортируйте результат.

$p | Where-Object {$_.HandleCount -gt 500 } | Sort-Object HandleCount

Отображаются следующие выходные данные.

Handles  NPM(K)  PM(K)  WS(K)  VS(M)  CPU(s)  Id   ProcessName
-------  ------  -----  -----  -----  ------  --   ----------
568      14      2164   4972   39     5.55    824  svchost
716       7      2080   5332   28    25.38    468  csrss
761      21      33060  56608  440  393.56    3300 WINWORD
791      71      7412   4540   59     3.31    492  winlogon
...

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

$p | Get-Member -MemberType Property

    TypeName: System.Diagnostics.Process

Отображаются следующие выходные данные.

Name                     MemberType Definition
----                     ---------- ----------
BasePriority             Property   System.Int32 BasePriority {get;}
Container                Property   System.ComponentModel.IContainer Conta...
EnableRaisingEvents      Property   System.Boolean EnableRaisingEvents {ge...
...