Windows Management Infrastructure Blog

Introducing new Management Infrastructure (MI) API

Osama Sajid [MSFT] — Thu, 16 May 2013 16:52:00 GMT

In Windows 8/Windows server 2012 we introduced new Management Infrastructure (MI) API for writing WMI provider and client applications. This blog post will explain our goals for "Improving developer Experience" and WHY we did a new API for client and provider, instead of updating existing WMI API.

We will continue to cover “HOW” to write providers and client applications using the new API in the blog series started by Haowei.

First a bit of recap:

Last year in March we had a blog post from Jeffrey and Wojtek explaining the big picture of Standards Based Management in Windows Server 2012 and Window 8 . To recap, our goal for WMI and WinRM in Windows 8 was the following

* Dramatically reduce the effort required to write WMI providers and standards-based management tools

* Update our code to comply with the latest DMTF standards

* Tightly integrate WMI, WinRM and Windows PowerShell

* Provide a clear and compelling value proposition for everyone to use standards based management on Windows or any other platform.

WMI was introduced way back during the days on Windows NT ; yes – and it just seems like yesterday but a lot of water has flown under the bridge. Things were changing for server - we are now best Cloud OS, and manageability is one of our key differentiators ( instead of some side thought as it used to be)

In the early days of Windows 8 planning, we had detailed discussions with partners and customers. Few things popped up early on

1. Writing WMI providers and client applications is complex. There is a learning curve and it requires knowledge of underlying infrastructure (COM, complex ref-counting , WMI engine complexities and so on)

2. Our infrastructure was not fully aligned with latest DMTF standards.

3. Last but not the least, some partners were not clear if they should write WMI providers or PowerShell cmdlets (We said both, and the answer was "come on - that is a lot of duplication")

This was great feedback. In order to meet the goals for Windows server to be the best cloud OS and meet our commitment for standards based management, we made it a goal to "Improve developer experience". This can be explained as following..

1. Simplify provider development process

- Hide the complexity of underlying infrastructure.

> Developer should focus 100% on business logic.

- Streamline end to end process (design, develop, deploy, test) -

> Generate strongly typed skeleton code from MOF,

> Provide compile time checking and type safety.

> Reduce the amount of code required to be written.

> Simplify provider registration.

2. Simplify client development

- Hide the complexity of underlying infrastructure (including the protocol - DCOM or WinRM)

- Simple Sync and Async models for all standard operations.

3. Enable tight integration with PS.

- Make WMI and CIM standard first class citizen in PowerShell

- Remove duplication of effort in writing WMI provider and PS Cmdlets.

4. Align with latest DMTF standards.

- Make WsMan as the default protocol for client-server communication

- Update the schema to CIM schema 2.6

As you can see, it was simply not possible to achieve the goals outlined above with existing API. We needed a new "model" built from scratch - retrofitting and old model was not going to get us where we wanted to go.

We introduced new “Management Infrastructure API” or MI API for writing providers and client. This is going to be the API going forward - although old API is still supported, it will be in maintenance mode. All our future development effort will go towards the new API.

By the end of Windows 8 development cycle – we were glad to see many-fold increase in adoption of WMI and WinRM. We changed the developer perception (inside Microsoft) from “COM-plex to CIM-plified”.

To summarize, following were some of the highlights for Server 2012 release last year.

Biggest increase in number on providers shipping in box in many releases
~1000 new cmdlets written using new MI provider API – with WS-Man as the default remoting protocol.
New Server Manager built using MI Client API - with WS-Man as the default remoting protocol.
New CIM Cmdlets built using MI Client API - enabling PowerShell to manage non-Windows systems and devices. (This was covered in a previous blog: Introduction to CIM Cmdlets)

Hope this blog explained the rationale and reason behind introducing a new model for writing providers and clients. Questions /comments are welcome - leave a note in the comments section below and we will get back to you.

Thanks

Osama Sajid,

Program Manager - Standards Based Management

Implementing MI Provider (3) - Generate Code

Haowei Qin [MSFT] — Sat, 11 May 2013 21:19:00 GMT

In blog Implementing MI Provider (2), we discussed schema definition of MI provider. Upon the schema ready, you can run Convert-MofToProvider.exe tool to generate MI provider skeleton code.

Where to install Convert-MofToProvider.exe tool?

Install windows 8 SDK first, then you could find the tool under SDK installation directory. For example, the file path on my desktop is "C:\Program Files (x86)\Windows Kits\8.0\bin\x64\convert-moftoprovider.exe"

Usage of Convert-MofToProvider.exe

C:\Program Files (x86)\Windows Kits\8.0\bin\x64>convert-moftoprovider.exe /?

Generates provider source code (C) from MOF class definitions.

Usage: Convert-MofToProvider.exe
                -MofFile <Mof files>
                -ClassList <Class list>
                -IncludePath <Path list>
                -InputParameterSet <Parameter Filename>
                [Other options]

-MofFile <Mof files>
        Specifies list of mof files that contains the MOF definitions
        (or includes them), which are seperated by space.
        It must include any dependent MOF defintions as well (such as
        the CIM schema).

-ClassList <Class list>
Specifies list of the names of the MOF classes to be generated.
If no class specified, it will generate all classes.

-IncludePath <Path list>
        Specifies list of the directories, from which to search for included
        MOF files. If no include path specified, it will search current
        directory by default.

