Create and install a package

Packages are the building blocks of Windows 10 IoT Core. From device drivers to system files, every component must be packaged to install on a device. Packages are the smallest servicable units on the device.

Step 1: Get set up

Install the tools

Set up your environment

• Launch IoTCorePShell.cmd ( this one launches in the elevated prompt )
• Create a new workspace using new-ws C:\MyWorkspace

To create your own image (FFU), follow the steps outlined in the «Create a basic image» lab in the IoT Manufacturing guide.

Step 2: Create a new package

Create a package definition xml file (.wm.xml file), and specify the files and reg keys you want to add. Learn more at Windows Universal OEM Package Schema.

Build the package: buildpkg filename.wm.xml . The .cab file will be created in the build directory \Build\\pkgs .

Create a package with files and reg keys

Below is an example for specifying files and reg keys.

Create an Appx package

Use Add-IoTAppxPackage to generate the .wm.xml file for a given appx file. This tool expects the appx dependencies in the sub directory named «dependencies» in the folder containing the appx file.

fga sets the appx as the foreground startup app, bgt sets the appx as the background task and none skips startup configuration. For older commandline tool, see newappxpkg.cmd

When you have to install multiple applications signed with same certificate, you can add the certificate along with one app and for the remaining apps, you can skip adding the certificate using the skipcert flag.

Create a driver package

The driver package contains the references (InfSource) to the Inf file for the driver. You can author the driver .wm.xml file manually or use Add-IoTDriverPackage that generates package xml based on the input inf file.

For the older commandline tool, use inf2cab.cmd creates the package xml file and also builds the cab file directly by invoking buildpkg.cmd internally.

Windows IoT Core supports Universal Inf only.

Step 3: Install on device

• Connect to the device (using SSH or using Powershell)
• Copy the .cab file to the device to a directory say C:\OemInstall
• Initiate staging of the package using applyupdate -stage C:\OemInstall\ .cab . Note that this step is be repeated for each package, when you have multiple packages to install.
• Commit the packages using applyupdate -commit .

You can also install the cab using Windows Update > CAB Install option in Windows Device Portal. The device will reboot into the update OS (showing gears) to install the packages and will reboot again to main OS. This process can take a few minutes.

Add updates to a Windows image

For many customizations, like adding .inf-style drivers, Windows updates or upgrading the edition, you can mount and edit the Windows image. Mounting an image maps the contents of a file to a temporary location where you can edit the files or use DISM to perform common deployment tasks.

Notes

Add languages before major updates. Major updates include hotfixes, general distribution releases, or service packs. If you add a language later, you’ll need to re-add the updates.

Add major updates before apps. These apps include universal Windows apps and desktop applications. If you add an update later, you’ll need to re-add the apps.

For major updates, update the recovery image too: These may include hotfixes, general distribution releases, service packs, or other pre-release updates. We’ll show you how to update these later in Lab 12: Update the recovery image.

If a Servicing Stack Update (SSU) is available, you must install it before applying the most recent General Distribution Release (GDR) or any future GDRs. See Windows 10 update history to see the most recent GDR.

Add a Windows update package to an image

Get a Windows update package. For example, get the latest cumulative update listed in Windows 10 update history from the Microsoft Update catalog. If the update has any prerequisite updates, get those too.

Add the updates to a mounted or online image. For packages with dependencies, either install the packages in order, or add them all at once using a single DISM command.

Example: adding a cumulative update to a mounted image:

Example: adding multiple updates:

Verify that the packages appear correctly:

Review the resulting list of packages and verify that the list contains the package. For example:

Each package will usually be a new KB, and will increase the build revision number of Windows on the device. The revision number of windows a device can be found in the following registry key: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\UBR .

If you’re done updating your image, you can unmount it, committing changes.

Update-Package (консоль диспетчера пакетов в Visual Studio) Update-Package (Package Manager Console in Visual Studio)

Доступно только в консоли диспетчера пакетов NuGet в Visual Studio в Windows. Available only within the NuGet Package Manager Console in Visual Studio on Windows.

