Connect User - Tistory

IMAGE CUSTOMIZATION GUIDE Microsoft Corporation

August 2013

SUMMARY

The Image Customization Guidance document provides partners with guidelines for customizing

their device’s image. By providing best practices for image customization, OEMs will ultimately

give the consumer a good Windows experience as soon as they unpack and power up their

Windows device.

Version: 0.3

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser

CONTENTS

Summary.......................................................................................................................................... 1

Document Changes ......................................................................................................................... 4

Purpose .............................................................................................. Error! Bookmark not defined.

Image Customization Goals ............................................................................................................. 4

Out-Of-Box Experience (OOBE) ....................................................................................................... 4

OEM Logo File .................................................................................................................................. 5

Creating the logo .......................................................................................................................... 5

Positioning the logo during POST ................................................................................................. 6

Adding the logo to the BGRT ........................................................................................................ 6

OEM HID pairing instructions .......................................................................................................... 7

Required files ............................................................................................................................... 7

Making sure HID pairing pages display correctly ....................................................................... 12

Recommendations ..................................................................................................................... 15

OEM registration ........................................................................................................................... 15

Customizing the Registration page ............................................................................................ 16

OOBE.xml settings ......................................................................................................................... 18

OOBE.xml sample ....................................................................................................................... 22

Time stamp................................................................................................................................. 24

User name .................................................................................................................................. 25

Managing and uploading user data ........................................................................................... 25

Generating public and private keys ........................................................................................... 26

Key generation code snippet ..................................................................................................... 27

Decrypting the data ................................................................................................................... 32

Finishing Setup ........................................................................................................................... 39

OEM License .................................................................................................................................. 40

OOBE.xml settings ...................................................................................................................... 41

OOBE settings ............................................................................................................................. 41

Single-language deployments .................................................................................................... 42

Multiple-language or region deployments ................................................................................ 43

Country/region folder format .................................................................................................... 45

Language folder format ............................................................................................................. 45

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser

Sample OOBE.xml file .................................................................................................................... 45

Windows Apps ............................................................................................................................... 52

Adding Apps To An Image .......................................................................................................... 52

Assigning app tile activity by using Unattend settings ............................................................... 54

Assigning apps to start ............................................................................................................... 56

Assigning one app to the lock screen by using Unattend settings............................................. 56

Naming your group of tiles ........................................................................................................ 57

Unattend.xml sample ................................................................................................................. 57

Background Apps ....................................................................................................................... 65

Internet Explorer ........................................................................................................................... 65

Internet Explorer Settings .......................................................................................................... 65

Internet Explorer Unattend Settings .......................................................................................... 66

The Windows Experience .............................................................................................................. 66

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser

Image Customization Guide

Microsoft Confidential. © 2013 Microsoft Corporation. All rights reserved. 4

INTRODUCTION

The manufacturing process culminates with a Windows device that delivers a quality Windows

experience. Building that device begins with a crucial step in a long chain of events that

originates from an “ideal” image on a source computer. This crucial step is image customization.

Important: The Image Customization document is not intended to communicate the Windows

Hardware Certification Requirements. The Windows Hardware Certification Requirements

document takes precedence to any information in the WEG. You must comply with the

Windows Hardware Certification Requirements.

DOCUMENT UPDATES

Date updated Description

May 2013 V0.1 is the initial release.

June 2013 V 0.2 includes info on configuring the default email signature, time zone configuration in the OOBE.XML file, and edits for better readability.

August 2013 V 0.3 includes the SystemDefaultBackgroundColor unattend setting.

IMAGE CUSTOMIZATION GOALS

This guidance document takes you through the image customization process and provides

instructions where necessary. Where applicable, this guide uses cross-references to existing

documents in the Windows Engineering Guides (WEGs) library, which includes WEGs and

supplemental documents. Supplemental documents address specific topics such as battery and

form factor guidance.

OUT-OF-BOX EXPERIENCE (OOBE)

When customers turn on their Windows Blue PCs the first time, OOBE (Out of Box Experience)

displays. OOBE is a series of screens that require them to make crucial choices and enter info for

their PC’s customized experience. For example, the customer will select which language they

want for their display. In Windows Blue, this flow is streamlined. The choices you make in your

hardware and software engineering determine how much work customers must do (while

completing OOBE screens) before they can enjoy their Windows Blue PCs.

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



OEM considerations for first boot include:

OEM Logo. Before customers see any actionable screens, your logo displays on the boot screen.

That same resource displays on every OEM screen in OOBE.

HID Pairing. If you include an unpaired wireless keyboard and mouse, you must include the

resources for the HID pairing screens to appear.

OEM registration. If you specify OOBE.xml settings for the title, subtitle, at least one labeled

screen element, and a public key for public/private key encryption, customers see the

Registration screen.

OEM License Terms. If you include an End User License Terms file and the correct settings in

OOBE.xml, these terms display next to the Windows License Terms.

OOBE.xml. If you include multiple language packs in the image, customers see a language

selection screen. You must use multiple OOBE.xml files to deploy to multiple countries or

regions.

Default color. If you want to set the default color for the background of the Windows OOBE

screens, use the Microsoft-Windows-Shell-Setup | VisualEffects |

SystemDefaultBackgroundColor setting. The default color will also be applied to the log in

screen when no user is selected.

OEM LOGO FILE

In Windows Blue, POST (Power-On Self-Test) and OS Startup times are dramatically faster

compared to Windows 7. To make sure the OEM has a proper branding moment, the OEM logo

is visible across both POST and the OS startup. In this new approach, the OEM logo is readily

recognizable, suitably sustained, and associated with a fast and reliable experience.

CREATING THE LOGO

The logo you add presents customers with their first visual encounter with their new

Windows Blue PCs, so it should be clean, crisp, and sharp, on its edges, as well as inside.

The background of the boot screen is always black, so use a logo that looks great on a black

background. It must also have a true black background so there's no noticeable difference

where the logo's black background ends and the screen's black background begins.

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



Transparency isn't supported. The black background optimizes system performance for both the

initial rendering of the logo and the fade-out at the end of boot for the transition from the UEFI

GOP to the OS native video driver. In addition, other areas of Windows use your logo —Setup,

Push Button Reset, Secure boot remediation, and Startup Repair Tool—all of which use a black

background. All of these experiences use the same logo from the Boot Graphics Resource Table

(BGRT).

POSITIONING THE LOGO DURING POST

The firmware draws the OEM logo at POST and places the logo in a predetermined position.

When Windows Blue OS Startup begins, the logo is kept in the video buffer. Desktops can detect

the panel's native resolution by reading its EDID (Extended display identification data).

To make the logo appear correctly across the entire sequence, POST needs to occur in the

device's native resolution. This makes sure the logo is the size, shape, and location you want and

that Windows requires.

The logo must appear on the screen at a specific location to showcase the PC's brand and affirm

the customer's personal choice in their purchase. It's important to the overall design of the

screen that the logo is placed with its center at 38.2% from the screen's top edge. This

positioning is based on the golden ratio's visual aesthetics and matches the Windows Blue

design proportions. This consistent positioning across all Windows Blue PCs lets Windows place

the progress ring in the correct location and make sure the logo and ring are visually balanced.

To further support this visual balance, the logo is limited in size to 40% of the screen's height

and width. This makes sure the screen appears correctly and that Windows can properly fade

out the logo at the end of boot. The logo's maximum area must start at no more than 18.2%

from the top of the screen.

These design principles apply to both landscape and portrait devices.

ADDING THE LOGO TO THE BGRT

In addition to correctly positioning the logo during POST, you also store the logo inside the BGRT

(Boot Graphics Resource Table). The BGRT dynamically defines new objects for Windows to use

to describe the resources and on-screen location. You must store the logo in

EfiBootServicesData and expose it via the BGRT. The BGRT interface supports this logo as either

a 24-bit bitmap with a pixel format of OxRRGGBB, or a 32-bit bitmap with a pixel format of

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



OxrrRRGGBB where rr is reserved. This is the standard interface Windows uses to access the

logo.

Two important fields in the BGRT are "Image Offset X" and "Image Offset Y". These are the (x,y)

values of the upper-left corner of the logo's on-screen placement. When you set these values,

make sure not to use the logo's position or the upper-left corner of the bounding box, or else

Windows won't correctly position the logo in Setup, Startup Repair, Push Button Reset, and

other experiences.

You should minimize padding in the logo resource and use only what's necessary for proper

centering. Using minimal padding saves space in the firmware and lets Windows scale the BGRT-

based logo properly. Too much extra spacing means your logo will appear much smaller when it

is scaled to display on the OOBE screens.