-InputParameterSet <Parameter Filename>
        Specifies the parameter filename, which defines the input parameters.
        This option cannot be used with other options.
        Example: Convert-MofToProvider.exe -InputParameterSet param.txt
        Example of content for the parameter file,
                -MofFile a.mof
                -ClassList MSFT_A MSFT_B
                -IncludePath C:\stdmof

[Other options]

......

EXAMPLES:
The following example generates a 'MSFT_ComputerSystem' class,
which is defined in schema.mof.

Convert-MofToProvider -MofFile schema.mof -ClassList MSFT_ComputerSystem

Convert-MofToProvider -MofFile schema.mof -ClassList MSFT_ComputerSystem
-IncludePath C:\mof\cim222

NOTE: [Other options] part was omitted, you can run "convert-moftoprovider.exe /?" to get the detail usage.

Generate code

Here are the steps to generate provider code skeleton for "process" provider, one of the sample provider inside MI API sample.

First, setup up a working directory used to generate source code files, say C:\MIProvider

Second, make sure both sample.mof & MSFT_Qualifiers.mof present under working directory, you can copy both files from MI API sample to C:\MIProvider

Third, download DMTF standard schema, which is a zip file contains list of standard mof files. Say CIM Schema 2.26.0, unzip the standard schema to a directory, say C:\DMTF2260

Finally, run the following command line from an elevated command prompt console (cmd.exe)

Convert-moftoprovider.exe -MofFile C:\MIProvider\sample.mof -ClassList MSFT_WindowsProcess MSFT_WindowsServiceProcess -IncludePath C:\DMTF2260 C:\MIProvider -ExtraClass Cim_Error -OutPath C:\MIProvider -SkipLocalize

This command will,

- use the MOF file called sample.Mof that in the folder C:\MIProvider

- use the CIM 2.26 schema located in the folder identified by C:\DMTF2260

- use MSFT_Qualifiers.MOF located in the folder identified by C:\MIProvider

- generate skeleton code for the 2 classes following -Classlist

- include generated schema & types for the Cim_Error class

- place all output in the folder identified by the -OutPath parameter, i.e., C:\MIProvider

- skip the generation of resource IDs used for localization

- Generated provider will implement 2 classes, MSFT_WindowsProcess and MSFT_WindowsServiceProcess.

Also, the command line generates provider contains schema definition of parent classes and one extra class CIM_Error. Generated code files can be found under C:\MIProvider.

To better understand the generated files and its content, Figure 3.1 shows generated files' list for any MI provider.

Figure 3.1 Generated Files

While Strings.rc is optional , if -SkipLocalize option was specified, then Strings.rc will not be generated. <class name>.h and <class name>.c are generated for all involved classes for MI Provider. Take above command line for example, it is going to generate following classes specific files,


 CIM_ConcreteJob.h
 CIM_EnabledLogicalElement.h
 CIM_Error.h
 CIM_Job.h
 CIM_LogicalElement.h
 CIM_ManagedElement.h
 CIM_ManagedSystemElement.h
 CIM_Process.h
 CIM_Service.h
 CIM_ServiceProcess.h
 MSFT_WindowsProcess.h
 MSFT_WindowsServiceProcess.h
 
 MSFT_WindowsProcess.c
 MSFT_WindowsServiceProcess.c

Basically, <class name>.c files are only generated for the class name specified with -ClassList option, while <class name>.h files are generated for all class names specified with -ClassList option, -ExtraClass option, and all of their ancestor classes.

Next blog will discuss the content of each generated file and its purpose. Thanks.

Haowei Qin

Senior SDE

Standards Based Management

Implementing MI Provider (2) - Define Schema

Haowei Qin [MSFT] — Thu, 09 May 2013 05:34:00 GMT

Define Schema

To implement a MI provider, the first step is to model the management data, i.e., to define the schema of data. The schema has to be defined in DMTF's Managed Object Format (MOF), which is very similar to WMI MOF format except partial syntax of WMI MOF is not compliant with DMTF MOF.

Definition of MOF file can be found at http://www.dmtf.org/education/mof. Following is the copy of the definition from the page, “A MOF file can be encoded in either Unicode or UTF-8 format. MOF files are text files that contains definitions of classes and instances using the Managed Object Format (MOF) language. They can be edited using your favorite text editor or tool of choice.”

For MI provider, the MOF file defines only classes that modeling the underline management objects. One class maps to one category of management objects, for example Win32_Process class was defined to manage processes that running on Windows OS.

As described in Implementing MI Provider (1), there are 3 categories of providers, instance provider, association provider and indication provider. The type of provider actually refers to the type of class that being implemented, while the type of class depends on the class qualifier. Following are MOF examples for the 3 typical classes,

class MSFT_WindowsProcess : CIM_Process
{
 
 …
 
}

MOF Example 2.0: (normal) Class

[Association]
 class MSFT_WindowsServiceProcess
 {
 
 …
 
 }

MOF Example 2.1: Association Class

[Indicaiton]
 
 class MSFT_WindowsServiceStopped
 
 {
 
 …
 
 }

MOF Example 2.2: Indication Class

Schema Sample

