{"id":15451,"date":"2011-03-01T00:01:00","date_gmt":"2011-03-01T00:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2011\/03\/01\/proxy-functions-spice-up-your-powershell-core-cmdlets\/"},"modified":"2024-04-02T09:53:31","modified_gmt":"2024-04-02T16:53:31","slug":"proxy-functions-spice-up-your-powershell-core-cmdlets","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/proxy-functions-spice-up-your-powershell-core-cmdlets\/","title":{"rendered":"Proxy Functions: Spice Up Your PowerShell Core Cmdlets"},"content":{"rendered":"

Summary<\/strong>: Microsoft MVP, Shay Levy, shows how to use Windows PowerShell proxy functions to extend the capability of Windows PowerShell cmdlets.<\/p>\n

\"Hey,<\/p>\n

Hey, Scripting Guy! I need to be able to modify the behavior of existing Windows PowerShell cmdlets. Is this something that can be accomplished by using \u201cnormal\u201d tools, or do I need to reverse engineer them by using Visual Studio?<\/p>\n

\u2014LS<\/p>\n

\"Hey, Hello LS,<\/p>\n

Microsoft Scripting Guy, Ed Wilson, here. Today our guest blogger is Shay Levy.<\/p>\n

\"Photo<\/a><\/p>\n

<\/h4>\n

Here is a bit of information about Shay:\nWindows PowerShell MVP\nBlog: http:\/\/PowerShay.com<\/a>\nFollow Shay on Twitter: https:\/\/twitter.com\/ShayLevy<\/a>\nDownload the PowerShell Community Toolbar: http:\/\/tinyurl.com\/PSToolbar<\/a><\/p>\n

Have you ever had a thought like, \u201cI wish that cmdlet had that parameter?\u201d<\/p>\n

I have had several thoughts like that one, and with proxy functions, I was able to implement them on my system. For example, take a look at a snippet that reads XML file content and casts the content to an XML document object:<\/p>\n

PS > $xml = [xml](Get-Content -Path c:\\test.xml)<\/span><\/p><\/blockquote>\n

Wouldn’t it be nice if the Get-Content<\/a> Windows PowerShell cmdlet had an AsXml <\/i>parameter? We could write the same command as shown here.<\/p>\n

PS > Get-Content -Path c:\\test.xml -AsXml<\/span><\/p><\/blockquote>\n

Windows PowerShell 2.0<\/a> includes a new and exciting feature called proxy commands. Proxy commands are used primarily by the remoting mechanism in Windows PowerShell. We can use it in restricted runspace configurations where we can modify sessions by adding or removing certain commands, providers, cmdlet parameters, and every other component of a Windows PowerShell session. For instance, we can remove the ComputerName<\/i> parameter from all cmdlets that support that parameter.<\/p>\n

Another major use for proxy commands is performed in implicit remoting. In a nutshell, implicit remoting lets you use commands from a remote session inside your local session (by using the Import-PSSession<\/a> cmdlet). For example, say you manage an Exchange Server 2010 server and you don’t have the Exchange Server admin tools installed on your admin computer. Normally, you would create a Remote Desktop session, launch the Exchange Management Shell, and perform your tasks.<\/p>\n

With implicit remoting, you can create a PSSession to the Exchange Server and import the Exchange commands into your local session. When you do that, Windows PowerShell dynamically creates a module in your TEMP folder, and the imported commands are converted to proxy functions. From now on, each time you run an Exchange command in your local session, it will run on the remote server. This feature enables us to manage multiple servers without installing admin tools locally on each server!<\/p>\n

So what is a proxy function? It is a wrapper function around a cmdlet (or another function). When we proxy a command, we get access to its parameters (which we can add or remove). We also get control over the command steppable pipeline, which is the three script blocks of a Windows PowerShell function: Begin<\/b>, Process<\/b>, and End<\/b>.<\/p>\n

In this post, I want to show you how easy it is to create a proxy function and how you can harness its power to extend existing cmdlets with new functionality by adding new parameters.<\/p>\n

The process of creating a proxy function is relatively easy (you can read more about it here<\/a>). You decide which cmdlet you want to wrap and then get the cmdlet metadata (command line syntax). In the following example, we get the code for the Get-ChildItem<\/a> cmdlet.<\/p>\n

PS > $MetaData = New-Object System.Management.Automation.CommandMetaData (Get-Command\u00a0 ConvertTo-Html)\nPS > [System.Management.Automation.ProxyCommand]::Create($MetaData) <\/span><\/span><\/span><\/p>\n

[CmdletBinding(DefaultParameterSetName=’Items’, SupportsTransactions=$true)]\nparam(\n[Parameter(ParameterSetName=’Items’, Position=0, ValueFromPipeline=$true, ValueFromPipelineByPropertyName=$true)]\n[System.String[]]\n${Path},<\/span><\/span><\/span><\/p>\n

\u00a0\u00a0\u00a0 [Parameter(ParameterSetName=’LiteralItems’, Mandatory=$true, Position=0, ValueFromPipelineByPropertyName=$true)]\n[Alias(‘PSPath’)]\n[System.String[]]\n${LiteralPath},<\/span><\/span><\/span><\/p>\n

\u00a0\u00a0\u00a0 [Parameter(Position=1)]\n[System.String]\n${Filter},<\/span><\/span><\/span><\/p>\n

\u00a0\u00a0\u00a0 [System.String[]]\n${Include},<\/span><\/span><\/span><\/p>\n

\u00a0\u00a0\u00a0 [System.String[]]\n${Exclude},<\/span><\/span><\/span><\/p>\n

\u00a0\u00a0\u00a0 [Switch]\n${Recurse},<\/span><\/span><\/span><\/p>\n

\u00a0\u00a0\u00a0 [Switch]\n${Force},<\/span><\/span><\/span><\/p>\n

\u00a0\u00a0\u00a0 [Switch]\n${Name})<\/span><\/span><\/span><\/p>\n

begin\n{\ntry {\n$outBuffer = $null\nif ($PSBoundParameters.TryGetValue(‘OutBuffer’, [ref]$outBuffer))\n{\n$PSBoundParameters[‘OutBuffer’] = 1\n}\n$wrappedCmd = $ExecutionContext.InvokeCommand.GetCommand(‘Get-ChildItem’, [System.Management.Automation.Command\nTypes]::Cmdlet)\n$scriptCmd = {& $wrappedCmd @PSBoundParameters }\n$steppablePipeline = $scriptCmd.GetSteppablePipeline($myInvocation.CommandOrigin)\n$steppablePipeline.Begin($PSCmdlet)\n} catch {\nthrow\n}\n}<\/span><\/span><\/span><\/p>\n

process\n{\ntry {\n$steppablePipeline.Process($_)\n} catch {\nthrow\n}\n}<\/span><\/span><\/span><\/p>\n

end\n{\ntry {\n$steppablePipeline.End()\n} catch {\nthrow\n}\n}\n<#<\/span><\/span><\/span><\/p>\n

.ForwardHelpTargetName Get-ChildItem\n.ForwardHelpCategory Cmdlet<\/span><\/span><\/span><\/p>\n

#><\/span><\/span><\/span><\/p>\n

Don’t get intimidated by the result. This is what a proxy function looks like. As you can see, the generated code starts by including all the cmdlet parameters and then defines the script blocks of the command. At the end, there are instructions for the Get-Help<\/a> cmdlet.<\/p>\n

In the Begin<\/b> block, the Get-ChildItem<\/b> command ($wrappedCmd) is retrieved and the parameters are passed to it (@PSBoundParameters). A steppable pipeline is initialized ($steppablePipeline), which invokes the cmdlet ($scriptCmd), and finally the Begin<\/b> starts. At the end of the code sample, you can find a multiline comment that is used to instruct the Help that Get-Help<\/b> should display when you type Get-Help<\/b> <ProxyFunction>.<\/p>\n

After this long introduction, it is time to introduce the proxy function that we are going to work on. For this blog, I chose to wrap the ConvertTo-Html<\/a> cmdlet. It can do everything that the ConvertTo-Html<\/b> cmdlet is capable of with two additional enhancements: It will be able to save the generated markup language (HTML) to a file and invoke the file in the default browser.<\/p>\n

Consider the following command:<\/p>\n

PS > <\/span>Get-Process<\/span><\/a> | <\/span>Select-Object<\/span><\/a> -Property Name,Id | ConvertTo-Html -FilePath gps.html -Invoke<\/span><\/p><\/blockquote>\n

Note the FilePath<\/i> and Invoke <\/i>parameters. <\/i>These parameters are not a part of the default ConvertTo-Html<\/b> parameters; they are added by our proxy function.<\/p>\n

If we wanted to use the default Windows PowerShell core cmdlets to achieve the same result, we would have to write it as follows:<\/p>\n

PS > Get-Process | Select-Object -Property Name,Id | ConvertTo-Html | <\/span>Out-File<\/span><\/a> -FilePath gps.html\nPS > <\/span>Invoke-Item<\/span><\/a> -Path gps.html <\/span><\/p><\/blockquote>\n

So, in essence we are creating a shortcut of some sort, with the added advantage that the proxy command is easier to read and understand. The output results for both of the previous commands is the same.<\/p>\n

So let’s get started. First, we need to generate the proxy command for the ConvertTo-Html<\/b> cmdlet. We will redirect the code to a new file and edit the file in the Windows PowerShell Integrated Scripting Environment (ISE) as seen here.<\/p>\n

PS > $MetaData = <\/span>New-Object<\/span><\/a> System.Management.Automation.CommandMetaData (<\/span>Get-Command<\/span><\/a> ConvertTo-Html)\nPS > [System.Management.Automation.ProxyCommand]::Create($MetaData) | Out-File -FilePath C:\\ConvertTo-Html.ps1\nPS > ise C:\\ConvertTo-Html.ps1<\/span><\/p><\/blockquote>\n

The Windows PowerShell ISE is shown here with the code generated by the previous command.<\/p>\n

\"Image<\/a><\/p>\n

Now let’s add a new parameter to the parameters section in the script file. (The two new parameters FilePath <\/i>and Invoke<\/i> are shown in bold text.)<\/p>\n

[ValidateNotNullOrEmpty()]\n[System.String[]]\n${PreContent},<\/span><\/p>\n

[ValidateNotNullOrEmpty()]\n[System.String]\n${FilePath},<\/span><\/b><\/p>\n

[Switch]\n${Invoke}\n<\/b>) <\/span><\/span><\/p><\/blockquote>\n