OEM HID PAIRING INSTRUCTIONS

Because OEMs can provide clear and precise HID pairing instructions within the context of the

first experience, customers who buy new Windows Blue PCs with an unpaired wireless mouse

and keyboard can finish their PC setup with confidence. For this feature to work, the mouse

and/or keyboard must be included with the PC and the PC must not have any other mice and/or

keyboards attached or connected to it. For example, laptops are not qualified for this feature.

Important

The OOBE.xml file that has HID Pairing instructions must be used only for PCs that use the OOBE

HID Pairing feature. For other PCs that don't use the OOBE HID Pairing feature, a different

OOBE.xml file that does not contain the HID Pairing instructions must be used. Otherwise, there

is a risk that users may inconveniently go through the HID Pairing experience even if they don't

need this feature.

REQUIRED FILES

On PCs that ship with an unpaired wireless mouse and keyboard, the HID pairing screens are

shown to the customer during the first experience, which is before language selection or any

other screen that requires user input. If you include verbal instructions, you must include those

instructions in every language that ships with the PC.

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



To provide a thorough, reliable, and satisfactory HID pairing experience, OEMs who ship these

systems must include these files:

IMAGE FOR MOUSE PAIRING

This should show a photorealistic image of the mouse that ships with the system. Generic

images decrease confidence and increase confusion in customers, who want images on the

screen to match the devices they're trying to use. Also, include iconic instructions for the actions

customers must take to pair their new hardware. For example, if the first step is to insert

batteries into the mouse, include an image of batteries near the mouse.

Typically, the three steps customers need to finish are: inserting batteries, turning on the power,

and turning on Bluetooth.

IMAGE FOR MOUSE PAIRING ERROR

If the customer can't pair the mouse in three tries, the error screen displays. This image should

show a photorealistic image of the mouse and include imagery that instructs the customer to

connect a wired mouse instead.

FIRST IMAGE FOR KEYBOARD PAIRING.

This should show a photorealistic image of the keyboard that ships with the system. Generic

images decrease confidence and increase confusion in customers, who want images on the

screen to match the devices they're trying to use. Also, include iconic instructions for the actions

customers must take to pair their new hardware. For example, if the first step is to insert

batteries into the keyboard, include an image of batteries near the keyboard.

Typically, the first set of steps customers need to finish includes inserting batteries, turning on

power, and turning on Bluetooth.

SECOND IMAGE FOR KEYBOARD PAIRING

This should show a photorealistic image of the keyboard that ships with the system.

Typically, the second set of steps customers need to finish includes entering a password or code

and pressing Enter.

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



IMAGE FOR KEYBOARD PAIRING ERROR

If the customer can't pair the keyboard in five tries, the error screen displays. This should show a

photorealistic image of the keyboard and include imagery that tells the customer to connect a

wired keyboard.

OOBE.XML FILE

Oobe.xml is a content file that OEMs can use to organize text and resources for the OEM screens

in Windows Blue. OEMs can use multiple Oobe.xml files for language- and region-specific license

terms and settings, so users see the correct info as soon as they start their PCs.

Note

Users are better able to finish the HID pairing task when the OEM includes brief and clear verbal

instructions on the images.

These illustrations are examples of how HID pairing instructions might look.

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



MAKING SURE HID PAIRING PAGES DISPLAY CORRECTLY

To display HID pairing screens correctly, these conditions must be met:

The PC should have Bluetooth capability and Bluetooth should be turned on.

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



The Bluetooth radio must be Windows Blue certified.

For the keyboard pairing page to appear, no wired keyboard should be connected to the PC.

For the mouse pairing page to appear, no wired mouse should be connected to the PC.

All of the OOBE.xml settings in the <hidsetup> section should be provided for the corresponding

pairing pages.

OOBE.XML SETTINGS AND ALLOWED VALUES

Setting Description Value

mouseImagePath Absolute path to the mouse pairing instruction image.

The image must not be larger than 630 x 372 pixels. It's scaled to fit in portrait mode or on small form factors.

Absolute path to image

mouseText Help text that displays at the bottom of the page.

String

mouseErrorImagePath Absolute path to the mouse pairing error image.


Absolute path to the image

mouseErrorText Error text that displays to users along with mouse pairing error image.

String

keyboardImagePath Absolute path to the first keyboard pairing instruction image.

The image must not be larger than 630 x 372 pixels. It’s scaled to fit in portrait mode or on small


Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser




form factors.

keyboardText Help text that displays at the bottom of the page.

String

keyboardPINImagePath Absolute path to the second keyboard pairing instruction image.



keyboardErrorImagePath Absolute path to the keyboard pairing error image.



keyboardErrorText Error text that displays with keyboard pairing error image.

String

Important

Any text in the OOBE.xml file or files—for example, any text in the <mouseText> setting—is the

text read by the Narrator, so make sure the text is clear, concise, and easy to understand.

OOBE.XML SAMPLE

This snippet of a sample OOBE.xml file shows how to use the HID Pairing settings.

<hidSetup>

<mouseImagePath>c:\fabrikam\MouseFirstInstruction.png</mouseImagePath>

<mouseText>Set up your Fabrikam mouse. Insert batteries, turn on, and press the Bluetooth

button.</mouseText>

<mouseErrorImagePath>c:\fabrikam\MouseError.png</mouseErrorImagePath>

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



<mouseErrorText>An error has occurred. Please contact Fabrikam.</mouseErrorText>

<keyboardImagePath>c:\fabrikam\KeyboardFirstInstruction.png</keyboardImagePath>

<keyboardText>Set up your Fabrikam keyboard. Insert batteries, turn on, and press the

Bluetooth button.</keyboardText>

<keyboardPINImagePath>c:\fabrikam\KeyboardSecondInstruction.png</keyboardPINImagePath

>

<keyboardPINText>Enter PIN and press the Enter key.</keyboardPINText>

<keyboardErrorImagePath>C:\fabrikam\KeyboardError.png</keyboardErrorImagePath>

<keyboardErrorText>An error has occurred. Please contact Fabrikam.</keyboardErrorText>

</hidSetup>

RECOMMENDATIONS

HID Emulation Mode (HEM). For PCs that ship without built-in mice, keyboards, or touchscreens,

we recommend OEMs include Bluetooth radios with HEM to provide a working end-to-end

scenario.

Background. There's no Bluetooth support in the BIOS before Windows loads. The workaround

is to have a Bluetooth radio with HEM. The radio looks like a USB mouse and keyboard to the

PC, and takes over the Bluetooth communication to the mouse and keyboard. This lets the

devices work outside of Windows and allows customers to use their paired Bluetooth mice and

keyboard during BIOS.

OEM REGISTRATION

If you choose to implement the optional Registration page, it marks the beginning of your

relationship with your customers. We recommend it provides info and opportunities that

benefit them. The page lets you gather user info, activate an antimalware app, and introduce

additional offers. You can customize it to suit your business needs. The simple design and single-

page format are designed to help users move quickly through the First Experience by minimizing

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



the amount of text they must enter. Because completing the form is so quick and easy, they're

less likely to skip filling it out.

Taking advantage of the Registration page is a multi-step process. This list provides an overview

of it.

Decide what elements of customer info you need to capture in the first experience. You might

require an email address so you can contact the customer about their PC, or a postal code so

you can send them info or offers specific to their region.

Decide what conditions you need to give customers a chance to agree to. You might need them

to agree to start an antimalware app trial or to receive email from your company.

Decide what info you need to expose to the customer. For example, you might need to present

license terms that must remain separate from your company's general terms.

Plan and deploy your custom OOBE.xml file or files as determined by the languages and regions

you ship your company's PCs in. Oobe.xml is a content file that OEMs can use to organize text

and resources for the OEM screens in Windows Blue. You can use multiple Oobe.xml files for

language- and region-specific license terms and settings so users see the correct info as soon as

they start their PCs.

Generate a public/private key pair for customer data encryption and decryption. To protect

customer privacy, Windows encrypts the customer data that's generated through participation

in, and completion of, the Registration page. If the OEM doesn't store a public key appropriately,

the Registration page isn't shown.

Create and preinstall a Windows Store app, or write a service, to collect the encrypted customer

data, the user name from the Windows.System.UserProfile namespace, and the local time

stamp of first sign-in, and then upload that data set to your server for decryption and use. A

Windows Store app must be started by the customer. The app can use the AUMID (Application

User Model ID) in Unattend.xml in the OEMAppId setting to collect the time stamp, user data,

session key, and check box state data written to the appdata folder for the app. Alternatively,

you can write a service that's set to run 30 minutes after first sign-in that collects the customer

