C# 预处理器指令

2025-07-14

尽管编译器没有单独的预处理器，但本节中所述指令的处理方式与有预处理器时一样。可使用这些指令来帮助条件编译。不同于 C 和 C++ 指令，不能使用这些指令来创建宏。预处理器指令必须是一行中唯一的说明。

基于文件的程序

基于文件的程序 是使用 dotnet run Program.cs （或任何 *.cs 文件）编译和运行的程序。 C# 编译器忽略这些预处理器指令，但生成系统对其进行分析以生成输出。在基于项目的编译中遇到这些指令时，这些指令将生成警告。

C# 编译器忽略以 #: 或 #!. 开头的任何预处理器指令。

#!预处理器指令使 Unix shell 能够直接执行一个 C# 文件，使用 dotnet run. 例如：

#!/usr/local/share/dotnet/dotnet run
Console.WriteLine("Hello");

前面的代码片段通知 Unix shell 使用 /usr/local/share/dotnet/dotnet run 来执行文件。在不同的 Unix 或 macOS 发行版上，dotnet CLI 的安装目录可能会有所不同。该 #! 行必须是文件中的第一行，以下标记是要运行的程序。需要为该功能启用对 C# 文件的执行（x）权限。

#:在基于文件的程序中使用的指令包括：

#:sdk:

第一个实例指定节点的值 <Project Sdk="value" /> 。后续实例指定 <Sdk Name="value" Version="version" /> 节点。版本可以会被省略。例如：
```
#:sdk Microsoft.NET.Sdk.Web
```
#:property:

#:property 实例被翻译为 <PropertyGroup> 中的属性元素。形式为 Name=value 的令牌必须跟随 property 令牌。以下示例指令是有效的 property 令牌：
```
#:property TargetFramework=net11.0
#:property LangVersion=preview
```
将上述两个属性转换为：
```
<TargetFramework>net11.0</TargetFramework>
<LangVersion>preview</LangVersion>
```
#:package:

实例 #:package 转换为 PackageReference 元素，以将具有指定版本的 NuGet 包包含在文件中。例如：
```
#:package [email protected]*
```
上述预处理器令牌将转换为：
```
<PackageReference Include="System.CommandLine" Version="2.0.0-*">
```

工具可以按照 #: 约定添加新令牌。

可为空上下文

设置 #nullable 预处理器指令注释和警告中的标记 可空上下文. 此指令控制是否可为空注释是否有效，以及是否给出为 Null 性警告。每个标志要么禁用，要么启用。

通过将 Nullable 元素添加到 PropertyGroup 元素中，可在项目级别（C# 源代码之外）指定这两个上下文。 #nullable 指令控制批注和警告标志，并优先于项目级设置。一条指令会设置它所控制的标志，直到另一条指令覆盖它，或直到源文件结束。

指令的效果如下所示：

#nullable disable: 设置可空上下文禁用.
#nullable enable: 设置可空上下文启用.
#nullable restore: 将可空上下文恢复为项目设置。
#nullable disable annotations: 将 nullable 上下文中的注释标志设置为残.
#nullable enable annotations: 将 nullable 上下文中的注释标志设置为启用.
#nullable restore annotations: 将可空上下文中的注释标志恢复为项目设置。
#nullable disable warnings: 将可空上下文中的警告标志设置为残.
#nullable enable warnings: 将可空上下文中的警告标志设置为启用.
#nullable restore warnings: 将可空上下文中的警告标志恢复为项目设置。

条件编译

使用四个预处理器指令来控制条件编译：

#if：打开条件编译，其中仅在定义了指定的符号时才会编译代码。
#elif：关闭前面的条件编译，并基于是否定义了指定的符号打开一个新的条件编译。
#else：关闭前面的条件编译，如果没有定义前面指定的符号，打开一个新的条件编译。
#endif：关闭前面的条件编译。

此外，生成系统还会感知表示 SDK 样式项目中不同目标框架的预定义预处理器符号。在创建可以面向多个 .NET 版本的应用程序时，这些符号会很有用。