An MI provider could implement one or more of above type’s classes. Be default those classes have fixed number of operations, generally, a (normal) class could have enumerate instance, get instance, delete instance, modify instance, and create instance; an association class could have assoicators of instance and references of instance operation; and an indication class could have enable indication, subscribe, unsubscribe, disable indication operations. Of course, a (normal) class could also have arbitrary number of methods defined, one method maps to one operation. Details will be discussed in the following blog Implementing MI Provider (3).

To understand how to define classes that derives from standard class, following table pastes the MOF file from Windows 8 SDK MIAPI Sample, it contains (normal) class, association class, and indication classes,

(1) MSFT_WindowsProcess derives from CIM_Process (CIM standard class), which models the process objects which is running on Windows Operating System. It is a (normal) class.

(2) MSFT_WindowsService derives from CIM_Service (CIM standard class), which models the win32 services objects configured on Windows Operating System. It is a (normal) class.

(3) MSFT_WindowsServiceManager defines only an static method, which reads service objects and return to client via streaming approach. The "stream" qualifier will be discussed in future blog.

(4) MSFT_WindowsServiceProcess derives from CIM_ServiceProcess (CIM standard class), which is an association class. The "association" qualifier is inherited from parent class "CIM_ServiceProcess".

(5) MSFT_WindowsServiceStopped derives from CIM_InstModification (CIM standard class), which is an indication class. It produces indication(s) upon the stop of any running window service.

(6) MSFT_WindowsServiceStarted derives from CIM_InstModification (CIM standard class), which is an indication class. It produces indication(s) upon the start of any window service.

// THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF

// ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO

// THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A

// PARTICULAR PURPOSE.

#pragma include ("cim_schema_2.26.0.mof")

#pragma include ("MSFT_Qualifiers.mof")

// MSFT_WindowsProcess class derives from CIM_Process class,

// which defines the schema for the processes running on windows OS.

[ClassVersion("1.0.0")]

class MSFT_WindowsProcess : CIM_Process

{

String CommandLine;

[Description("This instance method demonstrates modifying the "

"and any other number to indicate an win32 error code.")]

Uint32 SetPriority([In] uint32 Priority);

[static, Description("This static method demonstrates creating a process "
"by supplying commandline to start a new process."

"It will output the reference to the newly created process."

"The method returns an integer value of 0 if the process "

"was successfully created, and any other number to "

"indicate an win32 error code.")]

uint32 Create([In] string CommandLine, [Out] CIM_Process ref Process);

};

// MSFT_WindowsService class derives from CIM_Service class,

// which defines the schema for the services present on windows OS.

[ClassVersion("1.0.0")]

class MSFT_WindowsService : CIM_Service

{

// To implement methods defined in parent class,

// it is mandatory to copy those methods definition

// from parent class and redefine in child class

uint32 StartService();

uint32 StopService();

};

[Description("This class demonstrates designing a WMI class "

" having a static method to use the feature of steam output parameter, "

"which allows provider to send output array element one by one back to "

"client instead of sending the whole array back at one time."),

ClassVersion("1.0.0")]

class MSFT_WindowsServiceManager

{

// GetWindowsServices method reads list of MSFT_WindowsService instances with specific status,

// value of 0 for stopped services, 1 for running services, and other values for all services.

[static] uint32 GetWindowsServices(

[in, ValueMap { "0", "1", ".."}, Values {"Running","Stopped", "All"}]

uint32 status,

[out, stream, EmbeddedInstance("MSFT_WindowsService")]
string services[]);

};

// MSFT_WindowsServiceProcess class derives from CIM_ServiceProcess class,

// which associates present services instance with running process instance on windows OS.

[ClassVersion("1.0.0")]

class MSFT_WindowsServiceProcess : CIM_ServiceProcess

{

};

// MSFT_WindowsServiceStopped class derives from CIM_InstModification class,

// which presents the notification of a stopped service on windows OS.

[ClassVersion("1.0.0")]

class MSFT_WindowsServiceStopped : CIM_InstModification

{

};

// MSFT_WindowsServiceStarted class derives from CIM_InstModification class,

// which presents the notification of a started service on windows OS.

[ClassVersion("1.0.0")]

class MSFT_WindowsServiceStarted : CIM_InstModification

{

};

MOF of Windows 8 SDK MIAPI Sample

For complete MOF syntax, please refer to DSP0004 version 2.6.0.

Haowei Qin

Senior SDE

Standards Based Management

Implementing MI Provider (1) - Overview

Haowei Qin [MSFT] — Wed, 08 May 2013 18:51:00 GMT

Blog Standards-based Management in Windows Server “8” gives overview of standard-based management and architecture of the new management stack introduced in Windows 8 and Windows Server 2012. “Implementing MI Provider” series blogs are about to discuss how to implement MI provider step by step, including a brief tutorial on implementing a MI provider; an introduction to MI API; preparations for writing a MI provider; defining schema; generating provider skeleton code; implementing MI provider skeleton; registering a MI provider; and debugging MI provider(s).

This blog is about to discuss the concept of MI provider; availability of MI API; and preparations for writing a MI provider.

What is MI Provider?

Before introducing MI Provider, I assume you have the knowledge about “what is WMI” and “how to write WMI provider”. Similar to a WMI provider, MI provider(s) are used to expose data and operations to client applications and/or administrators via CIMOM server, which is WMI on windows OS.

