Utility SpotlightSMSMap

Jeff Tondt

Download the code for this article: UtilitySpotlight2007_07.exe (2477KB)

A picture is worth a thousand words. This familiar proverb refers to the idea that complex stories can be told with just a single image, or that an image can be more influential than even a substantial amount of text. It also aptly characterizes the goals of visualization, where large amounts of data must be absorbed quickly.

To a System Management Server (SMS) geek like me, seeing the whole SMS hierarchy in one picture helps me understand how my infrastructure is laid out. You could use such a picture, perhaps, to show the before and after of an SMS migration plan to management. In certain troubleshooting cases, such a diagram could be very useful in finding a solution or at least in getting help from others. And, of course, as a responsible SMS administrator, you need to document your system hierarchy for all sorts of other reasons.

Getting the Picture

It’s not that you can’t draw such a diagram yourself. You can certainly roll up your sleeves, manually draw the SMS hierarchy, and document the site settings by hand. If you have Microsoft® Operations Manager (MOM) monitoring your SMS servers, you can have it diagram your hierarchy—though I should note that MOM is not exactly picture-friendly and it certainly doesn’t document your site settings. There may be other methods or handy tools, but I haven’t yet come across anything that adequately creates pretty pictures and helps document the site settings—at least not to my satisfaction.

So, I decided to roll my own. Thus SMSMap 1.0 was born. SMSMap is a Visual Basic® .NET application that uses the SMS managed libraries in the SMS SDK and automates Microsoft Visio® via COM. The utility queries a targeted SMS site server and then creates a visually appealing Visio diagram and exports site settings into an XML file. XML was selected as it is the most compatible way of documenting the site settings. I chose to show the SMS roles as well, not just the physical servers related to other SMS servers. This allows tinkering with the diagram via Visio layers to look at the SMS hierarchy from several viewpoints.

Figure 1** Radial format **

Currently, the program lets you select six different formats for the Visio diagram. For example, Figure 1 shows a very simple SMS hierarchy using the radial format, while Figure 2 shows the same hierarchy using the flow chart format. The utility works quite well with much larger hierarchies, but I wanted to keep things simple here.

Figure 2** Flow chart format **

At some point, SMSMap will likely evolve to document all site settings. Currently, it documents only the SMS site roles and all boundaries. With little effort, many more site settings could be exported into the XML file.

Using SMSMap

The source code and installation files for SMSMap are available on the TechNet Magazine Web site. To install it, simply execute SMSMapSetup.msi, which walks you through the installation. Remember, SMSMap uses Visio, so you must also have that installed already. After the installation, execute C:\Program Files\Microsoft\smsmap\smsmap.exe (unless you installed it in a different location from the default).

You can run SMSMap from any machine; you don’t have to run it from the site server (and it’s unlikely that many SMS site servers will have Visio installed). Enter the SMS Site Server name where you want the query to originate. This can be the central site if you want to query the whole hierarchy or it can be any child primary site server, but in that case you only get the hierarchy from that child primary site on down. Next, enter the account that has permission to query SMS using the format domain\username, and then the password for that account. (The password will not be displayed, so you can run this in front of others.)

Six radio buttons let you select the layout, and you can choose whether to allow or prevent SMS roles from appearing in the drawing. These check boxes are located under the Options tab. Pressing the Draw button starts the utility. It first checks to see if Visio is available, then queries the specified SMS primary site server and adds the objects to the Visio diagram. The Visio diagram may look ugly while SMSMap is dumping in objects, but at the end the utility organizes them into the format you specified at the beginning.

Diving Deeper

Now you’ve seen why and how to document your SMS hierarchy using SMSMap. For those who want to flex their developer muscles, let’s take a closer look at how the utility works.

SMSMap uses the Managed SMS Site Server Interfaces to gather the SMS information, and the Visio Primary Interop Assemblies to generate a Visio diagram that lays out all the necessary shapes. The SMS 2003 SDK Version 3.1 contains the latest release of the Managed SMS Site Server Interfaces. This set of managed interfaces lets you connect and configure an SMS Site Server through any Microsoft .NET Framework-enabled language or application.

