Managing Clients with the ClientServicing Namespace

Applies To: Windows Server Update Services

The ClientServicing namespace must be used to register non-Windows clients running operating systems such as Windows Mobile. It must also be used to report on the updates available on these clients.

Registering clients with the ClientServicing namespace

You can register clients by first instantiating a ClientServicingProxy and then calling RegisterClient. The RegisterClient method takes a ClientInfo parameter that represents all the necessary information about the client. The following code shows how to populate a ClientInfo object for a client device that is running the Windows Mobile operating system.

ClientInfo info = new ClientInfo(Guid.NewGuid().ToString());  
info.DnsName = “someComputer.someDomain.com”;  
info.IPAddress = “123.12.123.123”;  
...  
info.OSFamily = “WindowsMobile”;

In order for the client to be recognized as a non-Windows client, the OSFamily property should contain a string that is not empty and is not “Windows”. (The default OSFamily value, if the OSFamily property is null or an empty string, is "Windows".) After you have filled out the ClientInfo object with the necessary information, you can use it to register the client with the WSUS server. The following example registers the client that was defined above for the Unassigned Computers computer group, since it passes in an empty StringCollection.

ClientServicingProxy proxy = new ClientServicingProxy();  
proxy.RegisterClient(info, new StringCollection());

Adding clients to specific target groups

When you register a non-Windows client in this way, you can also add it to one or more target computer groups if the WSUS server has client-side targeting turned on. If client-side targeting is not turned on, or if you attempt to add a client to a computer group that does not exist, the client will be assigned to the Unassigned Computers group. The following example adds the client defined above to the Accounting and Test computer groups.

StringCollection groupNameCollection = new StringCollection();  
groupNameCollection.Add(“Accounting”);  
groupNameCollection.Add(“Test”);  
proxy.RegisterClient(info, groupNameCollection);

Getting information about updates and approvals

The method GetPackageMetadataSet is used to get information about updates and their approvals. You can also use this method to retrieve updates and their approvals for custom categories and custom classifications. There are two overloads to this method, one that includes a MetadataStateCookie parameter and one that does not. When you want to get the complete set of update packages, or you are calling this method for the first time, use the overload without the cookie. The returned PackageMetadataSet object includes a LastChangeCookie property that indicates the date/time of the last change and its change number. If you want to get only the set of changes to updates, and you have a cookie from a previous call, use the overload that includes the cookie. The following example shows the different sets returned by the two overloaded methods.

//Get the complete set of updates  
PackageMetadataSet fullUpdates = clientServiceProxy.GetPackageMetadataSet(null, null);  
MetadataStateCookie lastCookie = fullUpdates.LastChangeCookie;  
//Get only the updates that have changed since the time of the last cookie  
PackageMetadataSet deltaUpdates = clientServiceProxy.GetPackageMetadataSet(null, null, lastCookie);

The PackageMetadataSet returned by these calls includes a set of SoftwareMetadata objects, which contain the basic information about the updates (prerequisites, installation behavior, etc.), as well as their approvals for different computer target groups. (The PackageMetadataSet may also include CategoryMetadata, ClassificationMetadata, and DetectoidMetadata] objects.) You can filter these SoftwareMetadata objects by category and classification.

If you invoke GetPackageMetadataSet with a NULL cookie on every call it may degrade the performance of the server. Instead, you should cache the results and use the cookie from the last call to get changes to the previously received updates and approvals. The HasPackageMetadataChanged is a light-weight call and must be used to check if there are changes to updates and approvals. If it returns true then GetPackageMetadataSet must be called. Also, to maintain an acceptable level of server performance GetPackageMetadataSet must not be called more than once a minute.

Finding the effective approval for an update

A SoftwareMetadata object returned as part of the package metadata from GetPackageMetadataSet has a property Approvals that contains the list of update approvals, each associated with a specific target group. Because a computer can belong to multiple target groups, there can be multiple approvals for a given client. The collection of update approvals in Approvals is sorted in descending order of precedence. To find the effective approval of an update for a given client, you should iterate through the Approvals collection to find an approval whose target group contains the client. The first approval found is the effective approval for the client. The following example shows how to find the effective approval for a client that belongs to the computer group with an id is "64C9E62C-9302-4B3C-AA8C-C44EF2F96479”. Please note that if a computer is part of multiple target groups, you should check for all the target groups.

PackageMetadataSet updates = clientServiceProxy.GetPackageMetadataSet(null, null);  
foreach (SoftwareMetadata update in updates)  
{  
   PackageApproval effectiveApproval;  
   ReadOnlyCollection<PackageApproval> approvals = update.Approvals;  
   foreach(PackageApproval approval in approvals)  
   {  
      if (approval.ComputerTargetGroupId == new Guid("64C9E62C-9302-4B3C-AA8C-C44EF2F96479"))  
      {  
         effectiveApproval = approval;  
         break;  
       }  
   }

Processing an approval

Before installing a software package, the client servicing proxy needs to evaluate the following properties of an approved update:

The property IsInstallableRule of the update evaluates to true.
The property IsSuperseded evaluates to false.
The property IsInstalledRule for each of the Prerequisites evaluates to true.
The property BundledPackages may contain a number of Bundled packages are typically used for per-language updates. The proxy must evaluate the applicability rules of each of the bundled packages to determine whether or not the update should be installed.

Reporting update status using the ClientServicing namespace

You must use a special method to write the status of updates on non-Windows clients to the WSUS database. (Note that it is used only to report on update status, not on update activity.) You first call GetPackageMetadataSet, which returns a PackageMetadataSet that includes the set of updates. When you have retrieved the data on updates and their installation status from the client, for each update instantiate a PackageState object and set the SoftwarePackageId and PackageInstallationState properties with the update ID and installation state. All updates or packages not included in the list of PackageState will assumed Not Applicable. Then for each client call ReportClientStatus. (Note that the client should be registered first before calling ReportClientStatus) The following example shows how to make this call for one client that has two updates, one of which is downloaded but not installed and the other has failed installation.

//Get the cookie by calling GetPackageMetadataSet  
PackageMetadataSet pms = clientServiceProxy.GetPackageMetadataSet(null, null);  
//The PackageState for the update that is downloaded  
PackageState ps1 = new PackageState();  
ps1.PackageInstallationState = PackageInstallationState.Downloaded;  
ps1.SoftwarePackageId = new Guid("4689c50e-7832-46f2-9ea5-17bbab8ee6d1");   
//The PackageStatefor the update that failed to install  
PackageState ps2 = new PackageState();  
ps1.PackageInstallationState = PackageInstallationState.Failed;  
ps1.SoftwarePackageId = new Guid("2131A676-FCE5-02C5-3BF0-68CD48A1919C");   
  
List<PackageState> psList = new List<PackageState>();  
psList.Add(ps1);  
psList.Add(ps2);  
  
//Client "c1" reports status for u1 and u2  
clientServiceProxy.ReportClientStatus("c1", psList, pms.LastChangeCookie);

Last updated on 2016-10-20