.NET 10 File-Based Apps：一个 .cs 文件搞定一切，C# 终于也能像 Python 一样写脚本了！

admin

2026年7月9日 10:12 本文热度 101

以下文章来源于dotNET跨平台，作者张善友 MVP

引言：告别 .csproj，C# 也能"单文件即运行"

还记得用 Python 写脚本时的那种爽快感吗？一个 .py 文件，直接 python hello.py 就能跑。而 C# 开发者呢？哪怕只是想写个"Hello World"，也得先 dotnet new console 生成一堆项目文件，然后才能编译运行。

这种"仪式感"，在 .NET 10 中终于成为历史。

.NET 10 引入了一个重磅新特性——File-Based Apps（文件级应用）。它允许你仅用一个 .cs 文件，无需任何 .csproj 项目文件，就能直接编译、运行、甚至发布为独立可执行文件。C# 从此真正具备了脚本语言的开发体验，同时保留了编译型语言的性能优势。

一、什么是 File-Based Apps？

File-Based Apps 是 .NET 10 SDK 引入的一项创新功能，允许开发者从单个 C# 源文件构建、运行和发布 .NET 应用程序，无需创建传统的项目文件（.csproj）。

.NET SDK 会自动根据源文件顶部的 #: 指令生成必要的项目配置，为脚本、工具和小型应用提供了一种轻量级的替代方案。

核心优势

特性	说明
零配置	无需 `.csproj` 文件，一个 `.cs` 文件即可运行
自包含	配置内嵌在源文件中，文件即项目
Native AOT 默认启用	发布时自动生成本地 Ahead-of-Time 编译的可执行文件
自动打包为 .NET 工具	支持 `dotnet pack` 直接打包为全局工具
平滑升级	可随时通过 `dotnet project convert` 转换为完整项目

二、环境准备

要使用 File-Based Apps，你需要：

.NET 10 SDK 或更高版本
任意文本编辑器（VS Code、Cursor、记事本均可）
C# 扩展（推荐，用于 IntelliSense 支持）

验证 SDK 版本：

dotnet --version
# 输出应为 10.0 或更高

三、快速上手：5 分钟写出第一个 File-Based App

3.1 最简单的 Hello World

创建一个文件 hello.cs：

Console.WriteLine("Hello, File-Based App!");

直接运行：

dotnet run hello.cs

或者使用更简洁的语法：

dotnet hello.cs

没错，就这么简单！没有 dotnet new，没有 .csproj，一个文件直接跑。

3.2 引用 NuGet 包：#:package 指令

File-Based Apps 使用 #: 前缀的指令来配置构建。最常用的就是 #:package，用于引用 NuGet 包。

创建一个 sqlite-demo.cs：

#:package Microsoft.Data.SQLite@8.0.0

usingMicrosoft.Data.Sqlite;

var connectionString ="Data Source=:memory:";
usingvar connection =newSqliteConnection(connectionString);
connection.Open();

var command = connection.CreateCommand();
command.CommandText ="CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT);"+
"INSERT INTO users (name) VALUES ('山友');"+
"SELECT * FROM users;";

usingvar reader = command.ExecuteReader();
while(reader.Read())
{
    Console.WriteLine($"ID: {reader.GetInt32(0)}, Name: {reader.GetString(1)}");
}

运行：

dotnet run sqlite-demo.cs

输出：

ID: 1, Name: 山友

版本控制技巧：
#:package Newtonsoft.Json
— 省略版本号（需配合 Central Package Management）
#:package Serilog@3.1.1
— 指定精确版本
#:package Spectre.Console@*
— 使用最新版本

3.3 指定 SDK：#:sdk 指令

默认使用 Microsoft.NET.Sdk，但你可以轻松切换为 Web SDK 或 Aspire SDK：

#:sdk Microsoft.NET.Sdk.Web
#:package Swashbuckle.AspNetCore

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/",()=>"Hello from File-Based Web App!");
app.MapGet("/api/health",()=>new{ status ="ok", timestamp = DateTime.UtcNow });

