App model

Windows Mixed Reality uses the app model provided by the Universal Windows Platform (UWP), a model and environment for modern Windows apps. The UWP app model defines how apps are installed, updated, versioned and removed safely and completely. It governs the application life cycle - how apps execute, sleep and terminate - and how they can preserve state. It also covers integration and interaction with the operating system, files and other apps.

2D apps arranged in the Windows Mixed Reality home in a breakfast area
Apps with a 2D view arranged in the Windows Mixed Reality home

App lifecycle

The lifecycle of a mixed reality app involves standard app concepts such as placement, launch, termination and removal.

Placement is launch

Every app starts in mixed reality by placing an app tile (just a Windows secondary tile) in the Windows Mixed Reality home. These app tiles, on placement, will start running the app. These app tiles persist and stay at the location where they are placed, acting like launchers for anytime you want to get back to the app.

Placement puts a secondary tile in the world
Placement puts a secondary tile in the world

As soon as placement completes (unless the placement was started by an app to app launch), the app starts launching. Windows Mixed Reality can run a limited number of apps at one time. As soon as you place and launch an app, other active apps may suspend, leaving a screenshot of the app's last state on its app tile wherever you placed it. See Windows 10 UWP app lifecycle for more information on handling resume and other app life cycle events.

After placing a tile, the app starts running State diagram for app running, suspended or not running
Left: after placing a tile, the app starts running. Right: state diagram for app running, suspended, or not running.

Remove is close/terminate process

When you remove a placed app tile from the world, this closes the underlying processes. This can be useful for ensuring your app is terminated or restarting a problematic app.

App suspension/termination

In the Windows Mixed Reality home, the user is able to create multiple entry points for an app. They do this by launching your app from the Start menu and placing the app tile in the world. Each app tile behaves as a different entry point, and has a separate tile instance in the system. A query for SecondaryTile.FindAllAsync will result in a SecondaryTile for each app instance.

When a UWP app suspends, a screenshot is taken of the current state.

Screenshots are shown for suspended apps
Screenshots are shown for suspended apps

One key difference from other Windows 10 shells is how the app is informed of an app instance activation via the CoreApplication.Resuming and CoreWindow.Activated events.

Scenario Resuming Activated
Launch new instance of app from the Start menu Activated with a new TileId
Launch second instance of app from the Start menu Activated with a new TileId
Select the instance of the app that is not currently active Activated with the TileId associated with the instance
Select a different app, then select the previously active instance Resuming raised
Select a different app, then select the instance that was previously inactive Resuming raised Then Activated with the TileId associated with the instance

Extended execution

Sometimes your app needs to continue doing work in the background or playing audio. Background tasks are available on HoloLens.

Apps can run in the background
Apps can run in the background

App views

When your app activates, you can choose what type of view you'd like to display. For an app's CoreApplication, there is always a primary app view and any number of further app views you would like to create. On desktop, you can think of an app view as a window. Our mixed reality app templates create a Unity project where the primary app view is immersive.

Your app can create an additional 2D app view using technology like XAML, to use Windows 10 features such as in-app purchase. If your app started as a UWP app for other Windows 10 devices, your primary view is 2D, but you could "light up" in mixed reality by adding an additional app view that's immersive to show an experience volumetrically. Imagine building a photo viewer app in XAML where the slideshow button switched to an immersive app view that flew photos from the app across the world and surfaces.

The running app can have a 2D view or an immersive view
The running app can have a 2D view or an immersive view

Creating an immersive view

Mixed reality apps are those that create an immersive view, which is achieved with the HolographicSpace type.

An app that is purely immersive should always create an immersive view on launch, even if launched from the desktop. Immersive views always show up in the headset, regardless of where they were created from. Activating an immersive view will display the Mixed Reality Portal and guide the user to put on their headset.

An app that starts with a 2D view on the desktop monitor may create a secondary immersive view to show content in the headset. An example of this is a 2D Edge window on the monitor displaying a 360-degree video in the headset.

Apps running in immersive view are the only one visible
An app running in an immersive view is the only one visible

2D view in the Windows Mixed Reality home

Anything other than an immersive view is rendered as a 2D view in your world.

An app may have 2D views on both the desktop monitor and in the headset. Note that a new 2D view will be placed in the same shell as the view that created it, either on the monitor or in the headset. It is not currently possible for an app or a user to move a 2D view between the Mixed Reality home and the monitor.

Apps running in 2D view share the space in the mixed world with other apps
Apps running in a 2D view share the space with other apps

Placement of additional app tiles

You can place as many apps with a 2D view in your world as you want with the Secondary Tile APIs. These "pinned" tiles will appear as splash screens that users must place and then can later use to launch your app. Windows Mixed Reality does not currently support rendering any of the 2D tile content as live tiles.

Apps can have multiple placements using secondary tiles
Apps can have multiple placements using secondary tiles

Switching views

Switching from the 2D XAML view to the immersive view

If the app uses XAML, then the XAML IFrameworkViewSource will control the first view of the app. The app will need to switch to the immersive view before activating the CoreWindow, to ensure the app launches directly into the immersive experience.

Use CoreApplication.CreateNewView and ApplicationViewSwitcher.SwitchAsync to make it the active view.

Note

  • Do not specify the ApplicationViewSwitchingOptions.ConsolidateViews flag to SwitchAsync when switching from the XAML view to the immersive view, or the slate that launched the app will be removed from the world.
  • SwitchAsync should be called using the Dispatcher associated with the view you are switching into.
  • You will need to SwitchAsync back to the XAML view if you need to launch a virtual keyboard or want to activate another app.

