The post suggests that this doesn’t work:

SPSite siteCollection = new SPSite("http://MOSSServer/");
SPWebApplication webApp = siteCollection.WebApplication;
// ...
webApp.WebConfigModifications.Add(modification);
webApp.Farm.Services.GetValue<SPWebService>().ApplyWebConfigModifications();

But this does:

SPWebService.ContentService.WebConfigModifications.Add(modification);
SPWebService.ContentService.Update();
SPWebService.ContentService.ApplyWebConfigModifications();

Drawing this final conclusion:

Instead of adding modifications to WebConfigModifcations of SPWebApplication object, we are using SPWebService.ContentService to call ADD and UPDATE methods. Whenever required, it is always advised to use SPWebService.ContentService to make the modifications rather than accessing Farm instance through SPWebApplication.

The suggestion is that there’s a problem with applying the changes through webApp.Farm. But that Farm is just SPFarm.Local:

public SPSite(string requestUrl) : this(SPFarm.Local, new Uri(requestUrl), false, SPSecurity.UserToken)
{
}

So the last line is essentially equivalent to this:

SPFarm.Local.Services.GetValue<SPWebService>()

Taking a peek at ContentService, we find this definition:

public static SPWebService get_ContentService
{
    if (SPFarm.Local != null)
    {
        return SPFarm.Local.Services.GetValue<SPWebService>();
    }
    return null;
}

The modified sample isn’t actually doing anything different to apply the changes! So the problem is either in how SharePoint handles Web Application-scoped web config changes, or that the changes aren’t being applied correctly. The latter is much more likely than the former, and indeed the solution is actually quite simple: just look for the only other significant difference between the code samples.

webApp.WebConfigModifications.Add(modification);
webApp.Update(); // Oops!
webApp.Farm.Services.GetValue<SPWebService>().ApplyWebConfigModifications();

A quick PowerShell session or console app would have verified that the config changes weren’t being saved to the database.

So what have we learned?

1. Always call Update() after making changes to an SPPersistedObject (like SPWebApplication or SPWebService).
2. SPWebService.ContentService is a shortcut for SPFarm.Local.Services.GetValue<SPWebService>.
3. Check your code carefully before blaming the SharePoint API!

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.)

<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?