V3 Documentation

Advanced Configuration

Simple/Complex Configuration Modes

The release of NCrunch version 3 saw the introduction of a new configuration system. The new configuration system gives you much more control over how NCrunch uses its settings. Unfortunately, this power comes at the cost of additional complexity. Because this complexity is likely to be confusing for new users of NCrunch when they are learning the product, the configuration system defaults to a 'Simple mode' under which its behaviour is similar to that of previous versions of NCrunch.

'Simple mode' can be deactivated with the checkbox at the top of the NCrunch Configuration Window.

Complex Configuration Mode

When 'Simple mode' has been deactivated, the Configuration Window will give you more options to control how settings are applied by the engine.

My Settings/Shared Settings

Under 'Complex mode', settings can be stored either locally (for just yourself) or shared (for your whole team). In the Configuration Window, this is represented by the two different solution nodes in the tree.

Settings applied for your team will be stored in the SolutionName.v3.ncrunchsolution and ProjectName.v3.ncrunchproject files.

Settings applied locally will be stored in the SolutionName.v3.ncrunchsolution.user and ProjectName.v3.ncrunchproject.user files.


Under 'Complex mode', settings can be applied at higher levels in the configuration tree than they otherwise would be. Settings targeted towards projects in your solution can be applied at a solution or global level. Likewise, most settings that normally target solutions can also be applied at a global level. When a setting is applied at a higher level, it will be inherited by all objects below it unless it has been specifically declared on these objects.

For example, you may have a solution that makes extensive use of pre-build events that are necessary for the building of each of its projects. Because NCrunch disables pre-build events by default, you would normally need to solve this by turning on the Run pre-build events configuration setting for every project in the solution. Instead, you can now switch this setting on for the entire solution without needing to touch the projects. Because none of the projects specifically declare their own value for this setting, they will inherit it from the solution. If a specific project in the solution is different and needs the setting disabled, this can be done on the project itself and the project-level setting will override the one applied at solution-level.

Inheritance is also applied between the local and shared settings. Any setting applied locally will automatically override a shared setting. This allows you to easily have different configuration settings from your team without needing to micro-manage them during VCS merges.

The inheritance system also takes consideration of the current engine mode and any values injected into the NCrunch console tool, as these are both mechanisms through which settings can be overridden outside of the options in the Configuration Window.

The full inheritance hierarchy is shown below. Settings applied to objects at the top of the list will be inherited by objects further down. Settings applied further down the list will override any settings applied above them.

Default valuesControlled by the system
Global settingsSet using the 'General Settings' node in the Configuration Window
Shared solution settingsSet using the shared solution settings node in the Configuration Window
My solution settingsSet using the my solution settings node in the Configuration Window
Engine mode overridesSettings that have been overridden by the current engine mode
Console tool injected settingsApplied by command-line into the NCrunch console tool. Not applicable to the VS Plugin.
Shared project settingsSet using the shared project settings nodes in the Configuration Window
My project settingsSet using the my project settings nodes in the Configuration Window

Understanding Effective Settings

To help with determining the currently applicable value for any setting and where it is being declared, the Configuration Window has two extra columns describing this:

'Effective Value' - Provides the current value of the setting as it is being used by the engine.

'Effective Value Source' - Details where the currently effective setting has been declared.

Simple Mode Compatibility

When settings have been applied using 'Complex mode' in a manner that cannot be represented in 'Simple mode', the option to re-enable 'Simple mode' will be disabled.