要点

从 dotnet new console 到一个真正有用的命令行小工具，只需要一个 Program.cs。现代 C# 的入口是顶级语句（top-level statements）——没有类、没有 Main 的裸代码，但 Main 一直都在，只是编译器替你写。理解这层语法糖与入口的关系，是从 Java 转过来最值得先搞清楚的一件事。

创建工程

dotnet new console -n wordcount
cd wordcount
dotnet run

三秒后输出 Hello, World!。目录里只有三个值得看的东西：

没有 src/、没有包结构、没有清单文件——C# 的文件名与类型名不需要对应（这点与 Java 完全不同），一个项目里 .cs 文件怎么组织全凭团队约定。

核心概念：顶级语句与 Main 的关系

默认模板里的 Program.cs 长这样：

// 一行 using 都没有：ImplicitUsings 把常用命名空间隐式引入了
Console.WriteLine("Hello, World!");

编译器把它翻译成一个合成的 Program.Main(string[] args)——入口从未消失，只是不必手写。与 Java 的三种写法对照：

两条规矩要记：一个项目只能有一个文件用顶级语句（它就是入口）；顶级语句必须是该文件最前面的语句，类型声明只能排在它后面。反模式：在同一个项目里既写顶级语句又写显式 Main——编译器直接报 CS8805（顶级语句与显式入口点不能共存），网上不少旧教程混着抄，一抄就中。

第一个应用：词频统计 CLI

目标：读一个文本文件，输出出现次数最多的前 N 个单词。功能小，但覆盖了真实 CLI 的全部要素——参数解析、文件 IO、错误处理、输出格式。完整代码，可直接替换 Program.cs：

// Program.cs —— 顶级语句就是入口，args 由编译器注入的 Main 传入
// 用法: dotnet run -- <文件> [前N，默认10]

if (args.Length < 1)
{
    Console.Error.WriteLine("用法: wordcount <文件> [前N]");
    return 1;                       // 顶级语句最后的 return 值 = 进程退出码
}

var path = args[0];
var top = args.Length > 1 && int.TryParse(args[1], out var n) ? n : 10;

if (!File.Exists(path))
{
    Console.Error.WriteLine($"文件不存在: {path}");
    return 2;
}

var text = await File.ReadAllTextAsync(path);   // IO 是异步的，入口天然支持 await

var topWords = text
    .Split([' ', '\n', '\r', '\t'], StringSplitOptions.RemoveEmptyEntries)
    // Trim 不认标点，这里按字符过滤：只保留字母数字，"dog." 和 "dog" 才会算同一个词
    .Select(w => new string(w.Where(char.IsLetterOrDigit).ToArray()))
    .Where(w => w.Length > 0)
    .GroupBy(w => w, StringComparer.OrdinalIgnoreCase)
    .Select(g => (Word: g.Key, Count: g.Count()))   // 投影成元组，下游直接点出属性
    .OrderByDescending(x => x.Count)
    .ThenBy(x => x.Word, StringComparer.OrdinalIgnoreCase)
    .Take(top);

foreach (var (word, count) in topWords)       // 元组解构
    Console.WriteLine($"{count,5}  {word}");  // 字符串内插，,5 表示右对齐宽度

return 0;

这几行代码里已经出现了 LINQ 方法链、元组投影与解构、字符串内插、out var 模式——都是下一篇语法篇的主角，这里先混个脸熟。

跑起来：

# 造个测试文件
printf 'the quick brown fox the lazy dog the end\n' > sample.txt

dotnet run -- sample.txt 3
1. 输出：
1.     3  the
1.     1  brown
1.     1  dog

注意 --：它之后的内容才传给程序，之前的留给 dotnet 自己（比如 dotnet run -c Release）。这是 CLI 惯例，与 npm run 的 -- 相同。

退出码与返回值

顶级语句里最后的 return 整数 映射为进程退出码——shell 脚本据此判断成败。惯例：0 成功，非零按错误类别区分（上面用 1 表示用法错误、2 表示文件不存在）。在 IDE 里调试时给参数，靠 Properties/launchSettings.json 的 commandArgs 字段，或直接终端 dotnet run。

发布成可执行文件

dotnet publish -c Release -o publish

1. 三种产物口径
1. 1. 框架依赖（默认）: publish/ 里的 dll 需要目标机器装有 .NET 10 运行时，产物小
1. 2. 自包含单文件: 加 --self-contained -p:PublishSingleFile=true，免装运行时，一个可执行文件
1. 3. Native AOT: 加 -p:PublishAot=true，编成原生机器码，启动最快、体积最小，限制最多

选型一句话：公司内机器默认有运行时就用框架依赖；发给用户的小工具用自包含单文件；追求极致启动且依赖简单再考虑 AOT。跨平台注意：自包含产物按发布时的操作系统架构生成，给 Linux 服务器发布要加 -r linux-x64。

最佳实践

• 入口薄，逻辑厚：顶级语句只做参数解析与顶层编排，超过五十行就拆出静态类或服务类
• 错误输出走 Console.Error，退出码区分错误类别——这是 CLI 与管道协作的礼貌
• 文件 IO 一律用 Async 版本（File.ReadAllTextAsync 而非 ReadAllText），CLI 也不嫌小
• 正式工程把 obj/、bin/ 进 .gitignore，csproj 提交

常见问题

CS8805：顶级语句与显式 Main 同时存在

删掉一个。保留顶级语句（推荐，模板默认），或者全项目走 class + Main 风格（老团队规范可能如此），别混。

CS5001：未找到入口点

项目里没有任何顶级语句文件，也没有合法 Main。常见原因：把 Main 写成了小写 main（C# 大小写敏感），或者入口文件被排除出编译（csproj 的 Compile Remove）。

改了代码没生效

dotnet run 每次都重新构建，不存在旧产物问题；但如果你直接运行 bin/ 下的旧 dll，那就是在跑上次编译的结果。开发期统一用 dotnet run 或 dotnet watch run。

练习与实践

• 练习一：给 wordcount 加 -i 参数控制是否忽略大小写，体会 args 解析膨胀后为什么该引入 System.CommandLine 或 Spectre.Console.Cli 这类库
• 练习二：用自包含单文件发布，把产物拷到一台没装 .NET 的机器上跑通，对比产物大小与框架依赖版的差异
• 练习三：把 GroupBy 换成手动遍历 Dictionary 累加计数，体会 LINQ 与手写命令式代码的取舍

延伸阅读

环境没搭好的先回《C# 与 .NET 环境搭建与工具链》；Java 背景的读者推荐同场对照《第一个 Java 程序》——那篇讲了 Java 入口的三次进化（经典 main、单文件直跑、Java 25 紧凑源文件），和本篇的顶级语句是一对镜子。下一篇《C# 语法要点》把本文代码里一闪而过的 LINQ、元组、可空类型逐个讲透。

版本核实（以官方文档为准）：顶级语句自 C# 9 / .NET 5 起可用，.NET 10 控制台模板默认启用，对应语言版本 C# 14；Native AOT 与自包含单文件发布为当前 SDK 稳定能力；Java 25 紧凑源文件用于对照（其 GA 为 2025-09）。文件式应用（dotnet run 单文件）为 .NET 10 新增，本文从项目起步、未依赖它。具体以官方文档为准。