BWren's Management Space

Updated PowerShell Post

2010-02-01T15:38:33Z

I did a post bacin February 2008 on running a PowerShell script from a management pack. This was prior to the native PowerShell modules that came with Operations Manager R2 and that I wrote about on a separate post. The original information is still valid though since it is the method you need to use if you want to run PowerShell scripts in an SP1 environment. Until Operations Manager 2007 SP1 is no longer supported, there will be reasons to keep using this method.

I just had some good feedback sent to me identifying some issues with that original post. Since I understand that people still refer to that information, I went ahead and modified it to include those corrections.

Specifically, the following changes have been made:

Changed the command line with the following:

Set the execution policy
Add the Arguments parameter
Fixed some syntax.
Fixed the incorrect statement that CDATA cannot be used for the command line.

Uses the parameter for IntervalSeconds rather than a fixed value.
Changes the RequiresOutput element to True.

New Blog

2010-01-29T16:45:23Z

Now that I’ve changed positions to own knowledge for management pack authoring, a blog more specific that topic was in order. I’ll be moving activities starting today to http://blogs.technet.com/MPAuthor. Please head over there for announcements on upcoming updates to the MP Authoring Guide and other information regarding MP Authoring.

Not sure if I’ll be updating this blog or not. Any MP authoring information will be going on the new blog. If I have any other topics to talk about, then they’ll go in here. I’ll certainly keep this one intact though since I have several posts that still have some relevant information.

MPAuthor Blog

Management Pack Authoring Guide v2

2010-01-11T08:00:25Z

After 13 years of consulting, I joined the UA team in Redmond last August as a technical writer focusing on management pack authoring. My initial focus is a new version of the Management Pack Authoring Guide which will provide background concepts, processes, and specific walkthrough examples on creating management packs for Operations Manager 2007.

The first section of the new Authoring Guide went live last Friday. This is the section on Service Model which describes classes, relationships, and discoveries. We have already made significant progress on the Composition section which will be the next to be published. This will give details on custom modules and workflows and hopefully make everyone confident to select menu items with the word Custom in the Authoring Console. This will be followed by sections on Health Model and Presentation (which will primarily talk about Views). We are also going to get some good reference information in there to help with forming variables and dealing with different data types.

It’s not common to publish section by section like this. We would typically complete the entire guide before going live. It didn’t seem to make any sense to hold back content that people could use immediately though while other sections were being written. That might have been our only solution back in the days of bound paper manuals, but it certainly doesn’t make any sense in today’s world.

We’re trying to select the order of publication in terms of demand. The most common questions that I get are related to the Service Model – what classes to create for an application, what base classes to use, the difference between a base class and a hosting relationship, when to use a containment relationship, etc, etc. That in addition to the fact that building a model is the first step in building a management pack made it pretty obvious that we needed to get that section published first.

Please share any feedback you have on the guide – whether it be positive, negative, corrections, suggestions, etc. If any of the existing content isn’t clear I want to make sure that we make appropriate modifications. You provide comments on TechNet, on this blog, or by mailing MOM Documentation Feedback.

MP Author Resource Kit

2009-10-22T06:40:00Z

I realize I haven’t posted anything in awhile – mainly due to my recent change of job within Microsoft (more information on that later). I had to get off my lazy butt to write this post though because the MP Author Resource Kit was just released today. I’ve had the opportunity to play with a beta of these tools, and they are absolutely outstanding. Some of the tools might be classified under the “nice to have” category but others absolutely change the entire authoring experience. Oh the time that these could have save me over the past couple of years…..

The rundown of tools in the new resource kit is as follows:

