Cross-Platform Development with the .NET Framework

If you're using Visual Studio 2012 as your development environment, everything you need to develop a Portable Class Library project is already available to you.

To install the Portable Class Library tools on a build machine without installing Visual Studio 2012, download the Portable Library Tools, and save the download file (PortableLibraryTools.exe) on your computer. Run the installation program from a Command Prompt window, and include the /buildmachine switch on the command line.

When you create a Portable Class Library project, you can choose two or more platforms you want to target. The following table shows the available platforms.

Platform	Versions
.NET Framework	.NET Framework 4 and higher .NET Framework 4.0.3 and higher .NET Framework 4.5 (selected by default)
Silverlight	Silverlight 4 and higher (selected by default) Silverlight 5
Windows Phone	Windows Phone 7 and higher (selected by default) Windows Phone 7.5 and higher Windows Phone 8 Important You must install the Windows Phone SDK 8.0 for the Windows Phone 8 option.
.NET for Windows Store apps (*)	N/A
Xbox 360	N/A

The table identifies the four platforms or versions that are selected by default. You can change these default platforms by using the Project Properties dialog box, as shown in the section Selecting the Platforms to Target.

When you specify the platforms you want to target in a Portable Class Library project, the supported assemblies for those platforms are automatically referenced in your project. You do not have to add or remove assemblies. The referenced assemblies are automatically updated if you change the target platforms.

If you target only the .NET Framework 4.5 and the .NET for Windows Store apps, you have access to a much larger set of assemblies than is available in other platform combinations. This larger set of assemblies is almost identical to the .NET for Windows Store apps, but doesn't include the classes in the Windows.UI.Xaml namespaces. For more information, see .NET for Windows Store apps – supported APIs in the Windows Dev Center.

The following table shows which features are supported on the available platforms and versions.

The types and members that are available in Portable Class Library projects are constrained by several compatibility factors:

• They must be shared across the target platforms you selected.

• The must behave similarly across those platforms.

• They must not be candidates for deprecation.

• They must make sense in a portable environment, especially when supporting members are not portable.

For example, the Portable Class Library project doesn't contain any UI-related types or members because of behavioral differences between the UIs of different devices. You may also encounter limitations if you target platforms (such as Xbox, the .NET Framework 4, and Windows Phone 7) that were released before the introduction of the Portable Class Library.

You can find which members are supported by the Portable Class Library in the reference topics for the .NET Framework Class Library. In the members table for a class, the following Portable Class Library icon appears next to supported members.

For example, the following image shows that the Chars property in the String class is supported in the Portable Class Library.

You can also look in the Version Information section of a reference topic for a note indicating that a type or member is supported in the Portable Class Library project, as shown below.

Frequently, you will want to call non-portable members from a portable class. You cannot call non-portable members directly, because those members are not available in the Portable Class Library project. Instead, you can create an abstract class in the Portable Class Library project and use that class from all portable code. In the platform-specific project, you create a child class of the abstract class and implement platform-specific behaviors.

The following example shows a portable class for working with local settings. Local settings are handled differently in a Windows Store app and a Silverlight app, so the portable class doesn't provide any implementation details.

Namespace ExamplePortableLibrary
    Public MustInherit Class ExampleLocalSettings
        Public MustOverride Sub SetLocalValue(name As String, value As Object)

        Public Shared Property Instance As ExampleLocalSettings
    End Class 
End Namespace

In your Portable Class Library project, you can use this method as follows.

ExampleLocalSettings.Instance.SetLocalValue("ExampleSetting ", "New value to add")

In your Silverlight project, you add a reference to the portable assembly, and then create a child class that implements the local setting operation that is specific to a Silverlight environment. The following example shows a Silverlight implementation of the ExampleLocalSettings class.

Imports ExamplePortableLibrary
Imports System.IO.IsolatedStorage;

Public Class SilverlightImplementation
    Inherits ExampleLocalSettings

    Public Overrides Sub SetLocalValue(name As String, value As Object)
        IsolatedStorageSettings.ApplicationSettings.Add(name, value)
    End Sub 
