October 2014

Volume 29 Number 10

Universal Windows Apps : Reuse Code Assets with Universal Windows Apps

Joel Reyes | October 2014

A lot has changedsince I wrote my July 2013 article, “Building Apps for Windows 8 and Windows Phone 8” (msdn.microsoft.com/magazine/dn296517). Today, developers with experience building apps for Windows 8.1 can reuse code and share assets to build new experiences for Windows Phone 8.1. Windows Phone 8 developers can also maximize the same code base when targeting Windows Phone 8.1. Visual Studio 2013, together with a unified Windows Runtime, makes it possible to develop apps that target Windows Phone 8.1 and other Windows devices from one Visual Studio solution. This new approach allows developers to significantly broaden the user base of their apps while maximizing code reuse.

In this article, I’ll share information that will help you get up to speed on the new universal Windows app capabilities found in Visual Studio 2013, including templates, languages, APIs, compilers, different approaches for code sharing, and considerations when updating platform-specific apps to universal Windows apps.

Figure 1 shows the relationship between the universal Windows apps template, the app solution and the compilation output package.

Figure 1 The Universal Windows App Template, Solution and Output Packages

Using the templates included with Visual Studio, such as the Hub app project template, you can create solutions structured to allow separate projects for each platform, as well as a special project for sharing. This shared space is where you can define the code to be reused for the applications targeting PCs, tablets and Windows Phone. This structure ensures all the elements unique to each app are within the appropriate project. The build process creates each specific application package, integrating all dependencies from the shared project. The Hub app template is a great starting point for building shopping, news, sports and media apps.

Figure 2 shows the Universal App New Project Hub App template for C#.

Starting with Update 2, Visual Studio included all the necessary support to make it easy to build Universal Windows apps that maximize code reuse.

Figure 2 Universal Windows App New Project Hub App Template

App Project Support

In a typical scenario where developers target both Windows 8.1 and Windows Phone 8.1, Solution Explorer displays three distinct projects, as shown in Figure 3:

1. A Windows project (Windows 8.1): for XAML pages and specific code for Windows.
2. A Windows Phone project (Windows Phone 8.1): for XAML pages and specific code for Windows Phone.
3. A Shared project: for any assets sharable between the target apps, such as .cs, .xml .png, .resw and other items. The Share project imports automatically into each platform project during the build process.

Figure 3 Universal Windows App Projects in Solution Explorer

For existing solutions you can use Add Windows Phone 8.1 or Add Windows 8.1 from the project context menu. 

Language Support

Code sharing can be accomplished using C++, C#, or JavaScript, whether your design involves XAML, HTML, or DirectX. For Visual Basic, recent updates allow calls to Windows Runtime (WinRT) APIs and include support for XAML and the assets folder of the Portable Class Library (PCL). F# developers can create shared code for both legacy and newer Microsoft .NET Framework and Windows Store apps.

API Support

A common Windows Runtime means massive unification of the supporting APIs for both platforms, Windows 8.1 (for PCs and tablets) and Windows Phone 8.1. This unification is the key to easier and more capable cross-platform development. Because universal Windows apps run on the same Windows Runtime, developers have a common way to architect and build apps for the range of Windows devices, from how they handle suspend and resume and do background processing, to the way they manage in-app security.  In fact, in terms of key language constructs, the Windows 8.1 SDK and Windows Phone 8.1 SDK share 566 classes, 119 struts and 57 interfaces. There are, however, some APIs that are available only in Windows Phone.

Compiler Support

Although the build process guarantees importing the associated XAML, code and assets for each project, sometimes you might need to include platform-specific code in the Shared Project. You can leverage the conditional compilation directives #if and #endif to indicate the code intended for each platform. For C#, the preprocessor compiler symbols are WINDOWS_APP and WINDOWS_PHONE_APP; for C++, they are WINAPI_FAMILY_­PC_APP and WINAPI_FAMILY_PHONE_APP.

The following C# example illustrates conditional compilation for a situation where the developer may want to move the App.xaml file to the Shared Project (this example assumes any styles defined in it use resources available to other types of apps):

#if WINDOWS_APP
  if (!rootFrame.Navigate(typeof(HubPage)))
#endif
#if WINDOWS_PHONE_APP
  if (!rootFrame.Navigate(typeof(WindowsPhoneStartPage)))
#endif
  // ...throw exception
Here’s the equivalent C++ conditional compilation:
#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

Code and XAML Editor Support

Visual Studio provides a lot of help to ease the development of universal apps. IntelliSense monitors your code to prevent the use of unsupported APIs in your Universal App project. Corresponding error messages will identify an inappropriate API when you build the project, as shown in Figure 4.

Figure 4 IntelliSense Showing an API Usage Error

The navigation bar allows you to switch project context. This is useful when you want to concentrate on only one project in Solution Explorer. The project context (Windows Phone or Windows 8) drives the IntelliSense experience in the editor and the designer.

During debugging, you may want to specify the default startup project for F5. Visual Studio provides an easy way to do this by using the debug target dropdown and, under Startup project, selecting the desired project. This feature is supported in both stores and is turned on when there’s more than one application project in the solution.

The Device Panel, shown in Figure 5, helps you make sure your application behaves as expected on all target devices. It lets you test your application using different display resolutions, orientations, accents, themes and so forth.

Figure 5Device Panel

Code Sharing Strategies

