But I found this task to be surprisingly challenging.  (Maybe it's just because I don't work with PowerShell as much as I should?) The hard part was to capture both output streams from the launched application. It's pretty easy to capture stdout using any one of several ways to launch stuff in PowerShell.  With some additional effort, it's also not that hard to capture stderr. But the hard part was to capture both. To do this you need to 'resort' to using the .net diagnostics library, and even then the approach seemed to be prone to hangs.

The problem is that you need to read from both streams at the same time. Even though there are lots of code samples out there showing calls to ReadToEnd on the standard streams, my experience is that one or the other call will hang forever waiting for input that never comes.

In the past, I've solved this problem in .Net using helper threads to read the streams while the main thread waits on the helper threads and the launched process to finish.  Unfortunately, it appears that creating multi-threaded apps in PowerShell is not supported.

Or is it? After some more digging I found a simple way to combine my old .Net threaded approach to capturing those streams with the new and modern PowerShell world.

The solution uses the very nifty PowerShell cmdlet call Add-Type. This cmdlet lets me create a Frankenstein like solution that incorporates a fragment of C# code that handles the running of the command and that captures of the output streams using some simple background threads. Once I have that output captured, I can log it to my heart's content.

The PowerShell script has the following components:

• Source code for a C# class in a string literal assigned to a variable.
• The C# class has one method. Call this method to launch a process. That method wraps the use of background threads to capture the output streams from the process.
• Use the Add-Type cmdlet to 'hydrate' that code into a class that can be instantiated in the script.
• Use New-Object to instantiate an object of this new class.
• Call a method on the new object to launch the process. When the method returns, you can harvest the captured output streams from properties of the object, and do what you want with them.

You can download the script from here:  https://blogs.msdn.com/cfs-file.ashx/__key/CommunityServer-Blogs-Components-WeblogFiles/00-00-01-03-40-PowerShell+with+C_2300_/3666.RunCommand-PowerShell.zip

Here is the source code. It shows how to launch two programs.  Hopefully you can imagine how this can be applied in your scripts to run commands and to get at all those exciting output streams.

#A powershell script that shows how to:

# - use Add-Type to define and use a class define in c#

# - launch a program from Powershell and capture both stdout and stderr





# Place C# definition of a class into a local string variable.

# This class provide one method that can be used to launch a process and waits for it to complete.

# The output streams stdout and stderr from the process are captured and made available via properties of the class.

#

$source = @"    

using System;

using System.IO;

using System.Threading;

using System.Diagnostics;



    public class RunCommand

    {

        private class AllAboutIO

        {

            public AllAboutIO(StreamReader reader)

            {

                this.reader = reader;

            }



            public string result;

            public StreamReader reader;

        }



        public string stdout;

        public string stderr;



        public void AsyncStreamReader(object data)

        {

            AllAboutIO myData = (AllAboutIO)data;

            myData.result = myData.reader.ReadToEnd();

        }



        public int Run(string Program, string Arguments)

        {       

            Process myProc = new Process();



            myProc.StartInfo.UseShellExecute = false;

            myProc.StartInfo.FileName = Program;

            myProc.StartInfo.Arguments = Arguments;

            myProc.StartInfo.CreateNoWindow = true;

            myProc.StartInfo.RedirectStandardError = true;

            myProc.StartInfo.RedirectStandardOutput = true;



            try

            {

                if (myProc.Start())

                {

                    AllAboutIO stdoutReader = new AllAboutIO(myProc.StandardOutput);

                    AllAboutIO stderrReader = new AllAboutIO(myProc.StandardError);



                    Thread readStdOutThread = new Thread(this.AsyncStreamReader);

                    Thread readStdErrThread = new Thread(this.AsyncStreamReader);



                    readStdOutThread.Start(stdoutReader);

                    readStdErrThread.Start(stderrReader);



                    myProc.WaitForExit();



                    readStdErrThread.Join();

                    readStdOutThread.Join();



                    stdout = stdoutReader.result;

                    stderr = stderrReader.result;



                    return myProc.ExitCode;

                }

                else

                {

                    stderr = "Process did not start. Verify that the program exists at the specified location.";

                    return 1;

                }

            }

            catch (System.Exception excp)

            {

                stderr = "Failed to launch the process: " + excp.Message;

                return 1;

            }

        }

    }

"@



# Create a type from the C#.

Add-Type -TypeDefinition $source -ReferencedAssemblies ("System.Core")



# Helper function for launching a a program.

