引言：告别 .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 会自动根据源文件顶部的 #: 指令生成必要的项目配置，为脚本、工具和小型应用提供了一种轻量级的替代方案。

核心优势

二、环境准备

要使用 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
using Microsoft.Data.Sqlite;
var connectionString = "Data Source=:memory:";
using var connection = new SqliteConnection(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;";
using var 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
using SharedLibrary;
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
using Spectre.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
using Newtonsoft.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
using Spectre.Console;
using System.CommandLine;
// 构建一个功能完整的 CLI 工具
var rootCommand = new RootCommand("文件批量重命名工具");
var patternOption = new Option<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
using Dapper;
using Microsoft.Data.SqlClient;
using CsvHelper;
using System.Globalization;
// 从数据库读取，写入 CSV — 一个文件搞定数据迁移

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

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

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

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

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

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

dotnet project convert app.cs

执行后，SDK 会：

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

十三、写在最后

.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

转自​https://www.cnblogs.com/shanyou/p/21227428