Task sequence editing has three separate pieces: groups of steps, commands (such as “Install Application” and “Partition Disk”), and conditions. With 1706 Current Branch and Technical Preview we now have PowerShell support for creating and removing groups, all conditional statements, and what have been identified as the most commonly used task sequence steps.

The typical flow is something like this:

1. Create your task sequence steps and groups (New-CMTaskSequenceStepCommand)
2. Create a task sequence (New-CMTaskSequence)
3. Add the steps you’ve created to the task sequence ($ts | Add-CMTaskSequenceStep –Step ($step1, $step2, $step3)

In 1706, the following Step types are supported for Get, New, Remove, and Set operations:

• Run command line (Verb-CMTaskSequenceStepRunCommandLine)
• Install application (Verb-CMTaskSequenceStepInstallApplication)
• Install software (Verb-CMTaskSequenceStepInstallSoftware)
• Install update (Verb-CMTaskSequenceStepInstallUpdate)
• Partition disk (Verb-CMTaskSequenceStepPartitionDisk)
• Reboot (Verb-CMTaskSequenceStepReboot)
• Run PowerShell script (Verb-CMTaskSequenceStepRunPowerShellScript)
• Setup Windows and Configuration Manager (Verb-CMTaskSequenceStepSetupWindowsAndConfigMgr)
• Set variable (Verb-CMTaskSequenceStepSetVariable)

We plan to add additional Step types in future releases.

Here’s an example showing how easy it is to create a new custom task sequence that runs two PowerShell scripts:

$step1 = New-CMTaskSequenceStepRunPowerShellScript -Name "Run script 1" -PackageID $PackageId -ScriptName "script1.ps1" -ExecutionPolicy Bypass
$step2 = New-CMTaskSequenceStepRunPowerShellScript -Name "Run script 2" -PackageID $PackageId -ScriptName "script2.ps1" -ExecutionPolicy Bypass
$ts = New-CMTaskSequence -Name "Run scripts" -CustomTaskSequence
$ts | Add-CMTaskSequenceStep -Step ($step1, $step2)

If you’re interested in tracking the ongoing progress of this feature, you can follow the original feedback for this issue on UserVoice.

These cmdlets allow you to do all of the same functionality that you can do in the UI: get updates, download updates, perform a prerequisite check, install updates, and monitor updates installation.

In this post, I will walk through a few scenarios and how you can now automate them in PowerShell.

New cmdlets for updates and servicing automation

The following new cmdlets have been created to automate updates and servicing scenarios:

• Enable-CMSiteFeature – Used to enable a pre-release feature. Note that this is a one-way operation so there’s no corresponding Disable-CMSiteFeature cmdlet.
• Get-CMSiteFeature – Gets the available features for the site.
• Get-CMSiteUpdate – Gets the available updates for the site.
• Get-CMSiteUpdateHistory – Gets the update history. This is only for informational purposes.
• Get-CMSiteUpdateInstallStatus – Gets the install status for a particular update. This can be used for monitoring.
• Install-CMSiteUpdate – Installs an update and allows for optionally skipping prerequisite checking and specifying a pre-release collection.
• Invoke-CMSitePromotePreproductionClient – Promotes a pre-production client.
• Invoke-CMSiteUpdateCheck – Checks with Microsoft for any updates to Configuration Manager.
• Invoke-CMSiteUpdateDownload – Downloads an available update.
• Invoke-CMSiteUpdatePrerequisiteCheck – Performs a prerequisite check for an update.

In addition to these new cmdlets, Set-CMHierarchySetting has been updated to allow for enabling pre-release features with the –EnablePrereleaseFeature parameter. Note that this is a one-way operation and once you enable pre-release features you cannot disable them.

We hope you find these new cmdlets useful for automating updates and servicing scenarios. Please report any bugs or issues you find with these new cmdlets on UserVoice or Connect.

Examples

Download an update and monitor its status

# Get the update object for the 1704 TP and invoke a download
$update = Get-CMSiteUpdate -Name "Configuration Manager Technical Preview 1704" -Fast
$update | Invoke-CMSiteUpdateDownload

# Now monitor the download status

while($true) {
    cls
   $update | Get-CMSiteUpdateInstallStatus  -Step Download | select orderid, progress, description | ft
    sleep 5
}

This will produce an output like this:

orderid progress description                                                                                                                                 
------- -------- -----------                                                                                                                                 
      0      100 Processing update package. Check dmpdownloader.log for details.                                                                             
      1        0 If your service connection point is online, the update package cab is downloaded. If your service connection point is offline, this step ...
      2        0 Extracting update package payload. Check dmpdownloader.log for details.                                                                     
      3        0 If redistributable files are required and not included with the update, they are downloaded.  If files do not need to be downloaded, this...
      4        0 The update package has been reported as downloaded. Check dmpdownloader.log and hman.log for details. 

Perform a prerequisite check and monitor its status

$update = Get-CMSiteUpdate -Name "Configuration Manager Technical Preview 1704" -Fast
$update | Invoke-CMSiteUpdatePrerequisiteCheck

while($true) {
    cls
    $update | Get-CMSiteUpdateInstallStatus -Step Prerequisite | select orderid, progress, description | ft
    sleep 5
}

This will produce an output like this:

orderid progress description                                                                                                                                 
------- -------- -----------                                                                                                                                 
      0      100 Verifies that the logged on user account has administrative rights on the site system computer.                                             
      0      100 Starting with version 1706, Upgrade Assessment Toolkit is no longer supported. https://go.microsoft.com/fwlink/?linkid=841654               
      1      100 Verifies that the user running Setup has local administrator rights on the central administration site server.                              
      2      100 Checks if the user account running Setup has sysadmin rights on the SQL Server for the CAS.                                                 
      3      100 Check Server Service (LanmanServer) is running.                                                                                             
      4      100 Verifies that the computer specified for installation is a member of a Windows domain.                                                      
      5      100 Verify that the Active Directory domain functional level is Windows Server 2003 or later.                                                   
      6      100 Checks that the site server computer has sufficient available disk space to install the site server.                                        
      7      100 Checks if a system restart is pending.                                                                                                      
      8      100 Checking unsupported Read-Only Domain Controller on site server.                                                                            
      9      100 Checking Site Server FQDN Length.                                                                                                           
     10      100 Verifies that the Microsoft Core XML Services (MSXML) version 6.0 or later libraries are installed.                                         
     11      100 Determines if the Windows Server 2003-based schannel hotfix is installed on the site server.                                                
     12      100 Verifies that the Microsoft Remote Differential Compression (RDC) library is registered on the computer specified for Configuration Manag...
     13      100 Checking Windows Installer Version >= 4.5.                                                                                                  
     14      100 Checks if the target site server computer already has existing Configuration Manager server components installed.                           
     15      100 Checks if the Windows Firewall is disabled or if a relevant Windows Firewall exception exists for SQL Server.                               
     16      100 Checks if the Windows Firewall is disabled or if a relevant Windows Firewall exception exists for SQL Server.                               
     17      100 Check SQL Server service running account.                                                                                                   
     18      100 Check to see if the selected SQL Server instance is already in use by another Configuration Manager site                                    
     19      100 Verifies that the site server's database collation matches the database collation of its parent site.                                       
     20      100 Verifies that the Microsoft .NET Framework version 3.5 is installed on Configuration Manager central administration site servers, primary...
     21      100 Checks whether the Windows Deployment Tools component of Windows Assessment and Deployment Kit (ADK) for Windows 10 is installed.           
     22      100 Checks whether the User State Migration Tool (USMT) component of Windows Assessment and Deployment Kit (ADK) for Windows 10 is installed.   
     23      100 Checks if the FQDN provided for the site system uses the primary DNS hostname for the computer.                                             
     24      100 Checks if the specified site code is already in use by another site in your hierarchy.                                                      
     25      100 Check the parent Central Administration Site has the same version.                                                                          
     26      100 Verifies that the SQL Server instance and Configuration Manager site database (if present) are configured to use a supported collation.     
     27      100 Verifies that the site server is processing critical inboxes in a timely fashion, and that inboxes do not contain files older than one day. 
     29      100 Verifies that all distribution points in the site have the latest version of software distribution packages.                                
     30      100 Verifies that the SQL Server database collation settings of the tempdb database and site database to be upgraded are the same.              
     31      100 Share Name in Package has invalid character: #.                                                                                             
     32      100 Verifies that SUM is not using any virtual locations for active SUPs.                                                                       
     33      100 Verifies that no active source hierarchy is currently configured for migration.                                                             
     34      100 Verifies that all site servers in the hierarchy meet the Configuration Manager minimum version that is required for upgrade.                
     35      100 No Active MP Replica detected                                                                                                               
     36      100 Verifies that the replication status of the parent site is Replication Active (corresponds to status=125).                                  
     37      100 Checking that the site system role 'Out of band service point' is not deployed.                                                             
     38      100 Checking whether the site system role 'System Health Validator' exists in the hierarchy.                                                    
     39      100 Checking whether there are software updates that are enabled for NAP                                                                        
     40      100 Pre-requisite rule to verify database consistency                                                                                           
     41      100 Verifies that the user account running Configuration Manager Setup has been granted sysadmin SQL Server role permissions on the SQL Serve...
     42      100 Verifies that the user account running Configuration Manager Setup has been granted sysadmin SQL Server role permissions on the SQL Serve...
     43      100 Verifies that the site server computer account has administrative rights on the SQL Server and management point.                            
     44      100 Verifies that the version of Microsoft SQL Server installed on the computer selected to host the site database meets the minimum requirem...
     45      100 Checking the site SQL Server is not Express Edition.                                                                                        
     46      100 Checking the site SQL Server Tcp is enabled and set to Static port.                                                                         
     47      100 Checks if the SQL Server hosting the Configuration Manager site database is using a case-insensitive collation.                             
     48      100 Check that the specified FQDN for the SQL Server computer is valid.                                                                         
     49      100 Check target SDK machine is not Windows Cluster Node.                                                                                       
     50      100 Checks whether the Windows Preinstallation Environment component of Windows Assessment and Deployment Kit (ADK) for Windows 10 is installed.
     51      100 Checks if SMS Provider machine has same domain as site server.                                                                              
     52      100 Checking whether there are custom Client Agent Settings that enable NAP                                                                     
     53      100 Checking whether the default Client Agent Settings enable NAP                                                                               
     54      100 Checking secondary read state of availability group replicas                                                                                
     55      100 Checking failover state of availability group replicas                                                                                      
     56      100 Checking availability group replicas for instance configuration                                                                             
     57      100 Checks if default value is set for SQL Index Create Memory                                                                                  
     58      100 Starting with version 1702, Configuration Manager does not support SQL Server 2008 R2. https://go.microsoft.com/fwlink/?linkid=841654. Th...
     59      100 Verifies that the site server operating system meets the minimum requirement of Windows Server 2008 R2 for site server installation.        
     61      100 Starting with version 1702, Configuration Manager does not support Windows Server 2008 R2 operating system. https://go.microsoft.com/fwli...
     62      100 Verifies that the site system to be upgraded meets the minimum operating system requirement of Windows Server 2008 R2 for site system ins...
     63      100 Starting with version 1702, Configuration Manager does not support Windows Server 2008 R2 operating system. https://go.microsoft.com/fwli...
     64      100 Starting with version 1702, Configuration Manager does not support Software Update Points on Loadbalancers (NLB/HLB).

Install an update and monitor its status

$update = Get-CMSiteUpdate -Name "Configuration Manager Technical Preview 1704" -Fast
$update | Install-CMSiteUpdate -IgnorePrerequisiteWarning -Force

while($true) {
    cls
    $update | Get-CMSiteUpdateInstallStatus -Step All -Complete | select orderid, progress, description -Last 10 | ft
    sleep 5
}

This uses the –Complete parameter for Get-CMSiteUpdateInstallStatus and only displays the completed steps. This can be useful for monitoring of long running tasks like installation.

For more information, see the post on the Enterprise Mobility and Security blog.

In the upcoming 1705 technical preview of Configuration Manager, we have finally added the much-requested ability to add enhanced detection method clauses to deployment types PowerShell. This posting will discuss the basic concepts of how this will work, along with what is and is not supported at this time.

What is supported

For 1704 technical preview the following functionality can now be done through PowerShell:

• Add and remove file, folder, registry key, registry key value, and MSI version detection clauses to MSI and script deployment types.
• Add and remove bundle and package detection clauses to Mac deployment types.

What is not supported

These features are planned to be added in a future release:

• Modify detection clauses in place
• Group/ungroup detection clauses

How it works

A detection clause object is created with one of the new New-CMDetectionClause<type> cmdlets, and then added to a new or existing deployment type using the -AddDetectionClause parameter. One or more detection clauses can be added at a time.

Example

Two detection clauses are created, one for an existing installer matching a specific value, and another for a directory to exist on the C drive. These clauses are then added to a new deployment type.

$clause1 = New-CMDetectionClauseWindowsInstaller -ProductCode $guid [Value -ExpressionOperator IsEquals -ExpectedValue "1.1.1.1" # Do a version check
$clause2 = New-CMDetectionClauseDirectory -DirectoryName "mymsi" -Path "C:\" -Existence # c:\mymsi should exist
$app | Add-CMMsiDeploymentType -ContentLocation "\\myserver\mypath\mymsi.msi" -Force -AddDetectionClause ($clause1, $clause2)

What cmdlets are included

These cmdlets have been created in 1704 to enable DCM rule and setting support:

• New-CMDetectionClauseDirectory (MSI, Script)
• New-CMDetectionClauseFile (MSI, Script)
• New-CMDetectionClauseMacBundle (Mac)
• New-CMDetectionClauseMacPackage (Mac)
• New-CMDetectionClauseRegistryKey (MSI, Script)
• New-CMDetectionClauseRegistryKeyValue (MSI, Script)
• New-CMDetectionClauseWindowsInstaller (MSI, Script)

Note: Add/Set-CMMsiDeploymentType, Add/Set-CMScriptDeploymentType, and Add/Set-CMMacDeploymentType now have new -AddDetectionClause and -RemoveDetectionClauseparameters to facilitate adding and removing enhanced detection methods.

In the upcoming 1705 technical preview of Configuration Manager, we have finally added the much-requested ability to add Settings and Rules to Configuration Items from within PowerShell. This posting will discuss the basic concepts of how this will work, along with what is and is not supported at this time.

What is supported

For 1704 technical preview the following functionality can now be done through PowerShell:

• Add/Remove/Modify Settings to Configuration Items. All Settings supported in the administrator console are supported through PowerShell: registry key, registry key value, script, file, folder, WQL query, AD query, assembly property, IIS metabase, SQL query, and XPath query.
• Add/Remove/Modify Rules linked to Settings within Configuration Items. This includes basic value checks, existential checks (exist, not exist, occurrence), and complex value checks for applicable Setting types (file/folder properties, assembly properties, registry key permissions).

How it works

All Settings can be created without corresponding Rules in a single cmdlet call. All settings with existential Rules can also be created with a single cmdlet call. Some settings with value Rules can be created with a single cmdlet call while other, more complex Rule types will require a more complicated but easily understandable pattern of cmdlet calls. We may simplify this in the future. (See Example 4 below.)

Example 1

Creating a registry key value Setting without any Rules:

# Creates a setting looking for HKLM\Software\Microsoft\Windows NT\CurrentVersion:ReleaseId
$ci | Add-CMComplianceSettingRegistryKeyValue -SettingName "ReleaseId no rule" -DataType String -Hive LocalMachine -KeyName "SOFTWARE\Microsoft\Windows NT\CurrentVersion" -ValueName "ReleaseId" -NoRule

Example 2

Creating a registry key value Setting with an existential Rule (must exist):

# Creates a setting requiring the HKLM\Software\Microsoft\WindowsNT\CurrentVersion:ReleaseId registry key to exist
$ci | Add-CMComplianceSettingRegistryKeyValue -SettingName "ReleaseId must exist" -DataType String -Hive LocalMachine -KeyName "SOFTWARE\Microsoft\Windows NT\CurrentVersion" -ValueName "ReleaseId" -ExistentialRule -Existence MustExist

Example 3

Creating a registry key value Setting with a value Rule (must equal “1703”):

# Creates a setting requiring the HKLM\Software\Microsoft\WindowsNT\CurrentVersion:ReleaseId registry key to be equal to "1703"
$ci | Add-CMComplianceSettingRegistryKeyValue -SettingName "ReleaseId must be 1703" -DataType String -Hive LocalMachine -KeyName "SOFTWARE\Microsoft\Windows NT\CurrentVersion" -ValueName "ReleaseId" -ValueRule -ExpressionOperator IsEqual -ExpectedValue "1703"

In value rules, critical parameters are “ExpressionOperator” and “ExpectedValue”. It’s worth noting that “ExpectedValue” supports arrays of values so if you’re using an ExpressionOperator that requires (Between) or supports many (OneOf/NoneOf/AllOf) values, you can use the same parameter for this. Cmdlets will validate the input to ensure you’re not doing something unsupported – such as using IsEquals with multiple ExpectedValue arguments.

Example 4

Some setting value Rules require more specialized input. As such, these Setting types do not support a single cmdlet at this time. For those scenarios, you need to follow this pattern:

1. Create the Setting using Add-CMComplianceSetting<type>
2. Get the DcmObjectModel Setting object (as opposed to a SMS Provider object) using Get-CMComplianceSetting
3. Create the Rule using New-CMComplianceRule<type>
4. Apply the Rule to the setting using Add-CMComplianceSettingRule

This example creates a file rule that requires the specified file to have a specific attribute:

$ci | Add-CMComplianceSettingFile -Path "C:\" -FileName "hiberfile.sys" -NoRule -SettingName "hiberfile.sys must have system attribute"
$setting = $ci | Get-CMComplianceSetting -SettingName "hiberfile.sys must have system attribute" # Get the SDK setting object
$rule = $setting | New-CMComplianceRuleFileFolderAttribute -RuleName "hiberfile.sys must be system" -System $true # Create the rule
$ci | Add-CMComplianceSettingRule $rule # Bind the rule to the CI

What cmdlets are included

These cmdlets have been created in 1704 to enable Configuration Item Rule and Setting support:

• Add/Set-CMComplianceSettingActiveDirectory
• Add/Set-CMComplianceSettingAssembly
• Add/Set-CMComplianceSettingDirectory
• Add/Set-CMComplainceSettingFile
• Add/Set-CMComplianceSettingIisMetabase
• Add/Set-CMComplianceSettingRegistryKey
• Add/Set-CMComplianceSettingRegistryKeyValue
• Add-CMComplianceSettingRule
• Add/Set-CMComplianceSettingScript
• Add/Set-CMComplianceSettingSqlQuery
• Add/Set-CMComplianceSettingWqlQuery
• Add/Set-CMComplianceSettingXPathQuery
• Get-CMComplianceRule
• Get-CMComplianceSetting
• New-CMComplianceRuleAssembly
• New-CMComplianceRuleExistential
• New-CMComplianceRuleFileFolderAttribute
• New-CMComplianceRuleFileFolderDate
• New-CMComplianceRuleFileFolderPermission
• New-CMComplianceRuleFileFolderSimple
• New-CMComplianceRuleFileFolderSize
• New-CMComplianceRuleRegistryKeyPermission
• New-CMComplianceRuleValue
• New-CMComplianceRuleVersion
• Remove-CMComplianceRule
• Remove-CMComplianceSetting

Note: The previously existing Add-CMComplianceRegistrySetting and New-CMComplianceRule cmdlets were experimental and for lab use only. They have been removed from 1704.

Here's a simple PowerShell script that demonstrates this:

# This must be set to match the path to the Configuration Manager 2012 SDK
 $modulePath = 'D:\Program Files (x86)\Microsoft System Center 2012 R2 Configuration Manager SDK\Redistributables\Microsoft.ConfigurationManagement.Messaging.dll'
 
 # Set this to match your machine name
 $name = 'R2311195'
 
 # This must be a name of your special DDR generator
 $agentName = 'MySpecialThirdPartyAgent'
 
 # This should match your site code
 $siteCode = 'R2S'
 
 # Now we generate the DDR object
 $ddr = New-Object -typename Microsoft.ConfigurationManagement.Messaging.Messages.Server.DiscoveryDataRecordFile -ArgumentList $agentName
 $ddr.SiteCode = $siteCode
 $ddr.Architecture = 'System'
 $ddr.AddStringProperty('Name', [Microsoft.ConfigurationManagement.Messaging.Messages.Server.DdmDiscoveryFlags]::Key -bor [Microsoft.ConfigurationManagement.Messaging.Messages.Server.DdmDiscoveryFlags]::Name, 32, $name)
 $ddr.AddStringProperty('Netbios Name', [Microsoft.ConfigurationManagement.Messaging.Messages.Server.DdmDiscoveryFlags]::Name, 16, $name)
 $ddr.AddIntegerProperty('TestInstallAuto', [Microsoft.ConfigurationManagement.Messaging.Messages.Server.DdmDiscoveryFlags]::None, 0)
 $ddr.AddIntegerProperty('TestInstall', [Microsoft.ConfigurationManagement.Messaging.Messages.Server.DdmDiscoveryFlags]::None, 1)
 $ddr.AddStringProperty('Wow', [Microsoft.ConfigurationManagement.Messaging.Messages.Server.DdmDiscoveryFlags]::None, 32, "Such custom")
 $ddr.SerializeToInbox()

This creates a new DDR and adds it into the inbox. After a few seconds, DDM will process this and those changes should be reflected in the discovery data for the machine:

In the past if you wanted to use a signed PowerShell script as a configuration item detection method or deployment type detection method, you would see an error on the client when it tried to process the script. Configuration Manager 2012 R2 CU2 has a fix in place to mitigate this problem and allow for using signed PowerShell scripts in configuration items and detection methods. You can download CU2 from here: https://support.microsoft.com/kb/2970177. Note that the signer of the script must be pre-trusted or else the script will continue to fail.

For this new functionality to work both the administrator console and client needs to be updated to R2 CU2 as this fix requires changes to both pieces of the product.

First let's talk about configuration item detection methods. To add a signed PowerShell script, when editing a discovery or remediation script you must use "Open" to add the signed script. You cannot copy and paste it. There's a UI change in that the script becomes read only in the admin console until you "Clear" it or change the data type. This is by design. Once the configuration item gets down to the client it should process the signed PowerShell script without any issues.

Things are more complicated with deployment type detection methods. At this time there is no UI code to allow for signed PowerShell scripts but fortunately the client-side fix to allow for signed PowerShell scripts applies both to applications and configuration items. You can use the PowerShell script attached to this blog posting to add a signed PowerShell script to a deployment type in a way the client will be able to properly process. The way it works is you edit the top few lines in the script to match your environment's site code and provider host name. Please also read the information in the header of the script carefully. Notably it will overwrite any previous script in your deployment type. If you edit the script in the admin console after adding it using this script, the script will fail on the client. There's examples in the header of the PowerShell script showing how to use it.

Feel free to let me know if you have any further questions!

updatescriptdt.ps1

If you want to use the object model to create your own custom inventory classes for collection, it’s pretty simple to do this. A prerequisite for making the most of this is knowledge about how XML Serialization in the .NET framework works as this process is heavily dependent on this internally. If you don’t know much about this it should still be pretty easy to get started; things just become more difficult when you’re trying to expose more advanced data sets.

For basic details on how to send a hardware inventory message, check out my post with an in-depth sample on how to use the messaging SDK.

Here’s an example inventory class that I created by extending the SDK for a Contoso Perpetual Energy Reactor attachment:

/// <summary>
/// This class represents an inventory instance of a Contoso Perpetual Motion Reactor attachment
/// </summary>
[XmlRoot("Contoso_PerpetualMotionReactor")] // Must define an XmlRoot that represents the class name
public sealed class InventoryElementRecordPerpetualMotionReactor : InventoryInstanceElement
{
    private readonly Collection<string> attachments = new Collection<string>();
 
    /// <summary>
    /// Reactor model
    /// </summary>
    [XmlElement]
    public string Model { get; set; }
 
    /// <summary>
    /// Version
    /// </summary>
    [XmlElement]
    public uint Version { get; set; }
 
    /// <summary>
    /// Attachments for the energy reactor
    /// </summary>
    [XmlElement]
    public Collection<string> Attachments
    {
        get { return attachments; }
    }
 
    /// <summary>
    /// Discover an inventory instance element based local configuration
    /// </summary>
    /// <remarks>This is optional and only here for documentation purposes. By default, DiscoverSelf() will simply throw a NotImplementedException unless
    /// you override it with your own discovery logic</remarks>
    protected override void DiscoverSelf()
    {
        base.DiscoverSelf();
    }
 
    /// <summary>
    /// Initializes a new instance of the <see cref="InventoryElementRecordPerpetualMotionReactor"/> class.
    /// </summary>
    public InventoryElementRecordPerpetualMotionReactor()
        : base(
            "Contoso_PerpetualMotionReactor", // associated base class
            "Contoso_PerpetualMotionReactor", // associated parent class
            @"root\Contoso" /* namespace (scope) */)
    {
    }
}

Keep in mind the XmlRoot and XmlElement attributes. These are used to format the class to XML before sending it to the management point. Here’s an example of how this class will look when serialized to XML (reformatted for clarity):

<Contoso_PerpetualMotionReactor>
    <Model>Contoso Perpetual Motion Reactor (Nuclear Powered)</Model>
    <Version>1</Version>
    <Attachments>Dirty Water Cooling Tower</Attachments>
    <Attachments>Unobtanium Heat Sink</Attachments>
    <Attachments>Analogue gauges</Attachments>
    <Attachments>Sport suspension package</Attachments>
</Contoso_PerpetualMotionReactor>

This will be embedded into the inventory report that’s sent to the management point. Here’s some sample code that could bring all these things together to send this:

ConfigMgrHardwareInventoryMessage customHinvMessage = new ConfigMgrHardwareInventoryMessage();
customHinvMessage.Settings.HostName = mpHostname;
customHinvMessage.AddCertificateToMessage(certificate, CertificatePurposes.Signing | CertificatePurposes.Encryption);
customHinvMessage.SmsId = clientId;
customHinvMessage.SiteCode = siteCode;
customHinvMessage.NetBiosName = "MyDummyHostName";
customHinvMessage.DomainName = "MyDomain.net";
 
InventoryElementRecordPerpetualMotionReactor reactor = new InventoryElementRecordPerpetualMotionReactor();
reactor.Model = "Contoso Perpetual Motion Reactor (Nuclear Powered)";
reactor.Version = 1;
reactor.Attachments.Add("Dirty Water Cooling Tower");
reactor.Attachments.Add("Unobtanium Heat Sink");
reactor.Attachments.Add("Analogue gauges");
reactor.Attachments.Add("Sport suspension package");
 
// Create an instance containing the element
InventoryInstance instance = new InventoryInstance(reactor);
 
// Now add the instance to the inventory list
customHinvMessage.AddInstanceToInventory(instance);
 
customHinvMessage.SendMessage(Sender);

Now when you do this, if you look at MP_Hinv.log on the management point you’ll notice something will be wrong. The MP’s hardware inventory processor will complain about this class with a log line that looks something like this:

Hinv: class name not found in the mapping table: Contoso_PerpetualMotionReactor    MP_HinvEndpoint    4/10/2013 1:44:38 PM    4592 (0x11F0)

The reason for this is you can’t just start creating new hardware inventory classes without taking some action on the site server. First you’ll need to create a .MOF file that represents the custom class you’re creating. Here’s one I created that represents the code above:

//=============================================================================
// SMS_Class_Template must be the parent of every class
//=============================================================================
class SMS_Class_Template
{
};
 
[ SMS_Report (TRUE),
  SMS_Group_Name ("Perpetual Motion Reactor"),
  SMS_Class_ID ("CONTOSO|PERPETUAL_MOTION_REACTOR|1.0"),
  Namespace ("\\\\\\\\.\\\\root\\\\contoso") ]
class Contoso_PerpetualMotionReactor : SMS_Class_Template
{
    [SMS_Report(TRUE), key]
    String Model;
 
    [SMS_Report(TRUE)]
    UInt32 Version;
 
    [SMS_Report(TRUE)]
    String Attachments[];
};

The next step is to import this MOF file into Configuration Manager. To do this, you need to go to the Administration view in the admin console, go to Client Settings, choose your client settings group, then go to Hardware Inventor, choose Set Classes, and import your mof file:

When you send this inventory a second time, it will get processed successfully by the management point with a line like this in the MP_Hinv.log:

Hinv Sax: Inserting class instance Contoso_PerpetualMotionReactor, attr=New    MP_HinvEndpoint    4/10/2013 2:04:54 PM    4592 (0x11F0)

Now if you open Resource Explorer for your system, you’ll see this new data represented for your client:

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.

The old library provided the ability to formulate a completely ad-hoc DDR which could be used to extend resource discovery by being able to add resources into Configuration Manager for objects and their properties that aren’t natively supported. For example, you could inventory your fax machines, printers, chairs (someone actually asked for this once!), and so on.

The class of interest for generating this inventory data is Microsoft.ConfigurationManagement.Messaging.Messages.Server.DiscoveryDataRecordFile.

Here is a code sample on how you may inventory a printer using this API:

DiscoveryDataRecordFile ddrFile = new DiscoveryDataRecordFile("Contoso Printersaurus"); // Agent name is the program that generated the DDR

ddrFile.Architecture = "Printer";

ddrFile.SiteCode = "NP1";

ddrFile.AddStringProperty("Name", DdmDiscoveryFlags.Key | DdmDiscoveryFlags.Name, 32, "MyPrinter001"); // You must have a field defined with Name flag

ddrFile.AddStringProperty("Model", DdmDiscoveryFlags.None, 128, "Contoso PaperMax 2000");

ddrFile.AddStringProperty("Version", DdmDiscoveryFlags.None, 12, "1.0");

ddrFile.AddStringProperty("Location", DdmDiscoveryFlags.None, 128, "Third Floor near break room");

ddrFile.AddDateTimeProperty("DateInstalled", DdmDiscoveryFlags.None, new DateTime(2011, 07, 07));

ddrFile.AddStringPropertyArray("Capabilities", DdmDiscoveryFlags.Array, 32, "Color", "Duplex", "Scanner");

ddrFile.AddIntegerProperty("RAM", DdmDiscoveryFlags.None, 64);

ddrFile.AddIntegerProperty("PagesPrinted", DdmDiscoveryFlags.None, 102);

ddrFile.AddDateTimeProperty("LastPrinted", DdmDiscoveryFlags.None, DateTime.Now);

ddrFile.AddIntegerPropertyArray("PaperLevelPercent", DdmDiscoveryFlags.Array, 100, 75, 0, 0);

ddrFile.AddStringPropertyArray("PaperType", DdmDiscoveryFlags.Array, 32, "Letter", "Letter Extended", "Legal", "A3");

string filename = ddrFile.SerializeToFile("."); // Normally you would use SerializeToInbox

Console.WriteLine("Write DDR to file: {0}", filename);

Pretty simple, right? Basically you define your properties, flags if needed, a maximum length where applicable, and then values. The Architecture field is very important as it will create SMS_R_Architecture resource tables that can be used for collections and query rules. In this sample because the architecture is “Printer”, a SMS_R_Printer class will be created.

The sample here used SerializeToFile to write a file for testing purposes and you’d drop this file into your ddm.box inbox on your site server. A better way to do this is to use the SerializeToInbox method that will automatically drop the file into the appropriate inbox.

Running this program and dropping the .DDR file into ddm.box will create an inventory record (which can be verified via ddm.log).

You can then create a Query (not a Collection since this isn’t a System or User resource) against all instances of SMS_R_Printer. I created one that looks like this:

You can then run this query, and see this resource in the admin console:

Since this data is all stored in SQL and accessible through the provider you can write reports or use other tools to slice and dice this data in interesting ways.

I hope you find this functionality useful!