What’s new in .NET Framework 4 Client Profile RTM

In .NET Framework 4 we have introduced a streamlined subset and more compact version of the .NET Framework called the Microsoft .NET Framework 4 Client Profile (aka NET4 Client Profile). The Microsoft .NET Framework 4 which is the Full Framework(aka NET4 Full) still exists and it is a superset of the Client Profile.
Hopefully folks have seen Soma’s blog announcing the availability of Visual Studio 2010 , .NET Framework 4 and .NET Framework 4 Client Profile.
I have discussed some of the beta features of Microsoft .NET Framework 4 Client Profile in details in my previous Beta 1 blog and Beta 2 blog posts.  In this post I wanted to highlight some of the key changes from our previous Beta 2 public release and reiterate some of the important features

What are the reasons for a Client Profile?
Although the NET4 Client Profile is smaller and faster to install compared to the NET4 Full Framework (NET4 is 7-8MB smaller in size than the Full Framework), the main reasons are not just better deployment size/time but also:

• Reduce the Framework deployment failures.
• By keeping ASP.Net and other components (that are mostly needed for servers) out of the Client Profile, we can reduce the attack surface and the number of future servicing events which may be caused by server component (such as ASP.Net) and are not needed for desktop scenarios.
• Making NET4 Client Profile available on Windows Update will make sure that most desktop machines will include NET4 Client Profile over time and apps that target the Client Profile will not need to carry or install the Framework which will improve the overall deployment experience.
• Enable us to add features and grow the size of overall Framework in future versions but still have a smaller core.

When to use NET4 Client Profile and when to use NET4 Full Framework?
NET4 Client Profile:
Always target NET4 Client Profile for all your client desktop applications (including Windows Forms and WPF apps).

NET4 Full framework:
Target NET4 Full only if the features or assemblies that your app need are not included in the Client Profile. This includes:

• If you are building Server apps. Such as:
  • ASP.Net apps
  • Server-side ASMX based web services
• If you use legacy client scenarios. Such as:
  • Use System.Data.OracleClient.dll which is deprecated in NET4 and not included in the Client Profile.
  • Use legacy Windows Workflow Foundation 3.0 or 3.5 (WF3.0 , WF3.5)
• If you targeting developer scenarios and need tool such as MSBuild or need access to design assemblies such as System.Design.dll

How big is Client Profile?
Below are the redistributable download size improvements since NET 3.5 SP1. As you can see we have made significant improvements.
Note that if you are downloading from the Web, the actual download size could be smaller since some components may already be on your machine (for example, Software Rasterizer (rgb9rast) , etc )

What is new in NET4 Client Profile RTM vs. Beta 2 ?

• File moves: We moved few files between Client Profile to Extended (Full). Most notably:
  Move System.ComponentModel.DataAnnotations.dll from the full framework to Client Profile
  Some additional file moves below.
• Removed Windows Imaging Components (WIC) from NET4 setup package (Full & Client).
  Since WIC is already included in XP SP3, Vista, Windows 7, and installed with .NET 3.5 SP1 it made sense to remove it and decrease setup size for almost all users that do not need it.
  Folks that need this component (mainly XP SP2/SP1 and Windows 2003 users that do not have NET 3.5 SP1 installed) can install it from here:
  32 bit: https://www.microsoft.com/downloads/details.aspx?FamilyId=8E011506-6307-445B-B950-215DEF45DDD8&displaylang=en
  64-bit: https://www.microsoft.com/downloads/details.aspx?familyid=F64654AC-6E26-41D9-A90A-0E7783B864EE&displaylang=en
  Note that if WIC is missing, NET4 setup will fail.
  We expect that very few machines will require WIC. Some apps that chain-install the NET4 framework may need to either block on WIC or chain-install WIC.