function Start-Proc  {   

    param (   

    $exe,   

    $arguments,

    [ref]$stdout,

    [ref]$stderr

     ) 



    $runCommand = New-Object RunCommand

    

    $runCommandResult = $runCommand.Run($exe, $arguments)

    

    $stdout.value = $runCommand.stdOut

    $stderr.value = $runCommand.stdErr

     

    return $runCommandResult       

 }

 



$stderr = ""

$stdout = ""



 

#A test of running a program that shows capture of stderr

$exitcode = Start-Proc ($env:windir + "\system32\net.exe") "/notacommand" ([ref]$stdout) ([ref]$stderr)

write-host "Exit code was: " $exitcode

write-host -ForegroundColor Green $stdout

write-host -ForegroundColor Red $stderr



#A test of running a command that shows capture of stdout

$exitcode = Start-Proc ($env:windir + "\system32\net.exe") "help" ([ref]$stdout) ([ref]$stderr)

write-host "Exit code was: " $exitcode

write-host -ForegroundColor Green $stdout

write-host -ForegroundColor Red $stderr

After seeing this you might think: Gosh that's a lot of work for just capturing some output from a command. It is. But it does illustrates some interesting capabilities of PowerShell. Thanks for reading.

Here are a few scenarios where this tool might be useful:

• You would like to understand in detail the configuration options for a vendor supplied management. Since the overrideable parameters are the primary means for configuring a management pack, this information can provide useful insights into how to tune a management pack for a specific environment.
• You want to provide detailed documentation for a custom developed management pack to your customer. The output of this tool can be easily incorporated into the documentation you provide with your management pack.
• You are looking for sample code that shows how to access management pack objects.

This tool requires a connection to the Management Group where the management pack is imported.

The tool is a simple command line program. It takes three arguments. The first specifies the management server (use "localhost" if running the command on the server). The second is the management pack name, and the third is the output file name.

For example:

GetOverrideableParameters.exe localhost Microsoft.SQLServer.2000.Monitoring c:\SqlMonitoringParamerts.html

Download the tool and the Visual Studio project from the links provided at the end of this article.

Implementation Details

The program is written in C# and was developed using Visual Studio 2010. It has been successfully used in a System Center Operations Manager R2 deployment.

The program references SCOM .Net assemblies Microsoft.EnterpriseManagement.OperationsManager and Microsoft.EnterpriseManagement.OperationsManager.Common. It should run on computers where the Operations Console has been installed.

The generated HTML is very basic and should be easy to enhance either through extension of the program or via direct editing in an HTML editor. The generated HTML consists of a table of parameters.  It is also straight forward to copy / paste this HTML from the browser into a Word document for more extensive formatting.

The program flow is as follows:

• - Connect to the management group
• - Get the Management Pack object
• - Emit the HTML header info
• - Loop through all Discoveries in the management pack and emit the overrideable parameters for each.
• - Loop through all Rules in the management pack and emit the overrideable parameters for each.
• - Loop through all UnitMonitors in the management pack and emit the overrideable parameters for each.
• - Emit the closing tags for the HTML
• - Close the output file

Note that the reason this program must connect to the Management Group is because the resolution of datasource information requires access to management packs referenced by the specified management pack.

Also note that the "Value" column displayws in the output file shows the parameter value as configured in the Management Pack. It does not reflect any overrides that may be in effect.

You can download a zip file containing the executable for the program from here: https://blogs.msdn.com/cfs-file.ashx/__key/CommunityServer-Blogs-Components-WeblogFiles/00-00-01-03-40-SCOM+Overrideable+Parameters/8345.GetOverrideableParametersExecutable.zip

You can download a zip file containing the Visual Studio project from here: https://blogs.msdn.com/cfs-file.ashx/__key/CommunityServer-Blogs-Components-WeblogFiles/00-00-01-03-40-SCOM+Overrideable+Parameters/1004.GetOverrideableParametersProject.zip

You can download a sample of the program output here: https://blogs.msdn.com/cfs-file.ashx/__key/CommunityServer-Blogs-Components-WeblogFiles/00-00-01-03-40-SCOM+Overrideable+Parameters/6675.sample.html

Here is a listing of the main program:

using System;

using System.Text;

using System.Collections.Generic;

using Microsoft.EnterpriseManagement;

using Microsoft.EnterpriseManagement.Common;

using Microsoft.EnterpriseManagement.Administration;

using Microsoft.EnterpriseManagement.Configuration;

using System.Collections.ObjectModel;

using System.IO;

using System.Xml;

namespace GetOverrideableParameters

{

    class Program

    {

        static void Main(string[] args)