Обновляет пакет и его зависимости или все пакеты в проекте до более новой версии. Updates a package and its dependencies, or all packages in a project, to a newer version.

Синтаксис Syntax

В NuGet 2.8 + Update-Package можно использовать для понижения уровня существующего пакета в проекте. In NuGet 2.8+, Update-Package can be used to downgrade an existing package in your project. Например, при наличии установленного Microsoft. AspNet. MVC 5.1.0-RC1 Следующая команда понизить ее до 5.0.0: For example, if you have Microsoft.AspNet.MVC 5.1.0-rc1 installed, the following command would downgrade it to 5.0.0:

Параметры Parameters

Параметр Parameter	Описание Description
Id Id	Идентификатор обновляемого пакета. The identifier of the package to update. Если этот параметр опущен, обновляет все пакеты. If omitted, updates all packages. Сам переключатель-ID является необязательным. The -Id switch itself is optional.
игноредепенденЦиес IgnoreDependencies	Пропускает обновление зависимостей пакета. Skips updating the package’s dependencies.
ProjectName ProjectName	Имя проекта, содержащего пакеты для обновления, по умолчанию — для всех проектов. The name of the project containing the packages to update, defaulting to all projects.
Версия Version	Версия, используемая для обновления, по умолчанию — последняя версия. The version to use for the upgrade, defaulting to the latest version. В NuGet 3.0 + значение версии должно быть одним из самых низких, наибольших, хигхестминор или хигхестпатч (эквивалентно-безопасности). In NuGet 3.0+, the version value must be one of Lowest, Highest, HighestMinor, or HighestPatch (equivalent to -Safe).
Safe Safe	Ограничивает обновления только версиями с той же основной и дополнительной версией, что и текущий установленный пакет. Constrains upgrades to only versions with the same Major and Minor version as the currently installed package.
Источник Source	URL-адрес или путь к папке для источника пакета для поиска. The URL or folder path for the package source to search. Пути к локальным папкам могут быть абсолютными или относительно текущей папки. Local folder paths can be absolute, or relative to the current folder. Если этот параметр опущен, Update-Package Поиск выполняется в текущем выбранном источнике пакета. If omitted, Update-Package searches the currently selected package source.
инклудепререлеасе IncludePrerelease	Включает предварительные пакеты для обновлений. Includes prerelease packages for updates.
Переустановка Reinstall	Ресинталлс пакеты, используя установленные в настоящее время версии. Resintalls packages using their currently installed versions. Дополнительные сведения см. в разделе Ограничение версий для обновления. See Reinstalling and updating packages.
филеконфликтактион FileConflictAction	Действие, предпринимаемое при запросе перезаписи или пропуска существующих файлов, на которые ссылается проект. The action to take when asked to overwrite or ignore existing files referenced by the project. Возможные значения: overwrite, ignore, None, овервритеалл и IgnoreAll (3.0 +). Possible values are Overwrite, Ignore, None, OverwriteAll, and IgnoreAll (3.0+).
депенденциверсион DependencyVersion	Используемая версия пакетов зависимостей, которая может быть одной из следующих: The version of the dependency packages to use, which can be one of the following: Самый низкий (по умолчанию): самая низкая версия Lowest (default): the lowest version Хигхестпатч: версия с наименьшим основным, наименьшим незначительным, самым высоким исправлением HighestPatch: the version with the lowest major, lowest minor, highest patch Хигхестминор: версия с наименьшим основным, наибольшим незначительным, самым высоким исправлением HighestMinor: the version with the lowest major, highest minor, highest patch Высший (по умолчанию для Update-Package без параметров): самая высокая версия Highest (default for Update-Package with no parameters): the highest version Значение по умолчанию можно задать с помощью dependencyVersion параметра в Nuget.Config файле. You can set the default value using the dependencyVersion setting in the Nuget.Config file.
тохигхестпатч ToHighestPatch	эквивалентно-Сейф. equivalent to -Safe.
тохигхестминор ToHighestMinor	Ограничивает обновления только версиями с той же основной версией, что и текущий установленный пакет. Constrains upgrades to only versions with the same Major version as the currently installed package.
WhatIf WhatIf	Показывает, что произойдет при выполнении команды без фактического выполнения обновления. Shows what would happen when running the command without actually performing the update.

