Basic Update Metadata

  • Article

 

Applies To: Windows Server Update Services

The basic update metadata is much the same for all types of update.

Root element

The root element of a locally-published update is the SoftwareDistributionPackage element. In addition to the namespace listing, this element has one required attribute: SchemaVersion. You should create this element by constructing a SoftwareDistributionPackage in the API, which ensures that the initial properties are set correctly.

The XML fragment below shows the start tag of the SoftwareDistributionPackage element.

<sdp:SoftwareDistributionPackage  
  xmlns=”http://www.w3.org/2001/XMLSchema”  
  xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”  
  
SchemaVersion=”1.2”>

Properties

The following properties appear under the Properties element of a SoftwareDistributionPackage. They can also be set from the authoring API. SoftwareDistributionPackage exposes these properties in the authoring API. It is recommended that you use either a tool or the API to set these properties instead of directly constructing XML. This will help ensure the properties are set correctly.

PackageID

A randomly-generated GUID. This value can be used by other updates that declare a relationship to this update (for example, as a prerequisite, or as one of the updates in a bundle). When you revise update metadata, you should preserve the ID to provide a good user experience. For more information about revising an update, see the topic Revising and Versioning Updates.

MoreInfoUrl

A URL providing more information than may have been available at publishing time, such as a Knowledge Base article. This property is purely informational and does not affect update installation.

SupportUrl

A URL which provides product support information for the update. The default value is an empty string. This property is informational and does not affect update installation.

ProductName

The marketing-approved product name but not the SKU (for example, "My Product SP1"). For updates, this is the name of the product(s) being patched and not the update itself. It allows administrators to sort updates by product. The default value is “Locally Published Updates”. This property is informational and does not affect update installation. For performance reasons you should create very few distinct product names, even if you have a large catalog of updates.

VendorName

The name of the vendor that created the software package. It allows administrators to sort updates by vendor. The default value is “Local Publisher”. This property is informational and does not affect update installation. For performance reasons you should create very few distinct vendor names, even if you have a large catalog of updates.

CreationDate

The UTC date and time that this revision of the update metadata was authored. This property is informational and does not affect update installation. If the package is revised, this property should be updated to the date and time of the revision.

CanSourceBeRequired

Specifies whether extra source code, such as a companion CD, may be required for installation of the update. If true for this update or for any children bundled by this update, source code may be required for installation. Otherwise the update can be installed without extra source code. The default value is false. It is recommended to leave it as false.

PublicationState

This is an optional property that defaults to "Published". It can be set to “Expired” to mark the update as no longer supported. For details about expiring updates, see the topic Revising and Versioning Updates. For all other scenarios, it should not be specified.

RestrictToClientServicingApi

Specifies whether this package is made available only through the Client Servicing API. This is optional and defaults to false. If true, agents talking to the WSUS web services will not receive this package. This is attribute that is typically not used by software publishers.

UpdateType

The type of the software package. This value is optional. UpdateType values are the following:

  • Software. The default value, designating an update package.

  • Driver. A driver must have either a command-line or an empty install-handler element. If the element is empty, it is a native driver installation. For more information about install handlers, see Install Handler Data.

  • Detectoid. A special update metadata file that provides shared applicability rules for many different updates. If a detectoid prerequisite is not met, the update will not be downloaded to the client. Detectoids are necessary to support large catalogs of updates, but they should be avoided in small catalogs because of their complexity.

SchemaVersion

Should be set to the string "1.2" if the update is a detectoid, bundle, or driver. It should also be set to "1.2" if the update declares prerequisites. In all other cases, it should be set to the string "1.1".

LocalizedProperties

The following elements appear under the LocalizedProperties element of a SoftwareDistributionPackage. These properties can be localized if necessary. They can also be set from the authoring API.

Language

The language of this set of localized properties. The first collection of properties is the default locale, in case the client or server has a locale that does not match. When using the authoring APIs, this value defaults to “en” for the initial set of properties. It must be specified in ISO 639-1 format, that is, two-letter language codes.

Title

The name or title of the package. This value is required. It should be less than 80 characters long for readability. We recommend titles such as:

Security Update for MyProduct (KB198704)

BIOS update for MyMachine (Reference number 87)

Description

A verbose description of the package. This will be rendered as text, not HTML.

UpdateSpecificData

