{"id":3336,"date":"2013-06-25T00:01:00","date_gmt":"2013-06-25T00:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2013\/06\/25\/use-powershell-to-interact-with-the-windows-api-part-1\/"},"modified":"2013-06-25T00:01:00","modified_gmt":"2013-06-25T00:01:00","slug":"use-powershell-to-interact-with-the-windows-api-part-1","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/use-powershell-to-interact-with-the-windows-api-part-1\/","title":{"rendered":"Use PowerShell to Interact with the Windows API: Part 1"},"content":{"rendered":"

Summary<\/strong>: Guest blogger, Matt Graeber, discusses how to use Windows PowerShell to interact with Windows API functions in Part 1 of a three-part series.<\/span><\/p>\n

Microsoft Scripting Guy, Ed Wilson, is here. Guest blogger, Matt Graeber, is back. Matt first joined us as a guest yesterday with his post <\/span>Use PowerShell and Regular Expressions to Search Binary Data<\/a>.<\/span> <\/span><\/p>\n

Welcome back, Matt… <\/span><\/p>\n

I often finding myself needing to use Windows PowerShell to interact with Windows API functions to accomplish a low-level task. For those who are not familiar with the Windows API, basically, it refers to the functionality that is exposed by your built-in system DLLs. For example, kernel32.dll exposes hundreds of functions that can be used by developers for interacting with the operating system. <\/span><\/p>\n

In Windows PowerShell, there are three ways to interact with Windows API functions: <\/span><\/p>\n

    \n
  1. Use the Add-Type<\/strong> cmdlet to compile C# code. This is the officially documented method.<\/li>\n
  2. Get a reference to a private type in the .NET Framework that calls the method.<\/li>\n
  3. Use reflection to dynamically define a method that calls the Windows API function.<\/li>\n<\/ol>\n

    Background to using Add-Type<\/h2>\n

    In the examples that follow, I use the CopyFile<\/strong> function in kernel32.dll as the function that Windows PowerShell will interact with. Now, you may have just asked the question, “Why would I want to call CopyFile<\/strong> when Windows PowerShell already has the Copy-Item<\/strong> cmdlet?” <\/span><\/p>\n

    That’s a very good question, indeed. As it turns out though, there are certain file paths that the Windows PowerShell file provider doesn’t know how to handle. In particular, it doesn’t know how to interpret special device object paths, such as: \\\\?\\GLOBALROOT\\Device\\HarddiskVolumeShadowCopy2\\Windows\\System32\\calc.exe. These are the kinds of paths that you need to deal with when you interact with files that are backed up by the Volume Shadow Copy Service. For example, running the following command lists the device object paths of each volume shadow copy: <\/span><\/p>\n

    # Run this from an administrative prompt<\/p>\n

    Get-WmiObject Win32_ShadowCopy | Select-Object DeviceObject <\/span><\/p>\n

    Before diving into using Windows PowerShell to call CopyFile<\/strong>, it is helpful to have some background on C\/C++ types vs. .NET types. <\/span>According to MSDN documentation (see <\/span>CopyFile function<\/a>), <\/span>CopyFile<\/strong> has the following function definition:<\/span> <\/span><\/p>\n

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

    So CopyFile<\/strong> has a return type of BOOL and three parameters—two ‘T’ strings and a bool. The key to interacting with Win API functions is knowing how to convert these C\/C++ types to the equivalent .NET type. Fortunately, there is a site dedicated to this cause: PINVOKE.NET<\/a> , which provides a treasure trove of the type of information you need to perform this task. It is worth a bookmark in your favorites. <\/span><\/p>\n

    If you search for CopyFile<\/strong> on PINVOKE.NET, you will find the following C# definition: <\/span><\/p>\n

    [DllImport(“kernel32.dll”, CharSet = CharSet.Unicode)]
    static extern bool CopyFile(string lpExistingFileName, string lpNewFileName, bool bFailIfExists);<\/p>\n

    You can now see the translation of C\/C++ types to .NET types:<\/span><\/p>\n

    BOOL -> bool<\/p>\n

    LPCTSTR -> string <\/span><\/p>\n

    Now, you should have the background needed to start using Windows PowerShell to interact with the CopyFile<\/strong> function. Let’s jump into our first method of interaction, Add-Type<\/strong>.<\/strong><\/p>\n

    Using Add-Type to call the CopyItem <\/em>function<\/h2>\n

    The Add-Type<\/strong> cmdlet is used to define .NET types that will be made available to your Windows PowerShell session. What’s really cool about it is that it can compile C# code on the fly. If you view the Help for Add-Type<\/strong>, you’ll find some good examples of how to call Windows API functions. <\/span><\/p>\n

    As an example, the following code allows me to call the CopyItem<\/strong> function within Windows PowerShell: <\/span><\/p>\n

    $MethodDefinition = @’<\/p>\n

    [DllImport(“kernel32.dll”, CharSet = CharSet.Unicode)]<\/p>\n

    public static extern bool CopyFile(string lpExistingFileName, string lpNewFileName, bool bFailIfExists);<\/p>\n

    ‘@<\/p>\n

    $Kernel32 = Add-Type -MemberDefinition $MethodDefinition -Name ‘Kernel32’ -Namespace ‘Win32’ -PassThru<\/span><\/p>\n

    # You may now call the CopyFile function<\/span><\/p>\n

    # Copy calc.exe to the user’s desktop<\/p>\n

    $Kernel32::CopyFile(“$($Env:SystemRoot)\\System32\\calc.exe”, “$($Env:USERPROFILE)\\Desktop\\calc.exe”, $False) <\/span><\/p>\n

    The $MethodDefinition<\/strong> variable simply contains the C# definition that I took from PINVOKE.NET with one minor modification: I defined the CopyFile<\/strong> method to be public. Methods that are added with Add-Type<\/strong> must be public to easily interact with them in Windows PowerShell. <\/span><\/p>\n

    I then call Add-Type<\/strong> and provide the C# source code, a type name, and a namespace. By specifying the type name and namespace, after calling Add-Type<\/strong> you can reference the new type in WindowsPowerShell with `[Win32.Kernel32]`.<\/p>\n

    Lastly, by default, <\/span>Add-Type<\/strong> doesn’t output the type definition that it creates. The <\/span>-PassThru<\/strong> parameter tells it to output the type definition.<\/span><\/p>\n

    After calling Add-Type<\/strong>, you can finally call CopyFile<\/strong> directly within Windows PowerShell. The previous example simply copies calc.exe to the user’s desktop. It’s worth noting the two colons that follow the $Kernel32<\/strong> variable. These indicate that you are calling a static .NET method. All static methods are called this way in Windows PowerShell.<\/p>\n

    To wrap things up, I wrote the Copy-RawItem<\/strong> function that wraps the CopyFile<\/strong> function nicely. The full script is also available in the Script Center Repository: Copy-RawItem (Add-Type Version)<\/a>.<\/p>\n

    Copy-RawItem Function<\/strong>:<\/p>\n

    function Copy-RawItem<\/p>\n

    {<\/p>\n

    <#<\/p>\n

    .SYNOPSIS<\/p>\n

        Copies a file from one location to another including files contained within DeviceObject paths.<\/p>\n

    .PARAMETER Path<\/p>\n

        Specifies the path to the file to copy.<\/p>\n

    .PARAMETER Destination<\/p>\n

        Specifies the path to the location where the item is to be copied.<\/p>\n

    .PARAMETER FailIfExists<\/p>\n

        Do not copy the file if it already exists in the specified destination.<\/p>\n

    .OUTPUTS<\/p>\n

        None or an object representing the copied item.<\/p>\n

    .EXAMPLE<\/p>\n

        Copy-RawItem ‘\\\\?\\GLOBALROOT\\Device\\HarddiskVolumeShadowCopy2\\Windows\\System32\\config\\SAM’ ‘C:\\temp\\SAM’<\/p>\n

    #><\/p>\n

        [CmdletBinding()]<\/p>\n

        [OutputType([System.IO.FileSystemInfo])]<\/p>\n

        Param (<\/p>\n

            [Parameter(Mandatory = $True, Position = 0)]<\/p>\n

            [ValidateNotNullOrEmpty()]<\/p>\n

            [String]<\/p>\n

            $Path,<\/p>\n

            [Parameter(Mandatory = $True, Position = 1)]<\/p>\n

            [ValidateNotNullOrEmpty()]<\/p>\n

            [String]<\/p>\n

            $Destination,<\/p>\n

            [Switch]<\/p>\n

            $FailIfExists<\/p>\n

        )<\/p>\n

        $MethodDefinition = @’<\/p>\n

        [DllImport(“kernel32.dll”, CharSet = CharSet.Unicode, SetLastError = true)]<\/p>\n

        public static extern bool CopyFile(string lpExistingFileName, string lpNewFileName, bool bFailIfExists);<\/p>\n

    ‘@<\/p>\n

     <\/p>\n

        $Kernel32 = Add-Type -MemberDefinition $MethodDefinition -Name ‘Kernel32’ -Namespace ‘Win32’ -PassThru<\/p>\n

     <\/p>\n

        # Perform the copy<\/p>\n

        $CopyResult = $Kernel32::CopyFile($Path, $Destination, ([Bool] $PSBoundParameters[‘FailIfExists’]))<\/p>\n

     <\/p>\n

        if ($CopyResult -eq $False)<\/p>\n

        {<\/p>\n

            # An error occured. Display the Win32 error set by CopyFile<\/p>\n

            throw ( New-Object ComponentModel.Win32Exception )<\/p>\n

        }<\/p>\n

        else<\/p>\n

        {<\/p>\n

            Write-Output (Get-ChildItem $Destination)<\/p>\n

        }<\/p>\n

    }<\/p>\n

    The following image illustrates using the Copy-RawItem<\/strong> function.<\/p>\n

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

    The only code in the Copy-RawItem<\/strong> that warrants explanation is the last few lines where error checking occurs. The MSDN documentation states that if CopyFile<\/strong> returns FALSE, an error occurred. In C\/C++, you would determine the cause for the error by calling GetLastError<\/strong>. In Windows PowerShell, you can channel the error by throwing a ComponentModel.Win32Exception object. This is what allows you to pry out the error from a Win API function without calling GetLastError<\/strong>.<\/p>\n

    ~Matt<\/p>\n

    Thank you, Matt. Join us tomorrow when Matt will continue this series.<\/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<\/strong> <\/span><\/p>\n","protected":false},"excerpt":{"rendered":"

    Summary: Guest blogger, Matt Graeber, discusses how to use Windows PowerShell to interact with Windows API functions in Part 1 of a three-part series. Microsoft Scripting Guy, Ed Wilson, is here. Guest blogger, Matt Graeber, is back. Matt first joined us as a guest yesterday with his post Use PowerShell and Regular Expressions to Search Binary […]<\/p>\n","protected":false},"author":596,"featured_media":87096,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[56,431,3,63,45],"class_list":["post-3336","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-scripting","tag-guest-blogger","tag-matt-graeber","tag-scripting-guy","tag-security","tag-windows-powershell"],"acf":[],"blog_post_summary":"

    Summary: Guest blogger, Matt Graeber, discusses how to use Windows PowerShell to interact with Windows API functions in Part 1 of a three-part series. Microsoft Scripting Guy, Ed Wilson, is here. Guest blogger, Matt Graeber, is back. Matt first joined us as a guest yesterday with his post Use PowerShell and Regular Expressions to Search Binary […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/3336","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\/596"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/comments?post=3336"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/3336\/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=3336"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=3336"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=3336"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}