PowerShell Coalesce and PowerShellASP Query String Parameters

I had fun initially with PowerShellASP, but its sealed classes prevented me from doing much useful with it in SharePoint. I really need to take a look at Andre de Cavaignac‘s PowerShellPages project, though the GPL license is a bit restrictive for my taste. Maybe I’ll just build my own…

Anyway, I actually had a practical use for PoShASP today, and in working with it I decided there needed to be a better way to handle QueryString values. The resulting function is fairly straight-forward, and supports typed and optional parameters:

<% QSParam w x,int,10 y,double z,zzz %>
w = <%= $w %>
x = <%= $x %>
y = <%= $y %>
z = <%= $z %>

With no query string, we get the following:

w =
x = 10
y =
z = zzz

However, if I use a query string like w=42&x=oops&y=3.14&z=pi, the valid values fall through:

w = 42
x = 10
y = 3.14
z = pi

Since ‘oops’ isn’t an [int], we get the default. But first…

PowerShell Coalesce

One of the most underused C# operators is the coalesce operator (??), which evaluates to the right-hand value if the left-hand value is null. PowerShell doesn’t include such an operator (to my knowledge), but we can certainly build a function to do the job. I found an implementation contributed anonymously in the comments here:

function Coalesce-Args {
    ([object[]]($args | ?{$_}) + ,$null)[0]
}

Which can be simplified to this:

function Coalesce-Args {
  (@($args | ?{$_}) + $null)[0]
}
Set-Alias ?? Coalesce-Args

The array subexpression @( ... ) always returns an array, to which we append $null in case the array is empty. Taking the first element yields the desired result. I also define an alias (??) for an easily remembered shorthand, though the usage is different from the binary C# operator. With our new function, my original QueryString pattern:

if( !($n = $Request.QueryString["n"] -as [int]) ) { $n = 10 }

Can be rewritten as:

$n = ?? ($Request.QueryString["n"] -as [int]) 10

QSParam Function

Now that we have Coalesce-Args, we can implement QSParam:

function QSParam {
  $QueryString = $Request.QueryString
  $args | ForEach-Object {
    $arg = @($_)
    $varName = $arg[0];
    $varType = $arg[1] -as [type];

    $qsValue = $QueryString[$varName]
    if ($varType -eq $null) {
      $varValue = Coalesce-Args $qsValue $arg[2] $arg[1]
    } else {
      $varValue = Coalesce-Args ($qsValue -as $varType) `
                                ($arg[2] -as $varType)
    }

    Set-Variable $varName $varValue -Scope script
  }
}

If  PowerShell can’t cast the second value as a type, we use it as a default value. If a third value is specified, that takes priority over the second value (which is how you can specify a default value that would otherwise be confused for a type: QSParam rhymesWithSquid,$null,guid). Finally, we assign the result to a script-scoped variable so we don’t have to dot source the function call.

And in case you don’t follow the PowerShell team blog (or missed the post), Channel 9’s Expert-to-Expert with Erik Meijer and Jeffrey Snover is definitely worth watching if you’re at all interested in the language internals and other geeky stuff. Jeffrey’s enthusiasm for the language is infectious.

PowerShellASP Applied: JSON Factory

Now that we can use PowerShellASP with SharePoint, what can we do with it? Well without master page or web part support, we can’t easily integrate PoShASP content directly into the SharePoint experience. Fortunately, we can leverage PowerShell in other ways. An easy example is generating JSON, perhaps from the PowerShell standby Get-Process:

<% $Response.ContentType = "application/json; charset=utf-8" %>
<% $Response.Cache.SetCacheability([System.Web.HttpCacheability]'NoCache') %>
<% $Response.Cache.SetExpires([DateTime]::MinValue) %>
<% if( !($n = $Request.QueryString["n"] -as [int]) ) { $n = 10 } %>
{"processes":[
  <% [string]::Join(",`n  ",
  (get-process | sort ws -desc | select -first $n | foreach {
  "{'ID':$($_.ID),'Name':'$($_.Name)','WS':$($_.ws)}" })) %>
]}