End Class

In your Windows Store app, you add a reference to the portable assembly, and then create a child class that implements the local setting operation that is specific to Windows Store apps. The following example shows an implementation of the ExampleLocalSettings class for a Windows Store app.

Imports Windows.Storage
Imports ExamplePortableLibrary

Public Class AppImplementation
    Inherits ExampleLocalSettings

    Public Overrides Async Sub SetLocalValue(name As String, value As Object)
        ApplicationData.Current.LocalSettings.Values(name) = value
    End Sub 
End Class

In both the Silverlight app and the Windows Store app, you must initialize the specific implementation of the child class and set it to the Instance property. Typically, you create this instance when the app starts. The following example shows how to initialize the Silverlight implementation.

ExampleLocalSettings.Instance = New SilverlightImplementation()

The following example shows how to initialize the implementation for the Windows Store app.

ExampleLocalSettings.Instance = New AppImplementation()

When you target the .NET Framework 4.5, .NET for Windows Store apps, Silverlight, and Windows Phone, you can implement the MVVM pattern in your solution. The classes to implement this pattern include the following:

• System.Collections.ObjectModel.ObservableCollection(Of T)

• System.Collections.ObjectModel.ReadOnlyObservableCollection(Of T)

• System.Collections.Specialized.INotifyCollectionChanged

• System.Collections.Specialized.NotifyCollectionChangedAction

• System.Collections.Specialized.NotifyCollectionChangedEventArgs

• System.Collections.Specialized.NotifyCollectionChangedEventHandler

• System.ComponentModel.DataErrorsChangedEventArgs

• System.ComponentModel.INotifyDataErrorInfo

• System.ComponentModel.INotifyPropertyChanged

• System.Windows.Input.ICommand

For more information about implementing the MVVM pattern in a Portable Class Library project, see Using Portable Class Library with Model-View-View Model.

To create a Portable Class Library project, you create a new project in Visual Studio 2012 and select the Portable Class Library template under Visual C# or Visual Basic.

By default, the Portable Class Library project targets the following platforms:

• .NET Framework 4.5

• Silverlight 4 and later

• Windows Phone 7 and later

• .NET for Windows Store apps

The project only references assemblies that are supported by those platforms. To change the target platforms, in Solution Explorer, open the shortcut menu for the Portable Class Library project, and then choose Properties.

On the project properties page, the Library tab specifies the platforms that are currently targeted.

To add or remove target platforms, choose the Change button, and then select the appropriate check boxes.

When you change the target platforms, the assemblies that are available in the project will change to match the set of assemblies that are supported for your selection. If your project references assemblies that are not supported by one of the platforms you selected, you must either remove the reference to the assembly or change the target platforms.

After you build your Portable Class Library project, you just reference it from other projects. You can reference either the project or specific assemblies that contain the classes you want to access.

To run an app that references a Portable Class Library assembly, the required version (or later) of the targeted platforms must be installed on the computer. Visual Studio 2012 contains all the required frameworks, so you can run the app without further modification on the computer that you used to develop the app.

<div id="silverlightControlHost">
    <object data="data:application/x-silverlight-2," 
           type="application/x-silverlight-2" width="100%" height="100%">
    <param name="source" value="ClientBin/SilverlightApplication.xap"/>
    <param name="onError" value="onSilverlightError" />
    <param name="background" value="white" />
    <param name="minRuntimeVersion" value="4.0.60129.0" />
    <param name="autoUpgrade" value="true" />
    <a href="http://go.microsoft.com/fwlink/?LinkID=149156&v=4.0.50826.0" 
             style="text-decoration:none">
      <img src=http://go.microsoft.com/fwlink/?LinkId=161376
             alt="Get Microsoft Silverlight" style="border-style:none"/>
    </a>
  </object>
   <iframe id="_sl_historyFrame" 
              style="visibility:hidden;height:0px;width:0px;border:0px">
   </iframe>
</div>

Concepts

Other Resources