data and delivers it to your server for decryption and further use.

CUSTOMIZING THE REGISTRATION PAGE

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



This image shows the Registration page with sample customizations by the fictional OEM

Fabrikam.

Note

This image is preliminary and subject to change. The fields and labels depicted aren't intended

as guidance and don't necessarily represent final functionality.

This image doesn't show the OEM logo that appears on the page.

The Registration page presents many customization opportunities. This list describes the

settings you can control.

Page title. You can create a title that makes sense for your use of the page.

Page subtitle. You can add a subtitle to help customers understand the tasks on the page or in

some other way guide them to complete the form.

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



Two text fields. You can label the text fields, set one of two input scopes for the touch

keyboard, and decide whether to show two, one, or no text fields.

Three check boxes. You can set the descriptive text for the check boxes, set their default state –

selected or not – and Decide whether to show three, two, one, or no check boxes.

Three flyout links. You can specify the link label and the in-place link text. Any text you associate

with these links must be in .rtf files stored locally in the OOBE\Info directory. You can also

decide whether to show three, two, one, or no links.

For more info about how to structure the OOBE\Info directory to accommodate .rtf files that

contain resources for different regions and languages, see OOBE.xml.

Some of the elements on the Registration page aren't customizable. The OEM logo is drawn

from the resource in the firmware. The buttons that customers use to complete or skip the page

are labeled by Windows. You can’t alter the default state of the buttons or disable them.

The layout of the page is locked, so the page elements can't be rearranged.

A minimum amount of info is required for the page to display at all. The page won't display if the

OEM hasn't provided a title, subtitle, at least one labeled screen element, and a public key for

public/private key encryption.

OOBE.XML SETTINGS

This table shows the Registration page settings and their allowed values in OOBE.xml.

Note

The ampersand symbol, (&) cannot be used in this section of OOBE.xml. Use the word “and”

instead.

Section Setting Description Value

title Required. Text to title the Registration page.

String of up to 25 characters.

subtitle Required. Text to describe the


Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser




Registration page.

textbox1

label Text to label textbox1. Required for textbox1 to appear.


inputscope Value to set scope of touch keyboard.

Two supported scopes:

4 (IS_EMAIL_USERNAME)

29 (IS_NUMBERS)

textbox2

label Text to label textbox2. Required for textbox2 to appear.


inputscope Value to set scope of touch keyboard.

Two supported scopes:

4 (IS_EMAIL_USERNAME)

29 (IS_NUMBERS)

checkbox1

label Text to label checkbox1. Required for checkbox1 to appear.

String of up to 250 characters. We strongly recommend using no more than 100 characters because this length of text fits on one line.

defaultvalue Value to set checkbox1 as selected or not selected.

True or False. True means the check box default condition is selected. False means the check box default condition isn't selected.

checkbox2

label Text to label checkbox2. Required for checkbox2 to appear


Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser






checkbox3

label Text to label checkbox3. Required for checkbox3 to appear




link1

label Label for the link to the .rtf file. Required for link1 to appear.


link File must be named linkfile1.rtf. OOBE searches for files named linkfile1.rtf, linkfile2.rtf, or linkfile3.rtf under the oobe\info folder. OOBE searches for files under the appropriate locale and language specific subfolders of oobe\info.

linkfile1.rtf

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser




link2



link File must be named linkfile2.rtf. OOBE searches for files named linkfile1.rtf, linkfile2.rtf, or linkfile3.rtf under the oobe\info folder. OOBE searches for files under the appropriate locale and language specific sub-folders of oobe\info.

linkfile2.rtf

link3



link File must be named linkfile3.rtf. OOBE searches for files named linkfile1.rtf, linkfile2.rtf, or linkfile3.rtf under the oobe\info folder. OOBE searches for files under the appropriate locale and language specific sub-folders of oobe\info.

linkfile3.rtf

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



Note

There's no limit to the size of the .rtf files that you can link to and show in the Registration page.

But because large files take longer to load and display, and slow the reader's progress through

the first experience, we strongly recommend you choose the shortest text possible.

OOBE.XML SAMPLE

This snippet of an OOBE.xml file shows how to use the Registration page settings.

<registration>



<title>Register your PC</title>



<subtitle>This page will help Fabrikam get to know you better </subtitle>



<textbox1>



<label>Email address</label>



<inputscope>4</inputscope>

</textbox1>



<textbox2>



<label>Postal code</label>

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



</textbox2>



<checkbox1>



<label>Use Fabrikam Antimalware to help protect your PC</label>



<defaultvalue>true</defaultvalue>

</checkbox1>

<checkbox2>


<label>Install the Fabrikam toolbar</label>

</checkbox2>

<checkbox3>


<label>Let Fabrikam send you the latest news and special offers</label>

</checkbox3>



<link1>

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



<label>Learn more about Fabrikam Antimalware</label>

</link1>



<link2>



<label>Learn more about the Fabrikam toolbar</label>

</link2>



<link3>



<label>Allow Fabrikam to send you info about updates and offers</label>

</link3>

</registration>

TIME STAMP

The time stamp of first sign-in is written to the Windows registry under this key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\OOBE\Stats

[EndTimeStamp]. The time stamp is written in UTC (Coordinated Universal Time) format.

If you implement a Windows Store app to collect customer data from the Registration page, you

can write the AUMID for that app so the time stamp is written to the appdata folder of your

app.

For more info about how to use AUMID and the AppData folder, see Application data on the

Windows Dev Center.

If you implement a service to collect customer data from the Registration page, your service can

read the time stamp from the registry.

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser

http://go.microsoft.com/fwlink/?LinkId=249458



TIME ZONE

When configuring the time zone in the OOBE.XML, OEMs specify the ship-to country in the

installation wizard. When entered, the corresponding time zone is configured. This helps create

a “home grown” Windows experience for the customer by referencing the applicable time zone.

For Windows Blue, states in India now see the correct time zone.

USER NAME

If, in addition to the data the user enters into Registration page, you also want to capture the

user name, we recommend using the GetUserNameEx API for a Win32 service app. For info

about this API, see GetUserNameEx function in the Windows Dev Center. A Windows Store app

uses the UserInformation WinRT API. For information about this API, see UserInformation Class in

the Windows Dev Center.

You can capture the first and last names only if a user has connected their account to a

Microsoft account.

MANAGING AND UPLOADING USER DATA

If a customer fills out the Registration page and clicks Next to submit their form input, Windows

writes and encrypts the text data to the \OOBE\Info folder in a Userdata.blob file and stores the

check box values in the Checkbox.xml file at the same location. In addition to the customer-

provided info, Windows writes the <label> values from your OOBE.xml file to the same location.

Comments from your OOBE.xml files aren't written to this location.

If the customer clicks Skip, no data is written or stored, including check boxes selected by

default. As a result, if a user clicks Skip, no customer choice or preference is saved. If a customer

fills out part of the form, all available data is captured and written to \OOBE\Info when they

click Next. Only the state of the check box when the user clicks Next is recorded. Whether that

value is or isn't the default value isn't captured.

To protect customer data, the OEM must generate a public/private key pair, and the public key

must be placed in the \OOBE\Info folder. If you are deploying images to multiple regions or in

multiple languages you should put the public key directly under region and language-specific

subdirectories following the same rules as you would for region or language-specific oobe.xml

files. You must never place the private key on the customer's PC; instead, it should be stored

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser

http://go.microsoft.com/fwlink/p/?LinkID=246586

http://go.microsoft.com/fwlink/p/?LinkId=246592



securely on the OEM's servers so the data can be decrypted after it's uploaded. If a customer

clicks Next on the Registration page, Windows uses the public key to create Sessionkey.blob in

the \OOBE\Info folder. Your service or Windows Store app should upload the data by using SSL

to your server. You then need to decrypt the session key in order to decrypt the customer data.

Important

If there's no public key in the \OOBE\Info folder, the Registration page isn't shown.

Do NOT store the private key on the customer's PC.

GENERATING PUBLIC AND PRIVATE KEYS

The OEM must make this sequence of calls to generate the public and private keys.

1. Acquire crypt context (needed to start using Crypto API):

CryptAcquireContext

Provider is MS_ENH_RSA_AES_PROV

Provider type is PROV_RSA_AES

2. Generate RSA crypt key:

CryptGenKey

Algorithm is CALG_RSA_KEYX

Set flags to CRYPT_EXPORTABLE

3. Serialize public key portion of crypt key (from Step 2):

CryptExportKey

Blob type is PUBLICKEYBLOB

4. Write serialized public key bytes (from Step 3) to file (Pubkey.blob):

[Using standard Windows File API]