The main logic of the following code is inside the Begin<\/b> script block (comments are inline, and code modifications are in bold text).<\/p>\n

begin\n{\ntry {\n$outBuffer = $null\nif ($PSBoundParameters.TryGetValue(‘OutBuffer’, [ref]$outBuffer))\n{\n$PSBoundParameters[‘OutBuffer’] = 1\n}\n# make sure we are wrapping a core cmdlet by specifiyng the command qualified name\n$wrappedCmd = $ExecutionContext.InvokeCommand.GetCommand(‘Microsoft.PowerShell.Utility\\<\/b>ConvertTo-Html’, [System.Management.Automation.CommandTypes]::Cmdlet)<\/span><\/p>\n

\u00a0\u00a0\u00a0 # remove the FilePath parameter if it was specified, otherwise it will get to the core cmdlet and we’ll get an error\n<\/span>if($PSBoundParameters[‘FilePath’])\n{\n$null = $PSBoundParameters.Remove(‘FilePath’)<\/b>\n# redirect the output to the a file\n$scriptCmd = {& $wrappedCmd @PSBoundParameters | Out-File $FilePath}<\/b>\n# if Invoke has been specified – remove it and invoke the file\n<\/span><\/span>if($PSBoundParameters[‘Invoke’])\n{\n$null = $PSBoundParameters.Remove(‘Invoke’)\nInvoke-Item $FilePath\n}\n}\nelse\n{\n$scriptCmd = {& $wrappedCmd @PSBoundParameters }\n} <\/b>\n$steppablePipeline = $scriptCmd.GetSteppablePipeline($myInvocation.CommandOrigin)\n$steppablePipeline.Begin($PSCmdlet)\n} catch {\nthrow\n}\n} <\/span><\/span><\/p><\/blockquote>\n

Finally, the code is wrapped in a function declaration that has the same name as the cmdlet, as shown here:<\/p>\n

function ConvertTo-Html\n{<\/span><\/p>\n

\u00a0\u00a0\u00a0 proxy function generated code<\/span><\/p>\n

}<\/span><\/p><\/blockquote>\n

By choosing the same name as the cmdlet, we can take advantage of the command discovery process in Windows PowerShell. Basically, if you have a cmdlet and a function with the same name, the function takes precedence. Here is the order of command precedence that is used by the command discovery process in Windows PowerShell:<\/p>\n

\u00b7 Alias<\/b>: <\/b>All Windows PowerShell aliases in the current session<\/p>\n

\u00b7 Filter\/Function<\/b>: All Windows PowerShell functions<\/p>\n

\u00b7 Cmdlet<\/b>: The cmdlets in the current session (“Cmdlet” is the default)<\/p>\n

\u00b7 ExternalScript<\/b>: <\/b>All .ps1 files in the paths that are listed in the Path<\/b> environment variable ($env:PATH)<\/p>\n

\u00b7 Application<\/b>: <\/b>All non-Windows-PowerShell files in paths that are listed in the Path<\/b> environment variable<\/p>\n

\u00b7 Script<\/b>: <\/b>Script blocks in the current session<\/p>\n

There is one gotcha to using the same name. If you need to call the core ConvertTo-Html<\/b> cmdlet, you need to specify its module\/snap-in fully qualified name. For the ConvertTo-Html<\/b> cmdlet, that name is seen here.<\/p>\n

PS > Microsoft.PowerShell.Utility\\ConvertTo-Html ….<\/span><\/p><\/blockquote>\n

More than likely, you will not know what that module\/snap-in fully qualified name is. Luckily, you can use Windows PowerShell to get the full name of a cmdlet by using the following command.<\/p>\n

PS > $cmd = Get-Command -Name ConvertTo-Html\nPS > <\/span>Join-Path<\/span><\/a> -Path $cmd.ModuleName -ChildPath $cmd.Name\nMicrosoft.PowerShell.Utility\\ConvertTo-Html <\/span><\/p><\/blockquote>\n

The same technique applies for getting Help. To get the Help for the core cmdlet and specify its full name, you would use the command shown here.<\/p>\n

PS > Get-help Microsoft.PowerShell.Utility\\ConvertTo-Html<\/span><\/p><\/blockquote>\n

If you do not like this behavior, you can give the proxy function a different name.<\/p>\n

Another gotcha occurs when you are using the Get-Help<\/b> cmdlet. By default, Get-Help<\/b> displays the Help content of a cmdlet, but if we have two commands with the same name, Get-Help<\/b> lists the two commands (note the Category<\/b> column):<\/p>\n

PS > Get-Help ConvertTo-Html <\/span><\/p>\n

Name Category Synopsis<\/span><\/p>\n

—- ——– ——–<\/span><\/p>\n

ConvertTo-Html Function ConvertTo-Html [[-Property] ] [[-Head] ] [[-Title] ] [[-Body] < browser.><\/span><\/p>\n

ConvertTo-Html Cmdlet\u00a0\u00a0 Converts Microsoft .NET Framework objects into HTML that can be…<\/span><\/p><\/blockquote>\n

To load the proxy command into your session, simply \u201cdot-source\u201d it as follows.<\/p>\n

PS > . C:\\ConvertTo-Html.ps1<\/span><\/p><\/blockquote>\n

Now, let us try the command that we used previously with the new proxy command.<\/p>\n

Get-Process<\/span><\/a> | <\/span>Select-Object<\/span><\/a> -Property Name,Id | ConvertTo-Html -FilePath gps.html -Invoke<\/span><\/p><\/blockquote>\n

You can see that it works great, as shown here.<\/p>\n

\"Image<\/a><\/p>\n

That is it. We now have a proxy function that wraps a cmdlet with additional functionality. You can download the function file here<\/a>.<\/p>\n

With regard to the AsXml<\/i> parameter mentioned earlier\u2026I already have this functionality in my profile, but I strongly recommend that you file a suggestion on Microsoft’s Connect<\/a> website so we all can get the benefit of having new parameters in future releases of Windows PowerShell. (Here’s my suggestion<\/a> for AsXml <\/i>support\u2014feel free to add your vote.) Until then, we can add this kind of functionality to core Windows PowerShell cmdlets right now!<\/p>\n

LS, that is all there is to using Windows PowerShell proxy functions to extend the capabilities of Windows PowerShell cmdlets. Thank you, Shay, for your hard work and for sharing it with us. Guest Blogger Week will continue tomorrow when Rob Campbell will join us.<\/p>\n

I invite you to follow me on Twitter<\/a> and Facebook<\/a>. If you have any questions, send email to me at scripter@microsoft.com<\/a>, or post your questions on the Official Scripting Guys Forum<\/a>. See you tomorrow. Until then, peace.<\/p>\n

Ed Wilson, Microsoft Scripting Guy<\/b><\/p>\n","protected":false},"excerpt":{"rendered":"

Summary: Microsoft MVP, Shay Levy, shows how to use Windows PowerShell proxy functions to extend the capability of Windows PowerShell cmdlets. Hey, Scripting Guy! I need to be able to modify the behavior of existing Windows PowerShell cmdlets. Is this something that can be accomplished by using \u201cnormal\u201d tools, or do I need to reverse […]<\/p>\n","protected":false},"author":595,"featured_media":87096,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[56,3,4,224,45],"class_list":["post-15451","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-scripting","tag-guest-blogger","tag-scripting-guy","tag-scripting-techniques","tag-shay-levy","tag-windows-powershell"],"acf":[],"blog_post_summary":"

Summary: Microsoft MVP, Shay Levy, shows how to use Windows PowerShell proxy functions to extend the capability of Windows PowerShell cmdlets. Hey, Scripting Guy! I need to be able to modify the behavior of existing Windows PowerShell cmdlets. Is this something that can be accomplished by using \u201cnormal\u201d tools, or do I need to reverse […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/15451","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/users\/595"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/comments?post=15451"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/15451\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media\/87096"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media?parent=15451"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=15451"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=15451"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}