Portable Class Libraries

  • Article

Updated: August 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 Xbox 360 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 the following in the specified order:

  1. Visual Studio 2010 Service Pack 1 (SP1)

  2. Portable Library Tools

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

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

Xbox 360

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 (from Silverlight)

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

Xbox 360 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.

Supported by Portable 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.

Supporting the View Model Pattern

When you target Silverlight and Windows Phone 7, you can implement the view model pattern in your solution. The classes to implement this pattern are located in the System.Windows.dll assembly from Silverlight. The System.Windows.dll assembly is not supported when you create a Portable Class Library project that targets the .NET Framework 4 or Xbox 360.

The classes in this assembly include the following:

The .NET Framework 4 also contains these classes, but they are implemented in assemblies other than System.Windows.dll. To use these classes with a Portable Class Library project, you must reference System.Windows.dll and not the assemblies listed in the .NET Framework 4 documentation.

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.

Select Portable Library project

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.

Project properties

To add or remove target platforms, click Change.

Change target

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 Xbox 360 platform is added to the targeted platforms.

Warning

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 with ClickOnce deployment: 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.

  • To create a dependency with a setup project: In Solution Explorer, click the setup project. On the Project menu, click Properties, and then click Prerequisites. Select the .NET Framework 4 update as a prerequisite.

For more information about deploying .NET Framework applications, see .NET Framework Deployment Guide for Developers.

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

August 2011

Added information about installing the Portable Class Library Tools without Visual Studio.

Information enhancement.

May 2011

Added information about supporting the view model pattern and creating dependencies.

Information enhancement.

March 2011

Added topic.

Information enhancement.