Implementing Context Menu Integration
Context menu integration gives you an easy mechanism for extending the functionality of one or more nodes in the SMS Administrator Console. The functionality you are incorporating is added to the context menu under the SMS Tools menu option. However, this is not the same as adding an extension snap-in to the context menu.
With this method, you are simply adding out-of-process (a separate process) functionality to a node. For example, you could start Notepad, run the ping command, or start your own SMS client application as if it were started from the command line. You simply add up to six registry entries in the system registry for each node whose functionality you wish to extend.
You can extend the functionality of any node in the scope pane or result pane. The functionality that you provide must be able to be executed from the command line and it only applies to those nodes that you have identified in the registry.
Context menu integration is not the same as adding an extension snap-in to the context menu. For information on how to extend the SMS Administrator Console snap-in, see Sharing Data With the SMS Administrator Console.
Determining the Node to Extend
You must define registry entries for each node you are going to extend. Each node in the console has a corresponding node in the system registry. The problem is that the nodes in the registry do not have the same name as the nodes presented in the console. The node is identified in the registry with a globally unique identifier (GUID). A node's GUID can be found on its property sheet in the console. The Node Information tab contains the GUID and instance data for the node. You must start the MMC using the command-line option /SMS:NodeInfo=2 to see the Node Information tab.
Registry Entries
The following table identifies the registry entries you must include in the MMC registry hive for each node that is to provide your extension.
| Key | Description |
|---|---|
| Name | Name of the application extension as it appears in the SMS Tools menu options. Names are presented alphabetically in the menu. |
| Description | Description displayed on the status bar when the option is highlighted. |
| CommandLine | Command line to execute.
The command line can contain any windowing or console-based executable file. Make sure you include the full path, when necessary, and all program arguments. The command line supports parameter substitution of both instance properties and system properties. |
| CriteriaQuery (optional) | Valid Windows Management Instrumentation (WMI) query. The query determines whether the command line is executed or a message is displayed to the user.
The command line is executed when one or more rows match the query. The CriteriaMessage value is displayed when no instances are returned by the query, or the query failed to execute. The query supports parameter substitution of both instance and system properties. You can enter a blank query string, such as "CriteriaQuery"="", which causes the command line to be executed without condition. |
| CriteriaMessage (optional) | String displayed to the user if the criteria is not met. This is a short, one-line string that cannot contain escape characters (including escape characters results in unpredictable behavior). You can use string substitution in your message. For more information, see Specifying Parameter Substitution. |
| Sub2Query (optional) | Optional query to provide parameter substitution for CommandLine and QueryMessage. This option lets you query for data that is not contained in the instance data of the node.
The data returned by the query is available for substitution using SUB2 and ARR2, in the same manner that you use SUB and ARR. Unlike CriteriaQuery, which prevents the command line from executing if it fails, Sub2Query provides no recourse when the query fails. |
To specify parameter substitution or use the CriteriaQuery, CriteriaMessage, and Sub2Query key options, a WBEM subject must exist for the node type you are extending. You can determine whether a WBEM subject exists by viewing the Node Information property sheet. If the node contains a WBEM subject, the property sheet contains the string, "Wbem Subject (Clone):", followed by the instance data for the node. If the node does not contain a WBEM subject, the string, "Wbem Subject (Clone):", is followed by "No WBEM Subject".
Adding the Registry Keys
The registry entries are added to [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MMC\NodeTypes\{GUID}\Extensions\SMS_Tools\<YourExtension>]. You need to replace GUID with the GUID found on the property sheet for the node that you want to extend. You will need to create the SMS*_*Tools key if this is the first extension you are adding to the GUID node. Replace YourExtension with a name that identifies the extension you are adding. You can add the registry keys using any of the following methods:
- You can use the regedit program to manually define the registry keys.
- You can create a .reg file, which is, by default, associated with the regedit program. Double-clicking on the file loads (merges) the registry entries into the system registry.
- You can build an installation program using a program like SMS Installer, which creates registry entries for you.
- You can programmatically create the registry entries using the Microsoft® Win32® APIs. Information can be found in Microsoft Developer Network (MSDN™) under REGISTRY for Visual Basic (VB) applications, and under Registry Functions for C++ Applications.
Node Extension Example
The following example shows the contents of a registry file (.reg) that extends the Site Database node in the SMS Administrator Console. This example assumes the SMS_Tools key does not exist, which is why the first HKLM entry is included — you would not include this entry if SMS_Tools already exists for this node.
REGEDIT4
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MMC\NodeTypes\{3AD39FC5-EFD6-11D0-BDCF-00A0C909FDD7}\Extensions\SMS_Tools]
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MMC\NodeTypes\{3AD39FC5-EFD6-11D0-BDCF-00A0C909FDD7}\Extensions\SMS_Tools\Ping]
"Name"="PING site server"
"Description"="Site config Tool"
"CommandLine"="cmd /K ping ##SUB:__SERVER##"
"CriteriaQuery"="SELECT sitecode FROM sms_site WHERE servername=\"##SUB:__SERVER##\""
"CriteriaMessage"="Sorry, incorrect site selected! ##SUB:__PATH##"
Sub2Query Example
The following example shows the use of the optional Sub2Query key. The example uses Sub2Query to get the TotalPhysicalMemory value, which is not included in the instance data of the node.
REGEDIT4
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MMC\NodeTypes\{4D26C0D4-A8A8-11D1-9BD9-00C04FBBD480}\Extensions\SMS_Tools]
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MMC\NodeTypes\{4D26C0D4-A8A8-11D1-9BD9-00C04FBBD480}\Extensions\SMS_Tools\Sample Tool]
"CommandLine"="cmd /s /k echo ##SUB:Name## Physical Memory = ##SUB2:TotalPhysicalMemory## Kb"
"CriteriaMessage"="Memory Hardware Inventory not available for ##SUB:Name##"
"CriteriaQuery"="SELECT * FROM SMS_G_System_X86_PC_MEMORY WHERE ResourceId=##SUB:ResourceId##"
"Description"="Displays the Total Physical Memory last reported by Hardware Inventory for the specified system"
"Name"="Physical Memory"
"Sub2Query"="SELECT TotalPhysicalMemory FROM SMS_G_System_X86_PC_MEMORY WHERE ResourceId=##SUB:ResourceId##"