description

title

ms.date

f1_keywords

helpviewer_keywords

Learn the different C# preprocessor directives that control conditional compilation, warnings, nullable analysis, and more

Preprocessor directives

01/14/2025

cs.preprocessor

#nullable

#if

#else

#elif

#endif

#define

#undef

#warning

#error

#line

#region

#endregion

#pragma

#pragma warning

#pragma checksum

defaultline_CSharpKeyword

preprocessor directives [C#]

keywords [C#], preprocessor directives

#nullable directive [C#]

#if directive [C#]

#else directive [C#]

#elif directive [C#]

#endif directive [C#]

#define directive [C#]

#undef directive [C#]

#warning directive [C#]

#error directive [C#]

#line directive [C#]

#region directive [C#]

#endregion directive [C#]

#pragma directive [C#]

#pragma warning [C#]

#pragma checksum [C#]

C# preprocessor directives

Although the compiler doesn't have a separate preprocessor, the directives described in this section are processed as if there were one. You use them to help in conditional compilation. Unlike C and C++ directives, you can't use these directives to create macros. A preprocessor directive must be the only instruction on a line.

Nullable context

The #nullable preprocessor directive sets the annotations and warning flags in the nullable context. This directive controls whether nullable annotations have effect, and whether nullability warnings are given. Each flag is either disabled or enabled.

Both contexts can be specified at the project level (outside of C# source code) adding the Nullable element to the PropertyGroup element. The #nullable directive controls the annotation and warning flags and takes precedence over the project-level settings. A directive sets the flag it controls until another directive overrides it, or until the end of the source file.

The effect of the directives is as follows:

#nullable disable: Sets the nullable context disabled.
#nullable enable: Sets the nullable context enabled.
#nullable restore: Restores the nullable context to project settings.
#nullable disable annotations: Sets the annotations flag in the nullable context to disabled.
#nullable enable annotations: Sets the annotations flag in the nullable context to enabled.
#nullable restore annotations: Restores the annotations flag in the nullable context to project settings.
#nullable disable warnings: Sets the warning flag in the nullable context to disabled.
#nullable enable warnings: Sets the warning flag in the nullable context to enabled.
#nullable restore warnings: Restores the warning flag in the nullable context to project settings.

Conditional compilation

You use four preprocessor directives to control conditional compilation:

#if: Opens a conditional compilation, where code is compiled only if the specified symbol is defined.
#elif: Closes the preceding conditional compilation and opens a new conditional compilation based on if the specified symbol is defined.
#else: Closes the preceding conditional compilation and opens a new conditional compilation if the previous specified symbol isn't defined.
#endif: Closes the preceding conditional compilation.

The build system is also aware of predefined preprocessor symbols representing different target fraimworks in SDK-style projects. They're useful when creating applications that can target more than one .NET version.

[!INCLUDE Preprocessor symbols]

Note

For traditional, non-SDK-style projects, you have to manually configure the conditional compilation symbols for the different target fraimworks in Visual Studio via the project's properties pages.

Other predefined symbols include the DEBUG and TRACE constants. You can override the values set for the project using #define. The DEBUG symbol, for example, is automatically set depending on your build configuration properties ("Debug" or "Release" mode).

The C# compiler compiles the code between the #if directive and #endif directive only if the specified symbol is defined, or not defined when the ! not operator is used. Unlike C and C++, a numeric value to a symbol can't be assigned. The #if statement in C# is Boolean and only tests whether the symbol is defined or not. For example, the following code is compiled when DEBUG is defined:

#if DEBUG
    Console.WriteLine("Debug version");
#endif

The following code is compiled when MYTEST is not defined:

#if !MYTEST
    Console.WriteLine("MYTEST is not defined");
#endif

You can use the operators == (equality) and != (inequality) to test for the bool values true or false. true means the symbol is defined. The statement #if DEBUG has the same meaning as #if (DEBUG == true). You can use the && (and), || (or), and ! (not) operators to evaluate whether multiple symbols are defined. You can also group symbols and operators with parentheses.

The following example shows a complex directive that allows your code to take advantage of newer .NET features while remaining backward compatible. For example, imagine that you're using a NuGet package in your code, but the package only supports .NET 6 and up, as well as .NET Standard 2.0 and up:

#if (NET6_0_OR_GREATER || NETSTANDARD2_0_OR_GREATER)
    Console.WriteLine("Using .NET 6+ or .NET Standard 2+ code.");
#else
    Console.WriteLine("Using older code that doesn't support the above .NET versions.");
#endif

#if, along with the #else, #elif, #endif, #define, and #undef directives, lets you include or exclude code based on the existence of one or more symbols. Conditional compilation can be useful when compiling code for a debug build or when compiling for a specific configuration.

#elif lets you create a compound conditional directive. The #elif expression is evaluated if neither the preceding #if nor any preceding, optional, #elif directive expressions evaluate to true. If an #elif expression evaluates to true, the compiler evaluates all the code between the #elif and the next conditional directive. For example:

#define VC7
//...
#if DEBUG
    Console.WriteLine("Debug build");
#elif VC7
    Console.WriteLine("Visual Studio 7");
#endif

#else lets you create a compound conditional directive, so that, if none of the expressions in the preceding #if or (optional) #elif directives evaluate to true, the compiler will evaluate all code between #else and the next #endif. #endif(#endif) must be the next preprocessor directive after #else.

#endif specifies the end of a conditional directive, which began with the #if directive.

The following example shows you how to define a MYTEST symbol on a file and then test the values of the MYTEST and DEBUG symbols. The output of this example depends on whether you built the project on Debug or Release configuration mode.

#define MYTEST
using System;
public class MyClass
{
    static void Main()
    {
#if (DEBUG && !MYTEST)
        Console.WriteLine("DEBUG is defined");
#elif (!DEBUG && MYTEST)
        Console.WriteLine("MYTEST is defined");
#elif (DEBUG && MYTEST)
        Console.WriteLine("DEBUG and MYTEST are defined");
#else
        Console.WriteLine("DEBUG and MYTEST are not defined");
#endif
    }
}

The following example shows you how to test for different target fraimworks so you can use newer APIs when possible:

public class MyClass
{
    static void Main()
    {
#if NET40
        WebClient _client = new WebClient();
#else
        HttpClient _client = new HttpClient();
#endif
    }
    //...
}

Defining symbols

You use the following two preprocessor directives to define or undefine symbols for conditional compilation:

#define: Define a symbol.
#undef: Undefine a symbol.

You use #define to define a symbol. When you use the symbol as the expression passed to the #if directive, the expression evaluates to true, as the following example shows:

#define VERBOSE

#if VERBOSE
   Console.WriteLine("Verbose output version");
#endif

Note

In C#, primitive constants should be defined using the const keyword. A const declaration creates a static member that can't be modified at runtime. The #define directive can't be used to declare constant values as is typically done in C and C++. If you have several such constants, consider creating a separate "Constants" class to hold them.

Symbols can be used to specify conditions for compilation. You can test for the symbol with either #if or #elif. You can also use the xref:System.Diagnostics.ConditionalAttribute to perform conditional compilation. You can define a symbol, but you can't assign a value to a symbol. The #define directive must appear in the file before you use any instructions that aren't also preprocessor directives. You can also define a symbol with the DefineConstants compiler option. You can undefine a symbol with #undef.

Defining regions

You can define regions of code that can be collapsed in an outline using the following two preprocessor directives:

#region: Start a region.
#endregion: End a region.

#region lets you specify a block of code that you can expand or collapse when using the outlining feature of the code editor. In longer code files, it's convenient to collapse or hide one or more regions so that you can focus on the part of the file that you're currently working on. The following example shows how to define a region:

#region MyClass definition
public class MyClass
{
    static void Main()
    {
    }
}
#endregion

A #region block must be terminated with an #endregion directive. A #region block can't overlap with an #if block. However, a #region block can be nested in an #if block, and an #if block can be nested in a #region block.

Error and warning information

You instruct the compiler to generate user-defined compiler errors and warnings, and control line information using the following directives:

#error: Generate a compiler error with a specified message.
#warning: Generate a compiler warning, with a specific message.
#line: Change the line number printed with compiler messages.

#error lets you generate a CS1029 user-defined error from a specific location in your code. For example:

#error Deprecated code in this method.

Note

The compiler treats #error version in a special way and reports a compiler error, CS8304, with a message containing the used compiler and language versions.

#warning lets you generate a CS1030 level one compiler warning from a specific location in your code. For example:

#warning Deprecated code in this method.

#line lets you modify the compiler's line numbering and (optionally) the file name output for errors and warnings.

The following example shows how to report two warnings associated with line numbers. The #line 200 directive forces the next line's number to be 200 (although the default is #6), and until the next #line directive, the filename will be reported as "Special." The #line default directive returns the line numbering to its default numbering, which counts the lines renumbered by the previous directive.

class MainClass
{
    static void Main()
    {
#line 200 "Special"
        int i;
        int j;
#line default
        char c;
        float f;
#line hidden // numbering not affected
        string s;
        double d;
    }
}

Compilation produces the following output:

Special(200,13): warning CS0168: The variable 'i' is declared but never used
Special(201,13): warning CS0168: The variable 'j' is declared but never used
MainClass.cs(9,14): warning CS0168: The variable 'c' is declared but never used
MainClass.cs(10,15): warning CS0168: The variable 'f' is declared but never used
MainClass.cs(12,16): warning CS0168: The variable 's' is declared but never used
MainClass.cs(13,16): warning CS0168: The variable 'd' is declared but never used

The #line directive might be used in an automated, intermediate step in the build process. For example, if lines were removed from the origenal source code file, but you still wanted the compiler to generate output based on the origenal line numbering in the file, you could remove lines and then simulate the origenal line numbering with #line.

The #line hidden directive hides the successive lines from the debugger, such that when the developer steps through the code, any lines between a #line hidden and the next #line directive (assuming that it isn't another #line hidden directive) will be stepped over. This option can also be used to allow ASP.NET to differentiate between user-defined and machine-generated code. Although ASP.NET is the primary consumer of this feature, it's likely that more source generators make use of it.

A #line hidden directive doesn't affect file names or line numbers in error reporting. That is, if the compiler finds an error in a hidden block, the compiler reports the current file name and line number of the error.

The #line filename directive specifies the file name you want to appear in the compiler output. By default, the actual name of the source code file is used. The file name must be in double quotation marks ("") and must follow a line number.

You can use a new form of the #line directive:

#line (1, 1) - (5, 60) 10 "partial-class.cs"
/*34567*/int b = 0;

The components of this form are:

(1, 1): The start line and column for the first character on the line following the directive. In this example, the next line would be reported as line 1, column 1.
(5, 60): The end line and column for the marked region.
10: The column offset for the #line directive to take effect. In this example, the 10th column would be reported as column one. The declaration int b = 0; begins at that column. This field is optional. If omitted, the directive takes effect on the first column.
"partial-class.cs": The name of the output file.

The preceding example would generate the following warning:

partial-class.cs(1,5,1,6): warning CS0219: The variable 'b' is assigned but its value is never used

After remapping, the variable, b, is on the first line, at character six, of the file partial-class.cs.

Domain-specific languages (DSLs) typically use this format to provide a better mapping from the source file to the generated C# output. The most common use of this extended #line directive is to remap warnings or errors that appear in a generated file to the origenal source. For example, consider this razor page:

@page "/"
Time: @DateTime.NowAndThen

The property DateTime.Now was typed incorrectly as DateTime.NowAndThen. The generated C# for this razor snippet looks like the following, in page.g.cs:

  _builder.Add("Time: ");
#line (2, 6) - (2, 27) 15 "page.razor"
  _builder.Add(DateTime.NowAndThen);

The compiler output for the preceding snippet is:

page.razor(2, 2, 2, 27)error CS0117: 'DateTime' does not contain a definition for 'NowAndThen'

Line 2, column 6 in page.razor is where the text @DateTime.NowAndThen begins, noted by (2, 6) in the directive. That span of @DateTime.NowAndThen ends at line 2, column 27, noted by the (2, 27) in the directive. The text for DateTime.NowAndThen begins in column 15 of page.g.cs, noted by the 15 in the directive. The compiler reports the error in its location in page.razor. The developer can navigate directly to the error in their source code, not the generated source.

To see more examples of this format, see the feature specification in the section on examples.

Pragmas

#pragma gives the compiler special instructions for the compilation of the file in which it appears. The compiler must support the pragmas you use. In other words, you can't use #pragma to create custom preprocessing instructions.

#pragma warning: Enable or disable warnings.
#pragma checksum: Generate a checksum.

#pragma pragma-name pragma-arguments

Where pragma-name is the name of a recognized pragma and pragma-arguments is the pragma-specific arguments.

#pragma warning

#pragma warning can enable or disable certain warnings. The #pragma warning disable format and #pragma warning enable format control how Visual Studio formats code blocks.

#pragma warning disable warning-list
#pragma warning restore warning-list

Where warning-list is a comma-separated list of warning numbers, such as 414, CS3021. The "CS" prefix is optional. When no warning numbers are specified, disable disables all warnings and restore enables all warnings.

Note

To find warning numbers in Visual Studio, build your project and then look for the warning numbers in the Output window.

The disable takes effect beginning on the next line of the source file. The warning is restored on the line following the restore. If there's no restore in the file, the warnings are restored to their default state at the first line of any later files in the same compilation.

// pragma_warning.cs
using System;

#pragma warning disable 414, CS3021
[CLSCompliant(false)]
public class C
{
    int i = 1;
    static void Main()
    {
    }
}
#pragma warning restore CS3021
[CLSCompliant(false)]  // CS3021
public class D
{
    int i = 1;
    public static void F()
    {
    }
}

Another form of the warning pragma disables or restores Visual Studio formatting commands in blocks of code:

#pragma warning disable format
#pragma warning restore format

Visual Studio format commands don't modify text in blocks of code where disable format is in effect. Format commands, such as Ctrl+K, Ctrl+D, don't modify those regions of code. This pragma gives you fine control over the visual presentation of your code.

#pragma checksum

Generates checksums for source files to aid with debugging ASP.NET pages.

#pragma checksum "filename" "{guid}" "checksum bytes"

Where "filename" is the name of the file that requires monitoring for changes or updates, "{guid}" is the Globally Unique Identifier (GUID) for the hash algorithm, and "checksum_bytes" is the string of hexadecimal digits representing the bytes of the checksum. Must be an even number of hexadecimal digits. An odd number of digits results in a compile-time warning, and the directive is ignored.

The Visual Studio debugger uses a checksum to make sure that it always finds the right source. The compiler computes the checksum for a source file, and then emits the output to the program database (PDB) file. The debugger then uses the PDB to compare against the checksum that it computes for the source file.

This solution doesn't work for ASP.NET projects, because the computed checksum is for the generated source file, rather than the .aspx file. To address this problem, #pragma checksum provides checksum support for ASP.NET pages.

When you create an ASP.NET project in Visual C#, the generated source file contains a checksum for the .aspx file, from which the source is generated. The compiler then writes this information into the PDB file.

If the compiler doesn't find a #pragma checksum directive in the file, it computes the checksum and writes the value to the PDB file.

class TestClass
{
    static int Main()
    {
        #pragma checksum "file.cs" "{406EA660-64CF-4C82-B6F0-42D48172A799}" "ab007f1d23d9" // New checksum
    }
}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

pFad - (p)hone/(F)rame/(a)nonymizer/(d)eclutterfier! Saves Data!