Authoring Console
Not too much has changed from the R2 version other than the new resource kit tools getting integrated into the menus.
MP Best Practices Analyzer
Scans the management pack to identify where it might deviate from best practices. Even allows automatic resolution for some issues. Don’t underestimate the recommendations made by this tool. These are very current best practices that have been identified from experience and lessons learned since Operations Manager 207 was released. Don’t let an MP out the door until it passes this analysis.
MP Spell Checker
Does exactly what the name implies. Cool thing is it allows you to maintain an exclusion list with all those application specific terms you deal with. Nothing like a silly spelling error to make your management pack just look cheesy. No more.
MP Visio Generator
Way cool. This creates two Visio diagrams for your service model. One showing class inheritance – all of the base classes that your classes are inheriting from. The other shows the relationships between all of your classes. This is great for documentation of your MP but also nice for analyzing another management pack that you didn’t write. A nice quick diagram of the service model.
MP Diff
Shows the differences between two different management packs. Useful for people like me who create all kinds of demo and sample MPs and then forget what the differences are.
Cookdown Analyzer
Lack of cookdown in rules and monitors targeted at classes with several instances on an agent is one of the biggest sources of overhead from a management pack. This tool will identify classes with the potential for multiple instances and then run an analysis on workflows targeted at them to determine if cookdown may break.
All References Add-in
Right click on any element in a management pack and get a listing of any other referenced elements. Great for quick sanity checks.
Workflow Analyzer
Finally, a means to debug a running workflow! Connect to an agent, select a workflow and watch the output from each module. This one will be useful to operations people in addition to MP authors.
Workflow Simulator
I saved the best for last. There simply aren’t enough nice things I can say about this one. Right click on a rule, monitor, or discovery and select Simulate. You’ll actually run a copy of that workflow right on your workstation and be able to inspect the output from each module right there your workstation. No need for a connection to a management group. You could do this on an airplane! We can actually create custom workflows and test them with just the Authoring Console before ever installing the MP. Now this changes the whole process and has the potential to save authors tons of time.

Just to show how cool the Workflow Simulator is, let me show a couple of screenshots. This is the StoreApp management pack that I’ve used at a couple of conferences for a sample. This particular monitor runs a script that collects a file count from several folders – simulating queues in the sample application.

All I have to do is right click on the monitor and select Simulate.

Then I get a dialog box showing me all of the overrideable parameters in case I want to change any for this simulation. I also get any target variables that are being passed to the monitor. When actually running, these are values that we would get from the properties of the target object. In the simulation though we have no target object, so I get the opportunity to provide my own values.

When I’m ready, I hit Start Simulation, and the monitor runs - listing each module and it’s output! Have a look at the screenshot below. I have a timestamp next to each module as it is loaded. You can see that the first data source is the scheduler. Once it fires, the script runs outputting three different property bags – one for each folder that my script finds. I then filter that to a single data source matching the particular folder I’m interested in, and then we see each of the expressions for the health states of the monitor. Right next to each module in the Data column, I can see the values in the resulting property bag. If I want to see the actual XML, it’s in the right pane.

For anyone who is used to only being able to test workflows by installing them and then waiting for them to deploy to the agent this is huge. An authoring experience not requiring a connection to a running environment, a quick means of testing workflows, and complete exposure into the execution and resulting data from each module in the workflow. What more could you possibly ask for?

Bottom line – go get the MP Resource Kit now. I’ve only been using it for a couple of weeks, and I already can’t imagine trying to write an MP without it.

Sample Application for SP1

2009-06-05T09:28:00Z

Attached to this post is a version of my sample application for Operations Manager SP1. This has the process monitor removed that relies on the modules in R2.

PowerShell Scripts in a Management Pack Part 2

2009-06-05T08:49:00Z

In a previous blog post, I explained how to run PowerShell scripts from a management pack. I honestly don’t remember why I titled that “Part 1” because I don’t remember what I figured that Part 2 was going to be. Turns out that using the native PowerShell modules in OpsMgr R2 is a perfect topic for Part 2 which I’ll present here (just pretend that I meant that all along).

Prior to R2 we could launch PowerShell scripts from a management pack, but we had to do it by building the command line and launching powershell.exe. This was more complicated, less efficient, and had the disadvantage that the agent didn’t actually know that it was running a script. If that script hit an error, we didn’t know about because the agent simply knew that it successfully launched the executable. Now that we have a native module, this is going to be much more efficient and reliable. I had some disclaimers in that post about overhead from PowerShell that don’t apply with the new modules. Keep in mind that PowerShell still has to be installed on the target agent.

There are some different details to know about using these modules though, and that’s exactly the point of this post. I updated my sample application with PowerShell equivalents of a discovery and a property bag script, so you might want to grab that to have as a reference as you read through the rest of this post.

Scripts