• Black assemblies:
  These are assemblies that although included in the NET4 Client Profile runtime they are not meant to be used by NET4 Client Profile applications.
  These assemblies are not included in the Reference Assemblies folder and they are not accessible/visible by Visual Studio 2010.
  NET4 currently includes only one such assembly:
  • ISymWrapper
• Grey APIs:
  These are APIs/namespaces that although included in the NET4 Client Profile runtime they are not supported and not meant to be used by NET4 Client Profile applications. The main reason these assemblies are not supported in the Net4 Client Profile is that they have dependencies on assemblies from NET4 Full so your Client Profile app may crash if you do use them on machines that only have Client Profile installed.
  In RTM, these APIs/namespaces are “grayed out” from the Reference Assemblies and are not accessible/visible in Visual Studio 2010.
  Note that if your app is targeting the NET4 Full you will be able to access these APIs/namespaces.
  In System.Web.Services, the following namespaces are “greyed out” for NET4 Client Profile:
  • System.Web.Services.WebService
  • System.Web.Services.Description.BasicProfileViolation
  • System.Web.Services.Description.BasicProfileViolationCollection
  • System.Web.Services.Description.BasicProfileViolationEnumerator
  • System.Web.Services.Description.ProtocolImporter
  • System.Web.Services.Description.ProtocolReflector
  • System.Web.Services.Description.ServiceDescriptionImporter
  • System.Web.Services.Description.ServiceDescriptionReflector
  • System.Web.Services.Description.SoapExtensionImporter
  • System.Web.Services.Description.SoapExtensionReflector
  • System.Web.Services.Description.SoapProtocolImporter
  • System.Web.Services.Description.SoapTransportImporter
  • System.Web.Services.Description.WebServicesInteroperability
  • System.Web.Services.Discovery.ContractSearchPattern
  • System.Web.Services.Discovery.DiscoveryDocumentLinksPattern
  • System.Web.Services.Discovery.DiscoveryDocumentSearchPattern
  • System.Web.Services.Discovery.DiscoveryRequestHandler
  • System.Web.Services.Discovery.DiscoverySearchPattern
  • System.Web.Services.Discovery.DynamicDiscoveryDocument
  • System.Web.Services.Discovery.ExcludePathInfo
  • System.Web.Services.Discovery.XmlSchemaSearchPattern
  • System.Web.Services.Protocols.HtmlFormParameterReader
  • System.Web.Services.Protocols.MimeParameterReader
  • System.Web.Services.Protocols.ServerProtocol
  • System.Web.Services.Protocols.ServerProtocolFactory
  • System.Web.Services.Protocols.ServerType
  • System.Web.Services.Protocols.SoapServerMessage
  • System.Web.Services.Protocols.SoapServerMethod
  • System.Web.Services.Protocols.SoapServerProtocol
  • System.Web.Services.Protocols.SoapServerProtocolFactory
  • System.Web.Services.Protocols.SoapServerType
  • System.Web.Services.Protocols.UrlParameterReader
  • System.Web.Services.Protocols.ValueCollectionParameterReader
  • System.Web.Services.Protocols.WebServiceHandlerFactory

What is new in Visual Studio 2010 for NET4 Client Profile

Since Beta 2 we made some small but important improvements to the he VS 2010 RTM UI:
(You can read about the changes we in Beta2 in my Beta 2 blog )
  A) Starting with VS 2010 RTM, the “Add Reference” indicates the target framework that assemblies are filtered against.
  B) The VS 2010 RTM toolbox now clearly indicates if 3^rd party controls are not available for the selected profile.

How to use Client Profile in Visual Studio 2010

Visual Studio 2008 introduced multi-targeting to allow application to target 2.0 and 3.x versions of the .NET Framework. VS 2010 has improved multi-targeting and starting in VS 2010 Beta2 many of the Client projects are targeting the NET4 Client Profile by default. I also discussed this in my Beta 2 blog .

Projects that target NET4 Client Profile by default

These projects starting with VS 20101 Beta2 target the NET4 Client Profile by default:

