C# 预处理器指令的**完整语言参考**，涵盖所有指令的精确语法、使用规则和边界条件。与前一篇教程风格的文章不同，这篇侧重**语法规范和细节**，适合需要精确查阅特定指令的开发者。

> **核心前提：**  C# 的预处理器指令没有独立的预处理器，由编译器直接处理。指令必须独占一行。不能像 C/C++ 那样创建宏，条件编译仅判断符号是否定义（布尔逻辑）。

|指令类别|涵盖指令|
| -----------------| ----------------------------------|
|Nullable 上下文|​`#nullable enable/disable/restore`及 annotations/warnings 子集|
|条件编译|​`#if`​、`#elif`​、`#else`​、`#endif`|
|符号定义|​`#define`​、`#undef`|
|代码区域|​`#region`​、`#endregion`|
|诊断信息|​`#error`​、`#warning`​、`#line`|
|编译器指令|​`#pragma warning`​、`#pragma checksum`|
|文件应用|​`#!`​（shebang）、`#:`|

## 一、`#nullable` — 可为空上下文

控制可为 null 引用类型的注释和警告。指令优先级高于项目设置，效果持续到下一指令或文件结束。

### 1.1 基本形式

|指令|效果|
| ------| ---------------------------------|
|​`#nullable disable`|禁用可为空上下文（注释 + 警告）|
|​`#nullable enable`|启用可为空上下文|
|​`#nullable restore`|恢复为项目级别的设置|

### 1.2 细粒度控制

可以单独控制**注释**（annotations，即 `?`​ 标记）和**警告**（warnings）：

|指令|效果|
| ------| ---------------------------------------|
|​`#nullable disable annotations`|禁用`?`标记（不检查 nullability 注释）|
|​`#nullable enable annotations`|启用`?`标记|
|​`#nullable restore annotations`|恢复注释设置为项目级别|
|​`#nullable disable warnings`|禁用可为 null 警告|
|​`#nullable enable warnings`|启用可为 null 警告|
|​`#nullable restore warnings`|恢复警告设置为项目级别|

**使用场景：**  在一个项目逐步迁移到 nullable aware 时，可以局部启用或禁用特定文件/区域。

```csharp
 // 整个文件默认启用 nullable
 #nullable enable
 ​
 public string? GetOptional() => null;   // string? 有效，返回 null 不报警告
 ​
 #nullable disable warnings
 public string GetRequired() => null;     // 返回 null 不报警告（warnings 已禁用）
 ​
 #nullable restore warnings
 // 后面的代码恢复警告
```

## 二、条件编译 — `#if`​ / `#elif`​ / `#else`​ / `#endif`

### 2.1 基本语法

```csharp
 #if SYMBOL
     // 当 SYMBOL 已定义时编译
 #elif OTHER_SYMBOL
     // 当 OTHER_SYMBOL 已定义且前面条件不满足时编译
 #else
     // 前面所有条件都不满足时编译
 #endif
```

### 2.2 支持的运算符

|运算符|含义|示例|
| --------| --------| ------|
|​`!`|逻辑非|​`#if !DEBUG`|
|​`==`|相等|​`#if NET8_0 == true`|
|​`!=`|不等|​`#if NET8_0 != true`|
|​`&&`|逻辑与|​`#if DEBUG && NET10_0`|
|​`\|\|`|逻辑或|​`#if DEBUG \|\| TRACE`|
|​`()`|分组|​`#if (DEBUG \|\| TRACE) && !PRODUCTION`|

### 2.3 预定义符号

SDK 风格项目根据目标框架自动定义一组符号：

**桌面 / 框架相关：**

|目标框架|精确版本符号|范围符号|
| ----------------------| --------------| ----------|
|.NET Framework 4.7.2|​`NET472`|​`NET472_OR_GREATER`|
|.NET Framework 4.8|​`NET48`|​`NET48_OR_GREATER`|
|.NET Standard 2.1|​`NETSTANDARD2_1`|​`NETSTANDARD2_1_OR_GREATER`|

**现代 .NET（.NET 5+）：**