In the last post I mentioned that the scripts don’t really change from their VBScript counterparts. We still create discovery data and property bags using the MOM.ScriptAPI object – we’ll just need to use the New-Object cmdlet in PowerShell instead of the CreateObject method in VBScript. That’s really the only difference when we were calling PowerShell.exe with the Command, but there are some other changes we’re going to need when using the native R2 modules.

Parameters

The first change is how we are going to accept parameters into the script. Note that the term “parameter” is going to get a little tricky here. Modules have parameters, and we can pass parameters to a script. As you’ll see below, the PowerShell modules have a module parameter called Parameter to make things even more confusing. I’ll do my best to keep the wording clear though, and you shouldn’t have too tough of a time sorting all of this out.

I’ll show how to pass the values to the script parameters below, but for now let’s just worry about the script itself. Instead of accessing positional arguments with the $args variable (the equivalent of WScript.Arguments in VBScript) we’re going to use named parameters. We accept these into the script using the param() command at the start of the script specifying the variables that the script is accepting the parameters into.

For example, for the queue statistics script in my sample application, we need to pass in two parameters - $topFolder and $debug. We do that with the following line:

param($topFolder,$debug)

This would allow us to specify named parameters on the command line when executing the script. This would look something like below for the Queue Statistics script.

.\QueueStats.ps1 -topFolder 'C:\StoreQueues' –debug $false

We might type that command line when testing the script, but we won’t be putting it into the management pack – I’ll show how we do that below. Just want to give you a basic idea of how PowerShell works with named parameters if you aren’t already familiar with it.

Returning Data

In VBScript, we return data using the Return method on the MOM.ScriptAPI object if we are returning discovery data or a single property bag. If we are returning multiple property bags, we use ReturnItems(). Those aren’t going to work very well from the R2 PowerShell modules though. Instead, we can simply return the objects themselves from the script. In PowerShell, you do this by typing the name of the variable on a line all by itself.

This is best illustrated by the following examples which show the PowerShell equivalent to a VBScript snippet:

Discovery Data

VBScript PowerShell
Set oAPI = CreateObject("MOM.ScriptAPI") Set oDiscoveryData = oAPI.CreateDiscoveryData() … … oAPI.Return(oDiscoveryData)
$api = New-Object -comObject 'MOM.ScriptAPI' $discoveryData = $api.CreateDiscoveryData() … … $discoveryData
Single Property Bag

VBScript PowerShell
Set oAPI = CreateObject("MOM.ScriptAPI") Set oBag = oAPI.CreatePropertyBag() … … oAPI.Return(oBag)
$api = New-Object -comObject 'MOM.ScriptAPI' $bag = $api.CreatePropertyBag() … … $bag
Multiple Property Bags

VBScript PowerShell
Set oAPI = CreateObject("MOM.ScriptAPI") 
For Each object in collection 
    Set oBag = oAPI.CreatePropertyBag() 
    … 
    … 
Next 
oAPI.ReturnItems()
$api = New-Object -comObject 'MOM.ScriptAPI' 
foreach (object in collection) 
{ 
    $bag = $api.CreatePropertyBag() 
    … 
    … 
    $bag 
}

Note that in the multiple property bag example, we’re simply returning each bag as we create it. That’s not complicated but certainly a different approach than in VBScript where we stack up all of the objects before returning them at once with ReturnItems(). The condition detection or write action that is going to accept the output will work against each property bag returned from the script. The end result is identical to using ReturnItems() in VBScript – just looks a little different in the script.

Consoles

The PowerShell modules will not be accessible in the Operations Console in R2 (no word yet if they will be in future releases). You are still going to be limited to writing scripts with VBScript or JScript if you are living only in that console.

You will be able to use the new modules in the Authoring Console, although wizards aren’t going to be available for them. You aren’t going to be able to simply select New Rule and see something like Timed PowerShell Script. You’re going to have to create custom modules, monitor types, monitors, and rules if you want to use the PowerShell modules. For creating workflows based on scripts this is typically what you want to do anyway to be able to use your script in multiple workflows and to present a nice set of overrideable parameters to the operator. Really shouldn’t be much more complicated than other custom modules that you’ve built.

Modules

Discoveries