5. Serialize private key portion of crypt key (from Step 2):

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



CryptExportKey

Blob type is PRIVATEKEYBLOB

6. Write serialized private key bytes (from Step 3) to file (Prvkey.blob):


KEY GENERATION CODE SNIPPET

This code snippet shows how to generate the keys.

HRESULT CryptExportKeyHelper(_In_ HCRYPTKEY hKey, _In_opt_ HCRYPTKEY hExpKey, DWORD

dwBlobType, _Outptr_result_bytebuffer_(*pcbBlob) BYTE **ppbBlob, _Out_ DWORD

*pcbBlob);

HRESULT WriteByteArrayToFile(_In_ PCWSTR pszPath, _In_reads_bytes_(cbData) BYTE const

*pbData, DWORD cbData);

// This method generates an OEM public and private key pair and writes it to Pubkey.blob and

Prvkey.blob

HRESULT GenerateKeysToFiles()

{

// Acquire crypt provider. Use provider MS_ENH_RSA_AES_PROV and provider type

PROV_RSA_AES to decrypt the blob from OOBE.

HCRYPTPROV hProv;

HRESULT hr = CryptAcquireContext(&hProv, L"OEMDecryptContainer",

MS_ENH_RSA_AES_PROV,

PROV_RSA_AES, CRYPT_NEWKEYSET) ? S_OK : HRESULT_FROM_WIN32(GetLastError());

if (hr == NTE_EXISTS)

{

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



hr = CryptAcquireContext(&hProv, L"OEMDecryptContainer", MS_ENH_RSA_AES_PROV,

PROV_RSA_AES, 0) ? S_OK : HRESULT_FROM_WIN32(GetLastError());

}

if (SUCCEEDED(hr))

{

// Call CryptGenKey to generate the OEM public and private key pair. OOBE expects the

algorithm to be CALG_RSA_KEYX.

HCRYPTKEY hKey;

hr = CryptGenKey(hProv, CALG_RSA_KEYX, CRYPT_EXPORTABLE, &hKey) ? S_OK :

HRESULT_FROM_WIN32(GetLastError());

if (SUCCEEDED(hr))

{

// Call CryptExportKeyHelper to serialize the public key into bytes.

BYTE *pbPubBlob;

DWORD cbPubBlob;

hr = CryptExportKeyHelper(hKey, NULL, PUBLICKEYBLOB, &pbPubBlob, &cbPubBlob);

if (SUCCEEDED(hr))

{

// Call CryptExportKey again to serialize the private key into bytes.

BYTE *pbPrvBlob;

DWORD cbPrvBlob;

hr = CryptExportKeyHelper(hKey, NULL, PRIVATEKEYBLOB, &pbPrvBlob, &cbPrvBlob);

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



if (SUCCEEDED(hr))

{

// Now write the public key bytes into the file pubkey.blob

hr = WriteByteArrayToFile(L"pubkey.blob", pbPubBlob, cbPubBlob);

if (SUCCEEDED(hr))

{

// And write the private key bytes into the file Prvkey.blob

hr = WriteByteArrayToFile(L"prvkey.blob", pbPrvBlob, cbPrvBlob);

}

HeapFree(GetProcessHeap(), 0, pbPrvBlob);

}

HeapFree(GetProcessHeap(), 0, pbPubBlob);

}

CryptDestroyKey(hKey);

}

CryptReleaseContext(hProv, 0);

}

return hr;

}

HRESULT CryptExportKeyHelper(_In_ HCRYPTKEY hKey, _In_opt_ HCRYPTKEY hExpKey, DWORD

dwBlobType, _Outptr_result_bytebuffer_(*pcbBlob) BYTE **ppbBlob, _Out_ DWORD *pcbBlob)

{

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



*ppbBlob = nullptr;

*pcbBlob = 0;

// Call CryptExportKey the first time to determine the size of the serialized key.

DWORD cbBlob = 0;

HRESULT hr = CryptExportKey(hKey, hExpKey, dwBlobType, 0, nullptr, &cbBlob) ? S_OK :


if (SUCCEEDED(hr))

{

// Allocate a buffer to hold the serialized key.

BYTE *pbBlob = reinterpret_cast<BYTE *>(CoTaskMemAlloc(cbBlob));

hr = (pbBlob != nullptr) ? S_OK : E_OUTOFMEMORY;

if (SUCCEEDED(hr))

{

// Now export the key to the buffer.

hr = CryptExportKey(hKey, hExpKey, dwBlobType, 0, pbBlob, &cbBlob) ? S_OK :


if (SUCCEEDED(hr))

{

*ppbBlob = pbBlob;

*pcbBlob = cbBlob;

pbBlob = nullptr;

}

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



CoTaskMemFree(pbBlob);

}

}

return hr;

}

HRESULT WriteByteArrayToFile(_In_ PCWSTR pszPath, _In_reads_bytes_(cbData) BYTE const

*pbData, DWORD cbData)

{

bool fDeleteFile = false;

HANDLE hFile = CreateFile(pszPath, GENERIC_WRITE, 0, nullptr, CREATE_ALWAYS,

FILE_ATTRIBUTE_NORMAL, nullptr);

HRESULT hr = (hFile == INVALID_HANDLE_VALUE) ? HRESULT_FROM_WIN32(GetLastError()) :

S_OK;

if (SUCCEEDED(hr))

{

DWORD cbWritten;

hr = WriteFile(hFile, pbData, cbData, &cbWritten, nullptr) ? S_OK :


fDeleteFile = FAILED(hr);

CloseHandle(hFile);

}

if (fDeleteFile)

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



{

DeleteFile(pszPath);

}

return hr;

}

DECRYPTING THE DATA

The OEM must make this sequence of calls in order to decrypt the data.

1. Acquire crypt context (needed to start using Crypto API):

CryptAcquireContext

Provider is MS_ENH_RSA_AES_PROV

Provider type is PROV_RSA_AES

2. Read OEM private key file (Prvkey.blob) from disk:

[Using standard Windows File APIs]

3. Convert private key bytes into crypt key

CryptImportKey

4. Read OOBE-generated session key file (Sessionkey.blob) from disk:


5. Use private key (from Step 3) to convert session key bytes into crypt key:

CryptImportKey

Export key is the private key imported in Step 3

6. Read OOBE-written encrypted user data (Userdata.blob) from disk:


Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



7. Use session key (from Step 5) to decrypt user data:

CryptDecrypt

DECRYPTION CODE SNIPPET

This code snippet shows how to decrypt the data.

HRESULT DecryptHelper(_In_reads_bytes_(cbData) BYTE *pbData, DWORD cbData, _In_

HCRYPTKEY hPrvKey, _Outptr_result_bytebuffer_(*pcbPlain) BYTE **ppbPlain, _Out_ DWORD

*pcbPlain);

HRESULT ReadFileToByteArray(_In_ PCWSTR pszPath, _Outptr_result_bytebuffer_(*pcbData)

BYTE **ppbData, _Out_ DWORD *pcbData);

// This method uses the specified Userdata.blob (pszDataFilePath), Sessionkey.blob

(pszSessionKeyPath), and Prvkey.blob (pszPrivateKeyPath)

// and writes the plaintext XML user data to Plaindata.xml

HRESULT UseSymmetricKeyFromFileToDecrypt(_In_ PCWSTR pszDataFilePath, _In_ PCWSTR

pszSessionKeyPath, _In_ PCWSTR pszPrivateKeyPath)

