C# Defining Preprocessor Symbols
In C#, preprocessor symbols can be defined or undefined in code or during compilation. With the use of the #if preprocessor directive, they determine which parts of the code are compiled and which are excluded from the final assemblies.
In a previous article I explained the use of the conditional preprocessor directives that allow you to include or exclude sections of source code from your final, compiled assemblies. The decision of whether code should be compiled or ignored is based upon the preprocessor symbols that are defined. However, I did not describe how those symbols are created and removed. In this article we'll see two methods for defining preprocessor symbols.
If the symbol that you wish to define has localised effects, usually affecting only one file, it is common to create it using the #define preprocessor directive. This directive is followed by the name of the symbol, as shown below. No value is applied.
The #define statement creates a symbol that is valid for a single code file. If you wish to use the same symbol in multiple files you must define it more than once. Symbols are not related to classes or other types, so if you use partial classes and each file for the class refers to a symbol, you must define the symbol in each file or using a project scoped symbol.
NB: The #define statement must appear before all other code in a file, except for other preprocessor directives.
Defining Project-Wide Symbols in Visual Studio
When you want to use the same preprocessor symbol across a larger number of files you can define it for an entire project. When using Visual Studio, this is configured in the project's properties. For Visual Studio 2003, open the project's properties dialog box. Expand the Configuration Properties section and select the Build settings. The dialog box shows a list of defined symbols in the Conditional Compilation Constants box. You can add your own items to the list, separating each with a space.
For Visual Studio 2005, 2008 or 2010, select the Build tab in the project property pages. Add your space-separated list of symbols to the Conditional compilation constants text box. In the example image below, the "MYSYMBOL" symbol is declared for the entire project.
If you prefer to use the command line compiler to build your projects you can define symbols using the /define switch. For example:
csc /define:MYSYMBOL /out:MyAssembly.exe MySource.cs
There may be situations where you define a preprocessor symbol for a project but wish to disable it for a single file. You can do so using the #undef directive. This is used in much the same way as #define. You simply add the directive and the name of the symbol that should be removed at the top of the code file.
There are several standard symbols that are used by Visual Studio. The two most common are present in all versions of the integrated development environment. These are DEBUG and TRACE. The DEBUG symbol is automatically added when building a project in debug mode and removed when in release mode. The TRACE symbol is used when you wish to conditionally add or remove tracing from compiled assemblies.
In Visual Studio 2003, the two symbols can be found in the Conditional Compilation Constants box, where you add your own symbols. For newer versions of Visual studio, the Build tab of the project property pages includes two checkboxes that permit the symbols to be enabled and disabled easily. These can be seen in the above image.
23 July 2011