Primary elements and attributes of a package project file

  • Article

The root XML element in the package project XML file is the Package element. This element is the base container element for all other package-related elements in a package project XML file. It must occur only once, and it contains all the package information in the project file as attributes and child elements. The information in the Package element can be divided into four key areas: attributes, macros, security capabilities, and components.

The following XML example shows the schema definition of the Package element.

  <xs:element name="Package">
    <xs:complexType>
      <xs:sequence minOccurs="1" maxOccurs="1">
        <xs:element minOccurs="0" maxOccurs="1" ref="CustomMetadata" />
        <xs:element minOccurs="0" maxOccurs="1" ref="Macros" />
        <xs:element minOccurs="0" maxOccurs="1" ref="Capabilities" />
        <xs:element minOccurs="0" maxOccurs="1" ref="Components" />
        <xs:element minOccurs="0" maxOccurs="1" ref="Authorization" />
      </xs:sequence>
      <xs:attribute name="Owner" type="xs:string" use="required" />
      <xs:attribute name="Component" type="xs:string" use="required" />
      <xs:attribute name="SubComponent" type="xs:string" use="optional" />
      <xs:attribute name="BinaryPartition" type="xs:boolean" use="optional" />
      <xs:attribute name="OwnerType" use="required">
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:enumeration value="Microsoft" />
            <xs:enumeration value="OEM" />
            <xs:enumeration value="SiliconVendor" />
            <xs:enumeration value="MobileOperator" />
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
      <xs:attribute name="ReleaseType" use="required">
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:enumeration value="Production" />
            <xs:enumeration value="Test" />
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
      <xs:attribute name="Partition" type="xs:string" use="optional" />
      <xs:attribute name="Platform" type="xs:string" use="optional" />
      <xs:attribute name="GroupingKey" type="xs:string" use="optional" />
      <xs:attribute name="Description" type="xs:string" use="optional" />
    </xs:complexType>
  </xs:element>

Package attributes

Attributes of the target package(s) are described by using the XML attributes of the Package element. This element currently supports the following attributes.

Attribute Definition

Owner

Required. String that specifies the owner of the package. For example, Contoso.

Component

Required. String that specifies the component represented by the package. This value is used as a portion of the package ID.

SubComponent

Optional. String that specifies the subcomponent represented by the package.

ReleaseType

Required. String that specifies the type of release for which the package should be included. Valid values are the following:

  • Production

  • Test

Important  

If a package is intended to be included in a retail image, it must be marked as Production. Packages marked as Test will fail retail signing and are not allowed in retail images.

OwnerType

Required. String that specifies the category of owner for the package. Valid values are the following:

  • Microsoft

  • OEM

  • SiliconVendor

  • MobileOperator

Partition

Optional. String identifier for the target partition for the package. By default, packages are installed to the MainOS partition unless another is explicitly specified.

Warning  

  • Packages that are intended to be updated must not target the data partition. The reason for this restriction is that the data partition is formatted when the device reset feature is used.

  • Packages must only target a single partition.

Platform

Required. String, such as “QC8960”, that specifies the target platform for the package if the package is targeting a specific platform. By default, this value is NULL.

Note  

Although this attribute is specified as optional in the schema, it is required for all packages where the OwnerType attribute is not set to Microsoft.

GroupingKey

Optional. OEM-defined string that specifies an identifier for grouping packages together. By default, this value is NULL.

BinaryPartition

Optional. Boolean value that indicates whether the package contains a binary partition object. By default, this value is set to False.

Description

Optional. String that can be used to provide additional details about the package. This field can contain any string and is not read by any Microsoft components once contained in the manifest.

 

The following XML example demonstrates how to specify the package attributes.

<Package xmlns="urn:Microsoft.WindowsPhone/PackageSchema.v8.00"
   Owner="OEMName"
   OwnerType="OEM"     
   ReleaseType="Test"
   Platform="PlatformName"     
   Component="ComponentName"
   SubComponent="SubName">
