Introduction

This article describes how to develop flexible WS Management-based solutions for Intel® Active Management Technology using the .NET development environment. The basic ingredients and building blocks of a WSMan-based solution will be presented. We've included some coding samples (written using Windows 2008) to help illustrate this information.

WS-Management (WSMan) is an industry standard SOAP-based protocol for managing systems such as desktops, notebooks, servers, and other IT-related infrastructure. WS-Management is now the primary interface used for Intel® Activate Management Technology (Intel® AMT) hardware.

Basic Ingredients of a WSMan Solution

Before we can sit start developing a WSMan solution we need make sure we have all the right ingredients at hand. A typical WSMan-based solution consists of the following:

A WSMan client

WSMan clients allow us to do the following:

• Get, put (update), create, and delete individual management resources such as configuration settings and dynamic values.
• Enumerate the contents of containers and collections, such as large tables and logs.
• Subscribe to events emitted by managed resources.
• Execute specific management methods with both input and output parameters.

In this article we will be using Windows* Remote Management (WinRM) as our WSMan client. There are other WSMan clients out there at various stages of completion or development. However, WinRM is widely available since it's built into the operating system starting with Vista and Win2008 and is easily integrated into the .NET environment.

A WSMan Sever

Next we will need a WSMan compliant Server that our client can talk to. In this case, we will Intel® AMT hardware as our WSMan Server. For the purpose of this article, the hardware should have at least Intel® AMT version 3.2.1 or above. Older versions of Intel® AMT did not have support of WSMan.

CIM Binding method

WSMan Servers typically describe their resources using the Common Information Model (CIM) and XML (also known as CIM-XML). Client programs need to bind this CIM data to WSMan operations and transform the XML representation into something that can be used in code.

One approach is to use files that describe the CIM schema, such as WSDLs, XSDs, or MOFs, and compile the bindings into code that be used in a specific programming environment. Currently, the Intel® AMT SDK provides MOF files that describe the CIM objects it supports, but the SDK does not provide any tool to compile them.

Yet another approach is to write code that can generically handle any CIM object without an actual schema. In this case, you will not require any schema files. In this article we will use the generic approach for handling the CIM bindings. The sample in this article uses a generic binding of CIM implemented in a library called CimAuto.dll and is included with the samples.

When using a generic binding you will notice we use strings for names and values instead of strongly typed data. This is because with generic bindings we don't use any schema files so the actual data types are not known at runtime. Good old fashioned strings are used pretty much for everything.

Preparing the Sample Environment

Before the samples can be run successfully, a few preparation steps need to be completed:

Configure WinRM

The WinRM client may need some pre-configuration before it can be used with Intel® AMT hardware in Small Business Mode. In this case, WinRM needs to be configured to accept Digest authentication and to accept non-TLS connections. There is a sample program called ConfigWinRM that does this. This sample will enable digest authentication and trust all computers without requiring the use of TLS. This sample is run on the same machine that will be running all the rest of the samples. ConfigWinRM needs to be executed only once and it does not require any command line arguments.

Register the Generic CIM binding library

If the CimAuto library has never been used before it needs to be registered as a COM object. Browse to the directory where CimAuto.dll is located and right-click and choose "Microsoft© Register Sever" as shown.

If you don't see "Microsoft © Register Server" in the right-click menu, don't worry. Just select the "Open With..." or "Choose Program" menu item. Then choose "Select the program from a list." Then click the Browse button. Next browse to the Windows System32 directory and select "regsvr32.exe."

After opening the CimAuto.dll with Microsoft© Register Server, the following message should appear:

The generic CIM binding library is now registered and can be used in .NET.

Set Up Intel® AMT Hardware

To set up Intel® AMT in what's sometimes referred to as Small Business Mode, you can boot the Intel ® AMT client and press CTRL-P during the boot process. If needed, change the password, change the Provisioning Mode to Small Business Mode. Set the host name to match the host name of the OS, and then exit all the menus. The Intel ® AMT system is now ready to go. To confirm AMT is set up correctly open a browser from another system on the same network and type "http://<your OS host name or IP>:16992." If an Intel Web page comes up then you've succeeded. If an Intel ® AMT Web page does not come up, check for a Firewall that might be blocking Intel® AMT packets.

The WSMan Ingredients in .NET

As discussed previously there are three basic ingredients in a typical WSMan solution:

• WSMan Client - WinRM will be used
• WSMan Server - Intel® AMT hardware will be used
• CIM binding method - Generic binding with CimAuto will be used