Windows Project (C# and VB) - WPF Application
- WPF Browser Application
- WPF Custom Control Library
- WPF User Control Library
- Windows Forms Application
- Windows Forms Control Library
- Console Application
- Empty Project
- Window Service

Visual F#
- F# Application
- F# Tutorial

Workflow (C# & VB) - Activity Designer Library
- Activity Library
- Workflow Console Application

WCF (C# & VB) - WCF  Service Library

Office 2007 & 2010 templates (C# & VB) -
All Projects

All other projects, including Class Library, target the Full Framework by default.
Mixed-target scenarios using Class Library may present interesting challenges. Read more below.

How to retarget your C#/VB.Net project

To change targeting of your project, open the project properties, select the "Application" page, and change the “Target framework” drop-down.
C# project example:

VB project example (Project Properties > Compile tab > “Advanced Compile Options…”):

Note that if you right-click the project and select “Add References”, the dialog shows only the .NET Framework assemblies that are part of the selected profile. This is accomplished by using reference assemblies (metadata-only versions of assemblies). The .NET Framework 4 Client Profile Reference Assemblies are located in:
     %programfiles%\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.0\Profile\Client

At compile time, the reference assemblies are matched up against the known "Client List" assemblies that are included in the Client Profile. If a project targeting the Client Profile has a reference to a .NET assembly that is not included in the "Client List", Visual Studio displays compile-time errors in the Error List.

How to change targeting for other projects

Some other VS 2010 projects such as Managed C++ (C++/CLI) still target the Full Framework by default. VS 2010 unfortunately does not provide UI to change the targeting.
Fortunately, you can still edit the project file manually in order to change the profile targeting. To do so:
a) Right click “Unload Project”
b) Right-Click “Edit <project_name>”
c) Set the appropriate project property to target Client Profile. e.g.

<TargetFrameworkVersion>v4.0</TargetFrameworkVersion>
<TargetFrameworkProfile>Client</TargetFrameworkProfile>

d) Right click “Reload Project”

In addition, for these projects, notice that VS does not create an <app.config> file for your project.
Note: If your project does not add references or access assemblies that are included in the Full Framework but are not part of the Client Profile, there is nothing to worry about. Your app will run on machines with either NET4 Client Profile or Full Framework just fine.
Otherwise, if you do access assemblies from the Full Framework, you should add <app.config> to indicate to CLR not to load your app if it is launched on the NET4 Client Profile.
E.g. add this:

<?xml version="1.0"?>
<configuration>
    <startup>
          <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.0"/>
   </startup>
</configuration>

If you don’t do so, your app may crash at random when it needs to load the assemblies that are missing from the Client Profile.

Deployment

The project Publish property page allows you to select the prerequisite needed for your ClickOnce deployment. VS 2010 automatically selects the correct profile (Client Profile or Full) depending on your primary project target.
 

Setup and Deployment Projects

The same prerequisite dialog from above appears when you create “Setup and Deployment” project (under “Add New Project”/“Other Project Types”). The NET4 Client Profile prerequisite entry is checked by default in this case.

 
If you create a new “Visual Studio Installer” setup project (under “Setup and Deployment“) and add the output of your NET4 Client Profile to it (Right-Click ->“Add”-> “Project Output…”’ select “Primary output”) , VS2010 adds a new “Launch Condition”. (Right-click on your new Setup project and then do “View->Launch Conditions”)

By default VS2010 will add NET4 Client Profile as a launch condition.

What this means is that once all prerequisites are installed and before the main installation launches, setup checks whether all the launch conditions are met. If not, setup blocks and displays an error message.

Testing NET4 Client Profile applications
VS 2010 itself requires the NET 4 Full in order to run and it therefore install NET 4 Full.
If your target NET4 Client Profile,it is highly recommended that youtest your application on a separate machine that only includes NET4 Client Profile.

