How to manage WMI qualifiers with PowerShell [WMI week – day 5]

This is the 5th post of a series of 6 articles entitled “WMI Week“. It tends to covers the automation tasks around WMI mainly using the powershell WMI module.

The first gives a short introduction concerning WMI, and show what tools are usefull when working with WMI. The second post covers how to manage WMI namespaces using windows powershell. The third post highlights how we can, create, retrieve delete, and manage WMI classes.  The fourth post  covers everything you need to know about WMI properties. The fifth post (this one)   will highlight everything related to WMI qualifiers, and the last and six’th post will explain everything you need the know about WMI Instances.

[important]By the way,the powershell WMI module is available here ( and Don’t forget to rate it  by clicking on the stars ;)).[/important]

Ok,on y va!

---

Hello hello everybody. Today is was quite a day. I was originally suppose to leave for the amazing city of Amsterdam today in order to meet the other scripting geeks for the european Powershell summit. I am quite excited about the event, but I wont open my laptop before this sunday since the there is currently a strike in France (again…). I had to change my flight, and instead of flying out tonight, I will only on sunday night… 🙁 (I was planning to visit family and friends during this weekend..).I was really looking forward to run again on the never-ending-dikes from Almere like I did years ago (Time flies…).

anyway’s let’s continue our WMI week and talk about WMI qualifiers.In today’s post, we will tackle the following topics:

• What is a WMI qualifier?
• How to retrieve the qualifiers ?
• What is a key qualifier and how to identify it.
• How to create / add a new qualifier to a property?
• How to delete / remove a qualifier?
• Download link (Also available above)

What is a WMI qualifier?

a WMI what? WMI can already be confusing, but let’s add an extra layer, just for the fun 😛

What is a Qualifier?

According to the MSDN web site, this is the definition of a WMI qualifier:

 

A qualifier is a data string that provides more information about a class, instance, property, method, or parameter.

 

Using my words, I would say that A WMI qualifier is a something like an attribute that will give additional information to our property. Every property can have one or several property qualifiers, but it should have at least one.

Technically, you can create a property within a class without any property qualifiers, but you wont be able to instanciate that class. In order to Instanciate a WMI class, you will need to have a something that is called a key qualifier.

A Key qualifier, could be compared to a primary key for example in SQL. This value needs to be given, and is the first source of our information. Key qualifiers are not the only qualifier that we can have, there are actually A LOT more. but for we will focus primarly on the key qualifier to keep things simple, since the principle is actually the same. Once you understood the concepts (which are not so hard heh^^) behind the Key qualifier, then you will have understood all about qualifiers. 🙂

[important]Qualifiers can be CIM or WMI specefic[/important]

How to work with wmi qualifiers?

lets look up the cmdlets we have to work with qualifiers:

 

we have 4 cmdlets that we can use in order to work with qualifier in the wmi-commands module.

• Get-WMIKeyqualifier
• Get-WMIQualifier
• Remove-WMIQualifier
• Set-WMIQualifier

Their names are pretty straitght forward, so I suggest we go foward and deep dive right into the interesting stuff!

How to find a wmi qualifier?

To find a property qualifier with the default powershell cmdlets I have to say that it is not really that easy.Thats why I actually wrote the WMI module. To retrieve information about property qualifiers you should use Get-WMIQualifier. Let’s look at the “path” property from the win32_share class. For that, we will use the following command:

This will return us the following information:

 

We can see that for the path property, we have 3 qualifiers that are returned using the get-wmiqualifier cmdlet.

To make it more readible, we will filter the query and only display the qualifier names using the following command:

The following 3 qualifiers are actually on the property “path”:

• CIMTYPE
  Technet definition: Contains text describing the type of a property.

• MappingStrings
  Technet definition: Set of values that indicate a path to a location where you can find more information about the origin of a property, class, association, indication, or reference.

• Read
  Technet definition: Indicates whether the property is readable. The default is TRUE.
  

So as I mentionned earlier, the WMI qualifiers are something that could be compared to attributes that we find in the filesystem. It gives us extra information on the item that we are retrieving the qualifier from.

Let’s get another example and dig into the “Name” property of the same “win32_share” class.

The following results will be returned:

Here we will find the following same qualifiers as before:

• CIMTYPE:
  Technet definition: Contains text describing the type of a property.

• MappingStrings:
  Technet definition: Set of values that indicate a path to a location where you can find more information about the origin of a property, class, association, indication, or reference.

• Read:
  Technet definition: Indicates whether the property is readable. The default is TRUE.

and two new ones:

• Override:
  Technet definition: Parent class or subordinate construct (property, method, or reference) which is overridden by the property, method, or reference of the same name in the derived class. The default is NULL.