To include the WinRM client in a .NET project, simply add it as reference using the Solution Explorer as shown:

If this is the first time WinRM is being used, navigate to the Windows System32 directory and add wsmauto.dll to the project.

If wsmauto.dll is not present then the system is probably running Windows XP or 2003. This can be fixed by installing KB936059.

Next, add the Generic CIM binding object by navigating to the directory that CimAuto.dll resides in and adding it as a reference, just like Wsmauto.dll was added above.

Assuming the Intel® AMT hardware has been properly enabled, we can begin looking at the sample code.

PowerControlSample

The included sample will load its application settings as part of the project. The settings can be editted by going to the Project menu and selecting the "PowerControlSample" properties. The "Settings" tab in the project properties will look like the following:

Before running the sample, change the SessionString to match the name or IP adress of an Intel® AMT client in your envioment. AMT hardware uses port 16992 for http and 16993 for https. The host name I am connecting to is m42.intelmas.net, which is an Intel® AMT 4.2 laptop in my enviroment. Also, change the user name and password to reflect your own Intel ® AMT credentals if they are different. The PowerCommand property is the CIM value of the Power comamnd to send. They are as follows: 2=PowerOn, 5=Power Reset,8=PowerOff.

The Sample has a few functions that demonstate the basic operations that a Wsman client would use. This inclues creating a wsman session, performing get() operations, enumerating items, and Invoking methods.

The sample program will be using both WSMANAutomation (WinRM) and a generic CIM binding library (CimAuto.dll)

The main program creates a WinRM object, then creates a session object that is used throughout the rest of the program.

The rest of the funtions in the sample demonstrate various WSMan operations with AMT hardware and ultimately end with a power control.

Establishing a Session

Before our client can send WSMan requests we need to establish a session with a WSMan server. To do this, we will use the CreateSession() method of the WSManAutomation.WSManClass. The method takes three arguments, the first being the connection string of the session, the second argument is session flags, the third argument is any authentication information that maybe needed to authorize the session. Creating a typical session with AMT would look like the following:

Basic WSMan Get Operation

Looking at the AMTHello() method in the project, we can see how to use WinRM and our generic CIM binding to retrieve the hostname of the hardware. The first thing this sample does is create an instance of a generic CIM binding. Then it assigns the ClassName property of the CIM Binding to the name of the class we want to get. Next, it performs a WSMan get operation using the full Resource URI of the CIM object. Finally, the sample uses the generic CIM binding to retrieve the value of the HostName property of the CIM object.

WSMan Get Operation with Selectors

Looking at the GetVersion() method in the project, we can see how to use WinRM and our generic CIM binding to retrieve the AMT version using a selector. Selectors are needed when getting objects that have more that one instance. For example, unlike AMT_GeneralSettings, there are many instances of CIM_SoftwareIdentity. So when getting an instance of CIM_SoftwareIdentity, we need to specify which instance we want. In this case, we want the CIM_SoftwareIdentity that has an InstanceID property with a value of "AMT."

WSMan Enumerate Operation

Looking at the GetPowerService() method in the project and we can see how to use WinRM and our generic CIM binding to enumerate instances of an object. When enumerating, WinRM will return an enumeration object. We will use this enumerator to items until there are no more or we found the one we are looking for.

WSMan Invoke Operation

Looking at the ChangePower() method in the project, we can see how to use WinRM and our generic CIM binding to invoke a method on a CIM object. Invoking a method requires two generic objects: an Input object and on Output object. The generic input object holds all the parameters that will be passed to the method, while the generic output object holds the return value and any output parameters after the method is executed.

Summary

Armed with WinRM, CIMAuto, and the Intel® AMT SDK class reference, you should be able to implement any of the flows for Intel® AMT. In this sample, we explored how to set up the .NET environment to use WSman and ran through the WSMan operations to perform a hardware power control.

Learn More about WS-Management

For further information regarding WS-Management, the following resources provide a good starting point:

•· Web Services for Management contains the actual specification for WS-Management protocol.

•· WS-Managment - CIM Binding contains the actual CIM-Binding specification for the WS-Management protocol

•· MSDN: Search for "WinRM" to get information regarding Windows Remote Management

The Intel ® AMT SDK 3.0 release contains the following resources regarding WS-Management.

•· Intel® Active Management Technology WS-Management Flows

•· WS-Management Classes\index.html