When building universal Windows apps, it’s best to maximize the application artifacts sharable across apps. Traditionally, developers have relied on linked files to share code across multiple projects. Visual Studio 2013 enhances this capability and provides two related artifacts to enable code sharing: the Shared Project and PCL.

A Shared Project (Shared Folder) offers a simple organizational structure for storing all the shared code and assets, including app.xaml and other XAML files, code files, images, XML/JSON and .resw files, as well as templates such as Common and DataModel. References in the Shared Project need to be resolved to resolve compiler errors.

The PCL is better supported in universal Windows apps. For instance, developers can now call and create WinRT APIs and portable XAML user controls. When you change the project target to include another platform, the compiler produces a single binary guaranteed to work on all the targets. You can also make a PCL target a specific platform by removing the other targets. This in-place conversion is only supported between PCL, Windows Store 8.1 and Windows Phone 8.1.

These PCL binaries can also be distributed to third parties, and this has generated a growing community of cross-platform developers who are porting their libraries to PCL. This ensures that abundant library capabilities will be available to developers, including Visual Studio Express developers, for targeting other platforms. Through MS Open Tech, Microsoft works with various open source communities to contribute code to popular frameworks and optimize them for Windows devices. For instance, JQuery fully supports the Windows Runtime so developers can reuse their existing code and skills to build Windows 8.1 apps.

Deciding Between Shared Projects and PCL

There’s a simple determinant for choosing between Shared Projects and PCLs: platform specificity.

• If your project isn’t targeting third-party distribution, Shared Projects will give you the best experience.  
• If your project involves third-party distribution, PCL is the better choice.

Figure 6 indicates some of the strengths and weaknesses of each approach.

Figure 6 Comparison of Shared Project and Portable Class Library

Other Code Sharing Considerations

Linking Files: Similar to Shared files, the Visual Studio Add as Link feature gives you explicit file sharing the traditional way, using compiler conditionals to share across additional platforms.

Code Sharing in the Front End: Both Windows Store 8.1 and Windows Phone 8.1 share the same WinRT XAML stack. This is great news as it allows developers to also target the UI for sharing. You can share the UI via a PCL, including using the XAML designer.

Code Sharing in the Back End: Universal Windows apps fully benefit from code sharing focused on back-end processing, and this is perfect for implementing shared data models with cloud dependencies. Microsoft Azure Mobile Services, in particular, is a good example of powerful back-end components that universal Windows apps can leverage across applications and devices to access services for notification and other functions. It serves both Windows Store and Windows Phone applications equally well, with the same level of data security, application availability and scalability.

Application Update Paths

Developers with apps in either store can now easily update the app to support the other store. All update paths require you to have Windows 8.1 and Visual Studio 2013 installed.

Updating a Windows Phone 8 app to a universal Windows app: Updating your Windows Phone 8 app to the Windows Runtime as a universal Windows app means you can use Windows XAML to create the new UX, and offer features like notification options that capitalize on the new Windows Phone 8.1 Action Center, or even offer entirely new features to users. Once you’ve updated to a universal app, you can easily share code with a parallel app for PCs and tablets.

If you’re updating your app from Windows Phone 8 to Windows Phone 8.1, check out the documentation for differences in API support, as there are several API behavior and feature changes (aka.ms/waphone81) related to background processing, files and storage, controls, and other device capabilities.

Updating a Windows Store app to a universal Windows app: If you’ve already built a Windows 8.1 app and want to publish to the Windows Phone 8.1 store, the universal Windows apps pattern also applies. As in the case of Windows Phone 8.1, it’s important to understand the API behavior changes (aka.ms/wawindows81) that may affect the migration process. For example, the AppBar, Flyout, Hub, and other controls are not supported on Windows Phone.

Updating a Windows Store app and adding Windows Phone 8.1 app: Providing a companion Windows Phone 8.1 app to your Windows Store app is simplified by the universal Windows app template, which allows you to simply add a new Windows Phone 8.1 project to your Windows Store solution. The code editor and compiler recognize the addition and make the appropriate changes to behaviors to guarantee successful development.

Store Certification

The Windows App Certification Kit (WACK) is an instrumental tool for developers preparing their application for submission to the store. You can also use the tool to test your Windows Phone 8.1 apps, but not Windows Phone 8 apps. WACK 3.3 is included in the Windows SDK for Windows 8.1 and you can find more information about the new requirements for WACK at bit.ly/1qXPKmf.

Wrapping Up

Platform convergence has been a long time coming and although we haven’t reached nirvana, the progress has given developers substantial improvements in platform capabilities, tools enhancement, UX features, and breadth of application scenarios support. Today, it isn’t enough to be able to execute code in different devices. The UX must maximize the specific characteristic of the device on which the application runs. It’s equally important to support feature parity across those devices. It’s simply what users expect.

This article has explored the key capabilities that allow you to simultaneously develop apps for both the PC/tablet and Windows Phone platforms, whether building solutions from scratch or upgrading from existing ones. Universal Windows apps offer an excellent way for developers to increase the value of their code investment, while broadening users’ reach.

You can find a comprehensive assortment of universal Windows app samples that you can execute on both Windows 8.1 and Windows Phone 8.1 at aka.ms/wasamples, and a large collection of feature samples that use the new universal Windows app template at aka.ms/uap.

Joel Reyes is senior technology evangelist in the Microsoft Developer Experience & Evangelism Group focused on Startup Development Strategy. You can reach him at joel.reyes@microsoft.com.

Thanks to the following Microsoft technical expert for reviewing this article: Lora Heiny