Portable Class Libraries
[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]
The Portable Class Library project in Visual Studio 11 Beta enables you to write and build managed assemblies that work on multiple .NET Framework platforms. For example, you can create classes that contain shared business logic for desktop, Metro style, and mobile apps, and you can then reference those classes from those projects.
Using a Portable Class Library project, you can build portable assemblies that work without modification in .NET Framework, Metro style, Silverlight, Windows Phone 7, and Xbox 360 apps. The Portable Class Library project supports a subset of assemblies from these platforms, and provides a Visual Studio template that you can use to build assemblies that run without modification on these platforms. If you don't use a Portable Class Library project, you must target a single app type and then manually rework the class library for other app types.
The features of the Portable Class Library are described in the following sections:
If you're using Visual Studio 11 Beta 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 11 Beta, 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. Four of these are selected by default and are marked by an asterisk (*) in the following table.
|
Platform |
Versions |
|---|---|
|
.NET Framework |
.NET Framework 4 and later (*) .NET Framework 4 Platform Update 3 and later (4.0.3) .NET Framework 4.5 Beta |
|
Silverlight |
Silverlight 4 and later (*) Silverlight 5 |
|
Windows Phone |
Windows Phone 7 and later (*) Windows Phone 7.1 SDK |
|
.NET for Metro style apps (*) |
N/A |
|
Xbox 360 |
N/A |
You can change these default platforms by using the Project Properties dialog box, as shown in the section Selecting the Platforms to Target.
The following assemblies are available within a Portable Class Library project:
-
mscorlib.dll
-
System.dll
-
System.Core.dll
-
System.ComponentModel.Composition.dll
-
System.ComponentModel.DataAnnotations
-
System.Net.dll
-
System.Runtime.Serialization.dll
-
System.ServiceModel.dll
-
System.ServiceModel.Web.dll
-
System.Xml.dll
-
System.Xml.Linq
-
System.Xml.Serialization.dll
-
System.Windows.dll
However, not all of these assemblies are supported on all platforms. When you specify the platforms you want to target, 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, System.Xml.dll, and System.Xml.Serialization.dll) are supported on all versions of all platforms.
The following table shows which assemblies are supported on the available platforms and versions.
|
Feature |
Assemblies |
.NET Framework |
Metro style |
Silverlight |
Windows Phone |
Xbox 360 |
|---|---|---|---|---|---|---|
|
Core |
mscorlib.dll, System.dll, System.Core.dll, System.Xml.dll, System.Xml.Serialization.dll |
√ |
√ |
√ |
√ |
√ |
|
Managed Extensibility Framework (MEF) |
System.ComponentModel.Composition.dll |
√ |
√ |
√ |
|
|
|
Network Class Library (NCL) |
System.Net.dll |
√ |
√ |
√ |
√ |
|
|
Serialization |
System.Runtime.Serialization.dll |
√ |
√ |
√ |
√ |
|
|
Windows Communication Foundation (WCF) |
System.ServiceModel.dll, System.ServiceModel.Web.dll |
√ |
√ |
√ |
√ |
|
|
Model-View-View Model (MVVM) |
System.Windows.dll |
Only 4.5 |
√ |
√ |
Only 7.1 |
|
|
Data annotations |
System.ComponentModel.DataAnnotations.dll |
Only 4.0.3 and 4.5 |
√ |
√ |
|
|
|
LINQ to XML |
System.Xml.Linq.dll |
Only 4.0.3 and 4.5 |
√ |
√ |
√ |
|
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.
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.
When you target the .NET Framework 4.5 Beta, .NET for Metro style apps, Silverlight, and Windows Phone 7.1, you can implement the MVVM pattern in your solution. The classes to implement this pattern are located in the System.Windows.dll assembly. They include the following:
-
System.Collections.ObjectModel.ReadOnlyObservableCollection<T>
-
System.Collections.Specialized.NotifyCollectionChangedAction
-
System.Collections.Specialized.NotifyCollectionChangedEventArgs
-
System.Collections.Specialized.NotifyCollectionChangedEventHandler
The .NET Framework 4.5 Beta also contains these classes, but they are not located in the System.Windows.dll assembly. 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.5 Beta documentation.
For more information about implementing the MVVM pattern in a Portable Class Library project, see Using Portable Class Library with Model-View-View Model (MVVM).
By default, the Portable Class Library project targets the following platforms:
-
.NET Framework 4 and later
-
Silverlight 4 and later
-
Windows Phone 7 and later
-
.NET for Metro style 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. In Solution Explorer, the assemblies that are not supported are marked with an exclamation point (!). For example, the following illustration shows that four assemblies (System.Net, System.Runtime.Serialization, System.ServiceModel, and System.Xml.Serialization) are not supported when Xbox 360 is added to the targeted platforms.
After you select the target platforms, some of the assemblies that are available for that combination are automatically referenced, and you can manually add references to others. You can see which assemblies have been referenced in the Reference Manager window:
-
Assemblies that are already referenced appear with a check mark.
-
Assemblies that you can reference appear undimmed, but without a check mark.
-
Assemblies that are unavailable for the target platforms that you selected appear dimmed.
For example, the following illustration shows that you can reference System.Windows and System.Xml.Linq with your current platform selections, but you cannot reference System.ComponentModel.Compositions and System.ComponentModel.DataAnnotations unless you change the target platforms.
If you reference an assembly that is not supported by the target platforms, Visual Studio will display a warning and will automatically change your target platforms to a combination that supports the assembly.
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 11 Beta contains all the required frameworks, so you can run the app without further modification on the computer that you used to develop the app.
Deploying a .NET Framework App
When you deploy a .NET Framework app that references a Portable Class Library assembly, you must specify a dependency on the correct version of the .NET Framework. By specifying this dependency, you ensure that the required version is installed with your app. If you target the .NET Framework 4 or later, the computer must have the .NET Framework 4 with an update, the .NET Framework 4 Platform Update 3, or the .NET Framework 4.5 Beta installed.
-
To create a dependency with ClickOnce deployment: In Solution Explorer, choose the project node for the project you want to publish. (This is the project that references the Portable Class Library project.) On the menu bar, choose Project, Properties, and then choose the Publish tab. On the Publish page, choose Prerequisites. Select the required .NET Framework version (or .NET Framework 4 update) as a prerequisite.
-
To create a dependency with a setup project: In Solution Explorer, choose the setup project. On the menu bar, choose Project, Properties, Prerequisites. Select the required .NET Framework version as a prerequisite.
For more information about deploying .NET Framework apps, see .NET Framework Deployment Guide for Developers.
Deploying a Silverlight-based App
When you deploy a Silverlight-based app that references a Portable Class Library assembly, you must ensure that the minimum runtime version required for the app matches its targeted version. If you target Silverlight 4, the version must be 4.0.60129.0 or later. You set the version by including <param name="minRuntimeVersion" value="4.0.60129.0" /> in the webpage that hosts the Silverlight-based app, as follows:
<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>
API Differences in the Portable Class Library
To make Portable Class Library assemblies compatible across all 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.
