Server 2008 and PowerShell published via OData

Repost from here

 

There is a new feature of Windows Server 8 that will allow for access to PowerShell cmdlets and objects via OData served through ASP.NET. Doug Finke wrote a blog post for PowerShell Magazine on the topic. The article gives a good overview of what the Management OData feature is and how to configure it. In this blog post I will be showing off some of the steps involved in getting the service configured and what it looks like to consume the OData in PowerShell.

Setting Up the Management OData Feature

The first step in utilizing the Management OData in Windows Server 2012 is to enable the feature. You can either use Server Manager or the following cmdlet.

Install-WindowsFeature -Name ManagementOData

Once the feature has been installed you will need to install Visual Studio 2011 Beta on the Server machine. I hope there is better tooling around this but currently this is what is required in order to build the samples found on MSDN. Make sure to download the Management OData Schema Designer. For a whole lot information on the topic, download and read the whitepaper. It walks you through all the steps I’m about to, in more detail.

What Management OData Does

In simple terms (read Doug’s post for more info), the Management OData service provides RESTful endpoints that server up PowerShell objects. The schema designer is used to map cmdlets and their resulting objects to OData objects. These can then be served as JSON back through the endpoint to the client.  The Management OData Schema Designer is used to take existing modules, cmdlets and objects and map them to XML files that can then be consumed by the Management OData system and served to clients. Included with the examples are PowerShell scripts used to install the OData endpoints once they have been compiled.

Installing the Basic Endpoint Sample

Once Visual Studio 2011 has been installed open the BasicPlugin.sln solution. You can download the sample here. Once the solution is open, build it. Once the solution is built, run the SetupEndpoints.ps1 file to configure the endpoint on the local server. The file is part of the Basic Endpoint solution folder. You should now be able to navigate to the URL:

http://localhost:7000/MODataSvc/Microsoft.Management.Odata.svc

This should result in this:

root

 

To query particular resources, you can now query it like so http://localhost:7000/MODataSvc/Microsoft.Management.Odata.svc/Process. This will return all the processes on the server machine. The Content property contains all the XML for the objects.

process

Additionally, processes can be filtered using a URI-based syntax. For example:

http://localhost:7000/MODataSvc/Microsoft.Management.Odata.svc/Process?$filter=(Handles gt 1000)

By default the returned format will be XML. In order to return JSON, you have to use the following syntax.

http://localhost:7000/MODataSvc/Microsoft.Management.Odata.svc/Process?$format=JSON

json

Remember that you can utilize the new ConvertFrom-Json cmdlet to to convert the JSON to objects.

results

Pretty powerful stuff!

Adding new Cmdlets and Objects

The Management OData Schema Designer is used to add more entities to the OData service. Once installed there should be an icon placed on the desktop. Open the designer. The first step is to load a module that you want to model and expose in OData. For this example I will use the NetAdapter module. Type the module name into the text box and click Load New Module. Once the module is loaded you will see a big list of the types of entities the designer finds within the module. These coincide with the nouns of the cmdlets within the module. The verbs Get, Set, New, Remove will appear as check boxes next to the noun names. If a cmdlet is not defined the verb will be grayed out.

In order to map a new OData action and entity, check one of the verb for a noun. I selected the Get and NetAdapter verb and noun. Next click the “from cmdlet output” button. The cmdlet will appear in the displayed box. Clicking Add-Type will add the new OData entity. In order to successfully generate the MOF and XML needed to define the object, you will need to set a Key property. This is the uniquely defining property on the object. Name is already selected for NetAdapter.

designer

Now you can click Generate Mof/Xml Schema. This will produce the mapping files that the Management OData service will use to translate between the REST request and the PowerShell cmdlet and resulting objects. Once saved, you can place this in C:inetpubwwwrootmodata.

Since the OData endpoint is constrained we need to play with the BasicPlugin a bit to get it to load the module we would like. In Visual Studio, I added the following lines to get the NetAdapter module to load into the runspace and to set the visibility of the proper cmdlets in the runspace. I just set them all to visible. Once built, copy the resulting DLL into the MOData folder and replace the one that is in there already. You may need to stop IIS first.

vs2011

Now you should be able to query to the location:

http://localhost:7000/MODataSvc/Microsoft.Management.Odata.svc/NetAdapter

Note that the resource identifier (e.g. NetAdapter) is case sensitive in the beta!

Remember there is also an Invoke-RestMethod cmdlet that can be used to query the entities. Using this method, it looks something like this.

results

I think this is insanely powerful functionality. It seems that the tooling isn’t quite 100% yet and requires quite a bit of setup to get running but the possibilities are endless. Creating RESTful services from PowerShell modules will be a cinch! I really encourage you to read the whitepaper about this that I mentioned earlier. It contains a ton of information.