目标框架	符号	其他符号（在 .NET 5+ SDK 中可用）	平台符号（仅在指定特定于 OS 的 TFM 时可用）
.NET Framework	`NETFRAMEWORK`、`NET481`、`NET48`、`NET472`、`NET471`、`NET47`、`NET462`、`NET461`、`NET46`、`NET452`、`NET451`、`NET45`、`NET40`、`NET35`、`NET20`	`NET48_OR_GREATER`、`NET472_OR_GREATER`、`NET471_OR_GREATER`、`NET47_OR_GREATER`、`NET462_OR_GREATER`、`NET461_OR_GREATER`、`NET46_OR_GREATER`、`NET452_OR_GREATER`、`NET451_OR_GREATER`、`NET45_OR_GREATER`、`NET40_OR_GREATER`、`NET35_OR_GREATER`、`NET20_OR_GREATER`
.NET Standard	`NETSTANDARD`、`NETSTANDARD2_1`、`NETSTANDARD2_0`、`NETSTANDARD1_6`、`NETSTANDARD1_5`、`NETSTANDARD1_4`、`NETSTANDARD1_3`、`NETSTANDARD1_2`、`NETSTANDARD1_1`、`NETSTANDARD1_0`	`NETSTANDARD2_1_OR_GREATER`、`NETSTANDARD2_0_OR_GREATER`、`NETSTANDARD1_6_OR_GREATER`、`NETSTANDARD1_5_OR_GREATER`、`NETSTANDARD1_4_OR_GREATER`、`NETSTANDARD1_3_OR_GREATER`、`NETSTANDARD1_2_OR_GREATER`、`NETSTANDARD1_1_OR_GREATER`、`NETSTANDARD1_0_OR_GREATER`
.NET 5 及更高版本（和 .NET Core）	`NET`、`NET9_0`、`NET8_0`、`NET7_0`、`NET6_0`、`NET5_0`、`NETCOREAPP`、`NETCOREAPP3_1`、`NETCOREAPP3_0`、`NETCOREAPP2_2`、`NETCOREAPP2_1`、`NETCOREAPP2_0`、`NETCOREAPP1_1`、`NETCOREAPP1_0`	`NET9_0_OR_GREATER`、、`NET8_0_OR_GREATER`、`NET6_0_OR_GREATERNET7_0_OR_GREATER`、`NET5_0_OR_GREATER`、`NETCOREAPP3_1_OR_GREATERNETCOREAPP3_0_OR_GREATERNETCOREAPP2_1_OR_GREATERNETCOREAPP2_2_OR_GREATER`、`NETCOREAPP2_0_OR_GREATER`、、 `NETCOREAPP1_1_OR_GREATERNETCOREAPP1_0_OR_GREATER`	`ANDROID`、、`BROWSERIOS`、`MACCATALYST`、`MACOS`、`TVOS`、、 `WINDOWS` `[OS][version]`（例如 `IOS15_1`）， `[OS][version]_OR_GREATER`（例如 `IOS15_1_OR_GREATER`）

注意

无论目标版本是什么，都将定义无版本符号。
仅针对目标版本定义特定于版本的符号。
为目标版本和所有早期版本定义 <framework>_OR_GREATER 符号。例如，如果针对 .NET Framework 2.0，则会定义以下符号：NET20、NET20_OR_GREATER、NET11_OR_GREATER 和 NET10_OR_GREATER。
NETSTANDARD<x>_<y>_OR_GREATER 符号仅针对 .NET Standard 目标定义，而不适用于实现 .NET Standard 的目标，例如 .NET Core 和 .NET Framework。
它们与 MSBuild TargetFramework 属性和 NuGet 使用的目标框架名字对象 (TFM) 不同。

注意

对于传统的非 SDK 样式的项目，必须通过项目的属性页面在 Visual Studio 中为不同目标框架手动配置条件编译符号。

其他预定义符号包括 DEBUG 和 TRACE 常数。你可以使用 #define 替代项目的值集。例如，会根据生成配置属性（“调试”或者“发布”模式）自动设置 DEBUG 符号。

仅在定义指定的符号时或者在使用 ! not 运算符时未定义指定的符号时，C# 编译器才编译 #if 指令和 #endif 指令之间的代码。与 C 和 C++ 不同，不能将数字值分配给符号。 C# 中的 #if 语句为布尔值，仅测试是否定义符号。例如，定义 DEBUG 时将编译以下代码：

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

未定义 MYTEST 时，将编译以下代码：

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

可以使用运算符 ==（相等）和!= （不相等）来测试 bool 值是 true 还是 false。 true 表示定义该符号。语句 #if DEBUG 具有与 #if (DEBUG == true) 相同的含义。可以使用 &&（和）、||（或），以及 !（不是）运算符来评估是否定义了多个符号。还可以用括号对符号和运算符进行分组。

以下示例演示了一个复杂指令，该指令允许代码利用较新的 .NET 功能，同时保持向后兼容。例如，假设你在代码中使用 NuGet 包，但该包仅支持 .NET 6（及更高版本）和 .NET Standard 2.0（及更高版本）：

