Executing PowerShell scripts from C#


In today’s post, I will demonstrate the basics of how to execute PowerShell scripts and code from within a C#/.NET applications. I will walk through how to setup your project prerequisites, populate the pipeline with script code and parameters, perform synchronous and asynchronous execution, capture output, and leverage shared namespaces.

Update 8/7/2014: Here is the downloadable solution file.
Update 11/5/2014: Added a section on execution policy behavior.

Prerequisites:

First, ensure that PowerShell 2.0 or later is installed on the system you are developing on. The features used below will not be supported on PowerShell 1.0. Next, start by making a new console application (targeting .NET 4.0) in Visual Studio.

In the solution explorer, add a project reference to the System.Management.Automation assembly*. On my machine (PowerShell 3.0), it was located at C:\Program Files (x86)\Reference Assemblies\Microsoft\WindowsPowerShell\3.0. Then, add using statements for the above referenced assembly, along with System.Collections.Objectmodel, which is used later for execution output.

Note: You will need to install the Windows SDK in order to obtain the System.Management.Automation assembly file.
Note: You do not have to distribute the System.Management.Automation assembly file with your application binaries – it is located in the GAC on machines with Windows PowerShell installed and should resolve automatically.

Prepare the Pipeline for execution:

The first step is to create a new instance of the PowerShell class. The static method PowerShell.Create() creates an empty PowerShell pipeline for us to use for execution. The PowerShell class implements IDisposable, so remember to wrap it up in a using block.

    using (PowerShell PowerShellInstance = PowerShell.Create())
    {
    }

Next, we can add scripts or commands to execute. Call the AddScript() and AddCommand() methods to add this content to the execution pipeline. If your script has parameters, adding them is easy with the AddParameter() method. AddParameter() accepts a string parameter name, and object for the parameter value. Feel free to pass in full object instances/types if you want. The scripts and pipeline handle it just fine. No need to limit yourself with only passing in string values.

