SDK: Using the client messaging SDK to leverage client notification services in ConfigMgr 2012 SP1

Configuration Manager 2012 SP1 added a new feature called “client notification services”. Normally clients send a request to the MP on an interval, but if you’re in a situation where you need clients to perform certain actions right away such as perform an anti-virus scan to detect a 0 day malware or request policy right away we now have a persistent network connection to the management point to facilitate this.

You can now also take advantage of this functionality with the SP1 release of the client messaging SDK (note: this will only work with a Configuration Manager 2012 SP1 or newer management point). As this is a completely new paradigm for messaging, it doesn’t work like traditional request/response functions of the client messaging SDK.

To use this facility, you essentially create a client notification session with the management point, and then you subscribe to events that will fire when instructions come from the management point. You respond to those messages asynchronously and then send a “response” message over the channel saying you handled the request.

In order to use the client notification feature you must have an existing SMSID and certificate. See my past posts on the client messaging SDK for details on how to get this.

Here’s some sample code on how to set up the session:

 ConfigMgrBgbSession session = ConfigMgrBgbSession.CreateSession(
     BgbSessionType.Http, 
     "10.229.77.180" /* hostname or IP of your management point */, 
     MessageSecurityMode.MixedMode, 
     smsId /* SMSID from client registration */, 
     new ClientVersionV5SP1(), 
     cert /* MessageCertificateX509 derived object */);
 session.BgbMessageReceived += session_BgbMessageReceived; /* Event that handles messages received from the client notification web service */
 session.BgbMessageSent += session_BgbMessageSent; /* Event that handles messages sent to the client notification web service */
 session.KeepAliveInterval = TimeSpan.FromMinutes(15); /* Interval to send "pings" back up to the client notification web service */
 session.OpenSession();

 Remember, this is asynchronous so once OpenSession() is called your code will continue. You will handle requests from the client notification web service with the BgbMessageReceived event handler. Here’s a sample implementation:

 static void session_BgbMessageReceived(object sender, ConfigMgrBgbSessionEventArgs e)
 {
     Console.WriteLine("Received message from client notification of type {0}: {1}", ((ConfigMgrBgbMessageReply)e.Message).Message, e.Message.Body.Payload);
     ConfigMgrBgbSynchronousMessageEventArgs configMgrBgbSynchronousMessageEventArgs = e as ConfigMgrBgbSynchronousMessageEventArgs;
     if (configMgrBgbSynchronousMessageEventArgs != null)
     {
         // Insert code here to act against the notification 
         configMgrBgbSynchronousMessageEventArgs.ResponseMessage.ReturnCode = 1; /* this says that you were successful */
         configMgrBgbSynchronousMessageEventArgs.SessionCallback.SendResponseMessage(configMgrBgbSynchronousMessageEventArgs.ResponseMessage);
     }
 }

You process the notification request from the client notification web service, then you send a response back saying that you were successful. What follows is sample of this code in action.

In the administrator console, I instruct a client notification for “Download Computer Policy” to be sent to my client (other options may also be available depending on how your site or hierarchy is configured):

 You can track the status of your clients through the “Client Operations” node of the “Monitoring” page of the admin console. Here we can see the status of this request:

This is not real-time so you will need to re-summarize the page if you want results immediately.

Using the sample code in a program, here’s what it might look like receiving a message and sending a response:

If you resummarize the monitoring page, you’ll see that it reflects that the client handled the message:

You’ll notice in the XML blob sent to the code that TaskType was set to 1. This is an instruction to request machine policy. There’s 2 other TaskType values: full anti-virus scan (2), and quick anti-virus scan (3).

When you’re done, you should use CloseSession() to cleanly terminate your session with the client notification web service.

By implementing this, your custom client will have all of the instant-response capabilities of a regular client!

Bonus trivia: why is the nomenclature “BGB” used throughout these SDK APIs? The feature was originally known internally as “big green button”, or “BGB” for short. The name “big green button” was to evoke the image of a panicked admin hitting the emergency button to tell all of the clients to do something right away. As for why it was a green button rather than a red button is something that has unfortunately been lost to antiquity. There’s still many references to this in log files and even in filenames before settling on the official name of “client notification”, and the SDK was one of those things that was not changed to reflect the official naming of the feature. It wouldn’t be the first time this has happened.

Comments

• Anonymous
  June 01, 2015
  Very useful and rare info man. Thanks :)