Build a Universal Windows 8 app

  • Article

[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]

You can build an app that runs on multiple Windows devices.

If you target Windows 8.1 devices, you'll have one solution but you'll build two separate apps. You'll build one app for a PC or tablet, and one for the Windows Phone. You can build an app for both these devices at the same time, and share code, user controls, styles, strings, and other assets between the two projects in Visual Studio. This reduces the time and expense associated with building and maintaining an app for each type of device.

If you target Windows 10 devices, you'll have one solution as well, but you'll build one app that runs on all Windows 10 devices so this means that you share virtually everything! Learn how to build a Windows 10 universal app that targets all Windows 10 devices.

To build a Windows 8.1 universal app that targets Windows 8.1 devices, install Microsoft Visual Studio 2013, or Microsoft Visual Studio 2015. Get the tools. Visual Studio is a collection of tools that you can use to create, code, debug, localize, package, and deploy apps for many platforms. In short, Microsoft Visual Studio can help you do just about anything you need to do to develop an app.

If you haven't used Visual Studio before, take a quick look around before you start writing code. Visual Studio has a lot of parts, but you don't need to know all about them to get started. Get more detailed information about the IDE here.

If you do already have a Windows Store app, you can easily add a Windows Phone Store app to the same solution. Similarly, if you started by creating a Windows Phone Store app, you can easily add a Windows Store app. Then take advantage of sharing code between the two apps.

Get a developer license

First, get a developer license. You'll need one to develop and test a Windows Store app before the Store can certify it.

When you run Visual Studio for the first time, it prompts you to obtain a developer license. Read the license terms and then click I Accept if you agree. In the User Account Control (UAC) dialog box, click Yes if you want to continue.

Register your Windows Phone 8 to test your Windows Phone Store app

It’s important to test your Windows Phone Store app on a real phone. Before you can deploy apps to your Windows Phone 8, you have to register the phone for development. After you register your phone, you can install, run, and debug apps on the phone.

Learn how to register your Windows Phone 8 device for development.

Get started writing a Windows 8.1 universal app

To get started, pick a project template for a Windows 8.1 universal app in the New Project dialog box.

The following screenshot shows the Windows 8.1 universal app project templates that are currently available for C#. Visual C++ has a similar set of templates for Windows 8.1 universal apps.

When you select a template for a Windows 8.1 universal app and create a solution, three projects appear in Solution Explorer.

  1. A Windows project.
  2. A Windows Phone project.
  3. A Shared project.

The following screenshot shows the solution that Visual Studio creates when you choose the project template for a Blank App (Universal Apps).

  • The Windows Store project contains XAML pages and code that target Windows.

  • The Windows Phone project contains XAML pages and code that target Windows Phone.

  • The Shared project is a container for code that runs on both platforms. The contents of the Shared project are automatically included in both the Windows Phone and the Windows Store projects and in their build output.

Building. When you build the solution, Microsoft Visual Studio builds a Windows Phone Store app and a Windows Store app. There is no build output from the Shared project.

Startup project. When you run the solution - for example by pressing F5 - the project that runs is the project that's selected as the startup project. To set the startup project, right-click on the project node in Solution Explorer and choose Set as Startup Project. The project that you choose shows in bold in Solution Explorer. In the previous screenshot, App1.Windows (Windows 8.1) is the startup project.

Debug target.

  • When the Windows project is the startup project, the Debug target drop-down displays options for the Windows Simulator or Local Machine.
  • When the Phone project is the startup project, the drop-down displays options for Device as well as various phone emulators.
  • In a C++ phone project, you must manually set the build configuration to the ARM platform in order to see the Device option and deploy the app to a physical device. The Win32 configuration is used for the phone emulators only. Set the platform by navigating to Project | Properties | Configuration Manager | Platform.

Consider starting with the template named Hub App (Universal Apps) instead of a Blank App. (Hub is the equivalent of Panorama in previous versions of Windows Phone.) The Hub App template creates an app that has three pages. You can find the Hub App template under the Universal Apps category. To read more about the Hub App project template, see Visual Studio templates.

The following screenshot shows the Hub App project template selected in the New Project dialog box.

Write cross-platform code in the Shared project

In the Shared project, you typically write code that runs on both platforms.

To isolate sections of code that are platform-specific, use the #ifdef directive . The constants WINDOWS_APP and WINDOWS_PHONE_APP are conveniently predefined for you. (In C++, use this directive to isolate Phone-specific code: #if WINAPI_FAMILY==WINAPI_FAMILY_PHONE_APP...#endif.)