        {

            if (args.GetLength(0) != 3)

            {

                Console.WriteLine("Error: Unexpected commandline argument count. Usage: GetOverrideableParameters <Management Group server name> <MP name> <outputfile>");

                System.Environment.Exit(1);

            }

            ManagementPack mp = null;

            ManagementGroup mg = null;

            try

            {

                mg = new ManagementGroup(args[0]);

            }

            catch (System.Exception excp)

            {

                Console.WriteLine("Error: Could not connect to management group: {0}", excp.Message);

                System.Environment.Exit(1);

            }

            try

            {

                mp = mg.GetManagementPacks(args[1])[0];

            }

            catch (System.Exception excp)

            {

                Console.WriteLine("Error: Could not get management pack: {0}", excp.Message);

                System.Environment.Exit(1);

            }

            ManagementPackElementCollection<ManagementPackRule> rules = mp.GetRules();

            ManagementPackElementCollection<ManagementPackMonitor> monitors = mp.GetMonitors();

            ManagementPackElementCollection<ManagementPackDiscovery> discoveries = mp.GetDiscoveries();

            StreamWriter writer = null;

            try

            {

                writer = new StreamWriter(args[2]);

            }

            catch (System.Exception excp)

            {

                Console.WriteLine("Error: Could not create output file: {0}", excp.Message);

                System.Environment.Exit(1);

            }

            // Output preamble for HTML document

            writer.WriteLine("<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\">");

            writer.WriteLine("<html xmlns=\"https://www.w3.org/1999/xhtml\" >");

            writer.WriteLine("<head>");

            writer.WriteLine("<title>Untitled Page</title>");

            writer.WriteLine("</head>");

            writer.WriteLine("<body>");

            writer.WriteLine("<h1>{0} Overrideable Parameters</h1>", mp.DisplayName == null ? mp.Name : mp.DisplayName);

            // Start the table and emit a header line

            writer.WriteLine("<table style=\"width: 100%;\" border=\"2\" >");

            writer.WriteLine("<tr><td>Monitoring Object</td><td>Parameter</td><td>Description</td><td>Value</td></tr>");

            foreach (ManagementPackDiscovery discovery in discoveries)

            {

                ManagementPackDataSourceModuleType datasourceType = (ManagementPackDataSourceModuleType)mg.GetMonitoringModuleType(discovery.DataSource.TypeID.Id);

                EmitOverrideableParameters(discovery.DisplayName != null ? discovery.DisplayName : discovery.Name, writer, discovery.DataSource.Configuration, datasourceType.OverrideableParameterCollection);

            }

            foreach (ManagementPackRule rule in rules)

            {

                string ruleName = rule.DisplayName != null ? rule.DisplayName : rule.Name;

                foreach (ManagementPackDataSourceModule datasource in rule.DataSourceCollection)

                {

                    ManagementPackDataSourceModuleType datasourceType = (ManagementPackDataSourceModuleType)mg.GetMonitoringModuleType(datasource.TypeID.Id);

                    EmitOverrideableParameters(ruleName, writer, datasource.Configuration, datasourceType.OverrideableParameterCollection);

                    ruleName = ""; // We only want the name to display on the first row emitted for this rule.

                }

            }

            foreach (ManagementPackMonitor monitor in monitors)

            {

                if (monitor is ManagementPackUnitMonitor)

                {

                    ManagementPackUnitMonitor unitMonitor = (ManagementPackUnitMonitor)monitor;

                    UnitMonitorType unitMonitorType = mg.GetUnitMonitorType(unitMonitor.TypeID.Id);

                    EmitOverrideableParameters(unitMonitor.DisplayName != null ? unitMonitor.DisplayName : unitMonitor.Name, writer, unitMonitor.Configuration, unitMonitorType.OverrideableParameterCollection);

                }

            }

            writer.WriteLine("</table>");

            writer.Close();

            Console.WriteLine("All done!");

        }

        /// <summary>

        /// Emit the HTML for a collection of overrideable parameters.

        /// </summary>

        /// <param name="Named"></param>

        /// <param name="Name"></param>

        /// <param name="writer"></param>

        /// <param name="Configuration"></param>

        /// <param name="OverrideableParameterCollection"></param>

        private static void EmitOverrideableParameters(string Name, StreamWriter writer, string Configuration, ManagementPackSubElementCollection<ManagementPackOverrideableParameter> OverrideableParameterCollection)

