Updating Part of an Instance

Occasionally, you may want to update only part of an instance. For example, some instances have a large number of properties. If you had to update a large number of these instances, you may reduce system performance. Therefore, you can choose to update only part of the instance, and thus reduce the amount of information you must send and retrieve to and from WMI. However, WMI does not directly support partial-instance operations, nor do most providers. Therefore, if you write an application that uses partial-instance operations, be prepared for your calls to fail with either the WBEM_E_PROVIDER_NOT_CAPABLE or WBEM_E_NOT_SUPPORTED error code in C++. In scripting languages the error codes are either wbemErrProviderNotCapable or wbemErrNotSupported.

In scripting, this operation is only necessary to aid performance when updating one or two writeable properties in a very large number of objects over an enterprise. Otherwise, the normal VBScript calls to SWbemObject.Put_ or SWbemObject.PutAsync_, while seeming to write the entire object, are actually only updating the properties which the provider has write-enabled.

The following procedure describes how to request a partial-instance update using PowerShell.

To request a partial-instance update using PowerShell

1. Retrieve the path of the object you wish to update.

   You can describe the path either manually, or else query the object and then retrieve the __Path property.

   $myWMIDrivePath = (get-wmiObject Win32_LogicalDisk -filter "Name = 'C:'").__Path
   #or
   $myWmiDrivePath = \\myComputer\root\cimv2:Win32_LogicalDisk.DeviceID="C:"
   

2. Set up a hash table listing the names of the properties to be updated, and use this hash table in a call to Set-WmiInstance.

   $newDriveName = @{VolumeName = "OSDisk"}
   Set-WmiInstance -Path $myWMIDrivePath -Arguments $newDriveName
   

The following procedure describes how to request a partial-instance update using C#.

To request a partial-instance update using C#

1. Create a new ManagementObject object that represents the specific instance to update.

   using System.Management;
   ...
   ManagementObject myDisk = new ManagementObject("Win32_LogicalDisk.DeviceID='C:'");
   

2. Set the property value with a call to ManagementObject.SetPropertyValue.

   myDisk.SetPropertyValue("VolumeName", "OSDisk");
   

The following procedure describes how to request a partial-instance update using VBScript.

To request a partial-instance update using VBScript

1. Create an SWbemNamedValueSet context object.

   Set objwbemNamedValueSet = CreateObject ("WbemScripting.SWbemNamedValueSet")
   

2. Add the Put extension values "__PUT_EXTENSIONS" and "__PUT_EXT_CLIENT_REQUEST" to the context object using the SWbemNamedValueSet.Add method.

   objwbemNamedValueSet.Add "__PUT_EXTENSIONS", True
   objwbemNamedValueSet.Add "__PUT_EXT_CLIENT_REQUEST", True
   

3. Set up an array listing the names of the properties to be updated and add this array to the SWbemNamedValueSet context object with the Put extension value "__PUT_EXT_PROPERTIES".

   arProperties = Array("propertyname1", "propertyname2") 
   objwbemNamedValueSet.Add "__PUT_EXT_PROPERTIES", arProperties
   

4. Set the iFlags parameter of the SWbemObject.Put_ call to wbemChangeFlagUpdateOnly. Without this flag the call will fail with an invalid context.

5. Pass your flag and context object to the provider in the objwbemNamedValueSet parameter of either SWbemObject.Put_ or SWbemObject.PutAsync_.

   call objSystem.put_( wbemChangeFlagUpdateOnly, objwbemNamedValueSet)
   

The following procedure describes how to request a partial-instance update using C++.

To request a partial-instance update using C++

1. Create an IWbemContext object with a call to CoCreateInstance.

   A context object is an object that WMI uses to pass in more information to a WMI provider. In this case, you are using the IWbemContext object to instruct the provider to accept partial-instance updates.

2. Add the "__PUT_EXTENSIONS" and "__PUT_EXT_CLIENT_REQUEST" named values to the IWbemContext object with a call to IWbemContext::SetValue.

   The following table lists the meaning of "__PUT_EXTENSIONS" and "__PUT_EXT_CLIENT_REQUEST".

   Named value	Description
   "__PUT_EXTENSIONS"	VT_BOOL set to VARIANT_TRUE. A value indicating that one or more of the other context values has been specified. This allows a quick check of the context object inside the provider to determine if partial-instance updates are being used.
   "__PUT_EXT_CLIENT_REQUEST"	VT_BOOL set to VARIANT_TRUE. Set by the client during the initial request. This value is used to prevent reentrancy errors.

    

3. Add the __PUT_EXT_STRICT_NULLS, __PUT_EXT_PROPERTIES, or __PUT_EXT_ATOMIC in any combination as needed to the IWbemContext object with another call to IWbemContext::SetValue.

   The following table lists the meaning of the named values.

   Named value	Description
   "__PUT_EXT_STRICT_NULLS"	VT_BOOL set to VARIANT_TRUE. Indicates that the client has intentionally set properties to VT_NULL and expects the write operation to succeed. If the provider cannot set the values to NULL, an error should be reported.
   "__PUT_EXT_PROPERTIES"	SAFEARRAY of strings containing a list of property names to be updated. May be used alone or in combination with "__PUT_EXT_PROPERTIES". The values are in the instance being written.
   "__PUT_EXT_ATOMIC"	VT_BOOL set to VARIANT_TRUE. Indicates that all updates must succeed simultaneously (atomic semantics) or the provider must revert back. There can be no partial success. May be used alone or in combination with other flags.

    

4. Set the iFlags parameter to WBEM_FLAG_UPDATE_ONLY. Without this flag the call will fail with an invalid context.

5. Pass the IWbemContext context object into any calls IWbemServices::PutInstance or IWbemServices::PutInstanceAsync in the pCtx parameter.

   Passing the IWbemContext object instructs the provider to allow partial-instance updates. In a full-instance update, you would set pCtx to NULL.

   The provider may write any necessary properties if the context object present in the call does not contain "__PUT_EXTENSIONS". If "__PUT_EXTENSIONS" is present in the context object, WMI requires the provider to either obey the semantics of the operation exactly or else fail the call. For more information, see Handling Access Denied Messages in a Provider.