mardi 20 mai 2008

PowerShell and ASP.NET Part 1

As you know, PowerShell let us create graphical interfaces with the .NET winforms. With it, we can build front end to manage our scripts. It's a really nice feature, and tools like AdminScriptEditor make it pretty easy.

I've been oftenly asked this question :

How could we integrate easely PowerShell scripting to a web site ?

This is really a good point, cause using a web portal instead of winforms brings many benefits :

No needs to install PowerShell and Snapins on every admin workstations in order to use scripts (I think about Active Directory provisioning, Support dashboard, virtual machines manager and so on...)

... in order to centralize and delegate administration easely

Filter acces and use of powershell in the company (everything is launched from the server and not from the workstation)

Tracability : from a single point, we know who did what (with appropriate logging), and could do a life-saving CTRL+Z on a innapropriate action

Can be embbeded in any entreprise web portal (Sharepoint/WSS for example)

This is a great story, however there's some drawbacks at first look for people who didn't put an hand on ASP.NET :

Developping with ASP.NET and C# is radically different from scripting

Samples of invocation method of PowerShell from C# seems difficult for Infrastructure people

We can do C# developpement to achieve result but ...

... we need to be lucky enough to have a "real" .NET developper at hand.

That's why I suggest you this first example of PowerShell/ASP.NET interaction that takes things from a different point of view, more "Infra-People compliant". To make it easier to understand, we will separate things :

ASP.NET and C# to manage only the user interface

Call PowerShell scripts directly (no C# block)

Establish a communication between PowerShell output and the web site to follow the progress

This let us use PowerShell as our process engine as usual (regular scripting)

As we'll see in this tutorial, the code is rather simple and the web site really light, but we will do pretty complex tasks by calling PowerShell. I won't make a ASP.NET tutorial, cause I'm not the best guy around to do this, and we'll only use basics to achieve our result.

However there's some unavoidable things to understand before going deeper in the code

Some bases on ASP.NET (for Infrastructure people)

To summarize intensely, you can look at a ASP.NET site as a HTML page that can call .NET code from a server, and not just the Browser/workstation.

Here's a example that will be our first project from this tutorial. Note that we can (and will do!) use the free version of Visual Studio for Web development: Visual Studio Web developper Express Edition, please download it. This version is really good for our needs and will let us do everything required for the entire development, so we won't hesitate.

The smallest possible ASP.NET site is composed of the following elements :

An ASP.NET page (Here : default.aspx) : Here we will find all the user interface definition of our project (Buttons, Dropdown list, Textboxes...). This is merely HTML / ASP.NET code. You can find javascript in other projects, but we won't use it for now.

A .CS file bind to the ASPX document (here : default.aspx.cs) : This file contains what is called the "Code-Behind". This is the server side code invoked by the asp.net site. This code is in a .NET language (C# or VB.NET). I'll use C# here cause it's easier to read and pretty close to PowerShell syntax.

web.config : This is the website configuration file. To makes things simple, we find in it the website config : Authentication Method, DLL invokation (like the ones used to call PowerShell), and so on...

Of course, Web developper express ease the process, everything is pre-build when you create a project. Before going deeper in the creation of the project, let me brief you with the strategy used to call scripts from our webform :

PowerShell interaction strategy

The following diagram presents the strategy used in this first example of PowerShell calling from ASP.NET. This is what we'll discuss in the second part of this tutorial :

Our first website is composed of 2 Textbox (one for script input, one for script output) and an "Execute" Button. That's all, as you can see, my first user interface is pretty basic.

The mecanism isn't too diffifcult to understand. We will go in the details in the Part 2 of this tutorial, but here's the resume :

When we fire "Launch Script", let's talk about what happen :

We activate the Timer (1), we'll come back on this after, but let say for the moment that this control execute some code at a certain rate (for example every second).

In the meantime, the code-Behind launch a PowerShell runspace and initialize a pipeline asyncrhonously. It read the first textbox, and execute it in the pipeline (2).

Every seconds, our Timer check the pipeline output (3), and write what it found in a special variable called "Session variable" (4) (we'll see why in the second part of the tutorial)

We refresh the output Textbox with the content of the Session Variable (5). The timer is activated until the end of the script in the pipeline (6).

Using a Timer let us have a near-realtime view of the script output (every seconds). Please note that a script used in this context isn't forced to have output : As every PowerShell script, many things can happen without any console output, so please be carefull with what you code here ;)

I keep all the code really simple to let you identify every functions more easely. We will improve it later.

We use some AJAX functionnality in this example. The Timer is a ASP.NET ajax control, we use an UpdatePanel too that let us refresh the output textbox without refreshing the entire document. Using this kind of Ajax control in ASP.NET with web developper Express is really easy (as simple as using every classic control like Textbox). We don't need to do any Javascript and XML here, you'll see that in the 2nd part of this tutorial.

For the moment, you can test this site. Open the attached project in Web developper Express. Launch it and you'll have this page :

Enter your script in the upper Textbox, launch it with the button, you'll see the result in the bottom Textbox.

Note : The script is run from the server side (if you test locally, your workstation will do the job). Note that we retrieve the "object" output of PowerShell : that's why I use in this example the "out-string" cmdlet to grab an output similar to what you see in the standard PowerShell console. Do some test, you'll see that you get objects in the output Textbox.

You can of course launche every kind of PowerShell commands and scripts, so be carefull ! :). This site is really lite to let you understand the code : I didn't put any error control or script management, nor advanced user interface.

We'll see in the second part the details of every element and code of this website, we'll see how to manage a script from Form controls, and advice regarding security.

This is an excellent article. Only thing I can't get the code to work. I followed all the steps to deploy the site. But, when I click the button, button becomes disabled, and only thing in the output shows the first line who is the user, but nothing else shows up after that. Is there any way to get a working code ?