        {

            // Load the config section into an XML document for use in looking up actual values.

            XmlDocument xmlConfig = new XmlDocument();

            xmlConfig.LoadXml("<root>" + Configuration + "</root>");

            bool firstRow = true;

            foreach (ManagementPackOverrideableParameter op in OverrideableParameterCollection)

            {

                writer.WriteLine("<tr>");

                // rule name

                writer.Write("<td>");

                if (firstRow)

                {

                    // Display object name only on the first row for this object.

                    writer.Write(Name);

                    firstRow = false;

                }

                writer.WriteLine("</td>");

                // Parameter name

                writer.Write("<td>");

                if (op.DisplayName == null)

                    writer.Write(string.Format("{0}", op.Name));

                else

                    writer.Write(string.Format("{0}", op.DisplayName));

                writer.WriteLine("</td>");

                // Parameter description

                writer.Write("<td>");

                if (op.Description == null)

                    writer.Write(string.Format(""));

                else

                    writer.Write(string.Format("{0}", op.Description));

                writer.WriteLine("</td>");

                // Get the parameter Value. This gets the value from the configuration in the MP. It does not take into account overrides.

                writer.Write("<td>");

                XmlNodeList nodes = xmlConfig.GetElementsByTagName(op.Name);

                if (nodes.Count > 0)

                    writer.Write(XMLEncode(nodes[0].InnerXml));

                writer.WriteLine("</td>");

                writer.WriteLine("</tr>");

            }

        }

        /// <summary>

        /// Helper function for encoding strings to be embedded in XML

        /// </summary>

        /// <param name="Value"></param>

        /// <returns></returns>

        private static string XMLEncode(string Value)

        {

            return Value.Replace("&", "&amp;").Replace("'", "&apos;").Replace("\"", "&quot;").Replace("<", "&lt;").Replace(">", "&gt;");

        }

    }

}

Have you ever been working on a Management Pack and wanted to have an application SME review all the knowledge articles in your new MP? Or maybe you would like to learn more about the internals of a vendor supplied MP by reading the Knowledge Articles they have included in the MP? Having a tool that would dump all the Knowledge Articles into a basic HTML document would make these scenarios simpler.

There's probably a tool like this out there somewhere already, but I have been unable to find it.  So I endeavored to build one. Links to the Visual Studio project and the compiled program are included at the end of the article.

The tool is a simple command line program.  It takes two arguments. The first specifies the input management pack file (either .xml or .mp format). The second is the output file name. The output will be a text file containing the HTML for the extracted Knowledge Articles.

For example:

GetKnowledge.exe Microsoft.SQLServer.2000.Monitoring.mp c:\SqlMpKnowledge.html

Implementation Details

The program is written in C# and was developed using Visual Studio 2010.

As you probably know, using the SCOM SDK, it's easy to extract the MAML for MP Knowledge Articles.  You might even have seen the sample code in the reference page for ManagementPackKnowledgeArticle.MamlContent property. It shows how to access the property, but right where the XSLT transform should be there's a mysterious comment: "Get the MAML content. You must write an XSLT to transform the MAML to HTML." Then you hunt for an XSLT transform, and find none.  My mission here is to fill that void by providing a simple tool based on this sample code that includes an actual working XSLT transform for MAML to HTLM.

The XSLT transform I created is quite basic and is not guaranteed to process all known MAML. In fact, it only processes the MAML fragments that I have found in actual management pack Knowledge Articles.  Over time, you should expect to have to evolve this transform, but for now it seems to work on all of the Microsoft provided Management Packs that I have tried it on.

The program extracts all Knowledge articles for rules and monitors in the specified Management Pack file, and outputs them as an HTML document.  It should be pretty easy to extend the program to output Knowledge Articles for other MP elements, but at the time I wrote the program, I was only interested in Rules and Monitors.

The generated HTML is very basic and should be easy to enhance either through extension of the program or via direct editing in an HTML editor. It is also straight forward to copy / paste from the browser into a Word document for more extensive formatting.