There is only a single data source module for executing PowerShell scripts - Microsoft.Windows.TimedPowerShell.DiscoveryProvider. This is the functional equivalent of the timed script discovery provider that you’ve probably used for creating a discovery with VBScript. I’m not going to list out all the parameters for the module since you’ll be familiar with most of them – IntervalSeconds, ScriptName, ScriptBody, etc. The new ones are going to be SnapIns and Parameters which I’ll get to below.

No real trick to using the module other than defining the new parameters. You’ll create a new discovery with that data source, plug in your script, and you’re on your way.

Property Bags

Scripts returning property bags are used for most monitors and rules using scripts. These are going to be trickier than the discovery scripts using R2 because we don’t have a data source module. We do have a probe action though called Microsoft.Windows.PowerShellPropertyBagProbe, so it’s a matter of creating a data source module using it and a System.Scheduler.

In the sample application, I have three data source modules for PowerShell property bag scripts as follows:

Demo.StoreApp.TimedPowerShell.PropertyBagProvider
Demo.StoreApp.TimedPowerShell.EventProvider
Demo.StoreApp.TimedPowerShell.PerformanceProvider

I’m not going to go into the details of each – you can have a look at the them yourself. They are the functional equivalents of the TimedScript modules in the Windows Library management pack. The first returns a property bag while the other two use the first one and then map the property bag output to either an event or perf data.

New Parameters

Parameters Parameter

Yes I know, a parameter called Parameters – sounds a little tricky. Actually pretty straightforward though. We have a module parameter that defines the script parameters that are going to be passed to our PowerShell script. This replaces the Arguments parameter on the VBScript modules and provides a more structured definition of the arguments being passed to the script.

The other thing that’s going to make this a bit tricky is that we’re going to have to directly edit the XML in order to provide the parameters. The structure is pretty simple, but you may not be familiar with launching an external editor from the Authoring Console. I’m not going to go into the details of that here, but I may do another blog post on it. It may seem a bit confusing how to do this and also why you have to.

The structure is pretty simple as you can see from the example below – just a matter of providing a name and value for each parameter. This is for the queue discovery in my sample application.

<Parameters> 
  <Parameter> 
    <Name>sourceID</Name> 
    <Value>$MPElement$</Value> 
  </Parameter> 
  <Parameter> 
    <Name>managedEntityID</Name> 
    <Value>$Target/Id$</Value> 
  </Parameter> 
  <Parameter> 
    <Name>topFolder</Name> 
    <Value>$Target/Property[Type="Demo.StoreApp.ComputerRole.CentralServer"]/QueuePath$</Value> 
  </Parameter> 
  <Parameter> 
    <Name>computerName</Name> 
    <Value>$Target/Host/Property[Type="Windows!Microsoft.Windows.Computer"]/PrincipalName$</Value> 
  </Parameter> 
  <Parameter> 
    <Name>debug</Name> 
    <Value>$true</Value> 
  </Parameter> 
</Parameters>

The first line of the script this module would be calling is the following Param command which collects each of the named parameters.

param($sourceId,$managedEntityId,$topFolder,$computerName,$debug)

Snap Ins Parameter

The other parameter is to define snap ins that your script requires. Your script may not need any in which case you won’t use this parameter. I don’t have in my sample application since those scripts just use the file system. To show an example of the parameter though, consider a script that requires access to Operations Manager data – something you might run from a Management Server. That would require the client snap-in which is called Microsoft.EnterpriseManagement.OperationsManager.Client. To specify this snap-in for your script, you would use the following

<SnapIns>
  <SnapIn>Microsoft.EnterpriseManagement.OperationsManager.Client</SnapIn>
</SnapIns>

Samples

Rather than paste a bunch of XML in here, you can just grab the latest version of the sample application attached to the post. I have a discovery script and property bag script in there that have plenty of comments. I haven’t updated the document yet, but I’ll get to that. I didn’t want to hold off on the post.

Sample Application Dependencies

2009-05-20T08:25:00Z

I’ve had a couple of people tell me that the sample application I used for my MMS presentations won’t load in their environment. That’s because the management pack requires the OpsMgr R2 beta. It won’t load into an SP1 management group. I used a monitor in there from the new process monitoring MP in R2.

I’m about to update the MP with some PowerShell examples. When I do, I’ll strip out the process monitoring in the original version and have a second version that can load into SP1 for those people without access to an R2 environment. Should just be a couple of days before I get that done.