{

// Acquire crypt provider. Use provider MS_ENH_RSA_AES_PROV and provider type

PROV_RSA_AES to decrypt the blob from OOBE.

HCRYPTPROV hProv;

HRESULT hr = CryptAcquireContext(&hProv, L"OEMDecryptContainer",

MS_ENH_RSA_AES_PROV, PROV_RSA_AES, CRYPT_NEWKEYSET) ? S_OK :


if (hr == NTE_EXISTS)

{

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



hr = CryptAcquireContext (&hProv, L"OEMDecryptContainer", MS_ENH_RSA_AES_PROV,

PROV_RSA_AES, 0) ? S_OK : HRESULT_FROM_WIN32(GetLastError());

}

if (SUCCEEDED(hr))

{

// Read in the OEM private key file.

BYTE *pbPrvBlob;

DWORD cbPrvBlob;

hr = ReadFileToByteArray(pszPrivateKeyPath, &pbPrvBlob, &cbPrvBlob);

if (SUCCEEDED(hr))

{

// Convert the private key file bytes into an HCRYPTKEY.

HCRYPTKEY hKey;

hr = CryptImportKey(hProv, pbPrvBlob, cbPrvBlob, 0, 0, &hKey) ? S_OK :


if (SUCCEEDED(hr))

{

// Read in the encrypted session key generated by OOBE.

BYTE *pbSymBlob;

DWORD cbSymBlob;

hr = ReadFileToByteArray(pszSessionKeyPath, &pbSymBlob, &cbSymBlob);

if (SUCCEEDED(hr))

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



{

// Convert the encrypted session key file bytes into an HCRYPTKEY.

// This uses the OEM private key to decrypt the session key file bytes.

HCRYPTKEY hSymKey;

hr = CryptImportKey(hProv, pbSymBlob, cbSymBlob, hKey, 0, &hSymKey) ? S_OK :


if (SUCCEEDED(hr))

{

// Read in the encrypted user data written by OOBE.

BYTE *pbCipher;

DWORD dwCipher;

hr = ReadFileToByteArray(pszDataFilePath, &pbCipher, &dwCipher);

if (SUCCEEDED(hr))

{

// Use the session key to decrypt the encrypted user data.

BYTE *pbPlain;

DWORD dwPlain;

hr = DecryptHelper(pbCipher, dwCipher, hSymKey, &pbPlain, &dwPlain);

if (SUCCEEDED(hr))

{

hr = WriteByteArrayToFile(L"plaindata.xml", pbPlain, dwPlain);

HeapFree(GetProcessHeap(), 0, pbPlain);

}

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



HeapFree(GetProcessHeap(), 0, pbCipher);

}

CryptDestroyKey(hSymKey);

}

HeapFree(GetProcessHeap(), 0, pbSymBlob);

}

else if (hr == HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND))

{

wcout << L"Couldn't find session key file [" << pszSessionKeyPath << L"]" << endl;

}

CryptDestroyKey(hKey);

}

HeapFree(GetProcessHeap(), 0, pbPrvBlob);

}

else if (hr == HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND))

{

wcout << L"Couldn't find private key file [" << pszPrivateKeyPath << L"]" << endl;

}

CryptReleaseContext(hProv, 0);

}

return hr;

}

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



HRESULT DecryptHelper(_In_reads_bytes_(cbData) BYTE *pbData, DWORD cbData, _In_

HCRYPTKEY hPrvKey, _Outptr_result_bytebuffer_(*pcbPlain) BYTE **ppbPlain, _Out_ DWORD

*pcbPlain)

{

BYTE *pbCipher = reinterpret_cast<BYTE *>(HeapAlloc(GetProcessHeap(), 0, cbData));

HRESULT hr = (pbCipher != nullptr) ? S_OK : E_OUTOFMEMORY;

if (SUCCEEDED(hr))

{

// CryptDecrypt will write the actual length of the plaintext to cbPlain.

// Any block padding that was added during CryptEncrypt won't be counted in cbPlain.

DWORD cbPlain = cbData;

memcpy(pbCipher, pbData, cbData);

hr = ResultFromWin32Bool(CryptDecrypt(hPrvKey,

0,

TRUE,

0,

pbCipher,

&cbPlain));

if (SUCCEEDED(hr))

{

*ppbPlain = pbCipher;

*pcbPlain = cbPlain;

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



pbCipher = nullptr;

}

HeapFree(GetProcessHeap(), 0, pbCipher);

} return hr;

}

HRESULT ReadFileToByteArray(_In_ PCWSTR pszPath, _Outptr_result_bytebuffer_(*pcbData)

BYTE **ppbData, _Out_ DWORD *pcbData)

{

*ppbData = nullptr;

*pcbData = 0;

HANDLE hFile = CreateFile(pszPath, GENERIC_READ, 0, nullptr, OPEN_EXISTING,

FILE_ATTRIBUTE_NORMAL, nullptr);

HRESULT hr = (hFile == INVALID_HANDLE_VALUE) ? HRESULT_FROM_WIN32(GetLastError()) :

S_OK;

if (SUCCEEDED(hr))

{

DWORD cbSize = GetFileSize(hFile, nullptr);

hr = (cbSize != INVALID_FILE_SIZE) ? S_OK : ResultFromKnownLastError();

if (SUCCEEDED(hr))

{

BYTE *pbData = reinterpret_cast<BYTE *>(CoTaskMemAlloc(cbSize));

hr = (pbData != nullptr) ? S_OK : E_OUTOFMEMORY;

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



if (SUCCEEDED(hr))

{

DWORD cbRead;

hr = ReadFile(hFile, pbData, cbSize, &cbRead, nullptr) ? S_OK :


if (SUCCEEDED(hr))

{

*ppbData = pbData;

*pcbData = cbSize;

pbData = nullptr;

}

CoTaskMemFree(pbData);

}

}

CloseHandle(hFile);

}

return hr;

}

FINISHING SETUP

To finish Setup customization, you need to collect and act on the user data collected on the

Registration page. You can do this either by using a Windows Store app or writing a service.

You can gather user data based on the Registration screen and time stamp through one

Windows Store app. Your best strategy for encouraging the user to start the app is to include

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



this data-gathering functionality in an app that's compelling and useful. For example, this would

be a great addition to your Know My PC app. For more info about how to design this app, see

Creating a Know My PC app.

The app can use the AUMID (Application User Model ID) in Unattend.xml in the OEMAppId

setting to collect the time stamp, user data, session key, and check box state data that are

written to the appdata folder for the app. The AUMID is the unique app identifier necessary to

place the data in the proper location so the Windows Store app can read that data. The OEM

needs to retrieve the AUMID from their app, provide it in the Unattend.xml file, and make sure

the Windows Store app is installed as part of the image. The data can be delivered to one app.

For info about how to access the data, see Accessing data and files in the Windows Dev Center.

For info about how to create a Windows Store app to finish the Registration actions, see the

Windows Dev Center.

If you create and run a service to upload the data, you should set the service to run at least 30

minutes after the user gets to the Start screen, and only run the service once. Setting your

service to run 30 minutes after the user gets to the Start screen means your service won't

consume system resources in the background while the user is getting their first chance to

explore the Start screen and their apps.

The service must gather the data from within the OOBE directory, as well as the time stamp and

user name, as applicable. The service should also determine what actions to take in response to

the user's choices. For example, if the user opted in to an antimalware app trial, your service

should start the trial rather than rely on the antimalware app to Decide if it should run. Or, as

another example, if your user opted in to emails from your company or partner companies, your

service should communicate that info to whoever handles your marketing emails.

For more info about how to write a service, see Windows Service Applications on MSDN.

OEM LICENSE

You may add your OEM license terms to the License Terms screen in the first experience. If you

include license terms, you must include a version of the license terms in each language that you

preinstall onto the PC. If you don't include terms for a specific language, an English (EN) version

of the license terms displays. The terms must be specific to each language, but they don't need

to be specific to each country or region that uses the language. Although the acceptance of the

terms isn't recorded, customers can’t proceed unless they accept them.

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser






REQUIRED FILES

If you want your customer to see the license terms in the first experience, you must add these

files:

License terms. These terms must be in an .rtf file or multiple .rtf files, depending on how many

languages are available to customers. You must place them in the

Windows\System32\Oobe\Info directory, or in subdirectories you create according to the

country or region and languages of the image you're shipping.

Oobe.xml file. Oobe.xml is a content file that OEMs can use to organize text and resources for

the OEM screens in Windows Blue. OEMs can use multiple Oobe.xml files for language- and

region-specific license terms and settings, so users see the correct info as soon as they start

their PCs.

Important

If an OEM ships a system with a high resolution screen with a 1.4 or 1.8 plateau display and the

default DPI setting (1.4 Plateau gets 125% DPI, 1.8 Plateau gets 150% DPI), this results in their

license terms text in OOBE displaying 20% smaller than on the 1.0 Plateau.

OEMs can specify a different DPI than the default. This can result in OOBE displaying the OEM

license terms text radically smaller or larger than the rest of OOBE, and therefore, we

recommend that OEMs don't alter the default DPI setting.

OOBE.XML SETTINGS

You must use this setting to display your license terms during the first experience.


Eulafilename Language- and location-specific version of manufacturer license terms in a rich-text format (.rtf) file

Absolute path to the .rtf file

OOBE SETTINGS

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



Oobe.xml is a content file that you can use to organize text and images and to specify and preset

settings for customizing the Windows Blue first experience. For Windows Blue, you can use

multiple Oobe.xml files for language- and region-specific license terms and settings so users see

appropriate info as soon as they start their PCs. By specifying info in the Oobe.xml file, OEMs

direct users to do only the core tasks required to set up their PCs.

Windows checks for and loads Oobe.xml in these locations, in this order:

1. %WINDIR%\System32\Oobe\Info\Oobe.xml