The XSLT transform code is embedded as a resource in the .Net program (and I've included it in the text of this article).

The program references SCOM .Net assemblies Microsoft.EnterpriseManagement.OperationsManager and Microsoft.EnterpriseManagement.OperationsManager.Common. It should run on computers where the Operations Console or the Authoring Console are been installed.

Here is the XSLT Transform:

<?xml version="1.0" encoding="utf-8"?>

 <xsl:stylesheet version="1.0" xmlns:xsl="https://www.w3.org/1999/XSL/Transform"

                           xmlns:msxsl="urn:schemas-microsoft-com:xslt"

                           xmlns:maml="https://schemas.microsoft.com/maml/2004/10"

                           exclude-result-prefixes="msxsl maml">

       <xsl:output method="html" indent="no"/>

        <xsl:template match="/root">

              <xsl:apply-templates />

       </xsl:template>

        <xsl:template match="maml:section">

              <xsl:apply-templates />

       </xsl:template>

        <xsl:template match="maml:navigationLink">

              <a>

                     <xsl:attribute name="href">

                           <xsl:value-of select="maml:uri/@href" />

                     </xsl:attribute>

                     <xsl:value-of select="maml:linkText"/>

              </a>

       </xsl:template>

       <xsl:template match="maml:listItem">

              <li>

                     <xsl:apply-templates />

              </li>

       </xsl:template>

       <xsl:template match="maml:list">

              <ul>

                     <xsl:apply-templates />

              </ul>

       </xsl:template>

       <xsl:template match="maml:title">

              <h2>

                     <xsl:value-of select="."/>

              </h2>

       </xsl:template>

       <xsl:template match="text()">

              <xsl:value-of select="."/>

       </xsl:template>

       <xsl:template match="maml:para">

              <p>

                     <xsl:apply-templates />

              </p>

       </xsl:template>

       <xsl:template match="maml:ui">

              <xsl:choose>

                     <xsl:when test="normalize-space(.)">

                           <span style="text-decoration:underline">

                                  <xsl:apply-templates />

                           </span>

                     </xsl:when>

                     <xsl:otherwise>

                     </xsl:otherwise>

              </xsl:choose>

       </xsl:template>

       <xsl:template match="maml:entry">

              <td>

                     <xsl:apply-templates />

              </td>

       </xsl:template>

       <xsl:template match="maml:row">

              <tr>

                     <xsl:apply-templates />

              </tr>

       </xsl:template>

       <xsl:template match="maml:table">

              <table  border="1">

                     <xsl:apply-templates />

              </table>

       </xsl:template>

</xsl:stylesheet>

Here is the c# code:

using System;

using System.Text;

using System.Collections.Generic;

using Microsoft.EnterpriseManagement;

using Microsoft.EnterpriseManagement.Common;

using Microsoft.EnterpriseManagement.Administration;

using Microsoft.EnterpriseManagement.Configuration;

using System.Collections.ObjectModel;

using System.IO;

using System.Xml;

using System.Xml.Xsl;

using System.Reflection;

namespace GetKnowledge

{

    class Program

    {

        static void TransformMamlFragmentToHtml(string mamlContent, StreamWriter writer)

        {

            // The maml from OpsMgr has no root node, so one must be added or else the xml is not valid.

            mamlContent = "<root>" + mamlContent + "</root>";

            // Wrap the maml string in a reader that is usable by the transform

            using (XmlReader doc = XmlReader.Create(new System.IO.StringReader(mamlContent)))

            {

                // Get the transfrom from a string resource in this assembly

                using (System.IO.Stream s = Assembly.GetExecutingAssembly().GetManifestResourceStream("GetKnowledge.KATransform.xslt"))

                {

                    using (System.Xml.XmlTextReader xsltReader = new System.Xml.XmlTextReader(s))

                    {

                        // Load the transform

                        XslCompiledTransform xslt = new XslCompiledTransform();

                        xslt.Load(xsltReader);

                        // Setup for writing the results

                        XmlWriterSettings settings = new XmlWriterSettings();

                        settings.ConformanceLevel = ConformanceLevel.Fragment;

                        // Do the transform

                        xslt.Transform(doc, XmlWriter.Create(writer, settings));

                    }

                }

            }

        }

        static void Main(string[] args)

        {

            if (args.GetLength(0) != 2)

            {

                Console.WriteLine("Error: unexpected commandline argument count. Usage: GetKnowledge <mp file> <outputfile>");

                System.Environment.Exit(1);

            }

            ManagementPack mp = null;

            try

            {

                // Load the MP from the file specified in the argument list.

                mp = new ManagementPack(args[0]);

            }

            catch (System.Exception excp)

            {

                Console.WriteLine("Error: Could not load the management pack: {0}", excp.Message);

                System.Environment.Exit(1);

            }

            // A hint of code that could be used to load the MP from management group instead of from the file

            //ManagementGroup mg = new ManagementGroup("localhost");

            //ManagementPack mp = mg.GetManagementPacks(args[0])[0];

            ManagementPackElementCollection<ManagementPackRule> rules;

            ManagementPackElementCollection<ManagementPackMonitor> monitors;

            rules = mp.GetRules();

            monitors = mp.GetMonitors();

            StreamWriter writer = null;

            try

            {

                writer = new StreamWriter(args[1]);

            }

            catch (System.Exception excp)

            {

                Console.WriteLine("Error: Could not create output file: {0}", excp.Message);

                System.Environment.Exit(1);

            }

            // Write out the HTML page header section

            writer.WriteLine("<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\">");

            writer.WriteLine("<html xmlns=\"https://www.w3.org/1999/xhtml\" >");

            writer.WriteLine("<head>");

            writer.WriteLine("<title>Untitled Page</title>");

            writer.WriteLine("</head>");

            writer.WriteLine("<body>");

            // Output Knowledge article for all rules

            foreach (ManagementPackRule rule in rules)

            {

                ManagementPackKnowledgeArticle article;

                try

                {

                    article = rule.GetKnowledgeArticle(System.Globalization.CultureInfo.CurrentCulture);

                }

                catch (Microsoft.EnterpriseManagement.Common.ObjectNotFoundException error)

                {

                    //There is no knowledge article for this rule.

                    continue;

                }

                if (article != null)

                {

                    if (article.HtmlContent != null)

                    {

                        //Get the HTML content.

                    }

                    else if (article.MamlContent != null)

                    {

                        writer.WriteLine("<h1>Rule: {0}</h1>", rule.DisplayName);

                        TransformMamlFragmentToHtml(article.MamlContent, writer);

                    }

                }

            }

            // Output knowledge article for all monitors

            foreach (ManagementPackMonitor monitor in monitors)

            {

                ManagementPackKnowledgeArticle article;

                try

                {

                    article = monitor.GetKnowledgeArticle(System.Globalization.CultureInfo.CurrentCulture);

                }

                catch (Microsoft.EnterpriseManagement.Common.ObjectNotFoundException error)

                {

                    //There is no knowledge article for this monitor.

                    continue;

                }

                if (article != null)

                {

                    if (article.HtmlContent != null)

                    {

                        //Get the HTML content.

                    }

                    else if (article.MamlContent != null)

                    {

                        writer.WriteLine("<h1>Monitor: {0}</h1>", monitor.DisplayName);

                        TransformMamlFragmentToHtml(article.MamlContent, writer);

                    }

                }

            }

            writer.WriteLine("</body>");

            writer.WriteLine("</html>");

            writer.Close();

            Console.WriteLine("All done!");

        }

    }

}

A zip file containing the Visual Studio 2010 project can be downloaded from here: https://blogs.msdn.com/cfs-file.ashx/__key/CommunityServer-Blogs-Components-WeblogFiles/00-00-01-03-40-SCOM+Knowledge+Extraction/7624.GetKnowledgeProject.zip

A zip file containing the program executable can be downloaded from here:
https://blogs.msdn.com/cfs-file.ashx/__key/CommunityServer-Blogs-Components-WeblogFiles/00-00-01-03-40-SCOM+Knowledge+Extraction/4162.GetKnowledgeExecutable.zip

This approach uses the registry to store state information. This isn’t really all that complex to do in a script, but the added value here is a wrapper class that approximates the ease of use that was provided by the state object in MOM 2005.

You’ll have to use your own judgment regarding the applicability of this to your application. Clearly, the registry is not appropriate for storing large amounts of rapidly changing date. It is safe to use this for a few numbers or strings. 

See the attachment for a script fragment that contains the VBScript class and associated declarations that provides a convenient registry based State object. Paste this into your script to take advantage of the class.

The state class defines two methods:

·         GetState(stateVariableName) – Get the value of a ‘state variable’ from the registry.

·         PutState(stateVariableName) – Set the value of a ‘state variable’ in the registry.

The stateVariableName is just a unique name for the item.  Pass a string that is descriptive and unique for this value. It is likely that you will need to utilize a naming convention to ensure uniqueness across MPs and scripts.

I couldn’t resist also utilizing the error class that is frequently used scripts found in the Microsoft Management Packs. See the attachment for more details on that class.

Here is an example of using the State object to save information to the registry:

' Put some data in the state object

Dim myDataIn : myDataIn = "save this data"

Call State.PutState("MyVarName", myDataIn)

Here is an example of using the State object to get the data back out of the registry.

' Get the data back out

Dim myDataOut

myDataOut = State.GetState("MyVarName")

It couldn’t be simpler. To be absolutely safe, it’s a good idea to embellish this code sample with error checking. Add logic that checks for non-zero value in g_oError.err property after the calls to GetState and PutState.

A few things to note about the State class in the attachment:

1.       It uses the RegRead and RegWrite methods of WshShell to the do the actual registry I/O.

2.       The secret sauce in this code is in the use of the GetScriptStateKeyPath method provided by the MOM.ScriptAPI script object. This method determines a unique registry path accessible by the current identity.  You don’t really need to know the registry path to use the code, but on my machine it is in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft Operations Manager\3.0\Modules\MyState\S-1-5-21-581608182-3256059318-2886809674-500\Script.

3.       Note the argument in the call to GetScriptStateKeyPath("MyState") in the attachment. The “MyState” becomes part of the registry path. Consider using this to uniquely identify your state by management pack or other means.

StateClass.zip

The purpose of the Management Pack is to monitor the health of an ETL process for a data warehouse. The customer wanted to be alerted when certain record counts processed by the ETL jobs varied more than a specified threshold from one day to the next.

The basic design for this type of monitor is unsurprising. I created a data source type that knew how to get the record counts. Then I built a unit monitor type that feed the record counts from the data source into a condition detection module (a.k.a. filter) based on System.Performance.DeltaValueCondition.   After the filter is the expression logic to test the delta against the thresholds.

The System.Performance.DeltaValueCondition filter is designed to do exactly what I needed: it outputs the delta between samples. It can be configured to calculate the delta in terms of percentage or absolute difference. I reflected these config settings into the configuration section of the Monitor type so that everything would be super flexible.

Everything seemed to work fine in my unit testing.

The issues didn’t show up until I ran the monitor under more realistic conditions. The primary difference between my unit testing and the production application is that the rules in production have an interval of 24 hours, whereas in testing I ran things much faster.

Here is what I discovered about System.Performance.DeltaValueCondition:

1)      It considerable effort to understand the meaning of the numsamples property. Basically I found that any setting other than 1 is of dubious value for my application. Numsamples controls the number of samples held in memory by the filter. The filter will start outputting the delta after it has seen 2 values, regardless of what the NumSamples is set to. However, the output delta is always between the incoming sample and the oldest sample in history, which eventually gets updated as the queue fills up and the oldest entry is removed to make room for the newer entry.

