Choosing the Instrumentation Folder
If you need to gather code coverage data while testing code in a binary, Visual Studio must first instrument that binary. The instrumentation process adds code to the binary that generates code coverage data. For more information about instrumenting binaries for code coverage, see How to: Obtain Code Coverage Data.
You have some control over the instrumentation process, namely where instrumentation is carried out. Visual Studio can instrument binaries in one of two ways:
In place. If you choose in-place instrumentation, Visual Studio instruments the binary in the folder where the binary resides before you run the test. If the binary is part of an application that you are creating, this is the folder where Visual Studio built the binary.
In the deployment folder. If you do not choose in-place instrumentation, Visual Studio instruments the binary in the deployment folder. Deployment folders are created specifically for test runs. For more information about the deployment process, see Test Deployment Overview.
To decide which folder to use, see Determining the Instrumentation Folder. Then, for information about setting the folder, see Specifying the Instrumentation Folder.
Determining the Instrumentation Folder
How do you determine the best folder in which to instrument the binary? Choosing between in place and in the deployment folder depends on the level of access you have to the binary and on the type of the binary.
Binaries with limited availability. Any binary in one or more of the following states is referred to in the following table as a binary with limited availability:
The binary is shared among multiple people. The problem with shared binaries is the possibility of conflict because of simultaneous usage by multiple users. An example would be if two users start test runs and also request code coverage data from the same binary at the same time.
The binary is on a network share, not on your local computer.
You have read-only access to the binary.
Binaries with a fixed load location. The test execution engine can load certain binaries only from a specific location. Such a binary is referred to in the following table as a binary with a fixed load location. These include the following types of files:
COM components
Control Panel pages
The following table provides guidance for choosing the correct instrumentation folder. See the Additional notes column for cases that have special factors to consider.
Load location of binary |
Binary availability |
Instrument in this folder |
Additional notes |
fixed |
not limited |
in place |
(none) |
not fixed |
limited |
in the deployment folder |
(none) |
not fixed |
not limited |
Both folders work, but it is recommended that you choose 'in the deployment folder'. |
If, after choosing in-place instrumentation, you re-build an instrumented binary during the test run, the test engine detects that the re-built binary is newer, does not restore its pre-instrumented version, and generates a run-level warning. |
fixed |
limited |
in place, but see Additional notes |
If you do not choose in-place instrumentation, any binary in a fixed location is not instrumented. This means that, although test execution succeeds and no run-level warning is generated, code-coverage data is not collected. For workaround suggestions, see Fixed-Location, Limited Availability Binaries. |
Specifying the Instrumentation Folder
You can choose between instrumenting in place and in the deployment folder in two ways:
To make your choice the default setting, go to the Options dialog box on the Tools menu of Visual Studio. To find this setting, look on the Test Execution page under the Test Tools node.
You can also specify the instrumentation folder for a particular test run configuration. On the Code Coverage page in the test run configuration editor, you can check Instrument assemblies in place. For more information, see How to: Specify a Test Run Configuration.
Fixed-Location, Limited Availability Binaries
The test engine must be capable of modifying the binary that is to be instrumented in-place. To make this possible, review the following criteria:
The binary file must not have the read-only attribute set. You can correct this setting if you have sufficient permissions on the file.
The test engine must have permissions to instrument the binary file. This means that the user who runs the test should have the required privileges to modify the binaries. Because instrumentation is performed by the host application, the account that needs those privileges is the account under which devenv.exe or MSTest.exe is being executed, regardless of local or remote execution. This account belongs to the person who is running Visual Studio, who has executed the MSTest.exe command, or who has started a build which, in turn, is running tests.
The binary file must not be in use or locked by another program. To correct this, you must either end the locking program or wait until it finishes.
If the test engine still cannot instrument one or more binaries, it generates a run-level warning.
See Also
Tasks
How to: Specify a Test Run Configuration
How to: Configure Test Deployment
Concepts
Instrumenting and Re-Signing Assemblies