2. %WINDIR%\System32\Oobe\Info\Default\Oobe.xml

3. %WINDIR%\System32\Oobe\Info\Default\<language>\Oobe.xml

4. %WINDIR%\System32\Oobe\Info\<country/region>\Oobe.xml

5. %WINDIR%\System32\Oobe\Info\<country/region>\<language>\Oobe.xml

If you have customizations that span all countries/regions and languages, you can place the

Oobe.xml files in Location 1.

If you're shipping a single-region, single-language system, you can place your custom Oobe.xml

file in the \Info (Location 1) or \Default (Location 2) directory. Those locations are functionally

equivalent.

If you're shipping to multiple countries/regions and your OOBE settings require customizations

for individual countries/regions, each with a single language, you should place all of your

Oobe.xml files in Locations 4 and 5.

If you're shipping to multiple countries/regions with multiple languages, these guidelines apply:

Place country/region-specific info in Location 4.

Place language-specific info for each respective country/region in Location 5.

SINGLE-LANGUAGE DEPLOYMENTS

If you're delivering PCs to one country/region in a single language, you should place a single

Oobe.xml file in \%WINDIR%\System32\Oobe\Info. This file can contain all of your

customizations to the Windows first experience.

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



For example, an English version of Windows Blue that's delivered to the United States can have

this directory structure:

\%WINDIR%\System32\Oobe\Info\Oobe.xml

If you're delivering PCs to more than one country/region in a single language, and you plan to

vary your customizations in different locations, place an Oobe.xml file in

\%WINDIR%\System32\Oobe\Info.

This file can contain the default regional settings that you plan to show to the user. You should

also include a default set of customizations, in case the user selects a country/region that you

haven't made specific customizations for. The Oobe.xml file should also contain the

<eulafilename> node with the name of the customized license terms that you plan to use.

Place an Oobe.xml file for each country/region that contains unique customized content in

\%WINDIR%\System32\<country/region that you're deploying to>\<language that you're

deploying in>. After the user selects a country/region, these files are used to display additional

customizations.

For example, an English version of Windows Blue delivered to the United States and Canada can

have this directory structure:

\%WINDIR%\System32\Oobe\Info\Oobe.xml (EULA file name and regional settings)

\%WINDIR%System32\Oobe\Info\244\1033\Oobe.xml (United States custom content)

\%WINDIR%\System32\Oobe\Info\39\1033\Oobe.xml (Canada custom content)

MULTIPLE-LANGUAGE OR REGION DEPLOYMENTS

If you're delivering PCs to one or more countries/regions and are delivering PCs running

Windows Blue with additional language packs, place an Oobe.xml file in

\%WINDIR%\System32\Oobe\Info. This file can contain the default regional settings you plan to

show to the user. You should also include a default set of customizations in case the user selects

a country/region you haven't made specific customizations for. This Oobe.xml should also

contain the <eulafilename> node with the name of the custom license terms that you plan to

use.

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



Place an Oobe.xml file for each country/region that contains unique customized content in


deploying in>. After the user selects a country/region, this file is used to display additional

customizations.

For example, an English version of Windows Blue that's delivered to the United States and

Canada would use this directory structure:

\%WINDIR%\System32\Oobe\Info\Oobe.xml (logo, EULA file name, and regional settings)

\%WINDIR%\System32\Oobe\Info\244\1033\Oobe.xml (United States custom content)

\%WINDIR%\System32\Oobe\Info\39\1033\Oobe.xml (Canada custom content)

If you're delivering PCs to one or more countries/regions and are delivering PCs running

Windows Blue with additional language packs, place an Oobe.xml file in

\%WINDIR%\System32\Oobe\Info. This Oobe.xml file should contain the <eulafilename> node

with the name of the customized EULA you plan to use.

Place an Oobe.xml for each Windows language you’re including in

\%WINDIR%\System32\Default\<language that you're deploying in>. These files should contain

the default regional settings you plan to show for a given language, as well as a default set of

customizations, in case the user selects a country/region you haven't made specific

customizations for.

Place an Oobe.xml file for each country/region that contains customized content in


deploying in>. After the user selects a country/region, this file is used to display your additional

customizations.

For example, a version of Windows Blue with English and French language packs delivered to the

United States and Canada would use this directory structure:

Logo and EULA:

\%WINDIR%\System32\Oobe\Info\Oobe.xml (logo and EULA file name)

Regional settings and fallback for content that's not localized for the specific country/region:

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



\%WINDIR%\System32\Oobe\Info\Default\1033\Oobe.xml (default regional settings and English

content if the user chooses a country/region other than the United States or Canada)

\%WINDIR%\System32\Oobe\Info\Default\1036\Oobe.xml (default regional settings and French

content if the user chooses a country/region other than United States or Canada)

Country-specific or region-specific content in the appropriate languages

\%WINDIR%\System32\Oobe\Info\244\1033\Oobe.xml (United States custom content in

English)

\%WINDIR%\System32\Oobe\Info\244\1036\Oobe.xml (United States custom content in

French)

\%WINDIR%\System32\Oobe\Info\39\1033\Oobe.xml (Canada custom content in English)

\%WINDIR%\System32\Oobe\Info\39\1036\Oobe.xml (Canada custom content in French)

COUNTRY/REGION FOLDER FORMAT

You must name the country/region folders according to their respective GeoID decimal

identifiers. For example, to create a "Canada" folder, name the folder "39".

For a complete list of GeoIDs, see the Table of Geographical Locations on MSDN.

Note

These values are provided in hexadecimal format and must be converted to decimal format to

be used in the folder structure.

LANGUAGE FOLDER FORMAT

You must name the language folders according to the decimal version of the Locale ID (LCID)

value for the given language. For example, to create an "English" folder, name the folder "1033".

There are many more LCIDs than languages. A few LCIDs correlate to the languages that can

release with Windows Blue. For more info about which languages release with Windows Blue, at

what level of localization, and their decimal identifiers, see Available Language Packs on TechNet.

SAMPLE OOBE.XML FILE

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser





This example of an OOBE.xml file shows how the fictional OEM, Fabrikam, would use OOBE.xml

settings. This sample isn't intended for use in a production environment.

<FirstExperience>

<oobe>

<oem>

<name>Fabrikam</name>

<eulafilename>eula.rtf</eulafilename>

<computername>Fabrikam-PC</computername>

<registration>

<title>Register your PC</title>

<subtitle>This page will help Fabrikam know about you.</subtitle>

<textbox1>

<label>Email address</label>

</textbox1>

<textbox2>

<label>ZIP Code</label>

</textbox2>

<checkbox1>

<label>Use Contoso Anti-Malware to help protect your PC</label>

<defaultvalue>true</defaultvalue>

</checkbox1>

<checkbox2>

<label>Let Fabrikam send you offers</label>

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



</checkbox2>

<checkbox3>

<label>Let Fabrikam send you offers</label>

</checkbox3>

<link1>

<label>Learn more about Contoso Anti-malware</label>

</link1>

<link2>

<label>Learn more about the Fabrikam offers</label>

</link2>

<link3>

<label>Fabrikam privacy statement</label>

</link3>

</registration>

</oem>

<defaults>

<language>1033</language>

<location>244</location>

<locale>1033</locale>

<moveRegionalSettingsAfterLanguage>true</moveRegionalSettingsAfterLanguage>

<keyboard>0409:00000409</keyboard>

<timezone>Eastern Standard Time</timezone>

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



<adjustForDST>true</adjustForDST>

</defaults>

<hidSetup>

<title>Pair Your Fabrikam MouseKeyboard</title>

<mouseImagePath>c:\fabrikam\mouse.png</mouseImagePath>

<mouseErrorImagePath>c:\fabrikam\errormouse.png</mouseErrorImagePath>

<mouseText>Pair your mouse now.</mouseText>

<mouseErrorText>Something has gone wrong.</mouseErrorText>

<keyboardImagePath>c:\fabrikam\keyboard.png</keyboardImagePath>

<keyboardErrorImagePath>C:\fabrikam\errorkeyboard.png</keyboardErrorImagePath>

<keyboardText>Now pair the keyboard.</keyboardText>

<keyboardErrorText>Keyboard pairing did not happen.</keyboardErrorText>

<keyboardPINImagePath>c:\fabrikam\keyboardpin.png</keyboardPINImagePath>

<keyboardPINText>Enter the PIN for your keyboard.</keyboardPINText>

</hidSetup>

</oobe>

</FirstExperience>

Note

Computer Names can use multi-byte characters (like Kanji), but these characters count toward

the 15-byte limit.

The Unattend setting: Microsoft-Windows-Shell-Setup | ComputerName is a string with a