A MI provider implements MI provider interface, which is C based and compliant with CIM standard. A MI provider exposes both schema (CIM class) information of the manageable objects and operations against the manageable objects. Generally, MI provider can be divided into 3 categories, instance provider; association provider; and indication provider.

An instance MI provider supports intrinsic methods, including enumerate instance, get instance, create instance, delete instance and modify instance; and extrinsic methods, including instance method and static method.

An association MI provider is similar to WMI association provider, which is used to associate instances of different classes. Details will be discussed in the following blogs.

An indication MI provider is similar to WMI Event provider, which delivers notifications about the changes of manageable objects from server to client. A specific indication class provides notification when specific events occur. An indication provider may implements multiple indication classes. Details will be discussed in the following blogs.

Availability of MI provider API

Windows 8 and Windows Server 2012 introduce a new set of management APIs, called the Windows Management Infrastructure (MI) APIs. This includes MI provider C APIs, client C APIs, and client .Net APIs. These set of new APIs are more tightly aligned with the CIM standard that is the basis for WMI, and provide support for the standard WS-Man protocol via WinRM.

These new APIs will interoperate directly with existing Windows Management Instrumentation (WMI) clients and providers. An application written using the new client APIs work with pre-existing WMI providers as well as providers based on the new MI C APIs. Likewise, providers written using the new APIs can be called from client applications written using the older version of the WMI .Net and C APIs.

Table 1.0 contains list of terms that might be useful to understand the content of the blog.

Name	Definition
CIM Class	A schema that represents a managed resource type on server
CIM Instance	A snapshot representation of an instance of a CIM class on a CIMOM server
CIM Provider	Provides set of CIM standard operations of a CIM class
CIMOM server	A process which responds to the client CIOMI request to any managed resources

Table 1.0 Terminologies

MI provider development process

Windows 8 and Windows Server 2012 introduce a new provider model, with code generation and provider registration tools, which works seamlessly with MI provider API.

A C based provider code skeleton can be generated from user-defined schema in the form of a MOF file, using the tool called Convert-MofToProvider.exe, which ships in the Windows 8 SDK.

Register-CimProvider.exe is a new provider registration tool, and ships with Windows 8 and Windows Server 2012, and is used to register a MI provider into WMI. These tools work only for providers based on the new APIs.

Figure 1.0 shows steps of writing a CIM provider, the remaining content of the blog serials follows exactly those steps.

Figure 1.0 MI provider development process

Assume you have your MI provider ready, then, you may ask a question - how do I access the data and operations exposed by the CIM provider(s)? The short answer is "many ways". You could use MI C API, MI .Net API, and of course Powershell cmdlets.

Powershell Cmdlets

There are two types of cmdlets introduced by windows 8 and windows server 2012, CIM-Based cmdlets and generic CIM cmdlets.

A CIM-Based Cmdlet model was introduced to support creation of PowerShell cmdlets, which expose the data and the operations of any provider to PowerShell users. It introduces a new way to create cmdlets by using an XML file to describe the cmdlet functionality, and then importing the new module into PowerShell. This new way of writing cmdlets works with both new providers written using the MI APIs, and providers written using the older WMI APIs.

A set of generic cmdlets called CIM Cmdlets, which are based on the MI client .Net API, and help to consume the data and operations from any new or existing providers.

In order to provide seamless Powershell Cmdlet experiences, a set of Powershell semantics specific provider APIs were introduced to allow MI provider to write verbose message to Powershell, update operation progress data, ask user confirmation for dangerous operations, etc. Those APIs will be discussed in following blogs.

To start writing a CIM provider, following are the preparation steps.

Preparation

First of all, there are set of tools to help implementing and debugging a CIM provider. For each step of figure 1.0, there are some tools available.

(1) For schema defining, you can use CIM IDE. Of course, you can create the mof in any text editor.

(2) Convert-MofToProvider.exe is used to generating provider skeleton code, which is shipped as of windows 8 SDK.

(3) You need visual studio 2012 and windows 8 SDK to implement and build the provider MI API sample, which contains a set of MI provider samples.

(4) Register-CimProvider.exe is the tool used for registering CIM provider(s) into WMI.

(5) For debugging a provider, you can use either visual studio 2012 or Windbg.

To setup a development environment, you may need to,

(1) Install visual studio 2012

(2) Install windows 8 SDK, which contains set of tools listed above; MI API header file as well as lib file, called mi.h and mi.lib respectively; and mi.net api.

(3) Install MI API sample, which contains several MI provider samples.

(4) If your class derives from DMTF standard class, then you may have to download the CIM standard schema from DMTF website.

Haowei Qin [MSFT]
Senior SDE
Standards Based Management

How to Implement a Profile Registration Provider

SBM Team [MSFT] — Mon, 25 Mar 2013 22:55:00 GMT

Introduction

The DMTF standard uses profiles to perform namespace
discovery. As an implementer of a
profile, you need to register a profile object that points to the
namespace of the implementing class. The profile object must be implemented under the root/interop namespace.

Profile Registration MOF Files

http://www.dmtf.org/sites/default/files/standards/documents/DSP1033_1.0.0.pdf

The above document fully describes the necessary profile
classes that the provider needs to implement.

For example, in order to implement the Ethernet switch
profile, you need to first
create the CIM_EthernetSwitchProfile class that derives from
CIM_RegisteredProfile as well as the CIM_EthernetSwitchConformsToProfile class
that derives from CIM_ElementConformsToProfile. The second class is an
association that provides the concrete implementation of the Ethernet switch
class (e.g. CIM_ComputerSystem).