Ни один из этих параметров не принимает входные данные конвейера или подстановочные знаки. None of these parameters accept pipeline input or wildcard characters.

Общие параметры Common Parameters

Update-Package поддерживает следующие Общие параметры PowerShell: Отладка, действие при ошибке, ErrorVariable, буфер, переменная, PipelineVariable, Verbose, WarningAction и WarningVariable. Update-Package supports the following common PowerShell parameters: Debug, Error Action, ErrorVariable, OutBuffer, OutVariable, PipelineVariable, Verbose, WarningAction, and WarningVariable.

Download and install package updates from the Store

Starting in Windows 10, version 1607, you can use methods of the StoreContext class in the Windows.Services.Store namespace to programmatically check for package updates for the current app from the Microsoft Store, and download and install the updated packages. You can also query for packages that you have marked as mandatory in Partner Center and disable functionality in your app until the mandatory update is installed.

Additional StoreContext methods introduced in Windows 10, version 1803 enable you to download and install package updates silently (without displaying a notification UI to the user), uninstall an optional package, and get info about packages in the download and install queue for your app.

These features help you automatically keep your user base up to date with the latest version of your app, optional packages, and related services in the Store.

Download and install package updates with the user’s permission

This code example demonstrates how to use the GetAppAndOptionalStorePackageUpdatesAsync method to discover all available package updates from the Store and then call the RequestDownloadAndInstallStorePackageUpdatesAsync method to download and install the updates. When using this method to download and install updates, the OS displays a dialog that asks the user’s permission before downloading the updates.

These methods support required and optional packages for your app. Optional packages are useful for downloadable content (DLC) add-ons, dividing your large app for size constraints, or for shipping additional content separate from your core app. To get permission to submit an app that uses optional packages (including DLC add-ons) to the Store, see Windows developer support.

This code example assumes:

• The code runs in the context of a Page.
• The Page contains a ProgressBar named downloadProgressBar to provide status for the download operation.
• The code file has a using statement for the Windows.Services.Store, Windows.Threading.Tasks, and Windows.UI.Popups namespaces.
• The app is a single-user app that runs only in the context of the user that launched the app. For a multi-user app, use the GetForUser method to get a StoreContext object instead of the GetDefault method.

To only download (but not install) the available package updates, use the RequestDownloadStorePackageUpdatesAsync method.

Display download and install progress info

When you call the RequestDownloadStorePackageUpdatesAsync or RequestDownloadAndInstallStorePackageUpdatesAsync method, you can assign a Progress handler that is called one time for each step in the download (or download and install) process for each package in this request. The handler receives a StorePackageUpdateStatus object that provides info about the update package that raised the progress notification. The previous example uses the PackageDownloadProgress field of the StorePackageUpdateStatus object to display the progress of the download and install process.

Be aware that when you call RequestDownloadAndInstallStorePackageUpdatesAsync to download and install package updates in a single operation, the PackageDownloadProgress field increases from 0.0 to 0.8 during the download process for a package, and then it increases from 0.8 to 1.0 during the install. Therefore, if you map the percentage shown in your custom progress UI directly to the value of the PackageDownloadProgress field, your UI will show 80% when the package is finished downloading and the OS displays the installation dialog. If you want your custom progress UI to display 100% when the package is downloaded and ready to be installed, you can modify your code to assign 100% to your progress UI when the PackageDownloadProgress field reaches 0.8.

Download and install package updates silently

Starting in Windows 10, version 1803, you can use the TrySilentDownloadStorePackageUpdatesAsync and TrySilentDownloadAndInstallStorePackageUpdatesAsync methods to download and install package updates silently, without displaying a notification UI to the user. This operation will succeed only if the user has enabled the Update apps automatically setting in the Store and the user is not on a metered network. Before calling these methods, you can first check the CanSilentlyDownloadStorePackageUpdates property to determine whether these conditions are currently met.