#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 以及 #else、#elif、#endif、#define 和 #undef 指令，允许基于是否存在一个或多个符号包括或排除代码。条件编译在编译调试版本的代码或编译特定配置的代码时会很有用。

#elif 可以创建复合条件指令。表达式 #elif 如果前面的 #if 或前面的任何内容，均为可选项、 #elif 指令表达式的值为 true. 如果 #elif 表达式计算结果为 true，编译器将计算 #elif 和下一条件指令间的所有代码。例如：

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

#else 允许创建复合条件指令，因此，如果先前 #if 或（可选）#elif 指令中的任何表达式的计算结果都不是 true，则编译器将对介于 #else 和下一个 #endif 之间的所有代码进行求值。 #endif(#endif) 必须是 #else 之后的下一个预处理器指令。

#endif 指定条件指令的末尾，以 #if 指令开头。

下例显示如何在文件上定义 MYTEST 符号，然后测试 MYTEST 和 DEBUG 符号的值。此示例的输出取决于是在“调试”还是“发布”配置模式下生成项目。

#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
    }
}

下例显示如何针对不同的目标框架进行测试，以便在可能时使用较新的 API：

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

定义符号

使用以下两个预处理器指令来定义或取消定义条件编译的符号：

#define：定义符号。
#undef：取消定义符号。

使用 #define 来定义符号。使用符号作为传递给 #if 指令的表达式时，表达式的计算结果为 true，如以下示例所示：

#define VERBOSE

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

注意

在 C# 中，应使用 const 关键字定义基元常量。 const 声明会创建一个在运行时无法修改的 static 成员。 #define 指令不能用于声明常量值，这与 C 和 C++ 中的通常做法一样。如果具有多个此类常量，请考虑创建一个单独的“常量”类来容纳它们。

符号可用于指定编译的条件。可通过 #if 或 #elif 测试符号。还可以使用 ConditionalAttribute 来执行条件编译。可以定义符号，但不能为符号分配值。文件中必须先出现 #define 指令，才能使用并非同时也是预处理器指令的任何指示。还可以通过 DefineConstants 编译器选项来定义符号。可以通过 #undef 取消定义符号。

定义区域

可以使用以下两个预处理器指令来定义可在大纲中折叠的代码区域：

#region：开始区域。
#endregion：结束区域。

利用 #region，可以指定在使用代码编辑器的大纲功能时可展开或折叠的代码块。在较长的代码文件中，折叠或隐藏一个或多个区域十分便利，这样，可将精力集中于当前处理的文件部分。下面的示例演示如何定义区域：

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

#region 块必须通过 #endregion 指令终止。 #region 块不能与 #if 块重叠。但是，可以将 #region 块嵌套在 #if 块内，或将 #if 块嵌套在 #region 块内。

错误和警告信息

使用以下指令指示编译器生成用户定义的编译器错误和警告，并控制行信息：

#error：使用指定的消息生成编译器错误。
#warning：使用指定的消息生成编译器警告。
#line：更改用编译器消息输出的行号。

#error 可从代码中的特定位置生成 CS1029 用户定义的错误。例如：

#error Deprecated code in this method.

注意

编译器以特殊的方式处理 #error version 并报告编译器错误 CS8304，消息中包含使用的编译器和语言版本。

#warning 允许你从代码中的特定位置生成 CS1030 第一级编译器警告。例如：

#warning Deprecated code in this method.

借助 #line，可修改编译器的行号及（可选）用于错误和警告的文件名输出。

以下示例演示如何报告与行号相关联的两个警告。 #line 200 指令强制下一行的数字为 200（尽管默认值为 #6），直到下一个 #line 指令，文件名将报告为“特殊”。#line default 指令将行号返回为其默认编号，这将计算上一指令重新编号的行数。

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;
    }
}

编译产生以下输出：

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

可在生成过程的自动、中间步骤中使用 #line 指令。例如，如果已从原始源代码文件中删除行，但仍希望编译器基于文件中的原始行号生成输出，可在删除行后，使用 #line 来模拟原始行号。

#line hidden 指令能对调试程序隐藏连续行，当开发者逐行执行代码时，介于 #line hidden 和下一 #line 指令（假设它不是其他 #line hidden 指令）间的任何行都将被跳过。还可通过此选项允许 ASP.NET 区分用户定义和计算机生成的代码。尽管 ASP.NET 是此功能的主要使用者，但可能有更多的源生成器使用它。

#line hidden 指令不影响错误报告中的文件名或行号。也就是说，如果编译器在隐藏块中找到错误，编译器将报告错误的当前文件名和行号。