Common Questions & Issues with NET4 Client Profile 1. How can I select the .NET Profile in the “New Project” dialog?
When you create new project in VS 2010, the “New Project” dialog does not indicate if the new project you are about to create is targeting Client Profile or Full. You can always go to the project Properties (see above) and change the target if you like.

2.  
I cannot find an assembly in “Add Reference” dialog The “Add Reference” .NET tab dialog only shows the .NET Framework assemblies that are part of the selected profile. So some assemblies, such as System.Web.dll are not included in NET4 Client Profile and will only show if you target the Full framework. If you must use System.Web.dll you need to retarget to the Full framework.
Starting with VS 2010 RTM, the “Add Reference” indicates the target framework that assemblies are filtered against.
3.  
My project cannot compile when I reference a Class Library You may encounter mixed-target scenarios: for example, when your Client Profile app adds a reference to a Class Library that is targeting the Full Framework (which it targets by default). You should be able to successfully build such solutions, as long as the Class Library does not use references to assemblies that only exist in the Full Framework. If it does, you may get warning/errors that are not completely clear.

For example you may see an error in your Client Profile app saying:
“The type or namespace name 'ClassLibrary1' could not be found (are you missing a using directive or an assembly reference?)”

This error is not clear because the class library exists and can be compiled when it is compiled by itself. However, when MSBuild tries to resolve the transitive closure of the Client Profile project, it cannot find the Full Framework assembly that is referenced by the Class Library. In this case it is better to look at the generated warnings which are more informative:
“The referenced assembly " …<your assembly>.." could not be resolved because it has a dependency on ""…<some assembly only available in Full Framework>…” which is not in the currently targeted framework ".NETFramework,Version=v4.0,Profile=Client". Please remove references to assemblies not in the targeted framework or consider retargeting your project.”

4.  
My controls or 3^rd party controls is now showing in the VS 2010 toolbox Some VS 2008 3^rd party Winforms controls will not work with VS 2010 NET4 Client Profile projects.
The reason is that some of these controls have do not have separate design-time and run-time components and have dependencies on assemblies that are in the Full Framework (for example dependency on System.Windows.Forms.Design.dll which is Full).
In VS 2010 RTM we made some changes to make it easier for developers to realize that.

Per the image below you can see that the VS 2008 DevExpress Winforms control are not showing in VS 2010 Toolbox and instead you see the message “Controls in this category are unavailable for the .NET Framework 4 Client Profile. To change this setting, open the Project Properties windows.”
The Xceed VS 2008 controls on the other hand do have separate design-time and run-time components and works fine in VS 2008 and VS 2010.
The good news is that many of the control vendors plan to release update to their control soon after VS 2010 RTM. Until such updates are available you need to retarget your project to NET4 Full if you must use these controls.

 
5.  
What should I do if a component that I need is not in NET4 Client Profile? Your first option is to try to find a workaround by modifying your code to use a component that is included in NET4 Client Profile. If this is not possible retarget your project to NET4 Full. As mentioned before, this is not ideal as most desktops are ikely to only have NET4 Client Profile so your app would need to chain-install NET4 full or block your app setup on NET4 full being present.

6. I want to write a custom WinForms control, what do I need to do for it to work with NET4 Client Profile?
When developing Windows Forms control libraries, it is necessary to separate the runtime code from the control designers in order to target the new Client Profile. If the assembly references classes that exist in the Full framework but not in the Client Profile, the project will not compile successfully. Custom control designers usually inherit from the System.Windows.Forms.Design.ControlDesigner class in System.Design.dll, which is not included in .Net Framework 4 Client Profile.

We posted a guide that can walk you through the steps of creating a Windows Forms control that can be used in the .NET Framework 4 Client Profile. See: https://code.msdn.microsoft.com/WinFormsCustomCtrl
Note that WPF custom controls do not inherit from classes in System.Design.dll and do not have this issue.

7. What’s the deal with <app.config> file ?
If you change the project to target the Full Framework, VS will add a configuration file (<app.config>) that declares the application as a "full" application.

