Association Traversal Using WSMan cmdlets

First let us review the concept of “CIM/WMI association”, then we’ll show examples on how to perform association traversal using WSMan-related cmdlets. Please note this is a generic discussion about association traversal but targeting Win7 implementation. Applying them to standard interop namespace and discovering DMTF profiles and associated instances targeting 3rd party implementation will be discussed later in detail in a separate blog.

 

In this blog, we discuss three topics:

• Concept of “CIM/WMI association”

• Associated instance traversal

• Association instance traversal

 

1) Concept of “CIM/WMI association”

An association in CIM/WMI describes a relationship between two or more classes. Every association is represented by a CIM/WMI association class that contains two or more references. The CIM uses "association" to link different parts of the enterprise model together. WMI also supports associations.

 

Taking the example of services on windows. Win32_Service WMI class represents a service on a computer system running Windows. Win32_ComputerSystem WMI class represents a computer system. A windows service is part of a computer system, this relationship is defined by the association class Win32_SystemServices which relates a computer system and a service program that exists on the system. A windows service may have several dependencies on other services, eg., WinRM service cannot start up unless both RpcSs and HTTP services start up. This dependency is defined by an association class Win32_DependentService which relates two interdependent services.

 

Win32_ComputerSystem?Name=MachineName

                                |

                                | Win32_SystemServices

                                |

Win32_Service?Name=winrm

                                |

                                | class Win32_DependentService

                                | {

                                | Win32_BaseService ref Antecedent;

                                | Win32_BaseService ref Dependent;

                                | };

                                |

Win32_Service?Name=RpcSs

 

2) Associated instance traversal

Here we want to retrieve instances that are associated with a particular source instance (rather than the intervening association instances). In the above diagram, the starting source instance is “Win32_Service?Name=winrm”, associated instance traversal will retrieve target instance “Win32_Service?Name=RpcSs”. The instances that are retrieved are referred to as the endpoints. Each endpoint is returned as many times as there are associations between it and the source object

 

The basic syntax for associated instance traversal using WSMan cmdlets is

Get-WSManInstance -Enumerate -ResourceURI <Uri> -Dialect <Uri> -filter <string> ……

Where filter string has the following format

{Object=EPR [;AssociationClassName=AssocClassName][;ResultClassName=ClassName]

[;Role=RefPropertyName][;ResultRole=RefPropertyName]}

Note: The filters enclosed in [] are optional. For example

PS C:\Windows\system32> Get-WSManInstance -Enumerate -ResourceURI wmicimv2/* -Dialect Association -filter "{Object=Win32_Service?Name=WinRM;

AssociationClassName=Win32_DependentService;ResultClassName=win32_service;

ResultRole=antecedent;Role=dependent}"

xsi : https://www.w3.org/2001/XMLSchema-instance

p : https://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32\_Service

cim : https://schemas.dmtf.org/wbem/wscim/1/common

type : p:Win32_Service_Type

lang : en-US

AcceptPause : false

……………………………………………………………………

 

Object: the source object is represented by an EPR such as “Win32_Service?Name=WinRM”. It is imperative to provide an EPR(Object) at a minimum to be able to retrieve associated instances, all others are optional and they’re used to narrow down on the associated instances.

AssociationClassName: Name of an association class such as “Win32_DependentService”. Specifying this qualifier implies a request for associated instances of a source Object which are associated to each other through this association class. The returned endpoints must be associated with the source through the specified class or one of its derived classes.

ResultClassName: Name of a CIM/WMI class (not an association) such as “Win32_Service”. Specifying this qualifier implies a request for associated class instances of (or derived from) ResultClassName which are associated to a source Object. The returned endpoints associated with the source object must belong to or be derived from the specified class.

Role: Name of a reference property defined in the association class such as “dependent”. Specifying this qualifier implies a request for associated instances that participate in an association where source Object plays this Role. In the above example, WinRM service is dependent on RpcSs service

ResultRole: Name of a reference property defined in the association class such as “antecedent”. Specifying this qualifier implies a request for associated instances that play this ResultRole in their association with the source Object. In the above example RpcSs service is antecedent so it must be started first before dependent WinRM service can be started

 

3) Association instance traversal

Here we want to retrieve all association instances that refer to a particular source instance (rather than the associated endpoints). In the above diagram, the starting source instance is “Win32_Service?Name=winrm”, association instance traversal will retrieve instances “Win32_DependentService”. The instances that are retrieved are the intervening association instances

 

The basic syntax for association instance traversal using WSMan cmdlets is

Get-WSManInstance -Enumerate -ResourceURI <Uri> -Dialect <Uri>

-Associations -filter <string> ……

Where filter string has the following format

{Object=EPR[;ResultClassName=ClassName][;Role=RefPropertyName]}

Note: The filters enclosed in [] are optional. -Associations indicate retrieval of association instances as opposed to associated instances. For example

PS C:\Windows\system32> Get-WSManInstance -Enumerate wmicimv2/* -Dialect Association

-filter "{Object=Win32_Service?Name=WinRM;

ResultClassName=Win32_DependentService;Role=dependent}" -Associations

xsi : https://www.w3.org/2001/XMLSchema-instance

p : https://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32\_DependentService

cim : https://schemas.dmtf.org/wbem/wscim/1/common

type : p:Win32_DependentService_Type

lang : en-US

Antecedent : Antecedent

Dependent : Dependent

TypeOfDependency : TypeOfDependency

xsi : https://www.w3.org/2001/XMLSchema-instance

p : https://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32\_DependentService

cim : https://schemas.dmtf.org/wbem/wscim/1/common

type : p:Win32_DependentService_Type

lang : en-US

Antecedent : Antecedent

Dependent : Dependent

TypeOfDependency : TypeOfDependency

 

Object: the source object is represented by an EPR such as “Win32_Service?Name=WinRM”. It is imperative to provide an EPR(Object) at a minimum to be able to retrieve association instances, all others are optional and they’re used to narrow down on the association instances.

ResultClassName: Name of the CIM/WMI association class such as Win32_DependentService. Specifying this qualifier implies a request for association class instances of (or derived from) ResultClassName for a source Object. The returned association objects must belong to or be derived from the specified class

Role: Name of a reference property defined in the association class such as “dependent”. Specifying this qualifier implies a request for those association instances where the source Object plays this Role in the association. In the above example, WinRM service is dependent on some other services