app.Run();

运行：

dotnet run webapi.cs

使用 Microsoft.NET.Sdk.Web 时，会自动包含同目录下的 *.json 配置文件（如 appsettings.json）。

3.4 设置 MSBuild 属性：#:property 指令

#:property TargetFramework=net10.0
#:property PublishAot=false
#:property LogLevel=$([MSBuild]::ValueOrDefault('$(LOG_LEVEL)', 'Information'))

Console.WriteLine($"Current Log Level: {Environment.GetEnvironmentVariable("LOG_LEVEL")??"Information"}");

#:property 支持完整的 MSBuild 属性表达式，包括环境变量读取、条件表达式等。

3.5 引用其他项目：#:project 指令

#:project ../SharedLibrary/SharedLibrary.csproj

usingSharedLibrary;

Console.WriteLine(Helper.GetMessage());

四、完整的 CLI 命令支持

File-Based Apps 并非"玩具功能"，它拥有完整的 CLI 支持：

运行应用

# 标准方式
dotnet run --file app.cs

# 简写（推荐）
dotnet run app.cs

# 更简写（当目录无 .csproj 时）
dotnet app.cs

# 传递参数
dotnet run app.cs -- arg1 arg2

# 从标准输入管道执行
echo'Console.WriteLine("hello from stdin!");'| dotnet run -

构建与清理

# 编译
dotnet build app.cs

# 清理构建产物
dotnet clean app.cs

# 清理所有 file-based apps 缓存
dotnet clean file-based-apps

发布与打包

# 发布（默认启用 Native AOT，生成独立可执行文件）
dotnet publish app.cs

# 打包为 .NET 全局工具
dotnet pack app.cs

# 转换为传统项目（平滑升级路径）
dotnet project convert app.cs

依赖恢复

# 显式恢复 NuGet 包
dotnet restore app.cs

# 构建时自动恢复（默认行为）
dotnet build app.cs

五、Native AOT：默认开启的高性能发布

File-Based Apps 的一个杀手锏特性是默认启用 Native AOT 发布。这意味着：

✅ 更快的启动速度 — 无需 JIT 编译预热
✅ 更小的内存占用 — 无运行时依赖
✅ 独立可执行文件 — 单文件分发，无需 .NET Runtime

如果你不需要 AOT（例如依赖反射较多的场景），可以关闭：

#:property PublishAot=false

六、用户机密（User Secrets）

File-Based Apps 支持用户机密管理，基于文件路径的哈希生成稳定的 Secrets ID：

# 设置机密
dotnet user-secrets set"ApiKey""your-secret-value"--file app.cs

# 查看机密
dotnet user-secrets list --file app.cs

七、Unix 系统上的 Shebang 支持

在 Linux/macOS 上，你可以让 .cs 文件像 Shell 脚本一样直接执行：

#!/usr/bin/env dotnet
#:package Spectre.Console

usingSpectre.Console;

AnsiConsole.MarkupLine("[green]Hello, World![/]");

赋予执行权限并运行：

chmod +x app.cs
./app.cs

⚠️ 注意：使用 Shebang 时，文件必须使用 LF 换行符，不能包含 BOM。

八、Launch Profile 配置

File-Based Apps 支持启动配置，使用 [应用名].run.json 文件：

// app.run.json
{
"profiles":{
"http":{
"commandName":"Project",
"launchBrowser":true,
"applicationUrl":"http://localhost:5000",
"environmentVariables":{
"ASPNETCORE_ENVIRONMENT":"Development"
}
},
"https":{
"commandName":"Project",
"launchBrowser":true,
"applicationUrl":"https://localhost:5001;http://localhost:5000",
"environmentVariables":{
"ASPNETCORE_ENVIRONMENT":"Development"
}
}
}
}

运行指定 Profile：

dotnet run app.cs --launch-profile https

九、目录组织最佳实践

