Covering IIS
NCover Desktop runs as a service, so it's already monitoring, ready to cover any .NET code executing on your machine.
This ability to gather data globally is key to understanding how to leverage the power of NCover. When setting up any project the first question you should ask is, What process do I want to cover? If NCover can find the executable or service that's exercising your code, it can collect coverage data.
If you want to cover your web application or service, NCover can capture .NET Framework activity by profiling the host process, which is usually IIS, though NCover can profile also IIS Express, the VS dev server, etc.
Resetting IIS
When covering IIS, it's very important to perform an iisreset before starting your web application testing. Unless IIS is reset, the NCover profiler can't attach to the w3wp process.
When your testing is complete, perform iisreset again to stop profiling and finalize your coverage.
Creating a Project
From the Home view of NCover, click Add New to open the "Create a New Project" window.
Match Rules
When the "Processes" tab displays, name your project and then select one of two methods to specify the processes to be covered.
Note: If you're setting up coverage for a process running locally on the machine where Desktop is installed, you can let Auto-Configure create project settings for you (see step 3 below).
You can also set up match rules manually, if you prefer.
The two match type options are Regex and Exe.
A regex is a good way to catch the worker process whenever it runs locally. For example, "w3wp".
You can use the Exe option to make sure that an executable is only profiled when this particular exe runs from this specific location -- from a debug folder, instead of a release folder, for example -- by using the full path to the executable.
Auto-Configure
Another option is to click on the Auto-Configure button and let NCover create match rules for you.
The Processes tab will switch to the Auto-Detection view and start monitoring for .NET processes as soon as you click on Auto-Configure.
Note: Reset IIS so that the NCover profiler can attach to the w3wp process.
Start your web application, and the executables and assemblies that are being loaded will display in the detection window.
Note: All modules are automatically included when the default "No filter" option is selected.
Switch the Pre-Coverage filter radio button to "Create filter" to review the "Modules to cover" and decide whether to include or exclude modules from the list.
Click the checkbox beside each module once to mark with an X to exclude the module. Click twice to mark with a check to include the module.
Note: You can specifically exclude modules by placing an X beside them on this screen, but any modules that are not specifically included will not be profiled, anyway. In other words, not creating an include is functionally the same as creating an exclude rule.
The selections shown above create the filter rules seen below when you click on the Filters tab.
Click on the "Processes" tab to see what match rules have been created.
Auto-configure has created an Exe match rule, which tells the NCover profiler to match on the executable name.
Click Re-detect processes, if necessary, to re-capture your processes/assemblies.
Collecting Coverage
When your project selections are complete, start or re-start IIS and run your manual or automated tests.
Go to the Home page and you'll see that the light beside your enabled project is pulsing green to indicate coverage is being collected.
Immediately to the right of your project name, the Modules Collecting counter displays the number of modules being profiled in the current execution of your project. The number will fluctuate while coverage is running, but the counter should eventually disappear when profiling is complete.
When your tests are complete, don't forget to stop or reset IIS to end profiling and allow NCover Desktop to collect coverage data.
As soon as processing is complete, the results will be automatically displayed below your project on the Home page.
Desktop makes the process of collecting code coverage simple, and then gives you access to dynamic and powerful views of coverage trends.
Troubleshooting
Symbol Path
When initial profiling of IIS isn't successful, we recommend using a symbol path, to help ensure NCover can find your PDB files.
If you'd like to try this:
- From the desktop, right-click on My Computer, and then click Properties.
- Click Advanced system settings, and on the Advanced tab, click Environment Variables.
- If it doesn't already exist, add the Variable name _NT_SYMBOL_PATH.
- Set the Variable value to "c:\symbols" -- where "c:\symbols" is any local directory on the hard drive -- and place the PDBs in that location.
Loading PDBs
Please note that NCover doesn't directly load PDB files. It uses the Windows debugging API through the CLR to load the PDBs.
The CLR has a loading preference for finding the appropriate file. The first place it looks is in the same directory as the dll. If the PDB can't be found there, then the CLR checks the symbol path, which you have set.
The PDBs and DLLs have an embedded identifier generated by the compiler that prevents a PDB from being used with a DLL different from the original one that was compiled to produce it, even if the DLL/code did not change at all between compiles.
Shadow Copy
Sometimes a lack of sequence point coverage is caused by IIS shadow copy. This process, which IIS does by default, creates temp files at run-time that NCover cannot find.
The dev team has these recommendations:
- Turn off IIS shadow copy, as described in this post: http://www.ipreferjim.com/2012/04/asp-net-appdomains-and-shadow-copying/
SymChk
- Use SymChk before running coverage, to verify that the MS debugger (which is what NCover 3 uses to find the PDBs) can find the symbol files as expected: http://msdn.microsoft.com/en-us/library/windows/hardware/ff560157%28v=vs.85%29.aspx