The string contents supplied to AddScript() can come from anywhere. Good choices may be text loaded from files on disk or embedded resources, or user input. For the purposes of this tutorial, I’m just hard-coding some example script text.

    using (PowerShell PowerShellInstance = PowerShell.Create())
    {
        // use "AddScript" to add the contents of a script file to the end of the execution pipeline.
        // use "AddCommand" to add individual commands/cmdlets to the end of the execution pipeline.
        PowerShellInstance.AddScript("param($param1) $d = get-date; $s = 'test string value'; " +
                "$d; $s; $param1; get-service");
       // use "AddParameter" to add a single parameter to the last command/script on the pipeline.         PowerShellInstance.AddParameter("param1""parameter 1 value!");     }

Script/Command Execution:

So far, we have a PowerShell pipeline populated with script code and parameters. There are two ways we can call PowerShell to execute it: synchronously and asynchronously.

Synchronous execution:

For synchronous execution, we call PowerShell.Invoke(). The caller waits until the script or commands have finished executing completely before returning from the call to Invoke(). If you don’t care about the items in the output stream, the simplest execution looks like this:

    // invoke execution on the pipeline (ignore output)
    PowerShellInstance.Invoke();

For situations where you don’t need to see or monitor the output or results of execution, this may be acceptable. But, in other scenarios you probably need to peek at the results or perform additional processing with the output that comes back from PowerShell. Let’s see what that code looks like:

    // invoke execution on the pipeline (collecting output)
    Collection<PSObject> PSOutput = PowerShellInstance.Invoke();
    // loop through each output object item     foreach (PSObject outputItem in PSOutput)     {         // if null object was dumped to the pipeline during the script then a null         // object may be present here. check for null to prevent potential NRE.         if (outputItem != null)         {             //TODO: do something with the output item              // outputItem.BaseOBject         }     }

The return object from Invoke() is a collection of PSObject instances that were written to the output stream during execution. PSObject is a wrapper class that adds PowerShell specific functionality around whatever the base object is. Inside the PSObject is a member called BaseObject, which contains an object reference to the base type you are working with. If nothing was written to the output stream, then the collection of PSObjects will be empty.

Besides the standard output stream, there are also dedicated streams for warnings, errors, debug, progress, and verbose logging. If any cmdlets leverage those streams, or you call them directly (write-error, write-debug, etc.), then those items will appear in the streams collections.

After invoking the script, you can check each of these stream collections to see if items were written to them.

    // invoke execution on the pipeline (collecting output)
    Collection<PSObject> PSOutput = PowerShellInstance.Invoke();
   // check the other output streams (for example, the error stream)     if (PowerShellInstance.Streams.Error.Count > 0)     {         // error records were written to the error stream.         // do something with the items found.     }

In my sample script supplied above, I am writing a few manually-created objects to the output stream and calling the get-service cmdlet, which also writes its output to the stream since I didn’t save the output in a variable.

As a test, I write the type name and ToString() on all of the base objects that came back from the sample script. As you can see, accessing the base object allows you to view or manipulate the object directly as needed. The base types that come back from execution are usually standard .NET types you may already be familiar with, just wrapped up in a PSObject.

    // loop through each output object item
    foreach (PSObject outputItem in PSOutput)
    {
        // if null object was dumped to the pipeline during the script then a null
        // object may be present here. check for null to prevent potential NRE.
        if (outputItem != null)
        {
            //TODO: do something with the output item 
            Console.WriteLine(outputItem.BaseObject.GetType().FullName);
            Console.WriteLine(outputItem.BaseObject.ToString() + "\n");
        }
    }
 
Asynchronous execution:

For asynchronous execution, we call PowerShell.BeginInvoke(). BeginInvoke() immediately returns to the caller and the script execution begins in the background so you can perform other work. Unlike the synchronous Invoke() method, the return type of BeginInvoke() is not a collection of PSObject instances from the output stream. The output isn’t ready yet. The caller is given an IAsyncResult object to monitor the status of the execution pipeline. Let’s start with a really simple example:

    using (PowerShell PowerShellInstance = PowerShell.Create())
    {
        // this script has a sleep in it to simulate a long running script
        PowerShellInstance.AddScript("start-sleep -s 7; get-service");
        // begin invoke execution on the pipeline         IAsyncResult result = PowerShellInstance.BeginInvoke();
        // do something else until execution has completed.         // this could be sleep/wait, or perhaps some other work         while (result.IsCompleted == false)         {             Console.WriteLine("Waiting for pipeline to finish...");             Thread.Sleep(1000);
            // might want to place a timeout here...         }
        Console.WriteLine("Finished!");     }

Note: If you wrap the PowerShell instance in a using block like the sample above and do not wait for execution to complete, the pipeline will close itself, and will abort script execution, when it reaches the closing brace of the using block. You can avoid this by waiting for completion of the pipeline, or by removing the using block and manually calling Dispose() on the instance at a later time.

In this first asynchronous example, we ignored the output stream. Again, this is only useful if you don’t care about your script results. Fortunately, the BeginInvoke() method has a few overloads that allow us to extend the functionality. Let’s improve the example by adding output collection and event handling for data hitting the pipeline.

First, we will create a new instance of PSDataCollection<PSObject>. This collection is a thread-safe buffer that will store output stream objects as they hit the pipeline. Next, we will subscribe to the DataAdded event on this collection. This event will fire every time an object is written to the output stream. To use this new output buffer, pass it as a parameter to BeginInvoke().

I added some other functionality and comments to the next code block. First, notice that you can check the state of the pipeline to see its status. The State will equal Completed when your script is done. If State is Failed, it is likely caused by an unhandled exception that occurred in the script, also known as a terminating error. Second, if your scripts utilize write-error, write-debug, write-progress, etc. (all thread-safe collections), you can review these during or after execution to check for items logged there. I have subscribed to the DataAdded event on the Error stream as well to be notified in real time.

    /// <summary>
    /// Sample execution scenario 2: Asynchronous
    /// </summary>
    /// <remarks>
    /// Executes a PowerShell script asynchronously with script output and event handling.
    /// </remarks>
    public void ExecuteAsynchronously()
    {
        using (PowerShell PowerShellInstance = PowerShell.Create())
        {
            // this script has a sleep in it to simulate a long running script
            PowerShellInstance.AddScript("$s1 = 'test1'; $s2 = 'test2'; $s1; write-error 'some error';start-sleep -s 7; $s2");

            // prepare a new collection to store output stream objects             PSDataCollection<PSObject> outputCollection = new PSDataCollection<PSObject>();             outputCollection.DataAdded += outputCollection_DataAdded;
            // the streams (Error, Debug, Progress, etc) are available on the PowerShell instance.             // we can review them during or after execution.             // we can also be notified when a new item is written to the stream (like this):             PowerShellInstance.Streams.Error.DataAdded += Error_DataAdded;
            // begin invoke execution on the pipeline             // use this overload to specify an output stream buffer             IAsyncResult result = PowerShellInstance.BeginInvoke<PSObjectPSObject>(null, outputCollection);
            // do something else until execution has completed.             // this could be sleep/wait, or perhaps some other work             while (result.IsCompleted == false)             {                 Console.WriteLine("Waiting for pipeline to finish...");                 Thread.Sleep(1000);
                // might want to place a timeout here...             }
            Console.WriteLine("Execution has stopped. The pipeline state: " + PowerShellInstance.InvocationStateInfo.State);
            foreach (PSObject outputItem in outputCollection)             {                 //TODO: handle/process the output items if required                 Console.WriteLine(outputItem.BaseObject.ToString());             }         }     }
    /// <summary>     /// Event handler for when data is added to the output stream.     /// </summary>     /// <param name="sender">Contains the complete PSDataCollection of all output items.</param>     /// <param name="e">Contains the index ID of the added collection item and the ID of the PowerShell instance this event belongs to.</param>     void outputCollection_DataAdded(object sender, DataAddedEventArgs e)     {         // do something when an object is written to the output stream         Console.WriteLine("Object added to output.");     }
    /// <summary>     /// Event handler for when Data is added to the Error stream.     /// </summary>     /// <param name="sender">Contains the complete PSDataCollection of all error output items.</param>     /// <param name="e">Contains the index ID of the added collection item and the ID of the PowerShell instance this event belongs to.</param>     void Error_DataAdded(object sender, DataAddedEventArgs e)     {         // do something when an error is written to the error stream         Console.WriteLine("An error was written to the Error stream!");     }
 

As you can see above, the complete asynchronous model allows for some pretty interesting scenarios with long-running scripts. We can listen for events like data being added to the output stream. We can monitor the progress stream to see how much longer a task may take and provide feedback to the UI. We can listen for new errors being written to the error stream and react accordingly, instead of waiting until all execution has completed.

Execution Policy:

When you invoke cmdlets through the PowerShell class in C#, the execution policy behavior is subject to the policy restrictions of the machine. This behavior is the same is if you opened up a PowerShell prompt on the machine. You can issue commands just fine, but invoking another script might get blocked if your execution policy is undefined or restricted in some way. An easy way to get around this is to set the execution policy for the scope of the application process. Simply run Set-ExecutionPolicy and specify the scope to be Process. This should allow you to invoke secondary scripts without altering the machine/user policies. For more information about policies and their order of precedence, see here.

Shared Namespace:

To wrap up our discussion, I’d like to share a potentially useful feature that can expand some of the functionality for your scripts. When you use the PowerShell class to invoke a script, that script has access to the classes inside the caller’s namespace, if they were declared public.

In the example code below, we make a public class with a single public property, and a public static class with a single public method. Both of these items exist in the same namespace as the PowerShell executor code. The script we execute creates a new instance of the class, sets the property, and writes it to the pipeline. The static class and method are then called directly from inside the script, saving the results to a string which is then written to the pipeline as well.

namespace PowerShellExecutionSample
{
    /// <summary>
    /// Test class object to instantiate from inside PowerShell script.
    /// </summary>
    public class TestObject
    {
        /// <summary>
        /// Gets or sets the Name property
        /// </summary>
        public string Name { getset; }
    }

    /// <summary>     /// Test static class to invoke from inside PowerShell script.     /// </summary>     public static class TestStaticClass     {         /// <summary>         /// Sample static method to call from insider PowerShell script.         /// </summary>         /// <returns>String message</returns>         public static string TestStaticMethod()         {             return "Hello, you have called the test static method.";         }     }
    /// <summary>     /// Provides PowerShell script execution examples     /// </summary>     class PowerShellExecutor     {         /// <summary>         /// Sample execution scenario 3: Namespace test         /// </summary>         /// <remarks>         /// Executes a PowerShell script synchronously and utilizes classes in the callers namespace.         /// </remarks>         public void ExecuteSynchronouslyNamespaceTest()         {             using (PowerShell PowerShellInstance = PowerShell.Create())             {
                // add a script that creates a new instance of an object from the caller's namespace
                PowerShellInstance.AddScript("$t = new-object PowerShellExecutionSample.TestObject;" + 
                                             "$t.Name = 'created from inside PowerShell script'; $t;" +
                                             "$message = [PowerShellExecutionSample.TestStaticClass]::TestStaticMethod(); $message");

                // invoke execution on the pipeline (collecting output)                 Collection<PSObject> PSOutput = PowerShellInstance.Invoke();
                // loop through each output object item                 foreach (PSObject outputItem in PSOutput)                 {                     if (outputItem != null)                     {                         Console.WriteLine(outputItem.BaseObject.GetType().FullName);
                        if (outputItem.BaseObject is TestObject)                         {                             TestObject testObj = outputItem.BaseObject as TestObject;                             Console.WriteLine(testObj.Name);                         }                         else                         {                             Console.WriteLine(outputItem.BaseObject.ToString());                         }                     }                 }             }         }     } } 
 