2)      The queue of values is in memory. Any time the system is restarted or the service restarts, the queue is lost and will need to be reprimed before alerts are output. For me, this means I will miss alerts for a 24 hour period after a service restart.

3)      The delta is a signed number. For some reason I assumed that the filter would output the ‘absolute value’ delta. Since, I couldn’t find an absolute value function in the expression syntax, my expressions doubled in complexity.

So the moral of the story is that while there are lots of great things available for reuse in the System MPs (and System.Performance.DeltaValueCondition is one of them), the devil is in the details and in the requirements of your application. Particularly in scenarios with very long cycles.

Because of these issues, I decided to forgo the flexibility promised by my initial design based on System.Performance.DeltaValueCondition. I rewrote the data source module (which is script based) to incorporate the delta logic. This removed the need for  System.Performance.DeltaValueCondition filter from my monitor type. The new data source outputs the ‘absolute value’ delta, and it has no statefulness  (it queries for current and previous values each polling cycle) so there is no delay in alerting and no issues with service restarts. The big tradeoff now is some loss of flexibility.

I had the opportunity to build a simple product connector for System Center Operations Manager 2007 last week. A product connector is used to forward alert information from OpsMgr to an external system.  This post describes how I built the product connector and contains some sample code. This sample extends the code found on MSDN by wrapping it in a windows service.