|目标框架|精确版本符号|范围符号|
| ----------| --------------| ----------|
|.NET 8|​`NET8_0`|​`NET8_0_OR_GREATER`|
|.NET 9|​`NET9_0`|​`NET9_0_OR_GREATER`|
|.NET 10|​`NET10_0`|​`NET10_0_OR_GREATER`|

**平台符号：**

|平台|符号|带版本号|
| ---------| ------| ----------|
|Android|​`ANDROID`|​`ANDROID35_0_OR_GREATER`|
|iOS|​`IOS`|​`IOS15_1_OR_GREATER`|
|Windows|​`WINDOWS`|​`WINDOWS10_0_17763_0_OR_GREATER`|

**通用符号：**

|符号|来源|
| ------| ------------------------|
|​`DEBUG`|Debug 生成配置自动定义|
|​`TRACE`|Trace 常量，默认开启|

### 2.4 多框架适配示例

```csharp
 public static string DownloadContent(string url)
 {
 #if NET40
     WebClient _client = new WebClient();
     return _client.DownloadString(url);
 #else
     HttpClient _client = new HttpClient();
     return _client.GetStringAsync(url).Result;
 #endif
 }
```

## 三、符号定义 — `#define`​ / `#undef`

### 3.1 语法

```csharp
 #define MYTEST         // 定义符号
 #undef MYTEST         // 取消定义
```

### 3.2 关键规则

|规则|说明|
| ------------| ----------------------------|
|位置|**必须在文件最开头**，在所有非预处理器代码之前|
|作用域|从定义位置到文件末尾|
|不能赋值|​`#define MYTEST 1`​是**非法**的，只能声明符号名|
|常量应用|需要常量值用`const`​，不要用`#define`|
|编译器选项|也可通过`DefineConstants`属性全局定义|

```csharp
 // 正确 ✅
 #define FEATURE_EXPERIMENTAL
 ​
 // 错误 ❌
 #define FEATURE_EXPERIMENTAL true   // 编译错误
```

## 四、`#region`​ / `#endregion` — 代码折叠 ⭐

### 4.1 语法

```csharp
 #region 区域名称
 // ... 可折叠的代码 ...
 #endregion
```

### 4.2 规则

|规则|说明|
| ------------| ----------------------------------------|
|配对|​`#region`​必须由`#endregion`终止|
|嵌套|​`#region`​内可以嵌套另一个`#region`|
|与`#if`的关系|**不能重叠**，但可互相嵌套：`#region`​内含`#if`​块，或`#if`​内含`#region`|
|编译影响|**不影响编译**，纯 IDE 大纲视图特性|

### 4.3 正确 vs 错误的嵌套

```csharp
 // ✅ 正确 — #if 完整包含在 #region 内
 #region 多框架适配
 #if NET8_0_OR_GREATER
     Console.WriteLine(".NET 8+");
 #endif
 #endregion
 ​
 // ✅ 正确 — #region 完整包含在 #if 内
 #if DEBUG
 #region 调试工具
     Console.WriteLine("Debug tools active");
 #endregion
 #endif
 ​
 // ❌ 错误 — 重叠（编译失败）
 #region 开始
 #if DEBUG
 #endregion       // ❌ 在 #if 没有 #endif 之前关闭 #region
 #endif
```

### 4.4 示例

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

> **常见坑：**  `#region`​ 不能拆分 `#if`​/`#endif`​ 块。如果你在一个 `#region`​ 内打开了 `#if`​，必须在同一个 `#region`​ 内用 `#endif` 关闭。

## 五、诊断指令 — `#error`​、`#warning`​、`#line`

### 5.1 `#error` — 主动生成编译错误

```csharp
 #error Deprecated code in this method.
 // 编译错误 CS1029: #error: 'Deprecated code in this method.'
```

**常用场景：**  在不支持的条件下阻止编译：

```csharp
 #if !NET8_0_OR_GREATER
     #error This library requires .NET 8 or later.
 #endif
```

### 5.2 `#warning` — 主动生成编译警告

