Windows Management Instrumentation<\/a>, or WMI, is the library to explore your system’s resources. It returns quite a lot of properties about a network adapter; for this exercise we will just use these select few:<\/p>\n public\u00a0class\u00a0NetworkAdapter\n {\n \u00a0\u00a0\u00a0\u00a0public\u00a0string\u00a0Name\u00a0{\u00a0get;\u00a0set;\u00a0}\n \u00a0\u00a0\u00a0\u00a0public\u00a0string\u00a0Description\u00a0{\u00a0get;\u00a0set;\u00a0}\n \u00a0\u00a0\u00a0\u00a0public\u00a0int\u00a0DeviceId\u00a0{\u00a0get;\u00a0set;\u00a0}\n \u00a0\u00a0\u00a0\u00a0public\u00a0string\u00a0Manufacturer\u00a0{\u00a0get;\u00a0set;\u00a0}\n \u00a0\u00a0\u00a0\u00a0public\u00a0string\u00a0NetConnectionId\u00a0{\u00a0get;\u00a0set;\u00a0}\n \u00a0\u00a0\u00a0\u00a0public\u00a0bool\u00a0PhysicalAdapter\u00a0{\u00a0get;\u00a0set;\u00a0}\n }\n<\/pre>\nStep 7: Decorate your class with OutputTypeAttribute<\/h2>\n
With your output object defined, you can now tell PowerShell what your cmdlet emits to the pipeline with the System.Management.Automation.OutputType<\/code><\/span> <\/code>attribute. \u00a0I have highlighted the new code in yellow here:<\/p>\n[Cmdlet(VerbsCommon.Get,\u00a0\"NetworkAdapter\")]\n[OutputType(typeof(NetworkAdapter))]\npublic\u00a0class\u00a0GetNetworkAdapterCmdlet:\u00a0Cmdlet\n{\n}\n<\/pre>\nThis is important for two reasons. First, it contributes to your cmdlet’s auto-generated help text. Here is what Get-Help<\/code><\/span> provides before and after applying the OutputType<\/code><\/span> attribute (note the use of the -Full<\/code><\/span> switch). Everything is the same except for the OUTPUTS<\/i> section, highlighted below:<\/p>\n PS> Import-Module .\\bin\\Debug\\PowerShellModuleInCSharp.dll -Force\n PS> Get-Help Get-NetworkAdapter -full\n \u00a0\n NAME\n \u00a0\u00a0\u00a0 Get-NetworkAdapter\n \u00a0\n SYNTAX\n \u00a0\u00a0\u00a0 Get-NetworkAdapter\u00a0 [<CommonParameters>]\n \u00a0\n INPUTS\n \u00a0\u00a0\u00a0 None\n \u00a0\n OUTPUTS # <<BEFORE>>\n \u00a0\u00a0\u00a0 System.Object\n \u00a0\n OUTPUTS # <<AFTER>>\n \u00a0\u00a0\u00a0 PowerShellModuleInCSharp.Containers.NetworkAdapter\n<\/pre>\nSecond, and perhaps more importantly, using the OutputType<\/code><\/span> provides tab completion! Before you add the OutputType<\/code><\/span> attribute, if you type this (the last part is “Select-Object<\/code>“, then a space, then a tab)…<\/p>\nPS> Import-Module .\\bin\\Debug\\PowerShellModuleInCSharp.dll -Force\nPS> Get-NetworkAdapter | Select-Object<space><tab>\n<\/pre>\n… nothing happens. But after<\/i> you apply the OutputType<\/code><\/span> attribute, here is what happens. (As this is not a video, you need to imagine the time-lapse nature of this figure.) When you type the first line of each pair, PowerShell turns it into the second line. I have added the highlighting to draw your attention to the iteration through the list of NetworkAdapter<\/code>‘s properties as defined above.<\/p>\n PS> Import-Module .\\bin\\Debug\\PowerShellModuleInCSharp.dll -Force\n \u00a0\n PS> Get-NetworkAdapter | Select-Object<space><tab>\n PS> Get-NetworkAdapter | Select-Object Description\n \u00a0\n PS> Get-NetworkAdapter | Select-Object Description<tab>\n PS> Get-NetworkAdapter | Select-Object DeviceId\n \u00a0\n PS> Get-NetworkAdapter | Select-Object DeviceId<tab>\n PS> Get-NetworkAdapter | Select-Object Manufacturer\n \u00a0\n PS> Get-NetworkAdapter | Select-Object Manufacturer<tab>\n PS> Get-NetworkAdapter | Select-Object Name\n \u00a0\n PS> Get-NetworkAdapter | Select-Object Name<tab>\n PS> Get-NetworkAdapter | Select-Object NetConnectionId\n \u00a0\n PS> Get-NetworkAdapter | Select-Object NetConnectionId<tab>\n PS> Get-NetworkAdapter | Select-Object PhysicalAdapter\n \u00a0\n PS> Get-NetworkAdapter | Select-Object PhysicalAdapter<tab>\n PS> Get-NetworkAdapter | Select-Object Description\n<\/pre>\nThe first <tab><\/code><\/span> activated the tab-completion, filling in the remaining portion of the first available choice lexicographically (from the set of NetworkAdapter<\/code>‘s properties), i.e.\u00a0 Description<\/code><\/span>.<\/p>\nBy immediately pressing <tab><\/code><\/span> again, you will cycle through to the next choice, DeviceId<\/code><\/span>. If you keep pressing <tab><\/span>\u00a0 it will eventually circle back to the start of the list, as shown. Note that I said the “remaining portion” just above. So if you had typed, say, “Select-Object De<tab>” then it will just fill in the first available choice beginning with “De”, namely, Description<\/code><\/span> and cycle between Description<\/span> and DeviceId<\/code><\/span>.<\/p>\nStep 8: Create your inputs<\/h2>\n
Now let’s turn our attention to the input side of things. Inputs to your cmdlet come from command-line parameters or from the pipeline or both. To provide parameters, you start with standard C# public properties. For this exercise, we will use three parameters whose names correspond to properties of the NetworkAdapter<\/code> object defined earlier. These will be used as filters by the cmdlet. That is, if for example the Name<\/code><\/span> parameter is supplied, the cmdlet will only return NetworkAdapter<\/code><\/span> objects whose name matches that Name<\/code><\/span> parameter. We will also define a fourth parameter, MaxEntries<\/code><\/span>, which lets us throttle the number of output records we receive from the cmdlet.<\/p>\npublic\u00a0string\u00a0Name\u00a0{\u00a0get;\u00a0set;\u00a0}\n\npublic\u00a0string\u00a0Manufacturer\u00a0{\u00a0get;\u00a0set;\u00a0}\n\npublic\u00a0bool\u00a0PhysicalAdapter\u00a0{\u00a0get;\u00a0set;\u00a0}\n\npublic\u00a0int\u00a0MaxEntries\u00a0{\u00a0get;\u00a0set;\u00a0} = 100;\n<\/pre>\nStep 9: Decorate your parameters with the ParameterAttribute<\/h2>\n
For PowerShell to know that you want certain properties to be exposed as parameters of your cmdlet, you must add the System.Management.Automation.ParameterAttribute<\/code><\/span>:<\/p>\n[Parameter]\npublic\u00a0string\u00a0Name\u00a0{\u00a0get;\u00a0set;\u00a0}\n\n[Parameter]\npublic\u00a0string\u00a0Manufacturer\u00a0{\u00a0get;\u00a0set;\u00a0}\n\n[Parameter]\npublic\u00a0bool\u00a0PhysicalAdapter\u00a0{\u00a0get;\u00a0set;\u00a0}\n\n[Parameter]\npublic\u00a0int\u00a0MaxEntries\u00a0{\u00a0get;\u00a0set;\u00a0}\n<\/pre>\nEach property decorated with the Parameter attribute becomes able to accept input as a command-line parameter. Examples:<\/p>\n
PS> Get-NetworkAdapter -Manufacturer Microsoft | Format-Table\n PS> Get-NetworkAdapter -Manufacturer Microsoft -Name WAN\n<\/pre>\nBut this does not<\/i> support obtaining input from the pipeline<\/i>. You can accept pipeline input in two different ways, covered in the next two steps.<\/p>\nStep 10: Setup a single pipeline input<\/h2>\n
Say you want to be able to list all the NetworkAdapter<\/code><\/span> objects for one or more specific manufacturers by feeding them from the pipeline:<\/p>\nPS> 'Intel', 'Microsoft' | Get-NetworkAdapter\n<\/pre>\nYou want to direct that pipeline input into the appropriate parameter-in this case, the Manufacturer<\/span> parameter. To do this, you add the ValueFromPipeline<\/b><\/b><\/span> argument to the Parameter<\/code><\/span> attribute for that parameter:<\/p>\n[Parameter(ValueFromPipeline\u00a0=\u00a0true)]\npublic\u00a0string\u00a0Manufacturer\u00a0{\u00a0get;\u00a0set;\u00a0}\n<\/pre>\nThere’s nothing technically stopping you from applying the ValueFromPipeline<\/code><\/span> argument to more than one parameter (say, for example, if you wanted to see whether the manufacturer or the name<\/i> of the network adapter contained Intel or Microsoft). But in practice, ValueFromPipeline<\/code><\/span> is typically attached to only one parameter because there is really no need to have two parameters receiving identical values. When you do want to get multiple different<\/i> inputs from the pipeline, set up multiple properties as described next.<\/p>\nStep 11: Setup multiple pipeline-able properties<\/h2>\n
Say you have a NetworkAdapter<\/code><\/span> object at hand; let’s call it $adapter1<\/code><\/span>. You want to feed $adapter1<\/code><\/span> to Get-NetworkAdapter<\/code><\/span> as a template, so that Get-NetworkAdapter<\/span> only returns objects that match the Name<\/code><\/span>, Manufacturer<\/code><\/span>, and PhysicalAdapter<\/code><\/span> values of $adapter1<\/code><\/span>; we will choose to ignore the other properties of $adapter1<\/span> for filtering purposes.<\/p>\nPS> $adapter1 | Get-NetworkAdapter\n<\/pre>\nEach property that we want to treat as significant must use the ValueFromPipelineByPropertyName<\/code><\/span> argument to the Parameter<\/code><\/span> attribute:<\/p>\n[Parameter(ValueFromPipelineByPropertyName\u00a0=\u00a0true)]\npublic\u00a0string\u00a0Name\u00a0{\u00a0get;\u00a0set;\u00a0}\n\n[Parameter(ValueFromPipelineByPropertyName\u00a0=\u00a0true,\u00a0ValueFromPipeline\u00a0=\u00a0true)]\npublic\u00a0string\u00a0Manufacturer\u00a0{\u00a0get;\u00a0set;\u00a0}\n\n[Parameter(ValueFromPipelineByPropertyName\u00a0=\u00a0true)]\npublic\u00a0bool\u00a0PhysicalAdapter\u00a0{\u00a0get;\u00a0set;\u00a0}\n\n[Parameter]\npublic\u00a0int\u00a0MaxEntries\u00a0{\u00a0get;\u00a0set;\u00a0}\n<\/pre>\nNotice that Manufacturer<\/code><\/span> now has two<\/i> arguments on its Parameter<\/code><\/span> attribute so you can still feed it an array of strings, as was done in the previous step, or you can feed an array of objects containing appropriate properties.<\/p>\nLet’s check our work so far. Recompile, re-import and examine the help. I’ve reduced the output to just the relevant parts here:<\/p>\n
PS> Import-Module .\\bin\\Debug\\PowerShellModuleInCSharp.dll -Force\nPS> Get-Help Get-NetworkAdapter -full\n \u00a0\n NAME\n \u00a0\u00a0\u00a0 Get-NetworkAdapter\n \u00a0\n SYNTAX\n \u00a0\u00a0\u00a0 Get-NetworkAdapter [-Name <string>] [-Manufacturer <string>]\n[-PhysicalAdapter <bool>] [-MaxEntries <int>]\n \u00a0\n \u00a0\n PARAMETERS\n \u00a0\u00a0\u00a0 -Manufacturer <string>\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Accept pipeline input?\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 true (ByValue, ByPropertyName)\n \u00a0\n \u00a0\u00a0\u00a0 -MaxEntries <int>\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Accept pipeline input?\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 false\n \u00a0\n \u00a0\u00a0\u00a0 -Name <string>\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Accept pipeline input?\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 true (ByPropertyName)\n \u00a0\n \u00a0\u00a0\u00a0 -PhysicalAdapter <bool>\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Accept pipeline input?\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 true (ByPropertyName)\n \u00a0\n INPUTS\n \u00a0\u00a0\u00a0 System.String\n \u00a0\u00a0\u00a0 System.Boolean\n<\/pre>\nNote that each parameter shows up in the SYNTAX<\/i> section, indicating its name and type. Then in the PARAMETERS<\/i> section, you again see the name and type of each parameter along with additional properties of the parameters-notably whether it accepts pipeline input. Finally, the INPUTS<\/i> section is there; not to be redundant, but to show-along with the OUTPUTS<\/i> section you have already seen-what data comes and goes in the pipeline. It seems<\/i> to be telling you that it accepts one string and one Boolean from the pipeline as inputs, but it really means that this cmdlet will accept one or more<\/i> strings and one or more<\/i> Booleans from the pipeline as input. It does not<\/i> reveal, as with this particular cmdlet, that, two strings and one Boolean may come from the pipeline.<\/p>\n
Note: This is an appropriate time to mention that you have about reached the limit of the documentation PowerShell can generate from your code alone, i.e. without you having decorated your code with documentation-comments. While this documentation is useful, it is but a mere skeleton of what your documentation should be. For a practical guide to easily instrumenting your code with doc-comments, see my recent article, Documenting Your PowerShell Binary Cmdlets<\/a>.<\/p>\nStep 12: Setup multiple inputs without the pipeline<\/h2>\n
You have seen that you can feed multiple inputs to the cmdlet like this:<\/p>\n
PS> 'Intel', 'Microsoft' | Get-NetworkAdapter\n<\/pre>\nThat works even though the receiving parameter, Manufacturer<\/code><\/span>, is just a simple string, not<\/i> a list or array!<\/p>\n[Parameter(ValueFromPipelineByPropertyName\u00a0=\u00a0true,\u00a0ValueFromPipeline\u00a0=\u00a0true)]\npublic\u00a0string\u00a0Manufacturer\u00a0{\u00a0get;\u00a0set;\u00a0}\n<\/pre>\nIt works because of the nature of the pipeline: the pipeline itself handles feeding multiple values one at a time, so Manufacturer<\/code><\/span> ever only gets asked to accept a single string at a time. But it would seem very reasonable to be able to specify multiple values to a parameter via direct parameters as well (i.e. not<\/i> through the pipeline):<\/p>\nPS> Get-NetworkAdapter -Manufacturer Intel, Microsoft\n<\/pre>\nTo do that, though, you must specify that Manufacturer<\/code><\/span> is an array-the only change here is using string[]<\/code><\/span> in place of string<\/code><\/span>:<\/p>\n [Parameter(ValueFromPipelineByPropertyName = true, ValueFromPipeline = true)]\n public string[] Manufacturer { get; set; }\n<\/pre>\nThus, while the commands typed by the user seem very similar, just inverted in a sense…<\/p>\n
PS> 'Intel', 'Microsoft' | Get-NetworkAdapter\nPS> Get-NetworkAdapter -Manufacturer Intel, Microsoft\n<\/pre>\n…internally they are handled quite differently. With the pipeline inputs, they are processed individually; the cardinality of the Manufacturer<\/code><\/span> array is always one. With direct inputs, the cardinality of Manufacturer<\/span> is the length of the array that you pass in.<\/p>\nStep 13: Setup inputs without accompanying parameter names<\/h2>\n
Revisiting the last examples, we can make the parallel between pipeline and direct inputs even closer by not forcing the user to specify the name of the parameter in the latter case (i.e. “-Manufacturer” has been omitted):<\/p>\n
PS> 'Intel', 'Microsoft' | Get-NetworkAdapter\nPS> Get-NetworkAdapter Intel, Microsoft\n<\/pre>\nTo accomplish this, you need to map your cmdlet parameters to positions on the command line, so that PowerShell will know-by position alone-which parameters you are filling with values. In this case, because we assume Manufacturer<\/code><\/span> will be wanted the most, we give that the first position, position zero. It is good practice to give all<\/i> your parameters position values, though, to allow the user to decide whether they want to use names at all.<\/p>\n[Parameter(Position=1,ValueFromPipelineByPropertyName = true)]\npublic string Name { get; set; }\n \u00a0\n[Parameter(Position=0,ValueFromPipelineByPropertyName = true, ValueFromPipeline = true)]\npublic string[] Manufacturer { get; set; }\n \u00a0\n[Parameter(Position=2,ValueFromPipelineByPropertyName = true)]\npublic bool? PhysicalAdapter { get; set; }\n \u00a0\n[Parameter(Position=3)]\npublic int MaxEntries { get; set; } = 100;\n<\/pre>\nWith these positions specified, as I’ve just demonstrated, \u00a0any of the commands below achieve precisely the same result. If you use parameter names, you can put them in any order you please, but if you want to omit names you must<\/i> honor the order based on the Position<\/code><\/span> argument to each Parameter<\/span> attribute:<\/p>\n PS> Get-NetworkAdapter -Name WAN -PhysicalAdapter true -Manufacturer Intel\n PS> Get-NetworkAdapter -PhysicalAdapter true\u00a0 -Name WAN -Manufacturer Intel\n PS> Get-NetworkAdapter -Manufacturer Intel -Name WAN -PhysicalAdapter true\n PS> Get-NetworkAdapter Intel WAN true\n<\/pre>\nStep 14: Provide parameter aliases<\/h2>\n
PowerShell automatically provides prefix-parameter recognition, which is a great convenience feature: you may<\/i> type the entire name of a given parameter, but you are only required<\/i> to type enough to make it unambiguous. For example, for the Manufacturer<\/code><\/span> parameter all of these are equivalent:<\/p>\nPS> Get-NetworkAdapter -Manufacturer Intel\nPS> Get-NetworkAdapter -Manufacture Intel \nPS> Get-NetworkAdapter -Manufac Intel \nPS> Get-NetworkAdapter -M Intel \n<\/pre>\nThat’s fine, you say, but everyone in your shop abbreviates ‘manufacturer’ as ‘mfg’. This is actually short for manufacturing<\/i>, but let’s run with it! Of course, ‘mfg’ is not a proper prefix of ‘manufacturer’ so that will not work by default. However, you can easily define an alias to accept an alternative name or several alternative names. \u00a0This example shows two aliases being defined.<\/p>\n [Parameter(\n \u00a0 \u00a0 Position=0,\n \u00a0 \u00a0 ValueFromPipelineByPropertyName = true,\n \u00a0 \u00a0 ValueFromPipeline = true)]\n [Alias(\"mfg\", \"vendor\")]\n public string[] Manufacturer { get; set; }\n<\/pre>\nAnd PowerShell provides prefix-parameter recognition on the aliases as well! So all of these are equivalent:<\/p>\n
PS> Get-NetworkAdapter -Manufacturer Intel\nPS> Get-NetworkAdapter -Manufac Intel \nPS> Get-NetworkAdapter -mfg Intel \nPS> Get-NetworkAdapter -mf Intel\nPS> Get-NetworkAdapter -vend Intel\n<\/pre>\nStep 15: Write some production code<\/h2>\n
To wrap up this short and simple (!) 15-step process to create PowerShell cmdlets in C#, let’s add just one more little detail-actual production code to do the work! To do this in your cmdlet skeleton, there are four principal methods you need to override:<\/p>\n
\nBeginProcessing <\/code>(to do initialization),<\/li>\n ProcessRecord<\/code> (to process each item in the pipeline),<\/li>\n
![\"2370-img39.jpg\"](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/imported\/2370-img39.jpg\")
<\/p>\n![\"2370-img3A.jpg\"](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/imported\/2370-img3A.jpg\")
<\/p>\n