File-Based Apps 会继承父目录的 Directory.Build.props、Directory.Packages.props 等隐式构建文件。为了避免冲突：

❌ 不推荐

📁 MyProject/
├── MyProject.csproj
├── Program.cs
└──📁 scripts/
    └── utility.cs  // 会受到 MyProject.csproj 的隐式文件影响

✅ 推荐

📁 MyProject/
├── MyProject.csproj
└── Program.cs
📁 scripts/
└── utility.cs  // 独立目录，避免干扰

十、实战场景：File-Based Apps 能做什么？

场景 1：快速原型验证

#:package Newtonsoft.Json

usingNewtonsoft.Json;

var data =new{ Name ="File-Based App", Version ="1.0", Features =new[]{"Fast","Simple","Powerful"}};
Console.WriteLine(JsonConvert.SerializeObject(data, Formatting.Indented));

场景 2：CLI 工具脚本

#!/usr/bin/env dotnet
#:package Spectre.Console
#:package System.CommandLine

usingSpectre.Console;
usingSystem.CommandLine;

// 构建一个功能完整的 CLI 工具
var rootCommand =newRootCommand("文件批量重命名工具");
var patternOption =newOption<string>("--pattern","匹配模式");
rootCommand.AddOption(patternOption);

rootCommand.SetHandler((string pattern)=>
{
    AnsiConsole.MarkupLine($"[blue]正在处理匹配模式: {pattern}[/]");
// 业务逻辑...
}, patternOption);

await rootCommand.InvokeAsync(args);

场景 3：数据迁移/ETL 脚本

#:package Dapper
#:package Microsoft.Data.SqlClient
#:package CsvHelper

usingDapper;
usingMicrosoft.Data.SqlClient;
usingCsvHelper;
usingSystem.Globalization;

// 从数据库读取，写入 CSV — 一个文件搞定数据迁移

场景 4：定时任务/自动化脚本

#:package Quartz

// 使用 Quartz 构建定时任务，部署为单文件后台服务

十一、File-Based Apps vs 传统 .csproj 项目

对比维度	File-Based Apps	传统 .csproj 项目
项目文件	❌ 不需要	✅ 需要
适合场景	脚本、工具、原型、小型应用	中大型应用、团队协作
启动速度	⚡ 更快（AOT 默认）	🔄 标准 JIT
依赖管理	`#:` 指令内嵌	`PackageReference`
测试支持	❌ 不支持 `dotnet test`	✅ 完整支持
团队规模	个人/小团队	任意规模
升级路径	`dotnet project convert`	本身就是完整项目

关键洞察：File-Based Apps 不是替代传统项目，而是填补空白——在那些"为了写个脚本还得建个项目"的场景下，它提供了恰到好处的轻量方案。

十二、从 File-Based App 到完整项目

当你的脚本逐渐复杂，需要单元测试、CI/CD 或多项目结构时，File-Based Apps 提供了平滑的升级路径：

dotnet project convert app.cs

执行后，SDK 会：

复制 .cs 文件到以应用名命名的目录
根据 #: 指令生成等效的 .csproj 文件
保留原始文件不变

十三、写在最后

.NET 10 的 File-Based Apps 是一个看似小巧、实则意义深远的特性。它标志着 .NET 平台在开发体验上的一次重要进化：

对初学者
：降低了 C# 的入门门槛，一个文件就能开始编程
对脚本开发者
：C# 终于可以像 Python 一样写脚本，同时享受编译型语言的性能
对运维/DevOps
：单文件可执行，部署极简，Native AOT 带来极致启动速度
对原型开发
：快速验证想法，需要时再平滑升级为完整项目

C# 不再是"重型企业级开发"的专属标签，它也能轻盈、敏捷、即刻运行。

参考资源

.NET 官方文档 - File-based apps
GitHub - awesome-dotnet-fba — 精选 .NET 10 File-Based Apps 代码示例集
.NET 10 File Based Apps Demonstration

该文章在 2026/7/9 13:19:08 编辑过