Build a universal Windows app

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. Because you can share most of your code between these apps, the term universal means that you share your code.

If you target Windows 10 devices, you'll have one solution as well, but you'll build one app that runs all Windows 10 devices so the term universal means that you share virtually everything.

To build a Windows universal app that targets Windows 8.1 devices, install Microsoft Visual Studio 2013, or Microsoft Visual Studio 2015 Preview or the latest Visual Studio 2015 CTP. See Get the Tools.

To build a Windows universal app that targets Windows 10 devices, install the Windows 10 Technical Preview tools.

Build a Windows universal app that targets Windows 8.1 devices

You can build an app for Windows and Windows Phone 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 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 app, you can easily add a Windows Store app.

Project templates for Windows universal apps are installed when you install Visual Studio 2013 with Update 2 or later.

In this section

Get started writing a Windows universal app

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

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

Universal Project templates in Visual Studio

When you select a template for a Windows 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).

Converged project in Solution Explorer

  • 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.

Hub App template in Visual Studio

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.

Context switcher drop-down list in the code editor

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, however, 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.

    Warning icons and Intellisense

  • 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.

Adding a Windows Phone 8.1 project

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.

Phone project added to solution.

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.

Files moved 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.

Assembly references 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");
                }


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.

Build a Windows universal app that targets Windows 10 devices

Now you can build one app that runs on all Windows 10 devices and design your pages so they render properly no matter what device is used to view them. If you want to get a sense of what’s possible, have a look at the Guide to Windows universal apps. Then, install the tools and build your first truly universal Windows app.

In this section

Get started creating a Windows universal app

Start by creating a Blank Application (UAP) project.

Windows 10 Blank App template in Visual Studio

When you've done that, notice that only one project appears in Solution Explorer. That's because your app is now truly adaptive and you only need one project to build it.

The project contains one page but you can add others. Each page renders on all devices that your project targets so you don't have to create multiple versions of them. If you want to optimize the experience of a page for a specific device, you most certainly can. We'll discuss that shortly.

Windows 10 Blank App in Solution Explorer

Add universal controls that adapt to the screen size, layout, and resolution of all Windows 10 devices

The Windows Universal Platform introduces some new controls, such as the RelativePanel and SplitView controls, that adapt their appearance for different types of devices, layouts, and device orientations.

These controls do not yet appear in the Visual Studio toolbox and they won't render properly in the Visual Studio designer, but you can add them to your XAML file manually and then run your app to see how they appear in different types of devices.

Learn more about adaptive controls.

Preview how your pages will appear for different types of devices

You can see how a page renders on different types of devices without having to run your app. Choose a device from a drop-down list at the top of your designer. The dimensions of the page that appears in your designer change with each selection. You can also choose to view your page in landscape or portrait mode.

In the current release of these tools, only a small list of device form factors appear in the drop-down list, and the functionality of this feature is limited. However, they give you an idea of the direction that these tools are taking as they evolve towards the final release.

View UI for different device sizes and resolutions

Run your app and debug your code

To run your app, choose a device target from the drop-down list next to the Local Machine button on the Standard toolbar.

Drop-down list of device targets for debugging your app

To see how your app appears on a tablet or desktop, run it locally, on a remote machine, or in a simulator. The simulator helps you simulate common touch and rotation events.

To see how your app appears on a phone, choose a phone emulator or attach a device directly to your computer.

Learn more about how to run your app in each of these device targets.

Learn more about how to debug and test your app in Visual Studio

Add platform-specific code

Most of your code will run on both PCs and mobile devices. Most likely, you won't have to do anything to make that happen. That's because most APIs have been converged into a single Universal App Platform SDK. You can find that SDK in your list of project references as shown here.

Universal App Platform SDK reference in Solution Explorer

However, sometimes, you'll have to write code that runs on only on a mobile device. To do that, open the Reference Manager dialog box, and then choose either the Windows Desktop Extension SDK (for PCs) or the Windows Mobile Extension SDK (For mobile devices).

Universal App Platform SDK reference in Solution Explorer

You'll have to make sure that an API is available on the running device before you use it. For example, this code assigns an event handler to the Windows.Phone.UI.Input.HardwareButtons.BackPressed event. The code compiles because your project contains a reference to the Windows Mobile Extension SDK, but what happens when a user runs this app on a PC?


Windows.Phone.UI.Input.HardwareButtons.BackPressed += HardwareButtons_BackPressed;  

The app would crash because a PC does not have a back button.

To address this issue, use the Windows.Foundation.Metadata.ApiInformation.IsTypePresent method to determine whether a type named Windows.Phone.UI.Input.HardwareButtons is available on the running device. If it is, then the app is running on a mobile device, and the code will execute without crashing the app. The following code does that.


if (Windows.Foundation.Metadata.ApiInformation.IsTypePresent("Windows.Phone.UI.Input.HardwareButtons"))
Windows.Phone.UI.Input.HardwareButtons.BackPressed += HardwareButtons_BackPressed; 


Use this pattern throughout your app to add device-specific functionality to your app experience.

Control how page elements render for different orientations or screen dimensions

Use design states in your XAML to specify how controls should appear based on things like the orientation of the device.

The Visual Studio Tools for Windows 10 Technical Preview does not yet contain features that help you add these design states but you can add them directly to your XAML file, and then run your app to see how they behave.

Learn about design states.

Create a device-specific view for a page

Sometimes you need more than adaptive controls and design states to achieve a tailored experience. No problem there. You can create device-specific views for your pages. they're not separate pages because they share the same code behind file.

Like device states, the Visual Studio Tools for Windows 10 Technical Preview does not yet contain features that help you create these but you can add them to your projects manually.

Learn more about Views.

Find solutions for known issues in the Visual Studio Tools for Windows 10 Technical Preview

As with any Preview release, you'll likely encounter some unexpected behaviors as you begin using with the Visual Studio Tools for Windows 10 Technical Preview. You might be able to resolve these issues by reviewing the release notes.

Review the release notes.

Related topics

Using Visual Studio to build Windows universal Apps
Windows universal app that consumes data from the Azure Marketplace
Sharing code accross platforms
C#, VB, and C++ project templates

 

 

Show:
© 2015 Microsoft