文件范围命名空间是C#9.0及更高版本中推出的语法特性，它允许开发者为整个文件声明一个命名空间，不需要额外的花括号包裹代码内容，能有效减少代码的缩进层级，让文件结构更简洁。这个特性特别适合单个文件只属于一个命名空间的项目场景，是优化代码可读性的实用技巧。
文件范围命名空间的基本语法
传统命名空间的声明方式需要在命名空间名称后添加花括号，所有属于该命名空间的代码都放在花括号内部，示例如下：
// 传统命名空间写法
namespace DemoProject.Models
{
public class User
{
public string Name { get; set; }
public int Age { get; set; }
}
public class Order
{
public string OrderId { get; set; }
public decimal TotalPrice { get; set; }
}
}
而文件范围命名空间的声明方式为namespace 命名空间名称;，不需要花括号，整个文件的后续代码默认都属于这个命名空间，对应上面的代码可以这样改写：
// 文件范围命名空间写法
namespace DemoProject.Models;
public class User
{
public string Name { get; set; }
public int Age { get; set; }
}
public class Order
{
public string OrderId { get; set; }
public decimal TotalPrice { get; set; }
}
文件范围命名空间的使用限制
使用文件范围命名空间时需要注意以下几个限制条件，避免出现语法错误：
- 一个文件只能声明一个文件范围命名空间，不能在同一个文件中声明多个不同的文件范围命名空间。
- 文件范围命名空间之后不能出现传统的带花括号的命名空间声明，也不能在同一个文件中混合使用两种命名空间写法。
- 如果文件中需要声明全局using指令，全局using指令需要放在文件范围命名空间声明之前。
- 文件范围命名空间仅支持C#9.0及以上版本的语言特性，项目的语言版本需要设置为9.0或更高。
两种命名空间写法的对比
我们可以通过下面的表格直观对比传统命名空间和文件范围命名空间的差异：
| 对比项 | 传统命名空间 | 文件范围命名空间 |
|---|---|---|
| 语法结构 | 需要namespace加花括号包裹代码 | namespace后加分号，无花括号 |
| 代码缩进 | 内部代码需要多一层缩进 | 无额外缩进层级 |
| 单文件多命名空间支持 | 支持 | 不支持 |
| 适用场景 | 单文件多命名空间、复杂代码结构 | 单文件单命名空间、简单代码结构 |
实际项目中的使用示例
在实际的ASP.NET Core项目中，模型类、控制器类通常都是单个文件对应一个命名空间，非常适合使用文件范围命名空间。比如下面是一个控制器类的示例：
// 全局using指令放在文件范围命名空间之前
global using Microsoft.AspNetCore.Mvc;
namespace DemoProject.Controllers;
[ApiController]
[Route("api/[controller]")]
public class UserController : ControllerBase
{
[HttpGet]
public IActionResult GetUser()
{
var user = new Models.User
{
Name = "张三",
Age = 25
};
return Ok(user);
}
}
从上面的示例可以看到，使用文件范围命名空间后，控制器类的代码没有额外的缩进，整体看起来更简洁，也符合单文件单命名空间的开发习惯。
常见问题说明
很多开发者会疑惑，如果项目中同时存在两种命名空间写法会不会有问题。实际上只要符合各自的语法规则，项目中可以同时存在两种写法，编译器会正常识别，开发者可以根据文件的实际场景选择合适的写法。另外如果项目需要兼容旧版本的C#语言，就不能使用文件范围命名空间，需要保持传统的命名空间写法。
C#FileScopedNamespace文件范围命名空间命名空间修改时间：2026-06-28 02:00:25