Product connectors use the Operations Manager SDK to poll for alerts. The connector API has a built-in mechanism for marking processed alerts to prevent the connector from outputting the same alert every polling cycle. It also has a mechanism for controlling the number of alerts that are read during each polling cycle. Because of the polling approach, a connector must be hosted by something that can periodically wake up and perform the polling operation.  The connector described here uses a service to host the polling logic.

Once you have installed a connector, the administrator must create a subscription that defines the alerts that are available to the connector. For more information on building and configuring product connectors, see https://msdn.microsoft.com/en-us/library/bb437511.aspx and https://blogs.msdn.com/jakuboleksy/archive/2008/01/09/scom-connector-quickstart-guide.aspx.

I simplified the connector that I built to create a small sample showing how to build an outbound connector. The sample was built using Visual Studio 2008 and written in c#. See the attached files for the complete sample.

This sample extends what you find on MSDN in the following ways:

•  It is a Windows Service instead of a command line program. MSDN suggests that you create a windows service if you intend to run the connector continuously.
• The sample includes code for use by the service installer.
• The sample utilizes a thread timer to control the alert polling.  The interval and startup delay are configurable via application settings.
• The sample writes alert information to an XML formatted text file.

The Installer Class

The project includes an installer class. The installer class will create the service and register the product connector using the Operations Manager SDK API. The uninstaller will do the reverse, as well as removing the subscriptions created for this connector.

You can install the service using the InstallUtil tool that is part of the .net framework. Look for this tool in the %windir%\Microsoft.NET\<.net version> folder.  Use the /u option of InstallUtil To uninstall the service.