This code example demonstrates how to use the GetAppAndOptionalStorePackageUpdatesAsync method to discover all available package updates and then call the TrySilentDownloadStorePackageUpdatesAsync and TrySilentDownloadAndInstallStorePackageUpdatesAsync methods to download and install the updates silently.

This code example assumes:

• The code file has a using statement for the Windows.Services.Store and System.Threading.Tasks namespaces.
• The app is a single-user app that runs only in the context of the user that launched the app. For a multi-user app, use the GetForUser method to get a StoreContext object instead of the GetDefault method.

The IsNowAGoodTimeToRestartApp, RetryDownloadAndInstallLater, and RetryInstallLater methods called by the code in this example are placeholder methods that are intended to be implemented as needed according to your own app’s design.

Mandatory package updates

When you create a package submission in Partner Center for an app that targets Windows 10, version 1607 or later, you can mark the package as mandatory and the date and time on which it becomes mandatory. When this property is set and your app discovers that the package update is available, your app can determine whether the update package is mandatory and alter its behavior until the update is installed (for example, your app can disable features).

The mandatory status of a package update is not enforced by Microsoft, and the OS does not provide a UI to indicate to users that a mandatory app update must be installed. Developers are intended to use the mandatory setting to enforce mandatory app updates in their own code.

To mark a package submission as mandatory:

1. Sign in to Partner Center and navigate to the overview page for your app.
2. Click the name of the submission that contains the package update you want to make mandatory.
3. Navigate to the Packages page for the submission. Near the bottom of this page, select Make this update mandatory and then choose the day and time on which the package update becomes mandatory. This option applies to all UWP packages in the submission.

For more information, see Upload app packages.

If you create a package flight, you can mark the packages as mandatory using a similar UI on the Packages page for the flight. In this case, the mandatory package update applies only to the customers who are part of the flight group.

Code example for mandatory packages

The following code example demonstrates how to determine whether any update packages are mandatory. Typically, you should downgrade your app experience gracefully for the user if a mandatory package update does not successfully download or install.

Uninstall optional packages

Starting in Windows 10, version 1803, you can use the RequestUninstallStorePackageAsync or RequestUninstallStorePackageByStoreIdAsync methods to uninstall an optional package (including a DLC package) for the current app. For example, if you have an app with content that is installed via optional packages, you might want to provide a UI that enables users to uninstall the optional packages to free up disk space.

The following code example demonstrates how to call RequestUninstallStorePackageAsync. This example assumes:

• The code file has a using statement for the Windows.Services.Store and System.Threading.Tasks namespaces.
• The app is a single-user app that runs only in the context of the user that launched the app. For a multi-user app, use the GetForUser method to get a StoreContext object instead of the GetDefault method.

Get download queue info

Starting in Windows 10, version 1803, you can use the GetAssociatedStoreQueueItemsAsync and GetStoreQueueItemsAsync methods to get info about the packages that are in the current download and installation queue from the Store. These methods are useful if your app or game supports large optional packages (including DLCs) that can take hours or days to download and install, and you want to gracefully handle the case where a customer closes your app or game before the download and installation process is complete. When the customer starts your app or game again, your code can use these methods to get info about the state of the packages that are still in the download and installation queue so you can display the status of each package to the customer.

The following code example demonstrates how to call GetAssociatedStoreQueueItemsAsync to get the list of in-progress package updates for the current app and retrieve status info for each package. This example assumes:

• The code file has a using statement for the Windows.Services.Store and System.Threading.Tasks namespaces.
• The app is a single-user app that runs only in the context of the user that launched the app. For a multi-user app, use the GetForUser method to get a StoreContext object instead of the GetDefault method.

The MarkUpdateInProgressInUI, RemoveItemFromUI, MarkInstallCompleteInUI, MarkInstallErrorInUI, and MarkInstallPausedInUI methods called by the code in this example are placeholder methods that are intended to be implemented as needed according to your own app’s design.