#line filename 指令可指定要在编译器输出中显示的文件名。默认情况下，将使用源代码文件的实际名称。文件名必须采用双引号（“”），并且必须遵循行号。

可以使用一种新的 #line 指令形式：

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

这种形式的组件包括：

(1, 1): 指令后一行第一个字符的起始行和列。在此示例中，下一行将报告为第 1 行第 1 列。
(5, 60)：标记区域的结束行和列。
10：将使 #line 指令生效的列偏移量。在此示例中，第 10 列将报告为第 1 列。声明 int b = 0; 从这一列开始。此字段可选。如果省略了该字段，则指令将对第 1 列生效。
"partial-class.cs"：输出文件的名称。

前面的示例将生成以下警告：

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

重新映射后，变量 b 位于 partial-class.cs 文件第 1 行的第 6 个字符处。

特定于域的语言 (DSL) 通常使用此格式来提供从源文件到生成的 C# 输出的更好的映射。此扩展 #line 指令的最常见用途是将生成的文件中出现的警告或错误重新映射到原始源。例如，请考虑以下 razor 页：

@page "/"
Time: @DateTime.NowAndThen

属性 DateTime.Now 被错误地键入为 DateTime.NowAndThen。在 page.g.cs 中，为此 razor 代码片段生成的 C# 如下所示：

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

前面的代码片段的编译器输出如下：

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

第 2 行第 6 栏 page.razor 是文本 @DateTime.NowAndThen 开始，由 (2, 6) 在指令中。该跨度 @DateTime.NowAndThen 在第 2 行第 27 栏结束，由 (2, 27) 在指令中。文本为 DateTime.NowAndThen 的第 15 栏开始。page.g.cs, 注意到 15 在指令中。编译器会将错误报告在 page.razor. 开发人员可直接导航到该错误在源代码（而不是生成的源）中的位置。

若要查看此格式的更多示例，请参阅示例部分中的功能规范。

Pragma

#pragma 为编译器给出特殊指令以编译它所在的文件。编译器必须支持您使用的实用程序。换句话说，不能使用 #pragma 创建自定义的预处理指令。

#pragma warning：启用或禁用警告。
#pragma checksum：生成校验和。

#pragma pragma-name pragma-arguments

其中 pragma-name 是可识别 pragma 的名称，pragma-arguments 是特定于 pragma 的参数。

#pragma warning

#pragma warning 可以启用或禁用特定警告。 #pragma warning disable format 和 #pragma warning enable format 控制 Visual Studio 如何设置代码块的格式。

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

地点 warning-list 以逗号分隔的警告编号列表，如 414, CS3021. “CS”前缀是可选的。未指定警告编号时，disable 会禁用所有警告，restore 会启用所有警告。

注意

若要在 Visual Studio 中查找警告编号，请生成项目，然后在“输出”窗口中查找警告编号。

disable 从源文件的下一行开始生效。警告会在后面的 restore 行上还原。如果文件中没有 restore，则在同一编译中任何之后文件的第一行，警告将还原为其默认状态。

// 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()
    {
    }
}

的另一种形式 warning pragma 在代码块中禁用或恢复 Visual Studio 格式化命令：

#pragma warning disable format
#pragma warning restore format

Visual Studio 格式命令不会在 disable format 生效的代码块中修改文本。格式命令（如 Ctrl+K、Ctrl+D）不会修改这些代码区域。通过该实用程序您可以对代码的可视化表达方式进行精细控制。

#pragma checksum

生成源文件的校验和以帮助调试 ASP.NET 页面。

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

其中，"filename" 是需要监视更改或更新的文件的名称，"{guid}" 是哈希算法的全局唯一标识符 (GUID)，"checksum_bytes" 是表示校验和字节的十六进制数字的字符串。必须是偶数个十六进制数字。奇数个数字会导致编译时警告出现，且指令遭忽略。

Visual Studio 调试器使用校验和确保它可始终找到正确的源。编译器为源文件计算校验和，然后将输出发出到程序数据库 (PDB) 文件。调试器随后使用 PDB 针对它为源文件计算的校验和进行比较。

此解决方案不适用于 ASP.NET 项目，因为计算出的校验和是针对生成的源文件，而不是 .aspx 文件。为解决此问题，#pragma checksum 为 ASP.NET 页面提供校验和支持。

在 Visual C# 中创建 ASP.NET 项目时，生成的源文件包含 .aspx 文件（从该文件生成源）的校验和。编译器随后将此信息写入 PDB 文件中。

如果编译器在文件中没有找到 #pragma checksum 指令，它将计算校验和，并将该值写入 PDB 文件。

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