Update Applicability Rules

Applies To: Windows Server Update Services

Applicability rules are used by the Windows Update agent to determine whether the update is needed by a given computer. Specifying the correct applicability rules is one of the most difficult parts of authoring an update.

Overview of applicability rules

Applicability rules specify the conditions that need to be met for an update to be needed on a computer. They are evaluated by the Windows Update Agent to determine whether the update should be offered for install.

There are three core applicability rules, IsInstalled, IsSuperseded, and IsInstallable, plus the Metadata element used for information shared by the three core rules. For a given update on a given computer, if IsInstalled is false, IsSuperseded is false, and IsInstallable is true, the update should be installed.

These applicability rules appear under the InstallableItem.ApplicabilityRules element under the SoftwareDistributionPackage element. The IsInstallable and IsInstalled rules can also be specified at the top level of the SoftwareDistributionPackage element. If they are specified in both places, the expressions are combined (using the Boolean AND operator) to form a composite applicability rule for the package. They can also be set from the authoring API.

IsInstalled

Specifies which conditions need to be met for the update to be considered as already installed. If this rule evaluates to true, then the update is already in place on this computer and should not be re-installed.

IsInstallable

Specifies which conditions need to be met for the update to be needed, regardless of whether or not it is already installed. If this rule evaluates to true, the update should be installed. However, if IsInstallable evaluates to true and IsInstalled evaluates to false, the update should not be installed.

IsSuperseded

Specifies which conditions need to be met for the update to be considered as superseded. A superseded update is subsumed or made unnecessary by a later update or service pack. (For example, an update may be superseded by a service pack, or a service pack may be superseded by a later service pack.) If IsSuperseded evaluates to true, the update should not be installed. This rule is rarely used, since the IsInstalled rule can specify the same conditions.

Metadata

Applicability metadata is a set of conditions needed by multiple applicability rules. For example, Windows Installer patch and product information is commonly listed under the Metadata element.

The structure of applicability rules

The structure of the applicability rules depends on the type of package.

MSP packages should use the rules generated by the method PopulatePackageFromWindowsInstallerPatch.

Windows Installer packages should use the rules generated by the method PopulatePackageFromWindowsInstaller, combined with additional IsInstallable rules that restrict the installation to some subset of computers (for example, a server application may require a server operating system).

