Specifying components in a package project file

  • 项目

This section provides more detailed information about the supported children of the Components element in a package project XML file.

OSComponent element

The OSComponent element is a container for Files and RegKeys elements. OSComponent has no attributes and is usually used to include system components such as shared DLLs, data files, and registry settings. For additional information about the Files and RegKeys elements, see Specifying files and registry entries in a package project file.

Note  

The OSComponent element must contain at least one Files element or RegKeys element.

The following XML example uses the OSComponents element to include various system files.

<Components>   
   <OSComponent>
      <Files>
         <File Source="$(_RELEASEDIR)\testdll.dll"/>
         <File Source="$(_RELEASEDIR)\testzh.dll"/>
         <File Source="$(_RELEASEDIR)\testEA.dll"/>
      </Files>
      <Files Language="*">
         <File DestinationDir="$(runtime.default)\mui\$(langid)" 
            Source="$(_RELEASEDIR)\$(LANGID)\testdll.dll.mui"/>
      </Files>
      <Files Language="(zh-CN;zh-TW)">
         <File DestinationDir="$(runtime.default)\mui\$(langid)" 
            Source="$(_RELEASEDIR)\$(LANGID)\testZH.dll.mui"/>
      </Files>
      <Files Language="(zh-CN;zh-TW;jp-jp;kr-kr)">
         <File DestinationDir="$(runtime.default)\mui\$(langid)" 
            Source="$(_RELEASEDIR)\$(LANGID)\testEA.dll.mui"/>
      </Files>
      <RegKeys Language="(zh-CN;zh-TW)">
         <RegKey KeyName="$(hklm.software)\microsoft\testZH\$(LANGID)">
            <RegValue Name="ZHConfig_$(LANGID)" Value="$(LANGID)" Type="REG_SZ"/>
            <RegValue Name="ZHConfig_$(LANGID)_Test" Value="$(LANGID)" 
               Type="REG_EXPAND_SZ"/>
         </RegKey>
      </RegKeys>
   </OSComponent>
</Components>

The files and registry keys can represent language-neutral or language-specific components.

Driver element

Windows 10 Mobile uses some of the same driver model as Windows 10 for desktop editions (Home, Pro, and Enterprise). You must import an .inf file for your driver into a package by using the Driver element. When an .inf file is specified, the packaging infrastructure calls the driver installation code to simulate the driver installation and determine the necessary registry change for the driver.

The following table describes the attributes of the Driver element.

Attribute Description

InfSource

Required. Specifies the .inf file for your driver to import into the driver package.

 

The following table describes the child elements of the Driver element.

Element Description

Reference