After we set the JSON ContentType and cache policy, we try to fetch an “n” query parameter. If n is missing or not a number, we default to 10. Now we can start building our JSON object. To build our array, we use System.String‘s static Join method (the backtick is PowerShell’s escape character, so `n is a newline). Join‘s string[] parameter is provided by a PowerShell pipeline that fetches our system processes, sorts by working set size, selects the top $n and then iterates through those process objects, returning a string of JSON with our desired properties. Note also that PoShASP seems to require an empty line at the end of the file, otherwise “]}” is ignored. Our output will look something like this:

{"processes":[
  {'ID':1672,'Name':'sqlservr','WS':506028032},
  {'ID':3296,'Name':'devenv','WS':230555648},
  {'ID':4720,'Name':'w3wp','WS':181100544},
  {'ID':376,'Name':'services','WS':121995264},
  {'ID':3372,'Name':'w3wp','WS':102522880}
]}

Let’s save our JSON endpoint as %12%\TEMPLATE\LAYOUTS\Get-Process.json.ps1x, which we can test by visiting http://server/_layouts/Get-Process.json.ps1x?n=5. Now it’s AJAX time! Since not everyone can use the ASP.NET AJAX Extensions, we’ll just do it the old-fashioned way. Starting with a Content Editor Web Part on a page of your choice, set the source to the following:

<div id="d_procs">
<img src="/_layouts/images/GEARS_AN.GIF"
  alt="Loading..." align="center" />
</div>
<script>
function getXmlHttpRequestObject() {
 if (window.XMLHttpRequest) {
  return new XMLHttpRequest();
 } else if(window.ActiveXObject) {
  return new ActiveXObject("Microsoft.XMLHTTP");
 } else {
  document.getElementById('d_procs').innerHTML =
  'Cound not create XmlHttpRequest Object.';
 }
}

var r = getXmlHttpRequestObject();
var c = 0;
var mTimer;

function getProcs() {
 if (r.readyState == 4 || r.readyState == 0) {
  r.open("GET", '/_layouts/Get-Process.json.ps1x?n=5', true);
  r.onreadystatechange = handleReceiveProcs;
  r.send(null);
 }
}

function handleReceiveProcs() {
 if (r.readyState == 4) {
  var d = document.getElementById('d_procs');
  var response = eval("(" + r.responseText + ")");
  var p = response.processes;
  var t = "<table width=\"100%\">";
  t += "<tr><th>ID</th><th>Name</th><th>WS(MB)</th></tr>";
  for(i=0;i < p.length; i++) {
   t += '<tr><td>'+p[i]['ID']+'</td>';
   t += '<td>'+p[i]['Name']+'</td/>';
   t += '<td align=\"right\">';
   t += (p[i]['WS']/(1024*1024.0)).toFixed(2);
   t += '</td/></tr>';
  }
  t += "</table><p>Refresh count: "+(++c)+"</p>";
  d.innerHTML = t;
  mTimer = setTimeout('getProcs();', 3000); // 3-sec refresh
 }
}

_spBodyOnLoadFunctionNames.push('getProcs');
</script>

I haven’t put much effort into cleaning up the code, but it does the job (in FF2 and IE7, at least):

With PowerShell’s ease of development and specialized adapters, this is just the tip of the iceberg. What other real-time data would you find useful?

PowerShellASP with SharePoint: Scripts in Content Database

In my last post, I mentioned that PowerShellASP doesn’t work for files stored in a SharePoint content database. It wasn’t hard to track down why this is the case, so my next step was to attempt a fix.

First, a recap of the relevant code. In PSHandler.ProcessRequest(HttpContext), the entry point for the handler, we have:

    string filename = A_0.Request.MapPath(A_0.Request.FilePath);
    ...
    this.a(filename);

MapPath doesn’t know to do anything special with content files, so it returns a useless path which is then passed to PSHandler.a(String A_0) and used here:

    using (StreamReader reader = new StreamReader(A_0)) {
      ...

Rather than modify the existing handler (much), I propose creating a SharePoint-specific handler that inherits from PSHandler. Before we can do that, we need to refactor the original slightly to facilitate the extension.

The biggest change is extracting the contents of the using(StreamReader) block into a new protected method that accepts a StreamReader:

    using (StreamReader reader = new StreamReader(A_0)) {
      this.a(reader);
    }

We should also change the private HttpContext field to protected, which I will call _a for our example. Now we have everything we need to extend PSHandler:

  public class SPPSHandler : PSHandler, IHttpHandler {
    public new void ProcessRequest(HttpContext context) {
      base._a = context;

      HttpRequest request = context.Request;
      string filePath = request.FilePath;
      string mappedPath = request.MapPath(filePath);
      if (File.Exists(mappedPath))
        using (StreamReader sr = new StreamReader(mappedPath)) {
          base.a(sr);
          return;
        }

      SPContext currentContext = SPContext.Current;
      if (currentContext != null) {
        SPWeb web = currentContext.Web;
        SPFile file = null;

        if (web != null && (file = web.GetFile(filePath)) != null && file.Exists)
          using (StreamReader sr = new StreamReader(file.OpenBinaryStream())) {
            base.a(sr);
            return;
          }
      }

      // Quoth the server...
      context.Response.StatusCode = 404;
    }
  }

A theoretical subclass is great and all, but does it work? Well we can’t change the original assembly, and I don’t feel like messing with reflection, so let’s build a mock PSHandler instead:

  public class PSHandler : IHttpHandler {
    protected HttpContext _a;

    public bool IsReusable {
      get { return true; }
    }

    public void ProcessRequest(HttpContext A_0) {
      this._a = A_0;
      A_0.Response.Write("PSHandler"); // Shouldn't see this
    }

    protected void a(StreamReader reader) {
      TextWriter o = _a.Response.Output;
      o.Write("<html><body><pre>");
      o.Write(SPEncode.HtmlEncodePreserveSpaces(reader.ReadToEnd().ToUpper()));
      o.Write("</pre></body></html>");
    }
  }

After adjusting the feature receiver to reference our new handler, we see that it does indeed behave as expected:
PowerShellASP in SharePoint - Extended Handler
I haven’t tested extensively, but it’s a start. I doubt the PoShASP team would bother with these changes just for me, so if you’re at all interested leave a comment or at least contact them.

PowerShellASP with SharePoint

PowerShellASP was announced earlier this week, and naturally my first thought was “Does it work with SharePoint?” It turns out that it does, but only for paths mapped to the file system (_layouts, _admin, etc). I’m hoping the authors will consider making a SharePoint extension of the handler to support files stored in the content database as well (more on that later). Just think…writing PowerShell in SharePoint Designer! What could be better?!

Solutionizing PoShASP

Of course you could just follow the provided installation instructions by hand, but what if we wanted to use a WSP?

Step 1: Install PowerShell 1.0

PowerShell is included on Windows Server 2008; for other flavors of Windows, download here.

Step 2: Web.Config Changes

PoShASP requires adding an HttpHandler to web.config. The preferred way to do this is through a WebApplication-scoped feature receiver. The code would look something like this:

using System;
using System.Collections.Generic;
using System.Collections.ObjectModel;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Administration;

namespace Solutionizing.PowerShellASP {
  class WebApplicationFeatureReceiver : SPFeatureReceiver {
    private const string MODS_OWNER = "PowerShellASP";
    private const string PS_VERB = "*";
    private const string PS_PATH = "*.ps1x";
    private const string PS_TYPE = "PowerShellToys.PowerShellASP.PSHandler, PowerShellToys.PowerShellASP";
    private const string MOD_PATH  = "configuration/system.web/httpHandlers";
    private const string MOD_NAME  = @"add[@path=""{0}""]";
    private const string MOD_VALUE = @"<add verb=""{0}"" path=""{1}"" type=""{2}""/>";

    private SPWebConfigModification AddHttpHandler(string verb, string path, string type) {
      SPWebConfigModification mod = new SPWebConfigModification(string.Format(MOD_NAME, path), MOD_PATH);
      mod.Value = String.Format(MOD_VALUE, verb, path, type);
      mod.Owner = MODS_OWNER;
      mod.Sequence = 0;
      mod.Type = SPWebConfigModification.SPWebConfigModificationType.EnsureChildNode;
      return mod;
    }

    public override void FeatureActivated(SPFeatureReceiverProperties properties) {
      SPWebApplication webApp = properties.Feature.Parent as SPWebApplication;
      webApp.WebConfigModifications.Add(AddHttpHandler(PS_VERB, PS_PATH, PS_TYPE));
      webApp.Farm.Services.GetValue<SPWebService>().ApplyWebConfigModifications();
    }

    public override void FeatureDeactivating(SPFeatureReceiverProperties properties) {
      SPWebApplication webApp = properties.Feature.Parent as SPWebApplication;
      Collection<SPWebConfigModification> mods = webApp.WebConfigModifications;

      int startCount = mods.Count;
      for (int c = startCount - 1; c >= 0; c--) {
        SPWebConfigModification mod = mods[c];
        if (mod.Owner == MODS_OWNER)
          mods.Remove(mod);
      }

      if (startCount > mods.Count) {
        webApp.Update();
        webApp.Farm.Services.GetValue<SPWebService>().ApplyWebConfigModifications();
      }
    }

    public override void FeatureInstalled(SPFeatureReceiverProperties properties) { }
    public override void FeatureUninstalling(SPFeatureReceiverProperties properties) { }
  }
}

And we need a feature for the receiver. (Download image here.)
PowerShell Logo

<Feature Id="316F5804-C11B-4E4B-9CD3-E6BD6801091A"
         Title="PowerShellASP"
         Description="Installs PowerShellASP - http://www.powershelltoys.com/"
         Scope="WebApplication"
         Version="1.0.0.0"
         ImageUrl="PowerShellASP/PoSh_60x45.jpg"
         ImageUrlAltText="PowerShell"
         ReceiverAssembly="Solutionizing.PowerShellASP, ..."
         ReceiverClass="Solutionizing.PowerShellASP.WebApplicationFeatureReceiver"
         xmlns="http://schemas.microsoft.com/sharepoint/" />

Step 3: Test Script

Before we finish the package, let’s add a sample script in LAYOUTS – test.ps1x:

<html>
<body>
<% $s = new-object Microsoft.SharePoint.SPSite($Request.Url) %>
<% $raw = $Request.RawUrl %>
<% $w = $s.OpenWeb($raw.Substring(0, $raw.IndexOf($Request.Path))) %>
<h1>Hidden Lists in <a href="<%=$w.Url %>"><%=$w.Title %></a></h1>
<table width="100%">
<tr><th>List Title</th><th>Items<tr></th></tr>
<% $w.Lists | ?{$_.Hidden -eq $true} |
   sort @{expression="ItemCount";Ascending=$true},@{expression="Title";Descending=$true} | %{ %>
<tr>
  <td><a href="<%= $w.Url %><%= $_.DefaultViewUrl %>"><%= $_.Title %></a></td>
  <td><%= $_.ItemCount %></td>
</tr>
<tr><td colspan="2"><p style="overflow: auto; height: 8em">
<%= [Microsoft.SharePoint.Utilities.SPEncode]::HtmlEncode($_.PropertiesXml) %>
</p></td></tr>
<% } %>
</table>
<pre>
<% $w %>
<% $s %>
<% $Request %>
</pre>
</body>
</html>

This contrived example fetches the current SPSite and SPWeb and then outputs a table of the hidden lists in the current site with a few properties. It also dumps the default PowerShell view of the current SPWeb, SPSite and HttpRequest objects. It’s not exactly pretty, but it sufficiently demonstrates a few key concepts of PoShASP.

Step 4: Deploy DLL

The final piece is the assembly, which needs to go in the web application’s bin directory. Our solution brings everything together:

<Solution SolutionId="5C594B30-9AE5-4910-8DA2-1D7BA622FACC"
          ResetWebServer="True"
          xmlns="http://schemas.microsoft.com/sharepoint/">
  <FeatureManifests>
    <FeatureManifest Location="PowerShellASP\feature.xml" />
  </FeatureManifests>
  <TemplateFiles>
    <TemplateFile Location="IMAGES\PowerShellASP\PoSh_60x45.jpg" />
    <TemplateFile Location="LAYOUTS\PowerShellASP\test.ps1x" />
  </TemplateFiles>
  <Assemblies>
    <Assembly Location="Solutionizing.PowerShellASP.dll"
              DeploymentTarget="GlobalAssemblyCache" />
    <Assembly Location="PowerShellToys.PowerShellASP.dll"
              DeploymentTarget="WebApplication" />
  </Assemblies>
</Solution>

Step 5: Deploy

Now that our solution is complete, we can install and deploy the WSP. Note that the package contains a resource—the PoShASP DLL—scoped for a web application, so deploy accordingly. Once the solution is deployed, the feature needs to be activated through Central Admin or stsadm (or PowerShell ;). If all goes according to plan, the application’s bin directory will contain PowerShellToys.PowerShellASP.dll and web.config will have an HttpHandler for .ps1x files. Now open your browser to http://yourapp/_layouts/PowerShellASP/test.ps1x and see what we have. You can also try http://yourapp/SubSite/_layouts/PowerShellASP/test.ps1x to see the change in site context. (Screenshot was taken before I rolled test.ps1x into my test solution.)

From Content Database

Earlier I mentioned that the handler doesn’t work for scripts stored in the content database. The easiest way to test this is to upload a .ps1x file to a document library. Attempting to open the file yields a lovely exception. So where is this exceptional path coming from? Well the stack trace gives us a good place to start:

   System.IO.StreamReader..ctor(String path) +112
   PowerShellToys.PowerShellASP.PSHandler.a(String A_0) +75

Cue Reflector. In PSHandler.a(String A_0) we find the following:

    using (StreamReader reader = new StreamReader(A_0)) {
      ...

And A_0 comes from the implementation of IHttpHandler.ProcessRequest(HttpContext):

    string filename = A_0.Request.MapPath(A_0.Request.FilePath);
    ...
    this.a(filename);

Since Docs/Documents/Get-Process.ps1x doesn’t map to anything special like _layouts, IIS just maps it to the local root of the site. We know this won’t work, but how can we let the handler in on our little secret? In my next post I’ll go over some code that could get us to that point.

With or without the content database limitation, how would you use PowerShellASP with SharePoint?