.NET Framework 4 RTM Application Compatibility Walkthrough
In this walkthrough, you will learn how to test your applications to make sure that they work properly with the .NET Framework version 4.
Tasks illustrated in this walkthrough include:
· How to test the .NET Framework 4 for client applications that use managed code.
· How to test the .NET Framework 4 for COM add-ins.
· How to test the .NET Framework 4 for ASP.NET server-based applications.
· How to test the .NET Framework 4 for ClickOnce applications.
The walkthrough also shows you how to test that applications work when you have an earlier version of the .NET Framework installed along with the .NET Framework version 4—that is, when the two versions are installed side-by-side.
Scenario Test Matrix
The following matrix helps you determine the appropriate scenarios to test for different kinds of applications.
|
|
Client Applications |
COM Add-in |
Server Applications |
ClickOnce |
||||
|
|
SxS |
.NET 4 |
SxS |
.NET 4 |
SxS |
.NET 4 |
SxS |
.NET 4 |
|
Scenarios |
1, 2, 3 |
1, 5 ,6 |
1, 4 |
1, 4 |
1, 7 ,8 |
1, 7 ,8 |
1, 9 |
1, 9 |
** Notes**
· SxS—Multiple versions of the .NET Framework are installed, including the .NET Framework 4.
· .NET 4—Only the .NET Framework 4 is installed on the computer (using Microsoft Windows XP).
Evaluating Results
After each scenario in this walkthrough, you should evaluate whether the tests that are described in the scenario showed the results that you expected. Certain scenarios have specific recommendations about what to do if the test passed or failed. If a scenario does not include an explicit recommendation for how to evaluate the results of the tests, do the following:
· Yes—The scenario ran as expected. In that case, proceed to the next scenario (if that scenario is relevant to your application).
· No—The scenario failed. If this occurs, you should file a bug on the Microsoft Connect Web site (https://connect.microsoft.com/) that describes the scenario you were testing. The bug should include the repro steps that resulted in the error and describe the results you got. If appropriate, you should then proceed to the next scenario.
Testing Client Applications in Side-by-Side Scenarios
This section of the walkthrough shows you how to test a managed-code client application when the .NET Framework 2.0 and 4 are installed side-by-side.
Scenario 1: Testing installation
This test verifies that you can install the application successfully on a computer that has the .NET Framework 2.0 and 4 installed on it.
Note If the application does not require an installation process, proceed to the next scenario.
1. Make sure that the computer you are testing on has the version of the .NET Framework that your application was created to use.
2. If an older version (test version) of the .NET Framework version 4 is installed, uninstall it so that you can install the latest version of the .NET Framework 4.
3. Before you install the .NET Framework 4, verify that the application works as expected without the .NET Framework 4.
4. Uninstall the application.
5. Install the .NET Framework version 4.
6. Install the application.
Evaluating Results
Evaluate the results and proceed as suggested in the following table.
Result |
Next Step |
Yes—The application installed as expected. |
Proceed to the next scenario. |
No—The installation process failed. |
1. Uninstall the .NET Framework 4 from your computer. 2. Install your application on the computer. 3. Reinstall the .NET Framework 4. 4. File a bug on the Microsoft Connect Web site (https://connect.microsoft.com/) that describes the repro steps that resulted in the error. |
Scenario 2: Verifying application behavior
This test verifies that your application functions correctly on a computer that has the .NET Framework 2.0 and 4 installed on it.
1. Run your application on the computer.
2. Explore all possible features to ensure that they are working correctly (covering as much code as possible).
Evaluating Results
For information about how to evaluate results, see Evaluating Results earlier in this document.
Scenario 3: Testing the application configured to run on .NET Framework 4
This test verifies that all applications on the computer can run using the .NET Framework 4.
1. Configure all managed applications on the computer to require the latest version of the .NET Framework. To do so, create or set the following registry key:
"OnlyUseLatestCLR"=dword:00000001
· On 32-bit computers, set the registry key under the following node:
[HKEY_LOCAL_COMPUTER\SOFTWARE\Microsoft\.NETFramework]
· On 64-bit computers that are running 32-bit applications, set the registry key under the following node:
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\.NETFramework]
· On 64-bit computers that are running 64-bit and 32-bit managed applications, set the registry key under both of the following nodes:
[HKEY_LOCAL_COMPUTER\SOFTWARE\Microsoft\.NETFramework]
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\ Microsoft\.NET Framework]
2. Explore all possible features of the application in order to verify that they work correctly using the .NET Framework 4. Some examples might be the following tests:
· Run any automated test suites you have.
· Try any scenarios that might be sensitive to timing or performance.
· Test on multiple operating systems, such as Windows Vista 32-bit and 64-bit, Windows XP, etc.
3. When you are done testing, restore the registry value to the following:
"OnlyUseLatestCLR"=dword:00000000
Note: The registry key OnlyUseLatestCLR is a machine-wide key which should solely be used for testing purposes. Using the registry key OnlyUseLatestCLR can break your apps and should not be used on production servers.
Evaluating Results
For information about how to evaluate results, see Evaluating Results earlier in this document.
Testing COM Add-Ins
This section of the walkthrough shows you how to test whether COM add-ins work properly when the .NET Framework versions 2.0 and 4 are installed side-by-side.
Scenario 4: Testing a COM add-in using the .NET Framework 4
This test works with a COM add-in that was built using the .NET Framework 2.0 and that runs in a .NET Framework 2.0 application. In the test, you configure the add-in to work with the .NET Framework 4.
1. Create an XML file for the add-in that is named *[*program].exe.config. For example, if the add-on is named Example.exe, create a file named Example.exe.config.
2. Copy the configuration file to the folder that contains the .exe file for the add-in.
3. Add the following elements to the file:
<configuration>
<startup useLegacyV2RuntimeActivationPolicy="true" >
<supportedRuntime version="v4.0" />
</startup>
</configuration>
4. Save the file.
5. Start the application and run the add-in.
6. Explore all possible features of your application in order to verify that they work correctly using the .NET Framework 4. Some examples are:
· Run any automated test suites you have.
· Try any scenarios that might be sensitive to timing or performance.
· Test on multiple operating systems, such as Windows Vista 32-bit and 64-bit, Windows XP, etc.
Evaluating Results
For information about how to evaluate results, see Evaluating Results earlier in this document.
Testing Client Applications with Only the .NET Framework 4 Installed on the Computer
This section of the walkthrough shows you how to test a managed-code client application that was created using an earlier version of the .NET Framework to verify that it works with the .NET Framework 4 alone.
Scenario 5: Testing installation
This test verifies that your application installs correctly on a computer that has only the .NET Framework 4 installed on it.
1. Configure a “clean" computer or Virtual PC image that has only the .NET Framework 4 installed.
2. Install the application on that computer. Your application might require that you download the .NET Framework version that the application was built with in order to proceed with the installation.
Evaluating Results
Evaluate the results and proceed as suggested in the following table.
Result |
Next Step |
Yes—The application installs as expected. |
Proceed to the next scenario. |
Yes—The application installs as expected after you install the version of the .NET Framework that is required by the application. |
Proceed to the next scenario. |
No—The application did not install as expected after the .NET Framework 4 was installed. |
File a bug on the Microsoft Connect Web site (https://connect.microsoft.com/) that describes the repro steps that resulted in the error. |
Scenario 6: Verifying application behavior
This test verifies that your application runs correctly on a computer that has only the .NET Framework 4 installed on it.
1. Configure a “clean" computer or Virtual PC image that has only the .NET Framework 4 installed.
2. Install the application on that computer. The application might require that you download the version of the .NET Framework that the application was built for in order to proceed with the installation.
3. Create or set the HKEY_LOCAL_COMPUTER\SOFTWARE\Microsoft\.NETFramework registry key as follows:
"OnlyUseLatestCLR"=dword:00000001
4. Explore all possible features of your application in order to verify that they work correctly using the .NET Framework 4. Some examples might be the following tests:
· Run any automated test suites you have.
· Try any scenarios that might be sensitive to timing or performance.
· Test on multiple operating systems, such as Windows Vista 32-bit and 64-bit, Windows XP, etc.
5. When you are done testing, restore the registry value to the following:
"OnlyUseLatestCLR"=dword:00000000
Note: The registry key OnlyUseLatestCLR is a machine-wide key which should solely be used for testing purposes. Using the registry key OnlyUseLatestCLR can break your apps and should not be used on production servers.
Evaluating Results
For information about how to evaluate results, see Evaluating Results earlier in this document.
Testing Web Applications
This section of the walkthrough shows you how to test an ASP.NET Web application when the .NET Framework 2.0 and 4 are installed side-by-side.
Scenario 7: Running a precompiled Web application using the .NET Framework 4
In this scenario, you test a Web application that was precompiled using an earlier version of the .NET Framework and make sure that it runs on the .NET Framework 4.
1. Precompile a Web site that currently targets version 2.0 or 3.5 of the .NET Framework. You can do this by running the command-line ASP.NET Compilation tool, using the following syntax:
[%WinDir%]\Microsoft.Net\Framework(64)\v2.0.x.x\aspnet_compiler -v /[ApplicationName] [TargetDir]
For example, to compile the Web application named ExampleWebApp and to put the resulting assembly in the C:\Target folder, use the following command:
aspnet_compiler -v /ExampleWebApp c:\Target
2. Copy the precompiled Web site to a computer that has the .NET Framework 4 installed on it.
3. To make sure the .NET Framework 4 is installed and enabled on the target computer, run the following command:
[%WinDir%]\Microsoft.Net\Framework(64)\v4.0.x.x\aspnet_regiis –i –enable
4. Check that the application pools target the .NET Framework 4 Beta2.
The Web site is now configured to run using the .NET Framework 4.
5. Run the Web site and explore all possible features of the application in order to verify that they work correctly using the .NET Framework 4.
Evaluating Results
For information about how to evaluate results, see Evaluating Results earlier in this document.
Scenario 8: Testing Dynamic Compilation Using the .NET Framework 4
This scenario tests for source-code compatibility between earlier versions of the .NET Framework and the .NET Framework version 4.
1. Install a Web site that targets the .NET Framework version 2.0 or version 3.5 on a computer that has the .NET Framework 4 installed on it.
2. To make sure the .NET Framework 4 is installed and enabled on the target computer, run the following command:
[%WinDir%]\Microsoft.Net\Framework(64)\v4.0.x.x\aspnet_regiis –i –enable
3. Check that the application pools target the .NET Framework 4 Beta2.
The Web site is now configured to run using the .NET Framework 4.
4. Run the Web site and explore all possible features of the application in order to verify that they work correctly using the .NET Framework 4.
Evaluating Results
For information about how to evaluate results, see Evaluating Results earlier in this document.
Testing ClickOnce Applications
This section of the walkthrough shows you how to test ClickOnce applications when the .NET Framework 2.0 and 4 are installed side-by-side.
Scenario 9: Configuring a ClickOnce application to be compatible with the .NET Framework 4
1. In the asmv1::assembly element of the application’s configuration file, add a compatibleFrameworks element to the application’s deployment manifest, as shown in the following example:
<compatibleFrameworks xmlns="urn:schemas-microsoft-com:clickonce.v2">
<framework profile="Full" targetVersion="4.0"
supportedRuntime="4.0.0" />
</compatibleFrameworks>
If you want the application to target a client profile of the .NET Framework 4, use the following configuration:
<compatibleFrameworks xmlns="urn:schemas-microsoft-com:clickonce.v2">
<framework profile="Client" targetVersion="4.0"
supportedRuntime="4.0.0" />
</compatibleFrameworks>
2. Update the existing application.config file to contain the following element:
<startup>
<supportedRuntime version="v4.0.0" />
</startup>
3. Update the existing file reference in the application manifest to include the configuration file, as shown in the following example:
<file name="[application file name].exe.config" size="[config file size]">
4. Using the Mage command, update the application manifest in order to update the hashes and then edit as required, using the following syntax:
Mage –update [path to application manifest]
5. Using the Mage command, sign the updated application manifest, using the following syntax:
Mage –Sign [path to application manifest] –CertFile [path to .pfx file]
6. Using the Mage command, update the deployment manifest and then edit as required, using the following syntax:
Mage –update [path to deployment manifest] –AppManifest [path to application manifest]
7. Using the Mage command, sign the updated deployment manifest, using the following syntax:
Mage –Sign [path to deployment manifest] –CertFile [path to .pfx file]
8. Run the application and explore all possible features of the application in order to verify that they work correctly using .NET Framework 4.
Evaluating Results
Evaluate the results and proceed as suggested in the following table.
Result |
Next Step |
Yes—The application runs as expected. |
Proceed to the next test scenario if appropriate. |
No—The application did not run as expected. |
File a bug on the Microsoft Connect Web site (https://connect.microsoft.com/) that describes the repro steps that resulted in the error. |
Testing Serialization
An important area of an application to test is data serialization. When internal data structures change, it can be hard to make sure that data is serialized or persisted in a way that is resilient to those changes. For example, the format might work when data is serialized in an application that is created using the .NET Framework 4 and that is then deserialized in another application (or the same one) created using the .NET Framework 4.However, if the data-serialization format has changed between versions of the .NET Framework, applications might not work properly in all cases. An application written using the .NET Framework 2.0 might not be able to read data that is serialized using the .NET Framework 4, and vice versa. The .NET Framework contains dozens of serialization classes, and application developers and developers of third-party libraries often write their own. Therefore, serialization is an area that’s particularly important to test.
Suggestions for testing serialization using different versions of .NET Framework include the following:
· Try saving data files in your application using the .NET Framework 2.0 and then reading them in your application using the .NET Framework 4.
· Try the opposite direction (save with the .NET Framework 4, read with the .NET Framework 2.0). Users might transfer files from an application on a new computer to an application on an old computer. Therefore, backward-compatibility scenarios are not unlikely. These are particularly hard to get right, because the older version must read data in the new format.
· Think about all the ways that the application can persist data. This includes saving user files, recovering from a crash, modifying configuration files, and so on. Test all scenarios.
Data is also serialized when a client exchanges data with a server. Try these tests:
· If the application can communicate with a server in the cloud, try running with a client that uses the .NET Framework 4 and a server that uses the .NET Framework 2.0. If possible, test the reverse situation as well.
· If the application has any peer-to-peer functionality, try that as well, using mismatched clients.