As we can see from the console output, the public static class and non-static class were both available from inside the script for use. The ability to leverage public members from the caller’s namespace allows you to create some interesting scenarios calling C# code directly from your PowerShell scripts.

Comments (40)

  1. tasos says:

    Hello.Nice article.I would like to ask you,what is the difference between runspace and powershell?When do i use using (var runspace = RunspaceFactory.CreateRunspace()) and when powershell(the way you do it?).I have memory leak issues and still searching for a solution.

    Thanks!

  2. Keith Babinec says:

    @tasos:

    The runspace factory and the PowerShell class provide similar functionality. Runspace factory was introduced early (powershell v1). The PowerShell instance class stuff was introduced in v2 I believe. The v2 method is just a little bit easier to use.

  3. tasos says:

    Thank you for replying!

    The fact that i have memory leaks after every powershell i execute is because of the specific cmdlets or because of system.management.automation?

    Thanks again!

  4. Keith Babinec says:

    I don't know why you would be having memory leaks. If you are still having problems I would recommend asking for support on the MSDN forums, they should be able to help you over there. social.msdn.microsoft.com/…/home

  5. Paul says:

    Excellent and well written article. Love the examples. Thank you!

  6. MSTech says:

    And of course you have a downloadable test project to go along with the article…

  7. Keith Babinec says:

    @MSTech – just updated the top of the article and posted a link to the solution.

  8. JR says:

    Outstanding article … especially appreciated the namespace example.

  9. Dan says:

    Hi Keith,

    Thanks for the wonderful article. I tried to import and run the code you have supplied above. I am getting the following error message "Could not load file or assembly 'System.Management.Automation, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35' or one of its dependencies. Strong name validation failed. (Exception from HRESULT: 0x8013141A)" could you please help me resolving this. I am able to see the System.Management.Automation.dll in the same location as you mentioned in your code.

    Thanks in Advance.

  10. Keith Babinec says:

    @Dan, I haven't run into that before. Are you running it from the downloadable solution link above? Or did you copy and paste the code snippets into a brand new project of your own? If its a brand new project, what .net framework version did you target?

  11. Dan says:

    @Keith I am running the downloadable solution link provided above.  I am getting the above error when I am running t.ExecuteSynchronously(); statement.

  12. Keith Babinec says:

    @Dan – one thing I would try would be to remove the reference to the assembly, and then re-add it back to the project. Alternatively, create a new project in Visual Studio, add the assembly reference, and try some of the sample code in that new project. See if that helps.  If you are still having issues after that I would recommend heading over to the MSDN forums for support.

  13. Greg says:

    Is there any way to specify the user that runs the power shell instance? I'd like to user a different use to that which runs the application.

  14. shanmuk says:

    Hello, thanks for the article.

    We’re trying to automate some of our PowerShell CmdLets in C#. In PowerShell Cmd we are getting an PSObject which has one more object nested.

    E.g:

    $a = Get-XYZ

    $a has some properties say prop1, prop2  etc.

    $a.prop1 also has some properties say prop1-1, prop1-2

    Please help me in getting values of prop1-1, prop1-2 via C#. we were able to access prop1 and prop2 as PSMemberInfo.

  15. carlos austria says:

    Hi Keith, i have deployed powershell to an mvc application.  this works well but i would like to improve the execution time.  the problem is i have a powershell script that loads all of the functions in memory and then the functions are called individually.  from a powershell console this works well. as long as the ps window is open, it remembers the functions.  from a website application, i always have to call this all-functions script and then on the same line call the function i want depending on what the user chooses from a drop down.  is there a way to load the functions script in memory and just call the individual functions as if you were in a ps console?  how would you handle releasing it from memory because users can close the browser or switch to another page anytime.

    thanks!

  16. Keith Babinec says:

    @Greg – by default the PowerShell instance will be run under the user context of the hosting process. I am not aware of any additional parameters or configuration to provide to the PowerShell class that would allow it to run as a different user. The solution to this problem really depends on the design and purpose of your application. Without more info its hard to say.

  17. Keith Babinec says:

    @Shanmuk – If you know the object type, can you try casting the PSObject (or PSObject.BaseObject) into your known class and access the properties that way?

  18. Keith Babinec says:

    @Carlos – Unfortunately I don't have any experience with MVC applications, but I have solved a similar problem in WCF web services using caching. What you could do is store a collection of fully initialized PowerShell instances in the web cache. Then when a user makes a request that requires PS, it just grabs one from the cache instead of initializing a brand new one.

  19. Pushpa says:

    I have installed Powershell 5.0 and i am calling powershell scripts from C# then the first script is executing fine but second script is blocked by first. I got error. Even I tried to set executionpolicy Unrestricted -scope process. Still no luck. My current execution policy is as follows:

                                                            Scope                                          ExecutionPolicy

                                                            —–                                               —————

                                                    MachinePolicy                                     Undefined

                                                       UserPolicy                                         Undefined

                                                          Process                                           Unrestricted

                                                      CurrentUser                                       RemoteSigned

                                                     LocalMachine                                     Unrestricted

    Please suggest me how to resolve this error.

  20. Keith Babinec says:

    @Pushpa, was the 2nd script downloaded from the internet, and potentially blocked (at the file)? Please provide the error message.

  21. Sen says:

    I use the the following code and it sends the output to text box only on completion of entire script.

    Can we use the same code when executing the power shell script via the aspx page ?,

    PSshell.Commands.AddScript(PSInput);

              IAsyncResult async = PSshell.BeginInvoke();

              Response.Write(async.ToString());

              ResultBox_ps.Text += async.ToString() + "rn";

              PSshell.EndInvoke(async);

                   foreach (PSObject result in PSshell.EndInvoke(async))

                   {

                      ResultBox_ps.Text += result.ToString() + "rn";

                   }

  22. Masson says:

    I had the problem with memory leak either. Then I used RunspaceFactory.CreateOutOfProcessRunspace and memory leak gone.

  23. sachin says:

    thanks for the information but I want to build a cmdlet using the c# which does the work of making a connection. if you know can you please help. thanks in advance

  24. Suresh says:

    @Keith:

    I tried to create a sample console application which execute PS script. Getting error "Common Language Runtime detected an invalid program." at "PowerShell PowerShellInstance = PowerShell.Create()". Tried googling for the solution for the issue. Found that there is a version mismatch with the assembly referred. But couldn't able to find the exact issue. If you have an idea can you please help.

    Thanks in advance.

  25. Nick says:

    @dan and for anyone else facing this issue.

    "Thanks for the wonderful article. I tried to import and run the code you have supplied above. I am getting the following error message "Could not load file or assembly 'System.Management.Automation, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35' or one of its dependencies. Strong name validation failed. (Exception from HRESULT: 0x8013141A)" could you please help me resolving this. I am able to see the System.Management.Automation.dll in the same location as you mentioned in your code."

    After hours of research, this is what I had to do.

    1. update my .csproj file to say

       <Reference Include="System.Management.Automation, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35, processorArchitecture=MSIL">

         <SpecificVersion>False</SpecificVersion>

         <HintPath>C:Program Files (x86)Reference AssembliesMicrosoftWindowsPowerShell3.0System.Management.Automation.dll</HintPath>

       </Reference>

    2. Target a lower version of .Net. I targeted 4.0 just like in the sample solution. Before I was targeting 4.5, which was wrong.

    After this, it started working. Good luck and hope you guys find this helpful.

    http://www.qtptutorial.net

  26. Paul Ganea says:

    Thanks for this article! Really appreciated it.

    If anyone else had trouble figuring out how to get error output within the Error_DataAdded method see below

    void Error_DataAdded(object sender, DataAddedEventArgs e)

    {

               var records = (PSDataCollection<ErrorRecord>)sender;

               // do something when an error is written to the error stream

               Console.WriteLine(records[e.Index].ToString());

    }

  27. EdsonAlcala says:

    Thanks so much for the article :)

    Can I ask you something, why Am I getting this result?

    http://1drv.ms/1dDZJOq

    Thanks in advance, Cheers

  28. Blentoza says:

    Great Article

    The only one on the net concernig startig PS async from c#.

    Could you maybe add an example with Output in a mulitiline TextBox of ListBox in windows form application.

    I am struggling with it.

    The First powershell script command result is shown in LIstBox and after that application is freezing…

    Thanks in advance and regards

  29. Ted says:

    How are you guys finding these memory leaks?  

    I've used the above methods and love it – everything appears to be going great, but I'd like to make sure?

  30. AMO says:

    Hi Keith

    The link to download appears broken. Could you please update?

    Many thanks!

  31. Keith Babinec says:

    @AMO

    Just tested the link its working for me.

  32. SavindraSingh says:

    Hello Keith,

    Can you please hep me with how to get the list of Properties associated an PSObject while iterating the PSObject collection returned by below function:

           string exCmdletResult = "";

           private Collection<PSObject> CmdletResults(string PSScriptText)

           {

               exCmdletResult = "";

               Collection<PSObject> PSOutput = null;

               PowerShell ps = PowerShell.Create();

               ps.AddScript(PSScriptText);

               try

               {

                   PSOutput = ps.Invoke();

               }

               catch (Exception ex) { exCmdletResult = "Error: " + ex.Message; }

               finally { ps.Dispose(); }

               return PSOutput;

           }

    I am calling the same through this button click even on a windows form:

           private void btnExecute_Click(object sender, EventArgs e)

           {

               string cmd_Script = txtCommand.Text;

               string commandOutput = "";

               Collection<PSObject> results = CmdletResults(cmd_Script);

               if (exCmdletResult.Contains("Error: "))

               {

                   txtOutput.Text = exCmdletResult;

               }

               else

               {

                   foreach (PSObject result in results)

                   {

                       // How to get the list of properties when you don't know the command

                   }

               }

               txtOutput.Text = commandOutput;

           }

    Thanks and regards,

    Savindra

  33. JENISH says:

    i got this error when tried to Stop my Website.

    "Retrieving the COM class factory for component with CLSID {688EEEE5-6A7E-422F-B2E1-6AF00DC944A6} failed due to the following error: 80040154 Class not registered (Exception from HRESULT: 0x80040154 (REGDB_E_CLASSNOTREG))."

  34. nim says:

    can i pass the output from the powershell script into a datatable or a list object?

    i want 2 columns fullname and name in a way i can check it against a database to see if that file already exists

  35. Shelly says:

    I just started doing this.

    An unhandled exception of type 'System.Management.Automation.PSInvalidOperationException' occurred in System.Management.Automation.dll

    I think its because Powershell wont allow its access from outside.

    What should I do ?

  36. Joe Robinson says:

    Thank you very much for laying out this information.   I've been working on a solution for a few months and I found that I needed to execute some powershell to complete a task.  Your article helped me achieve this.  

  37. garfius1 says:

    hehe

    private string spaceCharacter = "` ";

    and the parameters are for powershell.exe , not the script

  38. Rick says:

    I have everything from your article working but.I can't get the "get-service" to return anything but "System.ServiceProcess.ServiceController".   I tried putting the result in a $sc  variable and then displaying it.  Still nothing.  What am I missing?     I notice it  has the same problem if I substitute "Get-ChildItem" for "Get-Service".      Thanks so much for a very helpful article.  

  39. Rockie says:

    Thank You! Great article!