Portable Class Libraries

Updated: March 2011

The Portable Class Library project enables you to write and build managed assemblies that work on more than one .NET Framework platform. You can create classes that contain code you wish to share across many projects, such as shared business logic, and then reference those classes from different types of projects.

Using the Portable Class Library project, you can build portable assemblies that work without modification on the .NET Framework, Silverlight, Windows Phone 7, or XNA (Xbox) platforms. Without the Portable Class Library project, you must target a single platform and then manually rework the class library for other platforms. The Portable Class Library project supports a subset of assemblies from these platforms, and provides a Visual Studio template that makes it possible to build assemblies that run without modification on these platforms.

Prerequisites

To create a Portable Class Library project, you must install these components in the following order:

1. Visual Studio 2010 Service Pack 1 (SP1)

2. Portable Library Tools

Assemblies

The following assemblies are available within a Portable Class Library project:

• mscorlib.dll

• System.dll

• System.Core.dll

• System.Xml.dll

• System.ComponentModel.Composition.dll

• System.Net.dll

• System.Runtime.Serialization.dll

• System.ServiceModel.dll

• System.Xml.Serialization.dll

• System.Windows.dll (from Silverlight)

However, not all of these assemblies are supported on all platforms. In a Portable Class Library project, you specify the platforms you want to target, and only the supported assemblies for those platforms are referenced in your project. If you try to reference an assembly that is not supported for the platforms you have targeted, Visual Studio warns you of the incompatibility. The core assemblies (mscorlib.dll, System.dll, System.Core.dll, and System.Xml.dll) are supported on all platforms.

The following table shows which assemblies are supported on the available platforms.

Feature	Assemblies	.NET Framework 4	Silverlight	Windows Phone 7	XNA (Xbox)
Core	mscorlib.dll, System.dll, System.Core.dll, System.Xml.dll	Yes	Yes	Yes	Yes
Managed Extensibility Framework (MEF)	System.ComponentModel.Composition.dll	Yes	Yes	No	No
Network Class Library (NCL)	System.Net.dll	Yes	Yes	Yes	No
Serialization	System.Runtime.Serialization.dll	Yes	Yes	Yes	No
Windows Communication Foundation (WCF)	System.ServiceModel.dll	Yes	Yes	Yes	No
XML Serialization	System.Xml.Serialization.dll	Yes	Yes	Yes	No
View Model Support	System.Windows.dll	No	Yes	Yes	No

Portable Class Library projects target a combination of platforms. The following table shows the features that are supported for platform combinations.

Platforms	Support
Silverlight and Windows Phone 7	Everything except MEF
.NET Framework 4 and Silverlight	Everything except View Model Support
.NET Framework 4 and Windows Phone 7	Everything except View Model Support and MEF
.NET Framework 4, Silverlight, and Windows Phone 7	Everything except View Model Support and MEF
XNA and any other platform	Core only

Finding the Supported Members in Reference Documentation

You can find which members are supported by the Portable Class Library project 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.

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.

Creating a Portable Class Library Project

To create a Portable Class Library project, you create a new project in Visual Studio 2010 and select the Portable Class Library template under Visual C# or Visual Basic. If you do not see the template, make sure that you have installed the Portable Library Tools.

Selecting the Platforms to Target

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

• .NET Framework 4

• Silverlight 4

• Silverlight for Windows Phone 7

The project only references assemblies that are supported by those platforms. To select the platforms to target, in Solution Explorer, right-click the Portable Class Library project name, and select Properties.

The project properties page specifies the platforms that are currently targeted.

To add or remove target platforms, click Change.

When you change the target platforms, the assemblies referenced 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. In Solution Explorer, the assemblies that are not supported are marked with an exclamation point (!). The following illustration shows a warning for assemblies that are not supported when the XNA Framework is added to the targeted platforms.

Using the Portable Class Library

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

Creating a Dependency

To run a Portable Class Library application, an update for the .NET Framework 4 must be installed on your machine. This update is automatically installed with Visual Studio 2010 SP1, so you can run the Portable Class Library application without further modification on the computer that you used to develop the application. To run the application on a different computer, you can install the update manually.

When you deploy a .NET Framework 4 application that references a Portable Class Library assembly, you must specify a dependency on the .NET Framework 4 update. By specifying this dependency, you ensure that the update is installed with your application. To create a dependency, in Solution Explorer, click the project node for the project you want to publish. (This is the project that references the Portable Class Library project.) On the Project menu, click Properties, and then click the Publish tab. On the Publish page, click Prerequisites. Select the .NET Framework 4 update as a prerequisite.

Deploying with Silverlight

When you deploy a Portable Class Library assembly with a Silverlight-based application, you must ensure that the minimum runtime version required for the application is set to version 4.0.60129.0 or later. You set the minRuntimeVersion parameter value by including <param name="minRuntimeVersion" value="4.0.60129.0" /> in the webpage that hosts the Silverlight-based application.

<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="https://go.microsoft.com/fwlink/?LinkID=149156&v=4.0.50826.0" 
             style="text-decoration:none">
      <img src=https://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>

API Differences in the Portable Class Library

To make Portable Class Library assemblies compatible across all the supported platforms, some members have been slightly changed in the Portable Class Library. For details about which members were changed and how they were changed, see API Differences in Portable Class Library.

See Also

Concepts

API Differences in Portable Class Library

Change History

Date	History	Reason
March 2011	Added topic.	Information enhancement.