Profile Registration Provider Implementation

Once the MOF files are created, you need to generate a provider skeleton. This can be done using
the following command:

Convert-MofToProvider –MofFile <Mof file location>
-ClassList CIM_EthernetSwitchProfile CIM_EthernetSwitchProfileConformsToProfile

After creating the provider skeleton, you need to implement
EnumerateInstances by returning a static instance of the
CIM_EthernetSwitchProfile class. Here
is a sample implementation of EnumerateInstances:

/*
**==============================================================================
**
** Open Management Infrastructure (OMI)
**
** Copyright (c) Microsoft Corporation
**
** Licensed under the Apache License, Version 2.0 (the "License"); you may not
** use this file except in compliance with the License. You may obtain a copy
** of the License at
**
** http://www.apache.org/licenses/LICENSE-2.0
**
** THIS CODE IS PROVIDED *AS IS* BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
** KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY IMPLIED
** WARRANTIES OR CONDITIONS OF TITLE, FITNESS FOR A PARTICULAR PURPOSE,
** MERCHANTABLITY OR NON-INFRINGEMENT.
**
** See the Apache 2 License for the specific language governing permissions
** and limitations under the License.
**
**==============================================================================

void MI_CALL MSFT_EthernetSwitchProfile_EnumerateInstances(

_In_opt_ MSFT_EthernetSwitchProfile_Self* self,

_In_ MI_Context* context,

_In_opt_z_ const MI_Char* nameSpace,

_In_opt_z_ const MI_Char* className,

_In_opt_ const MI_PropertySet* propertySet,

_In_ MI_Boolean keysOnly,

_In_opt_ const MI_Filter* filter)

{

CIM_RegisteredProfile staticEthernetSwitchProfile;

CIM_RegisteredProfile_Construct(&staticEthernetSwitchProfile,
context);

CIM_RegisteredProfile_Set_InstanceID(&staticEthernetSwitchProfile,
MI_T("EthernetSwitchProfile"));

CIM_RegisteredProfile_Set_RegisteredName(&staticEthernetSwitchProfile,
MI_T("Ethernet Switch Profile"));

CIM_RegisteredProfile_Set_RegisteredOrganization(&staticEthernetSwitchProfile,
1); // Other
organization

CIM_RegisteredProfile_Set_OtherRegisteredOrganization(&staticEthernetSwitchProfile,
MI_T("Microsoft"));

CIM_RegisteredProfile_Set_RegisteredVersion(&staticEthernetSwitchProfile,
MI_T("1.0"));

CIM_RegisteredProfile_Post(&staticEthernetSwitchProfile, context);

MI_Context_PostResult(context, MI_RESULT_OK);

}

You need to
implement the EnumerateInstances method of CIM_EthernetSwitchConformsToProfile
by returning the actual implementation of the Ethernet switch (e.g. CIM_ComputerSystem)
as a CIM_ManagedElement. Here is a
sample implementation of EnumerateInstances:

void MI_CALL MSFT_EthernetSwitchConformsToProfile_EnumerateInstances(

_In_opt_ MSFT_EthernetSwitchConformsToProfile_Self* self,

_In_ MI_Context* context,

_In_opt_z_ const MI_Char* nameSpace,

_In_opt_z_ const MI_Char* className,

_In_opt_ const MI_PropertySet* propertySet,

_In_ MI_Boolean keysOnly,

_In_opt_ const MI_Filter* filter)

{

MSFT_EthernetSwitchConformsToProfile element;

CIM_ManagedElement computerSystem;

CIM_ManagedElement_Construct(&computerSystem,
context);

CIM_ManagedElement_Set_InstanceID(&computerSystem,
MI_T("ComputerSystem"));

CIM_ManagedElement_Set_Caption(&computerSystem,
MI_T("TOR Switch Computer System"));

CIM_ManagedElement_Set_Description(&computerSystem,
MI_T("Replace with concrete implementation"));

MSFT_EthernetSwitchConformsToProfile_Construct(&element,
context);

MSFT_EthernetSwitchConformsToProfile_Set_ConformantStandard(&element,
&staticEthernetSwitchProfile);

MSFT_EthernetSwitchConformsToProfile_Set_ManagedElement(&element,
&computerSystem);

MSFT_EthernetSwitchConformsToProfile_Post(&element,
context);

MSFT_EthernetSwitchConformsToProfile_Destruct(&element);

CIM_ManagedElement_Destruct(&computerSystem);

MI_Context_PostResult(context, MI_RESULT_OK);

}

Provider Registration

Multiple profiles
should be combined into one single provider. The provider can be registered
using the following command:

James Wei
[MSFT]

Windows Management Framework 3.0 Compatibility Update

SBM Team [MSFT] — Thu, 20 Dec 2012 02:16:00 GMT

We have an important update regarding WMF 3.0 ("Windows Management Framework") compatibility. Those who want to install WMF 3.0 to take advantage of all the great features this update provides can do so by installing the update from the Microsoft Download Center, after reading the known compatibility issues detailed in the blog post below.

http://blogs.msdn.com/b/powershell/archive/2012/12/20/windows-management-framework-3-0-compatibility-update.aspx

WMI cheat sheet and link to MSDN documentation

Osama Sajid [MSFT] — Sun, 28 Oct 2012 20:59:00 GMT

WMI team created a useful cheat sheet summarizing what's new in WMI. This is a great reference doc for developers. We are making them available through this blog post - as is.

The real documentation is still on MSDN (and it is being regularly updated). Cheat sheets are just a quick reference to get people started.

Some other useful links

WMI – MI API docs on MSDN	MSDN location of the new WMI Management Infrastructure API documentation.
SDK Samples	MI API Samples
WMF 3.0 download	Download the Windows Management Framework. Contains WMI, WS-Man & PowerShell updates from Win8. Applies to WinSrv2008, 2008R2, and Win7.
CIM IDE download	CIM IDE tool is a Visual Studio snap-in used to build WMI providers & CDXML.

Thanks to Keith Bankston, lead WMI PM , for authoring this this cheat sheet and sharing with community.

Thanks

Osama Sajid

Program Manager

PowerShell cmdlets invocation through Management ODATA using WCF client

Narine Mossikyan [MSFT] — Tue, 11 Sep 2012 00:35:00 GMT

Management ODATA uses the Open Data Protocol (ODATA) to expose and consume data over the Web or Intranet. It is primarily designed to expose resources manipulated by PowerShell cmdlets and scripts as
schematized ODATA entities using the semantics of representational state transfer (REST). The philosophy of REST ODATA limits the verbs that can be supported on resources to only the basic operations: Create, Read, Update and Delete.
In this topic I will talk about Management ODATA being able to expose resources that model PowerShell pipelines that return unstructured data. This is an optional feature and is called “PowerShell
pipeline invocation”. A single Management ODATA endpoint can expose schematized resources, or the arbitrary cmdlet resources or both.

In this blog I will show how to write a windows client built on WCF that creates a PowerShell pipeline invocation on MODATA endpoint. Any client can be used that supports ODATA. WCF Data Services includes a set of client libraries for general .NET Framework client applications that is used in this example. You can read more about WCF at: http://msdn.microsoft.com/en-us/library/cc668792.aspx. If you are building a WCF client, the only requirement is to use WCF Data Services 5.0 libraries to be compatible. In this topic I will assume you already have a MODATA endpoint configured and up and running. For more information on MODATA in general and how to create an endpoint please refer to msdn documentation at http://msdn.microsoft.com/en-us/library/windows/desktop/hh880865(v=vs.85).aspx

Since “PowerShell pipeline invocation” feature is an optional feature and is disabled by default, you will need to enable it by adding the following configuration to your MODATA endpoint web.config:

Table 1.1 – Enable Command Invocation

To make sure “PowerShell pipeline invocation” is now enabled, you will need to send a GET http://endpoint_service_URI/$metadata query to MODATA endpoint and should see a similar response in return:

Table 1.2 - Command Invocation Schema Definition

Management ODATA defines two ODATA resource sets related to PowerShell pipeline invocation: CommandDescriptions and CommandInvocations.
The CommandDescriptions resource set represents the collection of commands available on the server.
By enumerating the resource set, a client can discover the commands that it is allowed to execute and their parameters.The client must be authorized to execute Get-Command cmdlet for the CommandDescriptions query to succeed. At a high level, if a client sends the following request:

GET http://endpoint_service_URI/CommandDescriptions

Table 1.3 – Command Invocation Query Sample

…then the server might reply with the following information:

<entry>
<id>http://endpoint_service_URI/CommandDescriptions('Get-Process')</id>
<category scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" term="PowerShell.CommandDescription"/><link title="CommandDescription" href="CommandDescriptions('Get-Process')" rel="edit"/><title/><updated>2012-09-10T23:14:52Z</updated>-<author>
<name/>
</author>-<content type="application/xml">
-<m:properties>
    <d:Name>Get-Process</d:Name><d:HelpUrl m:null="true"/><d:AliasedCommand m:null="true"/>-<d:Parameters m:type="Collection(PowerShell.CommandParameter)">
      -<d:element>
        <d:Name>Name</d:Name>
        <d:ParameterType>System.String[]</d:ParameterType>
      </d:element>-<d:element>
        <d:Name>Id</d:Name>
        <d:ParameterType>System.Int32[]</d:ParameterType>
      </d:element>-<d:element>
        <d:Name>ComputerName</d:Name>
        <d:ParameterType>System.String[]</d:ParameterType>
      </d:element>-<d:element>
        <d:Name>Module</d:Name>
        <d:ParameterType>System.Management.Automation.SwitchParameter</d:ParameterType>
      </d:element>-<d:element>
        <d:Name>FileVersionInfo</d:Name>
        <d:ParameterType>System.Management.Automation.SwitchParameter</d:ParameterType>
      </d:element>-<d:element>
        <d:Name>InputObject</d:Name>
        <d:ParameterType>System.Diagnostics.Process[]</d:ParameterType>
      </d:element>-<d:element>
        <d:Name>Verbose</d:Name>
        <d:ParameterType>System.Management.Automation.SwitchParameter</d:ParameterType>
      </d:element>-<d:element>
        <d:Name>Debug</d:Name>
        <d:ParameterType>System.Management.Automation.SwitchParameter</d:ParameterType>
      </d:element>-<d:element>
        <d:Name>ErrorAction</d:Name>
        <d:ParameterType>System.Management.Automation.ActionPreference</d:ParameterType>
      </d:element>-<d:element>
        <d:Name>WarningAction</d:Name>
        <d:ParameterType>System.Management.Automation.ActionPreference</d:ParameterType>
      </d:element>-<d:element>
        <d:Name>ErrorVariable</d:Name>
        <d:ParameterType>System.String</d:ParameterType>
      </d:element>-<d:element>
        <d:Name>WarningVariable</d:Name>
        <d:ParameterType>System.String</d:ParameterType>
      </d:element>
    </d:Parameters>
</m:properties>
</content>
</entry>

Table 1.4 – Command Response Sample

This indicates that the client is allowed to execute the Get-Process cmdlet.

The CommandInvocations resource set represents the collection of commands or pipelines that have been invoked on the server. Each entity in the collection represents a single invocation of some PowerShell pipeline. To invoke a pipeline, the client sends a POST request containing a new entity. The contents of the entity include the PowerShell pipeline itself (as a string), the desired output format (typically “xml” or “json”), and the length of time to wait synchronously for the command to complete. A pipeline string is a sequence of one or more commands, optionally with parameters and delimited by a vertical bar character. For example, if the server receives the pipeline string “Get-Process –Name iexplore”,with output type specified as “xml” then it will execute the Get-Process command (with optional parameter Name set to “iexplore”), and send its output to “ConvertTo-XML”.

The server begins executing the pipeline when it receives the request. If the pipeline completes quickly (within the synchronous-wait time) then the server stores the output in the entity’s Output property, marks the invocation status as “Completed”, and returns the completed entity to the client.

If the synchronous-wait time expires while the command is executing, then the server marks the entity as “Executing” and returns it to the client. In this case, the client must periodically request the updated entity from the server; once the retrieved entity’s status is “Completed”, then the pipeline has completed and the client can inspect its output. The client should then send an ODATA DeleteEntity request, allowing the server to delete resources associated with the pipeline.

There are some important restrictions on the types of commands that can be executed. Specifically, requests that use the following features will not execute successfully:

1. script blocks
2. parameters using environment variables such as "Get-Item -path $env:HOMEDRIVE\\Temp"
3. interactive parameters such as –Paging (Get-Process | Out-Host –Paging )

Authorization and PowerShell initial session state are handled by the same CLR interfaces as for other Management ODATA resources. Note that every invocation calls some ConvertTo-XX cmdlet, controlled by the OutputFormat property of the invocation. The client must be authorized to execute this cmdlet in order for the invocation to succeed.

Here is the code snippet that shows how to send a request to create a PowerShell pipeline invocation and how to get the cmdlet execution result:

   public class CommandInvocationResource
    {
        public Guid ID { get; set; }

public string Command { get; set; }

public string OutputFormat { get; set; }

public int WaitMsec { get; set; }

public string Status { get; set; }

public string Output { get; set; }

public List<ErrorRecordResource> Errors { get; set; }

public DateTime ExpirationTime { get; set; }

        public CommandInvocationResource()
        {
            this.Errors = new List<ErrorRecordResource>();
        }
    }

    public class ErrorRecordResource
    {
        public string FullyQualifiedErrorId { get; set; }

public ErrorCategoryInfoResource CategoryInfo { get; set; }

public ErrorDetailsResource ErrorDetails { get; set; }

public string Exception { get; set; }
}

    public class ErrorCategoryInfoResource
    {
        public string Activity { get; set; }

public string Category { get; set; }

public string Reason { get; set; }

public string TargetName { get; set; }

public string TargetType { get; set; }
}

    public class ErrorDetailsResource
    {
        public string Message { get; set; }

public string RecommendedAction { get; set; }
}

Table 2.1 – Helper class definitions

// user needs to specify the endpoint service URI as well as provide user name, password and domain
Uri serviceroot = new Uri(“<endpoint_service_URL>”);
NetworkCredential serviceCreds = new NetworkCredential("testuser","testpassword","testdomain");
CredentialCache cache = new CredentialCache();
cache.Add(serviceroot, "Basic", serviceCreds);

//Powershell pipeline invocation command sample
string strCommand ="Get-Process -Name iexplore";

// Expect returned data to be xml formatted. You can set it to “json” for the returned data to be in json
string outputType = "xml";

//create data service context with protocol version 3 to connect to your endpoint. V3 supports all new ODATA fetures like property bags that is required for "PowerShell cmdlet invocation" feature
DataServiceContext context = new DataServiceContext(serviceroot,System.Data.Services.Common.DataServiceProtocolVersion.V3);
context.Credentials = cache;

//Create an invocation instance on the endpoint
CommandInvocationResource instance = new CommandInvocationResource()
{
Command = strCommand,
OutputFormat = outputType

};
context.AddObject("CommandInvocations", instance);
DataServiceResponse data = context.SaveChanges();

// Ask for the invocation instance we just created
DataServiceContext afterInvokeContext = new DataServiceContext(serviceroot,
System.Data.Services.Common.DataServiceProtocolVersion.V3);
afterInvokeContext.Credentials = cache;
afterInvokeContext.MergeOption = System.Data.Services.Client.MergeOption.OverwriteChanges;
CommandInvocationResource afterInvokeInstance = afterInvokeContext.CreateQuery
<CommandInvocationResource>("CommandInvocations").Where(it => it.ID == instance.ID).First();

Assert.IsNotNull(afterInvokeInstance, "instance was not found!");
while (afterInvokeInstance.Status == "Executing")
{
    //Wait for the invocation to be completed
   Thread.Sleep(100);
   afterInvokeInstance = afterInvokeContext.CreateQuery<CommandInvocationResource>
   ("CommandInvocations").Where(it => it.ID == instance.ID).First();
}

if (afterInvokeInstance.Status == "Completed")
{
   //Results is returned as a string in afterInvokeInstance.Output variable in xml format
}

// In case the command execution has errors you can analyze the data
if (afterInvokeInstance.Status == "Error")
{
    string errorOutput;
    List<ErrorRecordResource> errors = afterInvokeInstance.Errors;
    foreach (ErrorRecordResource error in errors)
    {
      errorOutput += "CategoryInfo:Category " + error.CategoryInfo.Category + "\r\n";
        errorOutput += "CategoryInfo:Reason " + error.CategoryInfo.Reason + "\r\n";
        errorOutput += "CategoryInfo:TargetName " + error.CategoryInfo.TargetName + "\r\n";
        errorOutput += "Exception " + error.Exception + "\r\n";
        errorOutput += "FullyQualifiedErrorId " + error.FullyQualifiedErrorId + "\r\n";
        errorOutput += "ErrorDetails" + error.ErrorDetails + "\r\n"; }
}

//Delete the invocation instance on the endpoint
afterInvokeContext.DeleteObject(afterInvokeInstance);
afterInvokeContext.SaveChanges();

Table 2.2 – Client Code Implementation

Narine Mossikyan
Software Engineer in Test
Standards Based Management

Introduction to CIM Cmdlets

Vaibhav Chugh — Wed, 29 Aug 2012 19:04:41 GMT

We recently posted a blog post related to our new CIM Cmdlets. The post is available on the powershell blog at the following link:

http://blogs.msdn.com/b/powershell/archive/2012/08/24/introduction-to-cim-cmdlets.aspx

We would love to know what you think about these new cmdlets. Please feel free to leave your comments below or on the powershell blog.

Thanks

Vaibhav Chugh [MSFT], WMI

Standards Based Hardware Management using PowerShell

Steve Lee [MSFT] — Wed, 08 Aug 2012 19:26:00 GMT

In my last post, I discussed the concept of DMTF Management Profiles and in this blog post I’m going to discuss applying them. Standards (particularly adopted ones) enable not only interoperability, but also reuse of tools. WS-Man enables a common remote management protocol. CIM Schema enables consistent models of management elements. DMTF Management Profiles enable consistent implementations of CIM models for a specific management domain. However, these standards are not sufficient for ITPros to easily manage their datacenter because although all the pieces are there, they were not designed to be easy to use (for ITPros).

PowerShell enables ITPros make easily make sense of this complexity, but only if there is an appropriate admin task abstracted cmdlet. In WMF3.0, we added new CIM cmdlets (get-ciminstance, invoke-cimmethod, etc…) that enable managing a remote CIM enabled node (over WS-Man by default), however, these cmdlets still require understanding of CIM, in some cases WS-Man, and certainly the DMTF Management Profile. These cmdlets were targeted more for the ITPro developer.

To solve this problem, I built a PowerShell module that uses the CIM cmdlets (and thus requires WMF3.0) and abstracts the details of CIM and Profiles to (mostly) simple admin task abstracted cmdlets. For the first release of this module, I’m targeting some common admin tasks: Getting hardware information, getting software information, getting and setting power state, getting and setting the boot order, getting the OS status, getting numeric sensors, and getting record logs and log entries.

Here I create two CimSessions, one to a desktop system that has the Broadcom DASH implementation and one to a desktop that has Intel’s AMT implementation. You’ll notice that the two systems listen on different ports. Port 623 is the HTTP port required by DASH conformant implementations. Intel's AMT supports both the DASH port (623) as well as an AMT specific port. In this example, I illustrate what it would look like to use two different ports.

Now, let’s turn on the first system. Retrieving the power state again, you can see that we were able to remotely turn on that system even though the OS was not running and the hardware was in a sleep (standby) state. The RequestedState showing Offline is a known issue.

Next, let’s gather some inventory information which uses multiple Management Profiles. Here you can see that the default formatting only shows a summary in tabular format while piping the same output to a list view shows all the information returned by the two respective implementations. Also notice that in many cases, I use the CIM values/valuemap data to convert integers to their textual counterparts.

Next, let’s see what software (meaning firmware in the case of hardware) is on these two systems:

Finally, a common operation you would want to do in hardware is to change the boot order. For example, let’s say you wanted to do a one-time network (PXE) boot to install the operating system. Here, we retrieve the current boot sources and configuration. Then we change the boot source to Network and finally retrieve the boot information again to confirm the change will be used:

As you can see, the complexities of CIM and Management Profiles are hidden with the PowerShell module so the ITPro only needs to focus on the tasks they care about without needing to understand the implementation details. The module itself is written as PowerShell script so you can see how everything works. You’ll note that I have many TODOs in the module which means that I will continue to improve upon this module with additional capabilities in the future.

The module is available on TechNet here: PowerShell Out-of-Band Hardware Management Module

Steve Lee [MSFT]
Principal Test Manager
Standards Based Management