• Key:
  Technet definition: The Key qualifier indicates whether the property is part of the namespace handle. If more than one property has the Key qualifier, then all such properties collectively form the key (a compound key). When taken together, the key properties must supply a unique reference for each class instance. If this qualifier is placed on a property, only the value TRUE is allowed.

 

In other words, the key qualifier identify the unique(s) properties that HAVE to be set when you want to instanciate a class. There wasn’t a key property for the path property, but there is one for the name property.

Let’s finalize this with a last example and let’s look at the qualifiers of the description property of the same win32_share class.

We have the following qualifiers for the description property:

• CIMTYPE:
  Technet definition: Contains text describing the type of a property..

• Read:
  Technet definition: Indicates whether the property is readable. The default is TRUE.

As you can see, whe have no key qualifiers for the Description property. And this is actually very logic, and will tell you why I actually choose the description property.

When you create a normal filesystem share, on a server or even on your own personal laptop, we need to provide it with a name AND a path. IF we want, we can add a description to it, but it is NOT obligatory. We could have a share without description. BUT we will always need to give a name to our share. A share without a name is actually not even a share. How would you refer to it? Also, the name of the share has to be unique. The name of the share will be the property that you will use in order to differenciate them from each other. It is a unique property. When we want to create a new share (create an instance of the win32_share, or “instanciate” it, we will need to provide a unique name for the share name. Technically, a folder (path) on a file system can have several shares (name) but each of this share has to be unique.

[important]Point 1:To sum up, the key property of a class, is the property that needs to be set, in order to create a new instance of it. Remeber, try to create a share without giving it a name; Windows will never let you finish it without you giving that parameter. The same principale occurs when you want to created a new instance of WMI class.[/important] [important] Point 2: The key qualifier has another very important role, and it is again related to the instanciation. When the intanciation is done, the value of the key property will also be used in order to generate the path to the WMI instance. The value of the key property It will be contained in __PATH and in the __RELPATH system properties. I will explain this in the chapter concerning instances.[/important]

How to get a wmi key property with powershell?

Ok great!, now that we know that, we can go on and start to dig deeper in the qualifiers possibilities. Yes, but I have a bonus here for you 😉
Sometimes, you will need to find the property key(s) of a class in order to create a new instance of it. You can either use the code I wrote above in order to find the key(s) or make your life simple and use the Get-KeyQualifier

The returned results are the following ones:

We can see we receive an object of the key qualifier of the win32_share class. As before, the key qualifier is the property with the name “name”

[notice]Remember, to find the key qualifier of specefic class, use the Get-WMIKeyQualifier [/notice]

How to create a new custom WMI Property qualifier with powershell?

Now that I explained what a WMI qualifier actually is, and why it is used for, let’s continue on our previously created example (the PowershellDistrict class) and let’s add a key qualifier to one of our existing properties.

Remember, IF we want to create and instance of our WMI class (Which is actually not even necessary), then we need to have at least one KEY qualifier.

In order to add a wmi property qualifier to an existing WMI property you will want to use the set–wmipropertyqualifier cmdlet as showed in the example below.

The cmdlet is pretty straitght forward, use it as followed in order to add a key qualifier to the url property:

 

It returns all the key(s) that are currently assigned to the property (and our key qualifier as well).

 

How to remove a WMI Property qualifier with powershell?

In order to remove a qualifier we will use the remove-WMIQualifier cmdlet as followed:

There is one caveat when we want to delete a qualifier, is that the class needs to no instance. If there is one or more, they need to deleted before the removal of the qualifier can really be done. If instance(s) are present, the following behaviour will happen.

To avoid this, the instances need to be removed first. We have not seen the WMI instances yet, but the following cmdlet will allow to delete them;

 

 

The following type of info is returned (the CM01 etc… was the RELPATH to the instance that was named “Plop“)

 

After deleting the instance(s) we can now delete the qualifiers with the previous command as showed underneath.

Download:

The download link is available hereunder.

[important]Download (and rate by clicking on the stars) the powershell WMI module here .[/important]

 

Dig more into it (References):

Standard qualifiers:

http://msdn.microsoft.com/en-us/library/aa393650(v=vs.85).aspx

Standard WMI qualifiers:

http://msdn.microsoft.com/en-us/library/aa393651(v=vs.85).aspx

Key qualifier:

http://msdn.microsoft.com/en-us/library/aa392157(v=vs.85).aspx

WMI qualifiers

http://msdn.microsoft.com/en-us/library/aa394571(v=vs.85).aspx

 

Ok, that is all for today. I will see you tomorow for new adventures and we will go through WMI instances.

Salut!

 [/fusion_builder_column][/fusion_builder_row][/fusion_builder_container]