NCover Pre-Instrumented Coverage Overview

Introduction

Prerequisites:

1. NCover Desktop/Collector/Code Central must be installed and licensed on the machine.
2. NCover windows service must be running at the time of instrumentation.
3. NCover windows service must be running at the time of coverage import.
4. Instrumented assemblies will only run on machines with a valid NCover license.
5. Only .NET applications can be profiled by NCover.

Collecting Coverage with Pre-Instrumentation

1. Instrument your application - NCover.exe Instrument
2. Execute your application normally - coverage collection completes on program exit
3. 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.

Sample Commands:

ncover instrument *.dll *.exe

ncover instrument my_program.exe

ncover instrument my_subset_of_files*.dll my_subset*.exe

Coverage Overview

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.

• Working directory.

• 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:

C:\Users<user>\AppData\Local\Packages<package GUID>AC\Temp

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"

Or simpler:

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.