These methods will call the Windows Installer function MsiExtractPatchXMLData (https://go.microsoft.com/fwlink/?LinkId=102041) to extract the detection logic automatically.

Command-line packages typically need hand-authored rules for both IsInstalled and IsInstallable. The IsInstallable rule restricts installation to some subset of computers. The IsInstalled rule should perform file and registry checks to make sure the package is installed. For updates, file versions should be checked carefully.

Bundles cannot have applicability rules (although they can declare prerequisites on detectoids).

Drivers can have only the standard driver applicability rules defined in WindowsDriver.xsd. Only the Metadata applicability rule element needs to be defined individually.

Detectoids

Detectoids are separate XML documents consisting of sets of applicability rules. They are used to factor out common applicability rules for packages. For example, if there are many updates for a given application, one detectoid can be written to detect whether the application is installed. Each update declares that detectoid as a Prerequisite. Since detectoids do not install updates, they are not associated with update binaries. As such, they should always have the IsInstallable rule set to false. Detectoids have only an IsInstalled rule to check for the presence of certain software on the machine. Detectoids and prerequisites are the only way to create applicability rules for drivers and bundles. Detectoids must be authored with UpdateType=detectoid and no install handler-specific data.

Example

Windows Installer package

The following example shows the code used to populate an update metadata file using a Windows Installer package.

SoftwareDistributionPackage msiPackage = new SoftwareDistributionPackage();  
msiPackage.PopulatePackageFromWindowsInstaller("C:\\test\\MSIPackage.msi");  
msiPackage.Title = "Windows Installer Package Title";  
msiPackage.Description = "Windows Installer Package Description";  
msiPackage.IsInstallable = "<lar:And> <bar:WindowsVersion Comparison='EqualTo' MajorVersion='6' MinorVersion='0' BuildNumber='6001' ServicePackMajor='0' ProductType='1' /> <msiar:MsiApplicationInstalled /> </lar:And>";  
msiPackage.Save("C:\\test\\MSIPackage.sdp");  

This code will produce an update metadata file like the following:

<sdp:SoftwareDistributionPackage   
 xmlns="http://www.w3.org/2001/XMLSchema"  
 xmlns:bar="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/BaseApplicabilityRules.xsd"  
 xmlns:bt="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/BaseTypes.xsd"  
 xmlns:cmd="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/Installers/CommandLineInstallation.xsd"  
 xmlns:lar="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/LogicalApplicabilityRules.xsd"  
 xmlns:msi="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/Installers/MsiInstallation.xsd"  
 xmlns:msiar="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/MsiApplicabilityRules.xsd"  
 xmlns:msp="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/Installers/MspInstallation.xsd"  
 xmlns:sdp="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/SoftwareDistributionPackage.xsd"  
 xmlns:uei="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/Installers/UpdateExeInstallation.xsd"  
 xmlns:usp="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/UpdateServicesPackage.xsd"  
 xmlns:drv="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/Installers/WindowsDriver.xsd"  
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  SchemaVersion="1.1"><sdp:Properties PackageID="58f30969-110e-4310-afbf-bd3a55311004" CreationDate="2007-09-10T20:08:51.519Z" PublicationState="Published" CanSourceBeRequired="false" UpdateType="Software"></sdp:Properties><sdp:LocalizedProperties><sdp:Language>en</sdp:Language><sdp:Title>Windows Installer Package Title</sdp:Title><sdp:Description>Windows Installer Package Description</sdp:Description></sdp:LocalizedProperties><sdp:ApplicationSpecificData /><sdp:InstallableItem ID="1c9c831e-7d97-461c-9337-69e7a22663ed" ><sdp:ApplicabilityRules><sdp:IsInstalled><msiar:MsiApplicationInstalled /></sdp:IsInstalled><sdp:IsSuperseded><msiar:MsiApplicationSuperseded /></sdp:IsSuperseded><sdp:IsInstallable><lar:And> <bar:WindowsVersion Comparison="EqualTo" MajorVersion="6" MinorVersion="0" BuildNumber="6001" ServicePackMajor="0" ProductType="1" /> <msiar:MsiApplicationInstalled /> </lar:And> /></sdp:IsInstallable><sdp:Metadata><msiar:MsiApplicationMetadata><msiar:ProductCode>{98f055d3-99cf-4bbb-bc35-3672f9a297c1}</msiar:ProductCode></msiar:MsiApplicationMetadata></sdp:Metadata></sdp:ApplicabilityRules><sdp:InstallProperties CanRequestUserInput="false" RequiresNetworkConnectivity="false" Impact="Normal" RebootBehavior="CanRequestReboot" /><sdp:UninstallProperties CanRequestUserInput="false" RequiresNetworkConnectivity="false" Impact="Normal" RebootBehavior="CanRequestReboot" /><msi:MsiInstallerData ProductCode="{98f055d3-99cf-4bbb-bc35-3672f9a297c1}" MsiFile="MSIPackage.msi"/></sdp:InstallableItem></sdp:SoftwareDistributionPackage>  

MSP package

The following example shows the code used to populate an update metadata file using an MSP package.

SoftwareDistributionPackage mspPackage = new SoftwareDistributionPackage();  
mspPackage.PopulatePackageFromWindowsInstallerPatch("C:\\test\\MSPPackage.msp");  
mspPackage.Title = "MSP Package Title";  
mspPackage.Description = "MSP Package Description";  
mspPackage.Save("C:\\test\\MSPPackage.sdp");  

This code will produce an update metadata file like the following:

<sdp:SoftwareDistributionPackage   
 xmlns="http://www.w3.org/2001/XMLSchema"  
 xmlns:bar="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/BaseApplicabilityRules.xsd"  
 xmlns:bt="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/BaseTypes.xsd"  
 xmlns:cmd="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/Installers/CommandLineInstallation.xsd"  
 xmlns:lar="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/LogicalApplicabilityRules.xsd"  
 xmlns:msi="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/Installers/MsiInstallation.xsd"  
 xmlns:msiar="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/MsiApplicabilityRules.xsd"  
 xmlns:msp="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/Installers/MspInstallation.xsd"  
 xmlns:sdp="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/SoftwareDistributionPackage.xsd"  
 xmlns:uei="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/Installers/UpdateExeInstallation.xsd"  
 xmlns:usp="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/UpdateServicesPackage.xsd"  
 xmlns:drv="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/Installers/WindowsDriver.xsd"  
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  SchemaVersion="1.1"><sdp:Properties PackageID="308f576d-2564-4e27-b989-b97cd2a0d5c8" CreationDate="2007-09-10T20:14:06.108Z" PublicationState="Published" CanSourceBeRequired="false" UpdateType="Software"></sdp:Properties><sdp:LocalizedProperties><sdp:Language>en</sdp:Language><sdp:Title>MSP Package Title</sdp:Title><sdp:Description>MSP Package Description</sdp:Description></sdp:LocalizedProperties><sdp:ApplicationSpecificData /><sdp:InstallableItem ID="4a43fe15-74bd-4e99-a6d4-3603a5797b15" ><sdp:ApplicabilityRules><sdp:IsInstalled><msiar:MsiPatchInstalled /></sdp:IsInstalled><sdp:IsSuperseded><msiar:MsiPatchSuperseded /></sdp:IsSuperseded><sdp:IsInstallable><msiar:MsiPatchInstallable /></sdp:IsInstallable><sdp:Metadata><msiar:MsiPatchMetadata><MsiPatch xmlns="https://www.microsoft.com/msi/patch_applicability.xsd" SchemaVersion="1.0.0.0" PatchGUID="{69EA8E11-FBF9-4864-A50F-CD90CA54E86F}" MinMsiVersion="1"><TargetProduct MinMsiVersion="200"><TargetProductCode Validate="true">{98F055D3-99CF-4BBB-BC35-3672F9A297C1}</TargetProductCode><TargetVersion Validate="true" ComparisonType="Equal" ComparisonFilter="MajorMinorUpdate">5.2.3790.0</TargetVersion><TargetLanguage Validate="false">0</TargetLanguage><UpdatedLanguages>0</UpdatedLanguages><UpgradeCode Validate="true">{50CA09F3-3FAE-4FE1-BEF2-C29980E95B9A}</UpgradeCode></TargetProduct><TargetProductCode>{98F055D3-99CF-4BBB-BC35-3672F9A297C1}</TargetProductCode></MsiPatch>  
</msiar:MsiPatchMetadata></sdp:Metadata></sdp:ApplicabilityRules><sdp:InstallProperties CanRequestUserInput="false" RequiresNetworkConnectivity="false" Impact="Normal" RebootBehavior="CanRequestReboot" /><msp:MspInstallerData FullFilePatchCode="{69ea8e11-fbf9-4864-a50f-cd90ca54e86f}"><msp:MspFileName>uddiadm.msp</msp:MspFileName></msp:MspInstallerData></sdp:InstallableItem></sdp:SoftwareDistributionPackage>  

Command-line package

The following example shows the code used to populate an update metadata file using an executable package.

SoftwareDistributionPackage sdp = new SoftwareDistributionPackage();  
sdp.PopulatePackageFromExe("C:\\PackageDir\\setup.exe");  
sdp.Title = "Exe Package";  
sdp.Description = "Exe Package Description";  
sdp.IsInstalled = “<lar:And> <bar:FileExists Path='%windir%\\sample.dll' Version='1.0.0.1' /> <bar:FileVersion Path='%windir%\\Microsoft.NET\\Framework\\v1.1.4322\system.web.dll' Comparison='LessThanOrEqualTo' Version='1.1.4322.2032' /> <bar:InstalledOnce /> </lar:And>”;  
sdp.IsInstallable = “<bar:WindowsVersion Comparison='GreaterThanOrEqualTo' MajorVersion='5' MinorVersion='1' />”;  
… //more setup  
sdp.Save("C:\\test\\exeInstall.sdp");  

This code will produce an update metadata file like the following:

<sdp:SoftwareDistributionPackage   
 xmlns="http://www.w3.org/2001/XMLSchema"  
 xmlns:bar="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/BaseApplicabilityRules.xsd"  
 xmlns:bt="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/BaseTypes.xsd"  
 xmlns:cmd="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/Installers/CommandLineInstallation.xsd"  
 xmlns:lar="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/LogicalApplicabilityRules.xsd"  
 xmlns:msi="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/Installers/MsiInstallation.xsd"  
 xmlns:msiar="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/MsiApplicabilityRules.xsd"  
 xmlns:msp="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/Installers/MspInstallation.xsd"  
 xmlns:sdp="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/SoftwareDistributionPackage.xsd"  
 xmlns:uei="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/Installers/UpdateExeInstallation.xsd"  
 xmlns:usp="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/UpdateServicesPackage.xsd"  
 xmlns:drv="https://schemas.microsoft.com/wsus/2005/04/CorporatePublishing/Installers/WindowsDriver.xsd"  
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  SchemaVersion="1.1"><sdp:Properties PackageID="37d08b18-d23b-47d5-84e9-ffc35124666d" CreationDate="2007-09-13T20:18:07.295Z" PublicationState="Published" CanSourceBeRequired="false" UpdateType="Software"></sdp:Properties><sdp:LocalizedProperties><sdp:Language>en</sdp:Language><sdp:Title>Exe Package</sdp:Title><sdp:Description>Exe Package Description</sdp:Description></sdp:LocalizedProperties><sdp:ApplicationSpecificData /><sdp:IsInstallable><bar:WindowsVersion Comparison='GreaterThanOrEqualTo' MajorVersion='6' MinorVersion='0' /></sdp:IsInstallable><sdp:InstallableItem ID="0b8aee66-0c1e-4a7b-9148-f6e208b68c7d" ><sdp:ApplicabilityRules><sdp:IsInstalled><bar:InstalledOnce /></sdp:IsInstalled><sdp:IsInstallable><lar:True /></sdp:IsInstallable></sdp:ApplicabilityRules><sdp:InstallProperties CanRequestUserInput="false" RequiresNetworkConnectivity="false" Impact="Normal" RebootBehavior="CanRequestReboot" /><cmd:CommandLineInstallerData Program="setup.exe" DefaultResult="Failed" RebootByDefault="false"><cmd:ReturnCode Code="0" Result="Succeeded" Reboot="false"></cmd:ReturnCode></cmd:CommandLineInstallerData></sdp:InstallableItem></sdp:SoftwareDistributionPackage>