This enables the CLR loader to block any NET4 apps that target full on machines that only have the Client Profile. In this case, the CLR prompts the user to install NET4 full. E.g. you may see this dialog:

 
Note that in NET4 Beta1 and NET3.5 SP1 Client Profile if the <app.config> was missing the CLR the assumption was that you targeted the Full Framework. This is now reversed.
In other words, if your NET4 app is missing <app.config> , by default the CLR assume that your app is targeting NET4 Client Profile! so, your app may crash at random when it needs to load the assemblies that

What components are new in NET4 Client Profile RTM?

This has not significantly changed since Beta2, so read my Beta 2 blog. We did make some tweaks however in RTM (and RC), most notably:

• Developers who need to use System.Web.HttpUtility in their client apps and had to reference System.Web.dll and therefore target NET4 full (System.Web.dll is in Full) , can now target the NET4 Client Profile by using the new System.Net.WebUtility class which is in System.dll (System.dll is in NET4 Client Profile).
  System.Net.WebUtility includes HtmlEncode and HtmlDecode. Url encoding can be accomplished using the System.Uri class (also in System.dll).
• Files moved from Client to Extended (Full):
    - csc.rsp and vbc.rsp
• Files moved from Extended (Full) to Client:
    - System.ComponentModel.DataAnnotations.dll
    - Microsoft.CSharp.Resources.dll and System.Dynamic.Resources.dll
    - InstallUtil.exe, Installutil.exe.config and InstallUtillib.dll

Enhancements in NET4 Client Profile vs. NET 3.5 SP1 Client Profile
This has not changed since Beta2, so read my Beta 2 blog .

What’s in and what’s not included in the Client Profile?
Other than the APIs that were “Grey” out in RTM (and RC) and the tweaks mentioned above, we did not make other significantly changes since Beta2, so read my Beta 2 blog.

Where can I get the NET4 Client Profile?
You can get .NET Framework 4 from here:

• dotNetFx40_Client_x86_x64.exe (41 MB): This is the Client Profile SKU that you must install on any supported 64-bit OS. This will also install on any supported 32-bit OS. Your app could run in WOW64 if it was compiled w/ "32-bit" flag or as 64-bit if you compile with "AnyCPU" or "64-bit" flags.
  If you are redistributing the Client Profile with your application you most likely want to redist this package as it can install on both 32 and 64 bit OS’s.
• dotNetFx40_Client_x86.exe (28.8 MB): This is the Client Profile SKU that you could use to install on any supported 32-bit OS.  Choose this only if all your users are running 32 bit OS. (in most times this will not be your case…)
• dotNetFx40_Full_x86_x64.exe (48.1 MB): This is the Full Framework SKU that you must install on any supported 64-bit OS. This will also install on any supported 32-bit OS.
  If you are redistributing the Full Framework with your application you most likely want to redist this package as it can install on both 32 and 64 bit OS’s.
• dotNetFx40_Full_x86.exe (35.3 MB): This is the Full Framework SKU that you could use to install on any supported 32-bit OS. Choose this only if all your users are running 32 bit OS (in most times this will not be your case…)
• NET 4 RTM Web Bootstrapper: This is what you want to install if you need NET4 Full and you are online. This will detect your OS and processor architecture and will install the appropriate Framework.
• NET 4 Client Profile RTM Web Bootstrapper: This is what you want to install if you need NET4 Client Profile and you are online. This will detect your OS and processor architecture and will install the appropriate Client Profile.

Related Blogs and Resources

• What's New in the .NET Framework 4
• NET Framework 4 Client Profile - Introduction
• What’s new in .NET Framework 4 Client Profile Beta 2.
• How to: Build Windows Forms Custom Control that Supports NetFx 4 Client Profile
• NET Framework 4 Beta 2 on WU

Appendix A:

Here are the files that exist in the NET4 Client Profile and NET4 Full framework.