Optional. Specifies any additional files that are required when installing the driver (such as the driver's .sys file). Adding a Reference element doesn't actually add the file to the package, however; to do that, you must still use a Files element.

Files

Optional. Specifies a file to include in the driver package (such as the driver’s .sys file). For more info, see Specifying files and registry entries in a package project file.

Security

Optional. Specifies how the driver is accessible applications and services. For more info, see Security element below.

 

The following example adds a driver to a package.

<Components>   
   <Driver InfSource=
      "$(_WINPHONEROOT)\Sample.inf">
      <Reference Source="$(_RELEASEDIR)\Sample.sys" />
      <Files>
         <File Source="$(_RELEASEDIR)\Sample.sys"/>
      </Files>
   </Driver>
</Components>

The default file location for driver installation is "$(runtime.drivers)". The staging of the driver object requires access to the Mobile Core hive files. Therefore, it is necessary to set the variable HIVE_ROOT to the directory that contains those hives, which by default is %WPDKCONTENTROOT%\CoreSystem. The following example shows a package generator (PkgGen.exe) command that sets the HIVE_ROOT variable.

Pkggen.exe <other arguments> /variables:"HIVE_ROOT=%WPDKCONTENTROOT%\CoreSystem";<other variables> <other arguments>

Note  

If the driver uses the Include INF directive to reference other drivers that are part of the Mobile Core subset of the operating system, use the WIM_ROOT variable instead of the HIVE_ROOT variable. The default directory for the staging WIM image is the same as the hives.

For Windows 10 Mobile, you must use both the HIVE_ROOT and WIM_ROOT parameters. If you use only WIM_ROOT, the package might not be complete.

For more information about command-line arguments for PkgGen.exe, see Command-line arguments for package generator.

Security element

Under the default security policy for drivers, drivers are accessible to other TCB components (including other drivers and the kernel) and to services. Some device experiences require a driver that can be accessed by applications as well as services. To enable this scenario, OEMs may need to add a Security element under the Driver element.

The Security element has the following attribute and child elements.

Attribute Description

InfSectionName

Required. This attribute specifies the name of an AddReg directive section in the driver's .inf file. This specification allows for the injection of a Security Descriptor Definition Language (SDDL) string into the .inf file as part of package generation.

 

Element Description

AccessedByCapability

Optional. This element is used to specify a capability ID that is required for non-TCB code to access the driver, as well as the rights granted to that capability. The capability ID is specified through the Id attribute, which accepts a string that is the capability name. The rights are specified through the Rights attribute, which accepts one or more of the following strings:

  • $(DEVICE_READ)

  • $(DEVICE_WRITE)

  • $(DEVICE_ALL)

  • $(DEVICE_EXECUTE)

AccessedByApplication

Optional. This element is used to specify an app that can access the driver, as well as the rights granted to that application. The app is specified through the Name attribute, which accepts a string that is the app's product ID GUID. The rights are specified through the Rights attribute, which accepts one or more of the following strings:

  • $(DEVICE_READ)

  • $(DEVICE_WRITE)

  • $(DEVICE_ALL)

  • $(DEVICE_EXECUTE)

Note  

The product ID GUID must be specified including brackets, for example {263AF644-C573-4e00-BB49-740DD4C69664}.

AccessedByService

Optional. This element is used to specify a service that can access the driver, as well as the rights granted to that service. The service is specified through the Name attribute, which accepts a string that is the name of the service. This value must match the name of the service as it was declared in the Name attribute of the Service element. The rights are specified through the Rights attribute, which accepts one or more of the following strings:

  • $(DEVICE_READ)

  • $(DEVICE_WRITE)

  • $(DEVICE_ALL)

  • $(DEVICE_EXECUTE)

 

Service element

The Service element describes a service in the system and is used for the packaging and configuration of partner services.

The following table describes the attributes of the Service element.

Attribute Description

Name

Required. The name of the service. The string is case sensitive.

DisplayName

Optional. The displayable name of the service.

Description

Optional. A description of the service.

Start

Required. An enumeration value that defines when the service will start. Valid values are the following:

  • Demand – The service starts after the OS has finished booting and the shell is available. Microsoft strongly recommends using this value for services in Windows 10 Mobile wherever possible.

  • Auto – The service starts automatically during system startup.

Type

Required. An enumeration value that defines the service type. Valid values are the following:

  • Win32OwnProcess – A service that runs in its own process.

  • Win32ShareProcess – A shared service that runs in a host process with other services.

DependOnService

Optional. A service on which the service being defined depends.

ErrorControl

Optional. An enumeration value that defines the severity of the error and the action to take if the service fails to start. Valid values are the following:

  • Ignore –The startup program should ignore the error and continue the startup operation.

  • Normal – The startup program should log the error in the event log but continue the startup operation.

  • Severe – The startup program should log the error in the event log. If the last-known-good configuration is being started, the startup operation continues. Otherwise, the system is restarted with the last-known-good configuration.

SvcHostGroupName

Required for shared services. A unique OEM-defined string that identifies a particular service group. All services shared in the same process must assign the SvcHostGroupName attribute to the same value.

 

The following table describes the child elements of the Service element.

Element Description

Executable

Required for services that run in their own process. This element defines the service executable through the following four attributes.

  • Name - Optional. The name for the executable on the device. If a name is not specified, the file name in the source path is used.

  • Source – Required. The source path of the service executable to be included in the package. This path can be an absolute or relative path. It is also valid to use macro references in the path.

    Note  

    If the executable file does not exist, package generation will fail.

  • DestinationDir – Optional. The destination folder on the device for the service executable. This path must start with a globally defined macro for a directory. If this attribute is not specified, the default location for services is used.

  • Attributes – Optional. The file system attributes for this file on the device. The value can be a combination of the following, separated by a space character.

    • Archive

    • Hidden

    • Offline

    • ReadOnly

    • System

    • Temporary

    • SparseFile

    • NotContentIndexed

    When not specified, a predefined default value is used.

    Note  

    The file system might not support all of these attributes.

FailureActions

Optional. This element defines the actions taken on the failure of the service. It has one child element (Action) and two attributes (Command and ResetPeriod).

The Action element specifies the action to be performed. At least one Action element is required when FailureActions is included, and each Action element must contain two attributes. The first attribute is Type, which is an enumeration value that specifies the type of action to take. The second attribute is Delay, which is a non-negative integer that specifies the time, in milliseconds, to wait before performing the action. Valid values for Type are the following:

  • None – No action.

  • RestartService – Restart the service.

  • RunCommand – Run a command.

The following list describes the two attributes of the FailureActions element.

  • Command – Optional. The command line of the process for the CreateProcess function to execute in response to a failure, when the RunCommand attribute is specified through the Action element. This process runs under the same account as the services.

    Note  

    If the value is NULL, the command is unchanged. If the value is an empty string (""), the command is deleted and no command is run when the service fails.

  • ResetPeriod – Required. The time, in seconds, after which to reset the failure count to zero if there are no failures. Specify INFINITE to indicate that the count should never be reset.

Files

Optional. This element, through its child element File, defines supporting files to include with the service. The File element has the following four attributes:

  • Name - Optional. The name for the file on the device. If a name is not specified, the file name in the source path is used.

  • Source – Required. The source path of the file to be included in the package. This path can be an absolute or relative path. It is also valid to use macro references in the path.

    Note  

    If the file does not exist, package generation will fail.

  • DestinationDir – Optional. The destination folder on the device for the file. This path must start with a globally defined macro for a directory. If this attribute is not specified, the default location for files is used.

  • Attributes – Optional. The file system attributes for this file on the device. The value can be a combination of the following, separated by a space character.

    • Archive

    • Hidden

    • Offline

    • ReadOnly

    • System

    • Temporary

    • SparseFile

    • NotContentIndexed

    When not specified, a predefined default value is used.

    Note  

    The file system might not support all of these attributes.

RegKeys

Optional. Specifies registry entries for the service through the child element RegKey. For additional information about the RegKey element, see Specifying files and registry entries in a package project file.

RequiredCapabilities

Optional. Specifies platform capabilities required by the service. When used, at least one child RequiredCapability element must be provided. The RequiredCapability element has one attribute, CapId, which specifies a valid platform capability.

ServiceDll

Required for shared services that run in a host executable. Specifies information about the DLL that implements the service. The ServiceDll element has the following attributes:

  • Source – Required. The full path of the service DLL on the development computer.

  • HostExe – Required. The full path of the service host executable for the service on the image. For example, "$(runtime.system32)\OEM_SampleHost.exe".

 

BinaryPartition element

The BinaryPartition element is used to create binary partition packages. If a package contains a BinaryPartition object, it can contain no other objects, including other BinaryPartition objects.

There is also a special package-level Boolean attribute called BinaryPartition. When this attribute is set, one and only one BinaryPartition element must be added.

The BinaryPartition element has only one attribute, ImageSource, which points to a file that contains a binary dump of the target partition. You must specify the appropriate value for the package-level Partition attribute.

ComServer element

The ComServer element describes a DLL and all of the COM classes and related items derived from the DLL. It is designed to simplify how CLSID-related registry settings are specified. The ComServer element is derived from OSComponent and includes three additional child elements:

  • Dll: This element specifies the DLL that exports all the COM classes in the ComServer object. The path of the DLL will also be used for the path stored under the InprocServer32 registry key.

  • Classes: This element specifies the classes exported from the Dll element. It contains multiple Class elements, each of which can have the following attributes.

    Attribute Description

    ID

    Required. A string that specifies the class ID. For example, "{a3079dc1-e685-4e37-af40-057ed6d0e252}"

    TypeLib

    Optional. A string that specifies the TypeLib class ID.

    AppId

    Optional. String.

    ProgId

    Optional. String.

    Description

    Optional. String.

    VersionIndependentProgId

    Optional. String.

    Version

    Optional. String.

    DefaultIcon

    Optional. String.

    ThreadingModel

    Optional. A string that specifies the threading model. Valid values are:

    • Apartment

    • Free

    • Both

    • Neutral

     

    In addition to these attributes, you can also specify zero or more RegKey child elements under a Class element. When registry information is included here, the built-in macro $(hkcr.clsid) (which is mapped to the string "HKCR\Classes\CLSID\<currentClsId>") can be used to add more settings for this class without mentioning the full key name. The following example demonstrates the definition of a Class object.

    <Class 
   Id="{2933BF90-7B36-11D2-B20E-00C04F983E60}" 
   Version="1.0" 
   TypeLib="{D63E0CE2-A0A2-11D0-9C02-00C04FC99C8E}" 
   ThreadingModel="Both" 
   ProgId="Microsoft.XMLDOM.1.0" 
   VersionIndependentProgId="Microsoft.XMLDOM" 
   Description="XML DOM Document">

   <RegKey KeyName="$(hkcr.clsid)\SideBySide">
      <RegValue Name="RefCount" Type="REG_DWORD" Value="00000001" />
      <RegValue Name="Version30RefCount" Type="REG_DWORD" Value="00000001" />
   </RegKey>
   <RegKey KeyName="$(hkcr.clsid)\VersionList">
      <RegValue Name="3.0" Type="REG_EXPAND_SZ" 
         Value="%SystemRoot%\System32\msxml3.dll" />
    </RegKey>
</Class>

  • Interfaces: This element contains a list of Interface elements that describe the interfaces implemented by the ComServer object. Similarly to Class elements, the following attributes and zero or more RegKey child elements can be specified.

    Attribute Definition

    ID

    Required. A string that specifies the class ID. For example, "{a3079dc1-e685-4e37-af40-057ed6d0e252}"

    TypeLib

    Optional. String that specifies the TypeLib class ID.

    Name

    Optional. String.

    ProxyStubClsid

    Optional. String.

    ProxyStubClsid32

    Optional. String.

     

    For the Interface element, there is a built-in macro $(hkcr.iid) that maps to "HKCR\Classes\Interface\<interfaceId>". The following example demonstrates the definition of an Interface object.

    <Interface 
   Id="{D4D4A0FC-3B73-11D1-B2B4-00C04FB92596}" 
   TypeLib="$(TypeLibId)" 
   Name="IXMLAttribute" 
   ProxyStubClsId="{00020424-0000-0000-C000-000000000046}" 
   ProxyStubClsId32="$(ProxyStubClsId)">
   <RegKey KeyName="$(hkcr.iid)\TypeLib">
      <RegValue Name="Version" Type="REG_SZ" Value="3.0" />
   </RegKey>
</Interface>

    The default device directory for this object is $(runtime.system32).

SettingsGroup element

A SettingsGroup element represents a settings group in the customization answer file. Managed Centralized Settings Framework (MCSF) provides a standard way to describe settings that are customizable within packages.

Custom OEM package metadata

OEMs have the ability to insert custom XML metadata into packages through the package project XML file (.pkg.xml). When packages are generated, this XML data is written to a separate file (.meta.xml) inside of the package. When the package is added to the image, the custom metadata will be available on the device.

Adding custom metadata to package files

The CustomMetadata element is used to add custom metadata under the Package node. The XML within CustomMetadata is a series of key-value pairs using the Field element as shown below.

<Package>
  <CustomMetadata>
    <Field Name="Key">Value</Field>
  </CustomMetadata>
  <Macros>
  </Macros>
  <Capabilities>
  </Capabilities>
  <Components>
  </Components>
  <Authorization>
  </Authorization>
</Package>

PkgGen writes out the content of CustomMetadata tag to the .meta.xml file in the package. The layout of this file is nearly identical to the input.

<?xml version="1.0" encoding="utf-8"?>
<CustomMetadata xmlns="urn:Microsoft.WindowsPhone/PackageSchema.v8.00">
  <Field Name="Key">Value</Field>
</Field>
</CustomMetadata>

The output metadata file is included in the package, and is installed on the phone in \Windows\Packages\CustomMetadataFiles, as PackageName.meta.xml. This folder is a sibling of the DsmFiles folder that is used for packages.

The packaging and device update tools treat the .meta.xml file like any other file on the phone.

Walkthrough – adding custom metadata

Use the following process to add custom data to an existing package.

To add custom data to an existing package

  1. Locate the desired package project XML file and open it in a text editor such as Notepad.

  2. Add the desired metadata tags right after the <Package> element. For example, to track a targeted version, model, and development team, add the following metadata value pairs.

    <CustomMetadata>
    <Field Name="TargetVersion">8.1</Field>
    <Field Name="PrimaryPhoneModel">DCD6000</Field>
    <Field Name="DevelopmentTeam">Alpha Team</Field>
  </CustomMetadata>

  3. Use PkgGen to generate a package. For more info, see Creating packages.

Walkthrough – viewing custom metadata

Use the following process to confirm that the metadata file is present in the generated package.

To confirm that the metadata file is in the generated package

  1. On a Windows PC, locate the generated package and add a ".cab" file extension to the package name.

  2. Double-click the renamed file to view files that are stored in the .cab file.

  3. The package files are renamed in the .cab file. To locate the filename of the metadata file that will be used on the device, click the man.dsm.xml file, extract it, and open it. One of the file entries will show the .meta.xml package name and the .cab file name that is used. In this example, 4_Contoso.xml is the name of the metadata XML file.

    …
   <FileEntry>
      <FileType>Regular</FileType>
      <DevicePath>\Windows\Packages\CustomMetadata\Contoso.TestApp.meta.xml</DevicePath>
      <CabPath>4_Contoso.xml</CabPath>
      <Attributes>Normal</Attributes>
    </FileEntry>

  4. Extract the 4_Contoso.xmland open it. Confirm that it contains the expected metadata.

    <?xml version="1.0" encoding="utf-8"?>
<CustomMetadata xmlns="urn:Microsoft.WindowsPhone/PackageSchema.v8.00">
  <Field Name="TargetVersion">8.1</Field>
  <Field Name="PrimaryPhoneModel">DCD6000</Field>
  <Field Name="DevelopmentTeam">Alpha Team</Field>
</CustomMetadata>

Creating packages