企业官网建设流程全解析

这种"仪式感"，在 .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

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(′([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.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。