NCover Pre-Instrumented Coverage Overview
- NCover Desktop/Collector/Code Central must be installed and licensed on the machine.
- NCover windows service must be running at the time of instrumentation.
- NCover windows service must be running at the time of coverage import.
- Instrumented assemblies will only run on machines with a valid NCover license.
- Only .NET applications can be profiled by NCover.
Collecting Coverage with Pre-Instrumentation
- Instrument your application - NCover.exe Instrument
- Execute your application normally - coverage collection completes on program exit
- Import the coverage files to NCover project
Sample Command Line Session
ncover instrument myapp.exe myapp.exe -- stuff happens here specific to your app -- ncover import project=MyApp file=*. ncprof
NCover Instrument < file mask >
This command will modify the assembly in disk. It is used for all assemblies in your application exe or dll. One, several or all assemblies within an application can be instrumented.
ncover instrument *.dll *.exe ncover instrument my_program.exe ncover instrument my_subset_of_files*.dll my_subset*.exe
Instrumentation will invalidate assembly signing, so it may be necessary to resign all the assemblies that are instrumented. An exception to this rule is if the entry .exe file is instrumented, it will not require loaded dlls to be signed. It's good to keep in mind that if a signed assembly will be loading an instrumented assembly, then that instrumented assembly will need to be resigned before execution.
Options: -b, --nobackup Do not make backup of original files. -p, --pdb, --nopdb Do not create matching pdb file after instrumentation. -n, --ns, --nostatic Do not perform static analysis -r, --fr, --forcereload Force overwrite of cached static captures. -s, --fs, --forcesync Send the affected captures to Code Central. -v, --verbose Print detailed status to console.
None of these options need be specified to complete valid instrumentation and collect coverage.
Using some of some of these options could prevent coverage import, or the ability to debug the instrumented assembly.
Integration to Visual Studio
It is possible to using the NCover Instrument command as a post-build step in the project build options. The post-build command would look something like the following example:
c:\program files\NCover Desktop\ncover.exe instrument $(TargetPath)
Data File Naming and Locations
Coverage files are created with .ncprof extension:
MyProcess635354970283932078.ncprof < processname >< ticks >.ncprof
Backups of instrumented assemblies are created with ncover\backup appended to extension:
myprogram.exe => myprogram.exe_ncover_backup
myassembly.dll => myassembly.dll_ncover_backup
Pdbs for instrumented assemblies have the .ncprof.pdb extension.
Coverage file location is determined in priority order by the following options:
Location specified by the NCOVER_COVERAGE_FOLDER environment variable, which controls the coverage file location.
User's "My Document" folder.
User's temp folder Location.
These coverage file locations are attempted by the process at runtime, and may roll to a location further down the list as permissions require.
Windows Store apps have limited access to the local machine. Coverage files are written to a location similar to the following:
Coverage files are created one per process Id, unless multiple app domains are created. When there are multiple app domains, the coverage files will contain the name of the app domain. Examples of app domain coverage files:
myapp3434383483483483483438.ncprof (default app domain) myapp[appdom1]3434383483434334834.ncprof myapp[appdom2]3434383483434354634.ncprof myapp[appdom3]3434383483434364654.ncprof
Importing Pre-Instrumented Coverage
The coverage files created when your application runs will grow in increments of 1Mb. The unused space is reclaimed at the end of execution if your application terminates normally.
If your app doesn't terminate normally, the size of your coverage files will be in equal increments of 1Mb, but they will be valid files and can be imported.
It is important to note that the file extension of .ncprof is the flag to indicate the type of coverage file being imported.
Import does not require that a project already exist. If a project is not found matching the name provided a project will be created to accept the import.
ncover import --project="project name for data" --file="c:\path\to\file\myprocess322342234234234.ncprof"
ncover import --project="project name for data" --file="c:\path\to\file\*.ncprof" Options: --project=< name of project > --file=< file mask for import > --overwrite (force import over existing execution with the same id)
Static Metadata Zip Files
To facilitate the portability of instrumented assemblies, a zipped copy of the assembly metadata required by the NCover import command is embedded as a resource in each instrumented assembly. When the application runs this zip file is extracted to the same location as the .ncprofcoverage files.
This file is used as needed during the import process. The file is essential for imports on a machine that was not the original instrumentation machine. The metadata does not contain source level detail for security purposes.