You can also drag and drop files from one of the platform-specific projects to the Shared project or vice versa to change the scope of the code.

Identify and isolate platform-specific code

When you're writing code in the Shared project, the Visual Studio code editor uses a context that targets one platform or the other. In C#, the Intellisense that you see as you write code is specific to the context of the code editor - that is, specific to Windows or to Windows Phone.

The following screenshot shows the context switcher in the Navigation bar.

If you use an API in shared code that’s not supported on both platforms, an error message will identify this API when you build the project. You don't have to build the project to confirm that you’re using cross-platform APIs. Check one of the following things in the code editor.

  • Look at the warning icons and the Intellisense text.

    The following screenshot shows an example of the warning icons and Intellisense for a type that's supported only in Windows Phone Store apps.

  • In the context switcher, switch the editor context to the other platform. This displays squiggly lines under APIs that are not supported on the selected platform. In C++, purple squiggles tell you if an API is not supported on the other platform, without switching the context or building the project.

After you identify platform-specific APIs, isolate them in your shared code by using the #ifdef directive.

Add support for Windows or Windows Phone

If you've already published a Windows Store app, it’s easy to reuse some of the code and publish a version of your app for Windows Phone. Similarly, if you started by creating a Windows Phone app, you can modify your solution to build for Windows tablets and desktops as well. To add support for one type of device or another, in Solution Explorer, right-click on the project and choose Add Windows Phone 8.1 or Add Windows 8.1.

Visual Studio adds a new Windows Phone or Windows Store project to the solution. Visual Studio also adds a Shared project.

The following screenshot shows a solution after adding a Windows Phone project to an existing Windows Store project.

Move files into the Shared project

You can move any code that you want to share between apps to the Shared project. For example, if you created your app by using a Visual Studio template, consider moving the Common, DataModel, and Strings folders into the Shared project. You can even move App.xaml into the Shared project, as described later in this topic.

Note  In C++, moving files from one project to another does not physically move them in the file system.

 

The following screenshot shows a solution after moving the suggested files and folders into the Shared project.

You may receive some compiler errors about the code that you move into the Shared project. In many cases, you can resolve the errors by configuring your new app project to have the same set of references as your initial project. For example, if your Windows Store app contained an assembly reference for a third-party library, and you move the associated code into the Shared folder, then you also have to reference the third-party library in the Windows Phone project.

The following screenshot shows the same assembly reference added to both projects.

If your shared code uses APIs that are specific to Windows, use the #ifdef directive with the WINDOWS_APP constant to isolate that section of code. Use the WINDOWS_PHONE_APP constant to isolate sections of code specific to Windows Phone 8.1. The next section shows how to apply these constants, and also mentions the constants used in C++.

Share the App.xaml

When you create a new solution for a Windows universal app, Visual Studio places App.xaml in the Shared project. When you convert an existing project to a Windows universal app, you can move App.xaml into the Shared project manually. After you move the file, you have to set the Build Action property of the page to ApplicationDefinition.

  1. In Solution Explorer, in the Shared project, select the App.xaml file.
  2. Select View > Properties Window.
  3. In the Properties window, in the Build Action drop-down list, select ApplicationDefinition.

You also have to decide how you want to open the first page of your app. For example, the App.xaml page of a Windows universal app might use the following code to open a page named HubPage. This code only works when both projects contain a page named HubPage.

if (!rootFrame.Navigate(typeof(HubPage)))
{
    throw new Exception(“Failed to create initial page”);
}

If you want to use a different start page for each app, you have to add #ifdef directives as shown below:

#if WINDOWS_APP
                if (!rootFrame.Navigate(typeof(HubPage)))
#endif
#if WINDOWS_PHONE_APP
                if (!rootFrame.Navigate(typeof(WindowsPhoneStartPage)))
#endif
                {
                    throw new Exception("Failed to create initial page");
                }

#if WINAPI_FAMILY==WINAPI_FAMILY_PHONE_APP
        if (!rootFrame->Navigate(WindowsPhoneStartPage::typeid, e->Arguments))
#else
        if (!rootFrame->Navigate(HubPage::typeid, e->Arguments))
#endif
        //...throw exception

Finally, ensure that any styles defined in your App.xaml file use resources that are available in both types of apps. Otherwise, move those style definitions into the Windows Store or Windows Phone project.

Next steps

To create your first app, see Your first app.

To learn more about developing an app by using the Visual Studio templates, see these topics:

Product Support and Accessibility

Accessibility in Store apps using JavaScript

Accessibility in Store apps (VB/C#/C++ and XAML)

Port an existing Windows 8 universal app