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:
|
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:
Note
The product ID GUID must be specified including brackets, for example |
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:
|
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:
|
Type |
Required. An enumeration value that defines the service type. Valid values are the following:
|
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:
|
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.
|
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:
The following list describes the two attributes of the FailureActions element.
|
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:
|
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:
|
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
Locate the desired package project XML file and open it in a text editor such as Notepad.
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>
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
On a Windows PC, locate the generated package and add a ".cab" file extension to the package name.
Double-click the renamed file to view files that are stored in the .cab file.
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>
Extract the
4_Contoso.xml
and 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>