Creating a project structure for cross platforms apps for Windows RT and Windows Phone

April 14. 2014 0 Comments

One of our goals as developers when building for multiple platform is to minimize the code duplication required to support each platform. For projects that target the Windows RT and Windows Phone platforms (and even Android and iOS using Xamarin) we can make use of a type of project called Portable Class Library, or PCL for short. There is a lot of documentation about how to use PCL in cross platform projects on the web so I will not talk about how to use PCL, but instead talk about one of the challenges that these kind of projects have: creating the solution and project structure in Visual Studio.

How to name projects? what namespaces should they use? how to name the assemblies? and how to make Visual Studio do what we want to do? In this article I will give a step-by-step guide on how to create a Visual Studio solution and projects for a cross platform application.

Let’s start by describing what we want: we want three projects, a PCL project, a WinRT project and WP project. As an example, we would like to create a project structure such as the one we have in the figure. We will use a suffix on the project name to specify the type of project. Let’s explain it in detail:

SampleApp.PCL: this is where all the logic for the app will be developed.
SampleApp.WinRT: this is the WinRT (in this case Windows 8.1) application, containing the views and platform specific services for WinRT. Notice that we have included a reference to the SampleApp.PCL project
SampleApp.WP: this is the Windows Phone (in this case, Windows Phone 8) application, containing the views and platform specific services for Windows Phone. Notice that we have included a reference to the SampleApp.PCL project

I have chosen to create blank projects for both WinRT and WP apps since I like to have control over all the code, but you can choose any template you want. You need to be careful when creating the projects since Visual Studio will use the name of the project as the default namespace and you will end up with three different namespaces (one for each project) and then changing this can be problematic.

It is important to specify the same default namespace for all three projects in order to minimize the using clauses on the code and xmlns declarations in the XAML. This is just a personal choice, you can of course have three different namespaces, one for each type of project if you want. In this case I want the default namespace for all the projects to be the same (SampleApp in the example).

I will describe how to achieve the project structure described above and I will use “SampleApp” as the name of my project in the examples, but of course, you can use your own project name.

The Portal Class Library project

Start by creating the PCL project first. VS will automatically create the solution when you’re creating the first project.

Open Visual Studio and create a new PCL project and call it “SampleApp”:

Notice that we don’t name the project “SampleApp.PCL”, we just use “SampleApp”. If we name it “SampleApp.PCL” VS will configure the project with a default namespace of “SampleApp.PCL” and we don’t want this. Although we can then change it in the project properties, this is easy for a PCL project, but it is somewhat difficult for a WinRT and WP project since we would have to go and change all the generated XAML files, and .cs files and change the namespace. So, for consistency, let’s do the same process on all our projects.

Choose the appropriate target frameworks, in our case choose Windows Store and Windows Phone. VS will create the PCL project. Remove the auto-generated Class1.cs file. Next, rename the project to “SampleApp.PCL”, and in the project properties change the assembly name to “SampleApp.PCL”. You will have something like this:

If you’re using TFS or Git (or any source code repository for that matter) don’t add the project to it just yet, let’s first create the structure and then we can add it to source control. It will be easier this way.

Now, here comes the tricky part. Since we will use the same project name (SampleApp) for all the projects, we need to change the folder name on disk, otherwise VS will put all the projects in the same folder, and will throw an error since files already exist.

Close VS, locate the folder on disk where the solution is stored, and rename the folder for the project from “SampleApp” to “SampleApp.PCL” (see the figure). Now you need to edit the solution file (SampleApp.sln) to tell VS that the project is now in a different folder. Open the solution file with a text editor, locate the line where the project file path is specified and change the directory to the appropriate one. In my case, this is the line I have to change:

Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SampleApp.PCL", "SampleApp.PCL\SampleApp.PCL.csproj", "{8DCACD8E-1DC0-4119-ADD8-41CDFE5E4D85}"

Now, we need to repeat the process for the rest of the projects.

The Windows Store project

Open the VS solution again, and add a Windows Store project to it:

Notice we use SampleApp as the name of the project. Once created, rename it to “SampleApp.WinRT”, open the properties for the project and change the assembly name to “SampleApp.WinRT”. Notice how the default namespace remains as we want to “SampleApp”. Of course, all the XAML and .cs files use the appropriate namespace.

Now, close VS, and change the folder name as we did with the PCL project. Rename the “SampleApp” folder to “SampleApp.WinRT” (see figure). Open the solution file with a text editor, locate the line where the project file path for this new project is specified and change the directory to the appropriate one. In my case, this is the line I have to change:

The Windows Phone project

One last time for the Windows Phone project. Open the VS solution again, and add a Windows Phone project to it:

Notice again we use “SampleApp” as the name of the project. Once created, rename it to “SampleApp.WP”, open the properties for the project and change the assembly name to “SampleAppWP”. Notice how the default namespace remains as we want to “SampleApp”. Of course, as with the WinRT case, all the XAML and .cs files use the appropriate namespace.

Notice that in the case of the WP project, the assembly name has no dot between the name of the project and the suffix. This is because when I specify the dot the WP emulator starts behaving strange. Maybe is something about my particular installation, but I rather not put the dot for the WP assembly.

Close VS, and change the folder name as we did with the PCL and WinRT projects. Rename the “SampleApp” folder to “SampleApp.WP” (see figure). Open the solution file, locate the line where the project file path for this new project is specified and change the directory to the appropriate one. In my case, this is the line I have to change:

Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SampleApp.PCL", "SampleApp.PCL\SampleApp.PCL.csproj", "{8DCACD8E-1DC0-4119-ADD8-41CDFE5E4D85}"
…
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SampleApp.WinRT", "SampleApp.WinRT\SampleApp.WinRT.csproj", "{DD03BAB5-6174-46F7-A926-0E1FAEB3BD62}"
…
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SampleApp.WP", "SampleApp.WP\SampleApp.WP.csproj", "{CAA9B94D-607E-42D7-829C-0D0B366180CB}"

Wrapping up

We have our project structure almost done. There is one last step we need to do: add the PCL project reference to both the Windows RT and Windows Phone projects, but I guess you know how to do this already.

Finally, we end up with a solution/project structure as the one in the first image of this article and we are now ready to start developing. At this point you can add your solution to source control if you like.

In a next article I will describe how to prepare and configure our projects for MVVM.