</Package>

Note  

The package attributes shown in this example support the use of macros.

The Macros element and local project macros

To simplify the creation of the package project XML, macros can be used in the project file. A macro is essentially a unique identifier in the project file that is later replaced by a defined value. Each macro definition is represented by a Macro element within the parent Macros element. Each macro is defined by the attributes Id and Value. The following XML example shows the use of the Macros element to define a macro.

<Macros>
   <Macro Id="TypeLibId" Value="{F5078F18-C551-11D3-89B9-0000F81FE221}"/>
   <Macro Id="ProxyStubClsId" 
      Value="{00020424-0000-0000-C000-000000000046}"/>
</Macros>

The following XML example shows the schema definition of the Macros element.

<xs:element name="Macros">
   <xs:complexType>
      <xs:sequence>
         <xs:element name="Macro" minOccurs="1" maxOccurs="unbounded">
            <xs:annotation>
               <xs:documentation>
                  A Macro element defines a text substitution macro that can be used 
                  in other elements. Macros are referenced using NMAKE syntax, i.e. 
                  $(runtime.windows).
               </xs:documentation>
            </xs:annotation>
            <xs:complexType>
               <xs:attribute name="Id" type="MacroIdType" use="required">
                  <xs:annotation>
                     <xs:documentation>
                        Required. The Id for this macro, used in macro references. 
                        For example, if the Id for this macro is "runtime.windows",
                        the macro would be referenced as $(runtime.windows).
                     </xs:documentation>
                  </xs:annotation>
               </xs:attribute>
               <xs:attribute name="Value" type="MacroValueStringType" use="required">
                  <xs:annotation>
                     <xs:documentation>
                        Required. The value that will be substituted for macro 
                        references in macro- enabled XML attributes.
                     </xs:documentation>
                  </xs:annotation>
               </xs:attribute>
            </xs:complexType>
         </xs:element>
      </xs:sequence>
   </xs:complexType>
</xs:element>
Attribute Definition

Id

Required. String that specifies the name of the macro. This identifier should always start with either letters or a “_” character and then be followed by letters, digits, the “_” character, or the “.” character. No other characters are allowed in the Id attribute.

Note  

The Id for a macro is case sensitive and must be unique for each defined Macro element in the package project XML file.

Value

Required. String that specifies the expansion of the macro identifier. This value can include most ANSI characters and must match the following regular expression pattern: [a-zA-Z0-9\-_!@#%\^\.,;:=\+~`'\{\}\(\)\[\]\$ \\]*".

 

Macros can be used throughout the project file by using the syntax $(MacroName). Although macros are valid in most elements of the project file, they are not supported in all. Macros cannot be referenced in a nested fashion—for example $(Macro1_$(Macro2)—and they cannot be used in the definition of package attributes. Some other items of note about macros are:

  • A macro definition can include the use of a macro. For example, the following is valid.

    <Macros>
   <Macro Id="Windows" Value="\windows"/>
   <Macro Id="System32" Value="$(Windows)\System32"/>
</Macros>

  • The order macros are defined does not matter as long as the definitions are not recursive.

There are additionally global macros that can be used in a package project XML file, but they cannot be redefined within the package. Redefining a global macro causes a failure when the package generator tries to build the package.

The Components element

The Components element is the most important part of a package. It defines for the package generator what files and settings are included in the target package(s). Files, registry settings, and other information are grouped into different kinds of objects for packaging. You can include multiple objects into the target package(s) by listing them in this XML section. Currently the following objects are defined:

  • OSComponent

  • AppResource

  • Application

  • BCDStore

  • BinaryPartition

  • ComServer

  • Driver

  • Service

  • SvcHostGroup

  • WinRTHost

  • FullTrust

  • InboxApp

  • SettingsGroup

For additional details about these components, refer to Specifying components in a package project file. You can have any number of these types of objects in your package project (with the exception of some restrictions for the BinaryPartition object).