The following elements appear under the UpdateSpecificData element. They can also be set from the authoring API. This element should be specified only for updates, not for applications, drivers, or detectoids.

SecurityBulletinID

Specifies the security bulletin ID of a vulnerability fixed by an update.

MsrcSeverity

This is a required field for security updates only, and should not be specified for other types of update. It is the maximum severity rating of the Microsoft Security Response Center (MSRC) bulletin associated with the update. Can be one of: Critical, Important, Moderate, or Low.

CveID

Specifies the Common Vulnerability and Exposures (CVE) identification number that provides security information about the software update. This is an optional field.

KBArticleID

Specifies the Microsoft Knowledge Base article ID associated with an update.

UpdateClassification

The classification of the update. Must be one of:

  • Updates. A broadly-released fix for a specific problem addressing a non-critical, non-security-related bug.

  • Critical Updates. A broadly-released fix for a specific problem addressing a critical, non-security related bug.

  • Security Updates. A broadly-released fix for a product-specific, security-related vulnerability. Security vulnerabilities are rated based on their severity, which is indicated in the Microsoft security bulletin as critical, important, moderate, or low.

  • Feature Packs. New product functionality that is first distributed outside the context of a product release, and usually included in the next full product release.

  • Update Rollups. A tested, cumulative set of hotfixes, security updates, critical updates, and updates packaged together for easy deployment. A rollup generally targets a specific area, such as security, or a component of a product, such as Internet Information Services (IIS).

  • Service Packs. A tested, cumulative set of all hotfixes, security updates, critical updates, and updates, as well as additional fixes for problems found internally after the release of the product. Service packs may also contain a limited number of customer-requested design changes or features.

  • Tools. A utility or feature that aids in accomplishing a task or set of tasks.

  • Hotfixes. Hotfixes address a specific customer situation and may not be distributed outside that customer organization.

InstallableItem Properties

The following elements appear under the InstallableItem element. They can also be set from the authoring API.

Note

The authoring and publishing APIs currently include a restriction that there can be only one installable item per package. This restriction may be removed in the future to support grouping-related updates (e.g., localized builds of the same update).

ID

This is a randomly-generated GUID that must be preserved across revisions of this update.

ApplicabilityRules

Additional applicability rules for this installable item, if any. If present, the rules are added (with the Boolean operator AND) to the ones specified at the package level. An item is not considered installable unless both its own IsInstallable rules and the package IsInstallable rules return true. If this element is omitted, the package-level rules are used.

For more information about setting applicability rules, see the topic Update Applicability Rules.

InstallProperties

Specifies the various behaviors for installation. It has the following sub-elements:

CanRequestUserInput

Specifies whether or not the package can request input from the user during installation. This attribute must be set to true if there is any possibility that input will be requested. Updates that can exhibit this behavior do not support automated deployment.

RequiresNetworkConnectivity

Specifies whether or not the package requires network connectivity for the installation or uninstallation to complete successfully. If true, the agent will not attempt the installation (or uninstallation) if the computer is not connected to a network. This attribute does not test the reachability of the Internet or any particular network server; that can be tested with applicability rules.

Impact

Specifies the level of the impact: normal impact, minor impact (zero-service interruption), or requires exclusive handling. Automatic Updates can be configured to install minor updates as soon as they arrive, rather than waiting for the next scheduled install. Updates that require exclusive handling are not installed in a batch with other updates.

RebootBehavior

Specifies whether installing this update always, never, or sometimes requires a reboot. For command-line installers, the installer-specific data must specify how to interpret the return code to know whether a reboot is required.

UninstallProperties

If present, specifies that the update can be uninstalled and the various behaviors for uninstallation. If not present, the update does not support uninstall.

InstallHandlerSpecificData

Data that is specific to the install handler (e.g., MSI, MSP, command-line). Each install handler defines its own format for this data. For more information, see the topic Install Handler Data.

OriginFile

If present, specifies the origin package file (for example, on the Microsoft Download Center). This property is used by ISVs to provide tools (like SCE or SCUP) with the URL of the update binary so that it can be downloaded and imported into the server. For local publishing scenarios this property is omitted.

Language

The language to which the binary has been localized. If unspecified, the item is language-independent. This refers to the language(s) of the binaries, as opposed to the languages supported by the metadata.