```csharp
 #warning Deprecated code in this method.
 // 编译警告 CS1030: #warning: 'Deprecated code in this method.'
```

### 5.3 `#line` — 修改编译输出行号/文件名

|指令|效果|
| ------| --------------------------------------------------------|
|​`#line 200 "Special.cs"`|强制编译器以第 200 行、"Special.cs" 文件名报告后续代码|
|​`#line default`|恢复默认行号|
|​`#line hidden`|对调试器隐藏后续行（逐步执行时跳过）|

**C# 高级语法（适用于 DSL / 代码生成器）：**

```csharp
 #line (起始行, 起始列) - (结束行, 结束列) 列偏移 "原始源文件名"
```

常用场景：Razor 页面将生成的 `.cs`​ 文件中警告/错误映射回 `.cshtml` 原始源代码。

## 六、`#pragma` 指令

### 6.1 `#pragma warning` — 警告控制

```csharp
 #pragma warning disable 414, CS3021   // 从下一行起禁用指定警告
 // ... 受抑制的代码 ...
 #pragma warning restore CS3021        // 恢复指定警告
```

**格式控制：**

```csharp
 #pragma warning disable format   // 禁用代码格式化（如 Ctrl+K,D）
 // ... 你想保留手动格式的代码 ...
 #pragma warning restore format   // 恢复格式化
```

### 6.2 `#pragma checksum` — 调试校验和

主要为 ASP.NET 页面设计，确保调试器找到正确的源文件：

```csharp
 #pragma checksum "file.cs" "{3673e4ca-6098-4ec1-890f-8fceb2a794a2}" "hex-bytes..."
```

参数：

1. **文件名** — 源文件路径
2. **GUID** — 文件的唯一标识
3. **校验和字节** — 十六进制字符串

## 七、`#!`​ 和 `#:` — 基于文件的应用

### 7.1 `#!` — Shebang

```csharp
 #!/usr/bin/env dotnet
 Console.WriteLine("Hello");
```

Unix 下配合 `chmod +x` 可直接执行。

### 7.2 `#:` — 文件级配置

C# 编译器**忽略** `#:` 开头的行，但它们被 .NET SDK 等工具按约定解析：

```csharp
 #:package Spectre.Console@*
 #:sdk Microsoft.NET.Sdk.Web
 #:property PublishAot=false
```

## 八、指令不重叠关系速查

|结构 A|结构 B|可以嵌套？|条件|
| --------| --------| ------------| --------------------|
|​`#region`|​`#region`|✅|完整嵌套|
|​`#if`|​`#if`|✅|完整嵌套|
|​`#region`|​`#if`|✅|一个完整包含另一个|
|​`#region`|​`#if`|❌|**不能重叠/交错**|

## 最后

这份参考文档覆盖了 C# 预处理器指令的**全部语法规范**。日常开发中最常用的就三类：`#if DEBUG`​、`#nullable enable`​、`#region`​。其余的（`#line`​ 高级映射、`#pragma checksum`​）主要在代码生成器和 ASP.NET 底层框架中使用。记住最核心的一条：C# 预处理指令没有宏，条件编译只判断符号有没有定义，不要把它当成 C/C++ 的 `#define` 宏来用。

‍


C# 预处理器指令的完整语言参考，涵盖所有指令的精确语法、使用规则和边界条件。与前一篇教程风格的文章不同，这篇侧重语法规范和细节，适合需要精确查阅特定指令的开发者。

C# 预处理器指令语言 - 完整语法速查

编程语言

C#预处理器指令完整指南，涵盖条件编译、可为空上下文、代码区域等核心语法。详细解析#if、#nullable、#region等指令的使用规则和边界条件，帮助开发者精确控制编译过程。重点说明C#预处理器与C/C++的区别，强调其仅支持符号定义而非宏替换的特性。

编译器

调试器

Android

Unix

热销域名限时优惠，新客首年免费！


domain

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

C# 预处理器指令语言 - 完整语法速查-腾讯云开发者社区-腾讯云

C# 预处理器指令语言 - 完整语法速查

C# 预处理器指令语言 - 完整语法速查

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