目录引言告别 .csprojC# 也能单文件即运行一、什么是 File-Based Apps核心优势二、环境准备三、快速上手5 分钟写出第一个 File-Based App3.1 最简单的 Hello World3.2 引用 NuGet 包#:package 指令3.3 指定 SDK#:sdk 指令3.4 设置 MSBuild 属性#:property 指令3.5 引用其他项目#:project 指令四、完整的 CLI 命令支持运行应用构建与清理发布与打包依赖恢复五、Native AOT默认开启的高性能发布六、用户机密User Secrets七、Unix 系统上的 Shebang 支持八、Launch Profile 配置九、目录组织最佳实践❌ 不推荐✅ 推荐十、实战场景File-Based Apps 能做什么场景 1快速原型验证场景 2CLI 工具脚本场景 3数据迁移/ETL 脚本场景 4定时任务/自动化脚本十一、File-Based Apps vs 传统 .csproj 项目十二、从 File-Based App 到完整项目十三、写在最后参考资源引言告别 .csprojC# 也能单文件即运行还记得用 Python 写脚本时的那种爽快感吗一个.py文件直接python hello.py就能跑。而 C# 开发者呢哪怕只是想写个Hello World也得先dotnet new console生成一堆项目文件然后才能编译运行。这种仪式感在 .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.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 Serilog3.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 TargetFrameworknet10.0 #:property PublishAotfalse #: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 # 从标准输入管道执行 echoConsole.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 setApiKeyyour-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 } } } }运行指定 Profiledotnet 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));场景 2CLI 工具脚本#!/usr/bin/env dotnet #:package Spectre.Console #:package System.CommandLine usingSpectre.Console; usingSystem.CommandLine; // 构建一个功能完整的 CLI 工具 var rootCommand newRootCommand(文件批量重命名工具); var patternOption newOptionstring(--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 appsGitHub - awesome-dotnet-fba — 精选 .NET 10 File-Based Apps 代码示例集.NET 10 File Based Apps Demonstration引入地址