Apps can switch between 2D views and immersive views When an app goes into an immersive view, the mixed world and other apps disappear
Left: apps can switch between 2D view and immersive view. Right: when an app goes into an immersive view, the Windows Mixed Reality home and other apps disappear.

Switching from the immersive view back to a keyboard XAML view

One common reason for switching back-and-forth between views is displaying a keyboard in a mixed reality app. The shell is only able to display the system keyboard if the app is showing a 2D view. If the app needs to get text input, it may provide a custom XAML view with a text input field, switch to it, and then switch back after the input is complete.

Like in the previous section, you can use ApplicationViewSwitcher.SwitchAsync to transition back to a XAML view from your immersive view.

App size

2D app views always appear in a fixed virtual slate. This makes all 2D views show the exact same amount of content. Here are some further details about the size of your app's 2D view:

  • The aspect ratio of the app is preserved while resizing.
  • App resolution and scale factor are not changed by resizing.
  • Apps are not able to query their actual size in the world.

2D apps appear with fixed window sizes
Apps with a 2D view appear with fixed window sizes

App tiles

The Start menu uses the standard small tile and medium tile for pins and the All Apps list in mixed reality.

The Start menu for Windows Mixed Reality
The Start menu for Windows Mixed Reality

App to app interactions

As you build apps, you have access to the rich app to app communication mechanisms available on Windows 10. Many of the new Protocol APIs and file registrations work perfectly on HoloLens to enable app launching and communication.

Note that for desktop headsets, the app associated with a given file extension or protocol may be a Win32 app that can only appear on the desktop monitor or in the desktop slate.

Protocols

HoloLens supports app to app launching via the Windows.System.Launcher APIs.

There are some things to consider when launching another application:

  • When doing a non-modal launch, such as LaunchUriAsync, the user must place the app before interacting with it.

  • When doing a modal launch, such as through LaunchUriForResultsAsync, the modal app is placed on top of the window.

  • Windows Mixed Reality cannot overlay applications on top of exclusive views. In order to show the launched app, Windows takes the user back to the world to display the application.

File pickers

HoloLens supports both FileOpenPicker and FileSavePicker contracts. However, no app comes pre-installed that fulfills the file picker contracts. These apps - OneDrive, for example - can be installed from the Microsoft Store.

If you have more than one file picker app installed, you will not see any disambiguation UI for choosing which app to launch; instead, the first file picker installed will be chosen. When saving a file, the filename is generated which includes the timestamp. This cannot be changed by the user.

By default, the following extensions are supported locally:

App Extensions
Photos bmp, gif, jpg, png, avi, mov, mp4, wmv
Microsoft Edge htm, html, pdf, svg, xml

App contracts and Windows Mixed Reality extensions

App contracts and extension points allow you to register your app to take advantage of deeper operating system features like handling a file extension or using background tasks. This is a list of the supported and unsupported contracts and extension points on HoloLens.

Contract or Extension Supported?
Account Picture Provider (extension) Unsupported
Alarm Unsupported
App service Supported but not fully functional
Appointments provider Unsupported
AutoPlay (extension) Unsupported
Background tasks (extension) Partially Supported (not all triggers work)
Update task (extension) Supported
Cached file updater contract Supported
Camera settings (extension) Unsupported
Dial protocol Unsupported
File activation (extension) Supported
File Open Picker contract Supported
File Save Picker contract Supported
Lock screen call Unsupported
Media playback Unsupported
Play To contract Unsupported
Preinstalled config task Unsupported
Print 3D Workflow Supported
Print task settings (extension) Unsupported
URI activation (extension) Supported
Restricted launch Unsupported
Search contract Unsupported
Settings contract Unsupported
Share contract Unsupported
SSL/certificates (extension) Supported
Web account provider Supported

App file storage

All storage is through the Windows.Storage namespace. See the following documentation for more details. HoloLens does not support app storage sync/roaming.

Known folders

See KnownFolders for the full details for UWP apps.

Property Supported on HoloLens Supported on immersive headsets Description
AppCaptures✔️✔️Gets the App Captures folder.
CameraRoll✔️✔️Gets the Camera Roll folder.
DocumentsLibrary✔️✔️Gets the Documents library. The Documents library is not intended for general use.
MusicLibrary✔️✔️Gets the Music library.
Objects3D✔️✔️Gets the Objects 3D folder.
PicturesLibrary✔️✔️Gets the Pictures library.
Playlists✔️✔️Gets the play lists folder.
SavedPictures✔️✔️Gets the Saved Pictures folder.
VideosLibrary✔️✔️Gets the Videos library.
HomeGroup✔️Gets the HomeGroup folder.
MediaServerDevices✔️Gets the folder of media server (Digital Living Network Alliance (DLNA)) devices.
RecordedCalls✔️Gets the recorded calls folder.
RemovableDevices✔️Gets the removable devices folder.

App package

With Windows 10 you no longer target an operating system but instead target your app to one or more device families. A device family identifies the APIs, system characteristics, and behaviors that you can expect across devices within the device family. It also determines the set of devices on which your app can be installed from the Microsoft Store.

  • To target both desktop headsets and HoloLens, target your app to the Windows.Universal device family.
  • To target just desktop headsets, target your app to the Windows.Desktop device family.
  • To target just HoloLens, target your app to the Windows.Holographic device family.

See also