These interfaces use the System.Management namespace to interact with an SMS provider through Windows® Management Instrumentation (WMI). To use the interfaces you must develop your application with a .NET-compatible language (for example, C#, Visual Basic .NET, and so forth) and reference the Microsoft.SystemsManagementServer.Automation.dll that the .NET assembly supplied with the SMS SDK.

The .NET Management classes clean up many of the idiosyncrasies of the WMI object model to present a consistent, object-oriented model. The basic tasks of WMI connection, object enumeration, method execution, object deletion, object retrieval and event capture can all be achieved through the .NET Management classes.

Visio Primary Interop Assemblies

A Primary Interop Assembly lets you use managed code to control COM apps like Visio programmatically. The Visio Primary Interop Assemblies allow you to integrate and extend Visio functionality into managed apps.

If you already have the .NET Framework installed on your computer, when you subsequently install Visio, the installer adds the Visio Primary Interop Assemblies to the Global Assembly Cache (GAC) on your computer. You can add a reference to the Visio Primary Interop Assemblies from your managed applications.

After adding the reference to the project, you can start working with Visio objects from your managed application. Visio has an extensive object model that provides a set of classes, interfaces, and enumerations so that you can create diagrams programmatically.

Program Flow

Now that I have described the main component interfaces for Visio and SMS, I will explain the flow of the utility itself.

The first step when using the managed interfaces is to connect to the SMS provider. This can be accomplished by creating a new instance of the SMSProvider class. Internally, this class will find the SMS provider for the specified site server and connect to it with a given set of credentials. If the provider is on the local machine, the currently logged-in credentials will be used instead of the supplied credentials when connecting to the provider. Although you can run SMSMap on the SMS server, I recommend running it on a separate workstation that has Visio installed. Most SMS site servers do not have Visio installed for obvious reasons.

When you access data on the SMS site through the SMSProvider class, security rights are treated as if you were using the SMS Administrators Console. This means, for instance, that if you try to configure the settings for a site server through an SMSProvider, the account you connect to the provider with must have the same set of rights as if you were using the administrator’s console.

The SMSProvider class supplies a GetSiteSettings method that allows you to get the site settings for the current site (which the provider belongs to) or for any site with a specific site code. The code snippet in Figure 3 shows how SMSMap connects to the provider for the targeted site server. The user credentials are expected to be passed in Domain\User format. You can also specify "." to indicate the current machine. Figure 3 also includes code that helps display the results in the UI and for logging.

Figure 3 GetSiteSettings snippet

Imports System.Management
Imports Microsoft.SystemsManagementServer.Automation

 oProvider = New SMSProvider(txtServer.Text, txtUser.Text, txtPassword.Text)
 oSite = oProvider.GetSiteSettings()
 Trace.WriteLine(“Connected to “ & txtServer.Text & “: “ & My.Computer.Clock.LocalTime)
 ListBox1.Items.Add(“Connected to “ & txtServer.Text & “: “ & My.Computer.Clock.LocalTime)
 Application.DoEvents()
...

The next step is to set up the XML file for gathering and recording the SMS information for the targeted site server, as shown in Figure 4.

Figure 4 Creating the XML file

‘ First, Create the XML File 
 oWriter = New XmlTextWriter(m_sXmlFile, System.Text.Encoding.UTF8)
 oWriter.WriteStartDocument()
 oWriter.WriteStartElement(“Hierarchy”)

 ‘ Export Target Site to XML
 oWriter.WriteStartElement(“Site”)
 oWriter.WriteAttributeString(“Code”, oSite.SiteCode.ToString.ToUpper)
 oWriter.WriteStartElement(“SiteServer”)
 oWriter.WriteAttributeString(“Name”, oSite.SiteServer.ToString.ToUpper)
 oWriter.WriteEndElement()
 oWriter.WriteStartElement(“ParentSiteCode”)
 oWriter.WriteAttributeString(“SiteCode”, “THIS_IS_THE_TOP”)
 oWriter.WriteEndElement()

...

Next, the targeted site needs to be drawn in the Visio diagram and updated in the UI and log, as you can see in Figure 5.

Figure 5 Drawing the site in Visio

 ‘Draw Central Site
 dblXLocation = 4.25
 dblYLocation = 8.5
 vApp = New Visio.Application()
 vDoc = vApp.Documents.Add(“”)
 vStencil = vApp.Documents.OpenEx(TEMPLATEPATH, 4)
 ‘ Add Layers
 vExistingLayers = CType(vDoc.Pages(1).Layers, Visio.Layers)
 vLayer = CType(vExistingLayers.Add(“Site”), Microsoft.Office.Interop.Visio.Layer)

...

 If oSite.SiteType = SiteTypes.PrimarySite Then
 vFlowChartMaster = vStencil.Masters(“Primary Site”)
 ElseIf oSite.SiteType = SiteTypes.SecondarySite Then
 vFlowChartMaster = vStencil.Masters(“Secondary Site”)
 End If
 vToShape = vApp.ActivePage.Drop(vFlowChartMaster, dblXLocation, dblYLocation)
 vLayer.Add(vToShape, preserveMembers)

...

To go through the entire hierarchy under the targeted site, the same basic code described above that queries SMS and draws in Visio is executed. This is a function named Level that is called recursively to ensure all child sites are queried no matter how large the hierarchy is. Level gathers the SMS site information and records it in XML, the UI, and the log for each child site under the targeted site. Finally, Figure 6 shows how the Visio diagram is formatted using the format selected when the utility starts. Then the XML and log files are closed.

Figure 6 Finishing Up

 vDoc.Pages(1).Layout()
 vDoc.Pages(1).ResizeToFitContents()

 ‘Calculate the page width and height with a 5% boundary 
 visCell = vDoc.Pages(1).PageSheet.Cells(“PageHeight”)
 dHeight = visCell.Result(“in”)
 visCell = vDoc.Pages(1).PageSheet.Cells(“PageWidth”)
 dWidth = visCell.Result(“in”)
 dHeight = dHeight + 1
 dWidth = dWidth + 1
 vDoc.Pages(1).PageSheet.Cells(“PageHeight”).Result(“in”) = dHeight
 vDoc.Pages(1).PageSheet.Cells(“PageWidth”).Result(“in”) = dWidth
 vDoc.Pages(1).CenterDrawing()
 Trace.WriteLine(“Arranged Sites “ & oSite.SiteServer & “: “ & My.Computer.Clock.LocalTime)
 ListBox1.Items.Add(“Arranged Sites “ & oSite.SiteServer & “: “ & My.Computer.Clock.LocalTime)
 vFlowChartMaster = vStencil.Masters(“Background world”)
 vApp.ActivePage.Drop(vFlowChartMaster, 0, 0)

 ‘Finish up
 vDoc.SaveAs(SAVENEWFILE)
 vDoc.Close()
 vApp.Quit()
 vDoc = Nothing
 vApp = Nothing
 GC.Collect()

...

Just a Beginning

Of course, this is just a start and there are many possibilities for improvement. Device Management Points need to be investigated as I don’t see them in the SDK. A number of additional site settings could be added to fully document a site. Perhaps some more work needs to be done on adding a wider variety of Visio layout settings in order to help make small and large hierarchies look better. Each layout type poses its own difficulties when trying to create effective displays. And, of course, adding support for System Center Configuration Manager 2007 is a very important next step. But even this first version of SMSMap can help SMS administrators display the big picture and try some what-if scenarios with Visio layers and transparency.

If you download the source code, you can extend the utility to meet your own needs. I tested SMSMap on Windows XP SP2 with Visio 2003 and Windows Vista™ Enterprise with Visio 2007. If you have any suggestions on how to improve this utility, please e-mail me at <jeff.tondt.microsoft.com>.

Jeff Tondt is a Senior Consultant II for Microsoft Consulting Services. He focuses on the areas of systems management, automation, and patch management. He is an SMS subject matter expert and can be reached at jeff.tondt@microsoft.com.

© 2008 Microsoft Corporation and CMP Media, LLC. All rights reserved; reproduction in part or in whole without permission is prohibited.