There are lots of names and descriptions to create when building a product connector. They are used for the service and for the product connector itself. Most are defined in the installer class. The service name is defined in the service class. You should update these names to be descriptive of your solution if you use this sample code.

The service is installed to run as local system by default. Consider changing this to use a less privileged account after installing the service.  You can use the service control manager to change the credentials of the service after it is installed.

The service is installed with a run mode of ‘Automatic’. You must manually start the service after the installation, but it will start automatically after a system restart.

Every product connector must have a unique guid. There is a property on the service class that defines the guid for the sample. You should change this guid if you create a product connector based on this sample.

The Configuration File

I used the appsettings section in the app.config file for three settings:

• PollingIntervalMS – This determines how frequently the service will poll for new alerts (in milliseconds).  You will need to find the correct tradeoff between polling overhead and latency for your application.
• StartupDelay – This allows you to specify a delay before starting the polling when the service first starts. I have found that if you attempt to connect and poll for alerts before the SDK is ready after a system restart, the connection will fail. A delay of a few minutes seems to be sufficient to avoid this problem.
• OutputFilePath – The full path for the output file where alerts are to be written.

The Management Group Connection

The service is written such that it expects to run on the RMS. It connects to the management group using the “localhost” identifier.

You Must Create a Subscription

The service won’t start outputting alerts to the file until you create a subscription. Use the Operations Console to do this. From the administrator view, select ‘Product Connectors’ from the tree view on the left. If you have installed the sample product connector, you should see it in the list of product connectors. Select it, and create a subscription for it just as you would for a notification. Note that the MSDN documentation states that a connector with no subscription will process all alerts. My experience was that the connector did not process any alerts until at least one subscription was created for it. Perhaps I was not waiting long enough?

The Timer

The service is designed around a thread based timer. When the OnStart event runs, the timer is created using the interval and startup values from the configuration file.

A few things to note about the timer function. I designed it to use a ‘lazy’ approach to connecting to the management group. When the timer function first runs, it detects that it needs to connect. Subsequent runs will use the existing connection. If an error of some sort occurs while connecting or polling for alerts, the connection is set back to null so that a new one will be created when the timer next fires. I wasn’t sure if there was a performance benefit from holding onto the connection, but I assumed there was. This approach makes the service fairly robust, but may create lots of events in your application log if the connection or polling is persistently broken.

The WriteAlert Method

The sample defines a WriteAlert method that is called for each alert. The purpose of this method is to do the work of output the alert to your target system. In the sample, this method just writes the alert the output file as an XML fragment containing many of the alert property.  There are many additional alert properties you might find useful in your connector.

The current WriteAlert method really only makes sense for demonstration purposes because it will result in an output file that grows continuously as alerts are processed. You will need to create a mechanism for rolling that file over or harvesting it in some way.

You will probably need to rewrite this function in your connector to format the alert as needed and to output to whatever device your external system requires.

You may also need to modify the OutputAlerts method to establish a connection your external device. This is the method that actually calls the WriteAlert method while walking over the alert collection.

Event Logging

The service will place events in the event log for any errors it encounters. You might consider setting up an Operations Manager rule to alert on these events. See the source code for specifics on event numbers. The event source will be the name of the service. Consider building a small MP to go along with your connector for the purpose of monitoring the connector.

Project Notes

The attachment to this post contains a zip file with the project used to build the service. The project contains references to both of the assemblies in the Program Files\System Center Operations Manager 2007\SDK Binaries folder.

Interesting Things in the Database

There are a few interesting columns in the AlertView view of the Operations Manager database that I have found useful in debugging connectors. They are ConnectorId and ConnectorStatus. The ConnectorId column will be populated with the guid for the connector that will process the alert. (I’m curious about what would happen if two connectors have subscriptions that cover the same alert). The ConnectorStatus column is used to track whether or not the alert has been processed yet by the connector. A value of 1 in this column indicates that the alert is pending processing; a value of 2 indicates that processing is complete. Since the sample doesn’t use the batch size version of the GetMonitoringAlerts method, you would expect all pending alerts that this connector subscribes to would be returned by that method.

Disclaimer

Use of included sample code is subject to the terms specified at https://www.microsoft.com/info/cpyright.htm.

Next Steps For Sample Code Users

• Consider adding more error checking everywhere.
• Does your connector need to use the batching overloads of the GetMonitoringAlerts method?
• Update the assorted names (connector name, description and service name).
• Create a new GUID for your connector
• Update the WriteAlert function to output the alert in the format you desire.
• Consider building a small management pack to monitor your connector service.

ProductConnectorSample2012.zip