R2 Authoring Console

2009-05-07T19:16:29Z

I’ve been getting this question quite a bit, so I thought I’d give a quick answer to it. The question is whether we can use the R2 Authoring Console to create management packs for SP1. The answer is that you absolutely can – with a minor caveat. There is nothing different about the structure of a management pack for SP1 or R2, and the Authoring Console just creates management packs in XML. There are R2 specific modules, and using those will make your MP unusable in SP1, but you could use those with any version of the Authoring Console or even editing XML directly.

But what about that one caveat? When you create a new management pack in the Authoring Console, it will automatically add references to the library MPs – System.Library, System.Health.Library, Microsoft.Windows.Library, and Microsoft.SystemCenter.Library. The R2 Authoring Console will create those references to the latest versions of those MPs (6.1.7043.0 as of RC version of R2). You probably aren’t going to use any specific features of those new versions, but if you leave those references, your management pack won’t load in a management group with pre-R2 libraries.

To fix this, you should be able to just go to the References tab in Management Pack Properties and change the versions of those references. The Key Token won’t change since the same certificate was used for sealing the different MP versions. For reference, the SP1 libraries are version 6.0.6278.0, and the RTM libraries are version 6.0.5000.0.

Bottom line is definitely use the R2 Authoring Console regardless of which version of OpsMgr you’re working with. Several improvements over the SP1 version including the ability to create elements that we used to have to drop out to XML for.

MMS 2009

2009-04-29T03:44:43Z

A bit wiped out after delivering four consecutive sessions on management pack authoring. I'm impressed with people who made it through the entire five hours. That was definitely not light content. Seems like they were well received though.

The sample management pack that I showed along with a document describing the MP and the sample application that it's based on is on the OpsManJam site. I'm planning on continuously updating this MP as l create other example scenarios. I thought that would be more interesting than continuing to do random examples, and l can keep them all packaged up in one clean MP. I'm also getting tired of all the random little XML files l have cluttering up my MP library.

I'm getting mocked quite a bit at the conference about my lack of blog updates. Now that I've gotten through these presentations as well as some other training l was working on, l should be able to get to that.

SNMP Queries

2009-01-21T19:22:35Z

I recently help someone out getting a monitor working that uses the System.SnmpQueryProvider module in the System.Snmp.Library management pack to perform a query against an SNMP device. They were getting back an error message showing some cryptic characters in the community string. They were just providing simple text like "public" for the CommunityString parameter on the module, so this looked pretty strange.

After some research, it turns out that module wants the community string specified in Base64 format. Nothing special from the MP perspective – you just need to specify the Base64 equivalent of your community string in the CommunityString parameter rather than the simple text.

If you already have a means of converting a string to Base64, then you should be fine. If not, here’s bit of PowerShell that will do the conversion for you.

$communityString = 'public'
[System.Convert]::ToBase64String([System.Text.Encoding]::UNICODE.GetBytes($communityString))

If I run that code, I get the following value: cAB1AGIAbABpAGMA. Pasting that into the CommunityString parameter on the module should get you the results you want. Obviously, if you have a community name different than "public" you would paste that in and use the resulting converted value.

Discovery Data
VBScript	PowerShell
Set oAPI = CreateObject("MOM.ScriptAPI") Set oDiscoveryData = oAPI.CreateDiscoveryData() … … oAPI.Return(oDiscoveryData)	$api = New-Object -comObject 'MOM.ScriptAPI' $discoveryData = $api.CreateDiscoveryData() … … $discoveryData

Single Property Bag
VBScript	PowerShell
Set oAPI = CreateObject("MOM.ScriptAPI") Set oBag = oAPI.CreatePropertyBag() … … oAPI.Return(oBag)	$api = New-Object -comObject 'MOM.ScriptAPI' $bag = $api.CreatePropertyBag() … … $bag

Multiple Property Bags
VBScript	PowerShell
Set oAPI = CreateObject("MOM.ScriptAPI") For Each object in collection Set oBag = oAPI.CreatePropertyBag() … … Next oAPI.ReturnItems()	$api = New-Object -comObject 'MOM.ScriptAPI' foreach (object in collection) { $bag = $api.CreatePropertyBag() … … $bag }