maximum length of 15 bytes of content. You can use ASCII characters (1 byte each) and/or

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



multi-byte characters like Kanji, so long as you don't exceed 15 bytes of content. Some non-

standard characters like emoji are not allowed.

Important

In Windows, if an OEM sets a <location> in oobe.xml they must also include a <locale> setting. If

they set <location> but don't specify the <locale>, the <location> setting is reset to the default

value after OOBE finishes.

The Windows Store depends on the <location> setting to provide the user the correct Windows

Store experience.

Note

The term "Western Sahara disputed" caused geopolitical issues within Morocco and they have

rejected devices when "Western Sahara" is shown. For this reason, we removed "Western

Sahara disputed" from the locations list. The OP2 release will feature this change.

Secti

on


OEM Name Name of the manufacturer.

String

Eulafilename Language- and location-specific version of manufacturer end-user license agreement (EULA).

.rtf file.

computername Specifies the computer name that displays as a hint to the customer.

15 byte string.

Computer Names can use multi-byte characters (like Kanji), but these characters count toward the 15-byte limit.

The Unattend setting: Microsoft-Windows-Shell-Setup | ComputerName is a string with a maximum length of 15 bytes of content. You can use ASCII

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



Secti

on


characters (1 byte each) and/or multi-byte characters like Kanji, so long as you don't exceed 15 bytes of content. Some non-standard characters like emoji are not allowed.

Computer names that cannot be validated through the DnsValidateName function cannot be used. For more info, see this MSDN

topic.

OEMs and corporate customers can customize computer names. They can add a string that displays as a hint to the customer.

Registration See OEM

registration for details on this section.

Defaults

Language Decimal identifier for input locale.

Decimal identifier for input locale. You can find these values in the Default

Input Locales topic in the Windows

Assessment and Deployment Kit (Windows ADK) documentation on TechNet.

Location The location is specified by using a GEOID value converted to its decimal value.

For a list of GEOIDs, see this MSDN

website.

Locale The locale is specified by using a locale identifier (LCID) value.

For a full list of LCIDs, see this Microsoft

Global Development Website. For a list of LCIDs and the versions of Windows in which they're available, download "Windows Language Code Identifier (LCID)

Reference" from MSDN. In this paper, in the left pane, go to "Appendix A: Windows Behavior" to see a table that shows the LCID and the Windows

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser















Secti

on


release in which it is available.

Keyboard Specifies the keyboard layout.

The keyboard layout is specified by the input locale identifier format, a combination of the hexadecimal value of the language identifier and a device identifier. Use the keyboard value that's listed in the registry under HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Control\Keyboard Layouts and prepend the LCID appropriate for the keyboard. These are listed in Supported Language Packs and Default

Settings.

Important

Unless you need to override the default setting for the keyboard, we recommend you don't use this setting.

Timezone Specifies the time zone of the computer's end user. The time zone is set by a string that specifies the time zone for the computer. The maximum length is 256 characters. New time zones might appear in future releases. To add support for a new time zone, you must enter the exact time

For a full list of time zones, see the values listed in the registry under HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Time Zones on a computer running Windows® 7. On a computer running Windows 7, you can use the tzutil command-line tool to list the time zone for that computer. The tzutil tool is installed by default on Windows Server 2008 R2.

Warning

If the time zone isn't specified, a default time zone value is used. The default time zone is based on the installed language and region specified in an answer file. If a region has more than one time zone, the time zone is set to the default time zone of that region. The default time zone for that region is specified by the location of the capital/major city. For example, if en-CA is specified, Eastern Standard Time is used as the default time zone because the Canadian capital, Ottawa, uses Eastern Standard Time. If en-US is specified as the UserLocale, the time

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser





Secti

on


zone string. zone of the Windows installation defaults to Pacific Standard Time.

adjustForDST Specifies whether to adjust for Daylight Savings Time. This setting is effective only when used in combination with the timezone and hideTimeAndDate settings to specify the time settings for the end user.

True or False.

hidSetup See OEM HID

pairing

instructions for details on this section.

moveregionalsettingsafterlanguage

Specifies whether to move the Regional screen after the language screen.

True or False

WINDOWS APPS

ADDING APPS TO AN IMAGE

A custom data file is a single file that you can add to the package of your Windows Store app at

the provisioning time of the image. The custom data file allows you to specify information that

the app can use to display different visual assets or to activate different features of your app. By

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



using a custom data file for your Know My PC app, you can provide a more relevant experience

for each PC model that you ship. For example, you can structure your custom data to include

photorealistic images of the PC that the customer is using and mockups of the apps that you've

included on that line of PCs. You can structure your custom data to add information about the

hardware specifics, and even identify a particular promotion that the PC was sold under.

By using custom data, you can develop a single, dynamic, Know My PC app that uses the custom

data file to create the best experiences for each PC model in your brand.

You should also design the app to use default settings if a custom data file isn't available.

Although the custom data file stays with the app if the app is updated from the Store, it's

removed from the PC if a user deletes the app from the PC. If the user later reinstalls the app

from the Store, the app doesn't regain the data file for a custom experience. Nevertheless, your

app should gracefully still provide a great experience with only default settings available.

You can design your app to use any format you choose for the custom data. For example, you

can use XML, a text file, or another file type to organize your data. We recommend that you

consider how you can test and validate the file. For example, you can create an XML schema to

use for validation.

You can specify any type of file with any file name for the custom data. It's renamed

Custom.data and saved in the app data store when you add the app package with the custom

data file by using the Deployment Image Servicing and Management (DISM) tool. You must

include all of the resource files in your app package, including image files for different brands.

For more information on how to use and provision a custom data file, refer to Using custom

data files.

The custom data file can't be modified by the app. It's a read-only resource.

You can access the Custom.data file for an app from your code by using Windows APIs to get

information for the current package. For example:

Windows.ApplicationModel.Package.current.installedLocation.getFileAsync("microsoft.system.p

ackage.metadata\\custom.data")

For more information about developing with the Package.current property, see How to query

package info in the Windows Dev Center.

Note

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser





For more information about accessing the custom.data file via GetFileAsync() and by using

StorageFile objects, see Accessing data and files in the Windows Dev Center.

USING A CUSTOM DATA FILE FOR MAIL

When configuring devices, OEMs can specify a default email signature, which identifies the

device. For example, “Sent from my Fabrikam Phone.”

To display the device name in the default email signature, OEMs can supply the custom.data file

for the Mail app to Microsoft. For a tablet, the default email signature might read, “Sent from

my Fabrikam 5000” if the custom.data file is provided. Mail only accepts custom.data files that

meet the following requirements:

File must be in UTF-8 format.

OEMs must provide the device name with the following format: DEVICE <friendly device

name>

OEMs cannot provide anything other than the device name.

Mail app cannot detect incorrect file formats; it can only parse UTF-8. Therefore, if an

incorrect file format is used, you could see: Sent from my .

Trademark symbols (©, ®, and ™) require the correct Unicode character. The Mail app

doesn’t auto-replace the letters C/R/TM with the Unicode symbols. For the correct UTF-8

characters, please refer to the corresponding Unicode Consortium webpage:

http://www.unicode.org/resources/utf8.html

In enterprise scenarios, another party may replace this custom.data file using the DISM

command.

ASSIGNING APP TILE ACTIVITY BY USING UNATTEND SETTINGS

To help Windows Blue feel personally relevant to users from the first time they sign in, OEMs

may set up to 10 of the preinstalled Windows Store apps in each regionally defined set of apps

to run a background task during first run. The user can't interact with the PC while the

background tasks are processed. The longer the background tasks take to complete, the longer

the user sees the post-OOBE animation. Also, if an app fails to report completion of its first-run

background task, Windows keeps the animation playing until the timeout expires.

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



http://go.microsoft.com/fwlink/?LinkID=248024

http://www.unicode.org/resources/utf8.html



We recommend that you select apps that use their first-run background task only to establish a

channel with the Windows Notification Service or to register for polling to update an app's tile

before the user interacts with the app for the first time. The developer defines the background

task for an app, so it's important to work closely with your app partners to ensure these tasks

run quickly and adhere to this guidance.

To use this setting, you need to specify the activatable class ID to be run as a <firstruntask> upon

the user's first sign-in. This node is optional for only wide and square tiles and should only be

used if you would like to enable these apps to run code at a user's first sign-in.

Windows processes up to 10 OEM-specified background tasks. If you specify more than 10 tasks

for each regionally defined set of apps, Windows processes only the first 10 that are registered.

Task registrations are enumerated in order of app tile name, and the order of app tile name is

SquareTile1, SquareTile2, and so on, and then WideTile1, WideTile2, and so on. For example, if

you set first run tasks for SquareTile1 through SquareTile10, and you set a first run task for

WideTile1, the first run task for WideTile1 isn't processed.

The time it takes for an app tile to become active, or live, depends on the app. If the app needs

information from the Internet, the task can take some time, but the attempts to become live

begin as soon as the user completes OOBE.

All background tasks are run in parallel. All background tasks must report completion within 120

seconds from the time Windows begins processing the first task. Any background task that

hasn't completed in that time will be canceled. Depending on what the task did during that time,

this could mean that its app tile isn't active until the user actually launches it.

Windows doesn't cancel a task that corresponds to a lock screen app, however, after 120

seconds, that task is sandboxed, meaning it's subject to the normal quota restrictions that apply

to all Windows Store app background tasks, and the task runs at low priority. During the initial

120 seconds, the background tasks run at Normal priority and no quotas are enforced.

When a task is canceled because of the timeout, an event is added to the Microsoft-Windows-

Shell-AuthUI/Operational event log with the message "The first run task for package <package

name> exceeded the maximum runtime allotted and has been cancelled." The event name for

this is operational_FirstRunTaskCancelled, and its ID is 5012. This event occurs once for each app

that times out.

For more information about using background tasks, see this MSDN blog post, or download the

Introduction to Background Tasks white paper from the Download Center.

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser





For more information about these settings, see the StartTiles settings topics in the Microsoft-

Windows-Shell-Setup component in the Windows Unattended Setup Reference in the Windows

Assessment and Deployment Kit on TechNet.

ASSIGNING APPS TO START

Use the Microsoft-Windows-Shell-Setup | StartTiles | <tileSetting> | FirstRunTask setting to set

a background task to run for each app tile on the Start screen that you want to be active, or live,

by default.

Each app tile setting can include an optional task to run in the background. To make a tile live,

specify the activatable class ID to be run as a <firstruntask> upon the user's first sign-in. This

node is optional for Windows Store app tiles.

For more information about these settings, see the StartTiles settings in the Microsoft-

Windows-Shell-Setup component in the Windows Unattended Setup Reference (Unattend.chm).

ASSIGNING ONE APP TO THE LOCK SCREEN BY USING UNATTEND SETTINGS

The Lock screen is shown when the computer is locked, rebooted, or woken from sleep state.

It's designed to show information that a user can review in a glance. You're allowed to specify

one app to appear on the Lock screen, and that app is allowed to show a badge and toast

notifications. The app is represented as a monochrome version of the icon that's specified by

the developer. The app developer must supply the monochrome icon. No additional work is

required on your end to make it monochrome; Windows displays this as monochrome

automatically.

Badges should stay current so users can scan the tile, get the latest information, and then get on

with using their PCs. Badges present customers with easy-to-understand information. Clicking or

touching the badge of an app doesn't activate the app.

Lock screen badges should be easy to understand. Unlike those shown on an app's Start tile, the

badges on the Lock screen are shown without any additional information from the app tile,

unless the app is currently occupying the detailed status slot. So, it's imperative that a Lock

screen badge presents information that needs no additional explanation.

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser





Badges should provide personally relevant information. These apps are very special—only a few

appear on the Lock screen at a time. By placing the app on the Lock screen, you're stating that

it's important enough to be seen even when the user isn't actively using the PC.

You must choose a Windows Store app that has a background task.

IMPLEMENTATION DETAILS

Use the Microsoft-Windows-Shell-Setup | StartTiles | Lockscreen | Badge | AppId setting to

specify the app for the lock screen. For more information about this setting, see the Lockscreen

setting in the Microsoft-Windows-Shell-Setup component in the Windows Unattended Setup

Reference (Unattend.chm).

NAMING YOUR GROUP OF TILES

You can specify a group name for your apps. It must be your OEM brand and can only include

OEM-owned brands. OEMs must only use brands with the OEM's name or as listed in the

Company Brand Names and Trademark section of Master License Agreement. Windows appends

your OEM name with the word apps.

Whether the OEM name is applied to one group or to two groups depends on the screen size,

resolution, and DPI of the destination PC. In the case of two groups of OEM-specified apps on

the Start screen, the same name is used for both groups.

IMPLEMENTATION DETAILS

Use the Microsoft-Windows-Shell-Setup | OEMName setting to specify the OEM name for the

group or groups of app tiles that you pin to the Start screen.

For more information about this setting, see the OEMName setting in the Microsoft-Windows-

Shell-Setup component in the Windows Unattended Setup Reference (Unattend.chm).

UNATTEND.XML SAMPLE

The following XML output shows how a sample of how to use the StartTiles settings.

<StartTiles>

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser

http://technet.microsoft.com/en-us/library/ff699026.aspx





<LockScreen>

<Badge>

<AppId>BadgeAppId</AppId>

</Badge>

</LockScreen>

<WideTiles>

<WideTile1>

<AppId>AppIdwide1</AppId>

<FirstRunTask>BackgroundTaskwide1</FirstRunTask>

</WideTile1>

<WideTile2>



</WideTile2>

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



<WideTile3>



</WideTile3>

<WideTile4>



</WideTile4>

<WideTile5>



</WideTile5>

<WideTile6>


Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser




</WideTile6>

</WideTiles>

<SquareTiles>

<SquareTile1>

<AppId>AppIdSquare1</AppId>

<FirstRunTask>BackgroundTaskSquare1</FirstRunTask>

</SquareTile1>

<SquareTile2>


</SquareTile2>

<SquareTile3>


Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



</SquareTile3>

<SquareTile4>


<FirstRunTask>backgroundTaskSquare4</FirstRunTask>

</SquareTile4>

<SquareTile5>


</SquareTile5>

<SquareTile6>


</SquareTile6>

<SquareTile7>


Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



</SquareTile7>

<SquareTile8>



</SquareTile8>

<SquareTile9>


</SquareTile9>

<SquareTile10>



</SquareTile10>

<SquareTile11>

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser




</SquareTile11>

<SquareTile12>


</SquareTile12>

<SquareOrDesktopTile1>

<AppIdOrPath>C:\programdata\microsoft\windows\start

menu\programs\desktoptile1.lnk</AppIdOrPath>

</SquareOrDesktopTile1>






Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser


















</SquareTiles>

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



</StartTiles>

<OEMName>OEM</OEMName>

BACKGROUND APPS

By default, the device’s position is landscape first but accommodates portrait. The visual cues

created by branding, logo placement, and button and connector locations should support this

design. In landscape position, buttons and connectors should not block a user’s grip. When

placing the Windows button, the optimal position is the bottom long bezel. If the bottom long

bezel doesn’t work, place the Windows button in the center of the right short bezel.

INTERNET EXPLORER

As with any Windows device, Internet Explorer is the de facto browser.

INTERNET EXPLORER SETTINGS

As with any Windows device, Internet Explorer is the de facto browser.

You:

Set Internet Explorer as the default browser.

Add no more than two Home page tabs to Internet Explorer on the desktop.

Add no toolbars to Internet Explorer on the desktop.

We recommend that you do not include more than two browser helper objects in Internet Explorer.

Internet Explorer launch time should be faster than 0.5 seconds.

The assessment scores of Internet Explorer should be:

IE Blizzard snowflakes greater than 1200

IE Fish in fishbowl greater than 150

IE Speed reading score less than 23

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser



For more information about measuring, analyzing, and improving performance in your Windows

image, see the Perf WEG.

INTERNET EXPLORER UNATTEND SETTINGS

Internet Explorer Unattend Settings let you customize your home page, favorites, search provider, feeds, Accelerators, web slices, and settings for top result searches. We recommend you refer to the following websites related to Internet Explorer Unattend settings:

Microsoft-Windows-IE-InternetExplorer: Talks about settings such as accelerators, Company Name, etc.

Microsoft-Windows-IE-ESC: Talks about turning on Internet Explorer Enhanced Configuration (EHC) to reduce exposure to potential security attacks.

Microsoft-Windows-IE-ClientNetworkProtocolImplementation: Talks about network policy settings.

THE WINDOWS EXPERIENCE

As mentioned earlier, these best practices ultimately help you build devices the customer has

come to know and associate with a good Windows experience. With more customers buying

multiple devices, image customization is important as it not only fills a business need to create

custom images for different device types, but also lets you meet expectations a customer has

when using them.

Mic

roso

ft Con

fiden

tial f

or: C

onne

ct U

ser

Date post:	26-Mar-2022
Category:	Documents
Upload:	others
View:	16 times
Download:	0 times

Connect User - Tistory

Documents