csproj，C# 也能“单文件即运行“

这种仪式感在 .NET 10 中终于成为历史。.NET 10 引入了一个重磅新特性——File-Based Apps文件级应用。它允许你仅用一个 .cs 文件无需任何 .csproj 项目文件就能直接编译、运行、甚至发布为独立可执行文件。C# 从此真正具备了脚本语言的开发体验同时保留了编译型语言的性能优势。一、什么是 File-Based AppsFile-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 App3.1 最简单的 Hello World创建一个文件 hello.csConsole.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.SQLite8.0.0using 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 Serilog3.1.1 — 指定精确版本#:package Spectre.Console* — 使用最新版本3.3 指定 SDK#:sdk 指令默认使用 Microsoft.NET.Sdk但你可以轻松切换为 Web SDK 或 Aspire SDK#:sdk Microsoft.NET.Sdk.Web#:package Swashbuckle.AspNetCorevar 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 TargetFrameworknet10.0#:property PublishAotfalse#:property LogLevel([MSBuild]::ValueOrDefault(′([MSBuild]::ValueOrDefault(([MSBuild]::ValueOrDefault(′(LOG_LEVEL), ‘Information’))Console.WriteLine($“Current Log Level: {Environment.GetEnvironmentVariable(“LOG_LEVEL”) ?? “Information”}”);#:property 支持完整的 MSBuild 属性表达式包括环境变量读取、条件表达式等。3.5 引用其他项目#:project 指令#:project …/SharedLibrary/SharedLibrary.csprojusing 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 PublishAotfalse六、用户机密User SecretsFile-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.Consoleusing Spectre.Console;AnsiConsole.MarkupLine(“[green]Hello, World![/]”);赋予执行权限并运行chmod x app.cs./app.cs⚠️ 注意使用 Shebang 时文件必须使用 LF 换行符不能包含 BOM。