控制台应用程序入门：从创建项目到运行第一个程序

控制台应用程序没有图形界面，通常通过终端或命令提示符接收输入、显示输出。它适合做文件处理、批量任务、运维脚本、数据转换、开发工具和服务端程序的辅助工具。对于第一次接触编程的人来说，它也是理解项目结构、运行流程和输入输出的好起点。

本文使用 C# 和 .NET SDK 创建一个控制台应用程序，从打印第一行文字开始，逐步加入命令行参数、输入校验和文件操作，并说明控制台程序适用与不适用的场景。示例以常见的现代 .NET SDK 为基础；不同版本的模板或命令选项可能略有差异，遇到不一致时可以查看本机的 dotnet --help。

一、什么是控制台应用程序

控制台应用程序是一种通过文本流与用户或其他程序交互的程序。它通常从标准输入读取数据，通过标准输出显示正常结果，通过标准错误输出错误或诊断信息。标准输入、标准输出和标准错误通常分别简称为 stdin、stdout 和 stderr。

最简单的交互形式是启动程序后直接显示一段文字；也可以让程序读取用户键入的内容，或由另一个程序把参数和数据传给它。例如：

• 运行 tool --help，让程序根据参数显示帮助信息。
• 运行 tool input.txt output.txt，让程序处理指定文件。
• 使用管道把一个命令的输出传给另一个命令。
• 把程序安排在定时任务或持续集成流程中自动执行。

“控制台程序”描述的是一种交互和启动形式，并不意味着程序只能做简单计算。它可以连接网络、读写数据库、处理文件，甚至在后台运行很长时间。反过来，它也不天然适合所有场景：如果需要复杂的可视化交互、移动设备界面或面向普通用户的桌面操作体验，应考虑图形界面、Web 应用或移动应用。

二、准备 .NET SDK

要编译和运行 C# 项目，需要安装 .NET SDK。SDK 包含运行时、编译器和项目命令行工具；只安装运行时通常不足以创建和编译项目。

安装后打开终端，执行：

dotnet --version

如果终端显示一个版本号，通常说明命令行工具已经可以使用。如果提示找不到命令，请先确认已安装 SDK，并重新打开终端；在某些系统上，安装目录还需要加入 PATH 环境变量。可以使用下面的命令查看已安装的 SDK 和运行时：

dotnet --list-sdks
dotnet --list-runtimes

SDK、运行时和目标框架不是一回事。SDK 用来开发和构建项目，运行时用来运行应用程序，项目中的目标框架则声明应用程序面向哪个 .NET 版本。开发机上可用的 SDK 数量，并不自动保证部署目标机上具备相应运行时。

三、创建并运行第一个项目

先在终端切换到一个用于保存项目的目录，再执行以下命令：

dotnet new console -n HelloConsole
cd HelloConsole
dotnet run

dotnet new console 使用 SDK 内置模板创建控制台项目；-n HelloConsole 指定项目名称。之后进入项目目录，dotnet run 会构建并运行项目。新建模板通常会输出类似下面的内容：

Hello, World!

模板具体生成的代码会随 SDK 版本变化。打开目录中的 Program.cs，可能看到类似下面的最简程序：

Console.WriteLine("Hello, World!");

把内容改成更容易识别的问候语：

Console.WriteLine("你好，控制台！");
Console.WriteLine("程序已经成功运行。");

保存后再次运行：

dotnet run

Console.WriteLine 会把文本写入标准输出，并在末尾换行。如果不希望换行，可以使用 Console.Write。例如：

Console.Write("请输入姓名：");
string? name = Console.ReadLine();
Console.WriteLine($"你好，{name}！");

Console.ReadLine 会读取一行文本。返回类型为可空字符串，因为输入流结束时它可能返回 null。如果用户只是按下回车，读取到的则是空字符串。两种情况并不相同，程序应该根据实际需求处理。

四、了解项目文件和运行流程

新建项目后，目录里通常会包含源代码文件 Program.cs、项目文件 HelloConsole.csproj，以及构建时生成的目录。项目文件用 XML 描述项目配置，例如目标框架和可空引用类型设置。它可能类似这样：

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

</Project>

实际文件中的目标框架可能是其他版本，例如 net9.0。不要为了照抄示例而随意更改目标框架；目标版本需要与项目使用的 SDK、依赖和部署环境相匹配。

在现代 C# 项目中，Program.cs 可以使用顶级语句，不必显式声明 Main 方法和程序类。下面两种形式表达的都是程序入口，只是写法不同。

简洁的顶级语句：

Console.WriteLine("从程序入口开始执行。");

传统的入口形式：

using System;

internal class Program
{
    private static void Main(string[] args)
    {
        Console.WriteLine("从程序入口开始执行。");
    }
}

刚开始学习时，顶级语句通常更容易阅读。学习类、方法和程序入口后，再理解传统写法也不迟。需要注意的是，顶级语句不是另一种运行机制，最终程序仍然有入口点。

dotnet run 适合开发时快速构建并启动程序。仅构建而不运行，可以执行：

dotnet build

构建结果通常放在项目的 bin 目录，编译中间文件通常放在 obj 目录。这些目录一般由构建工具生成，不需要手动编辑。

五、读取和验证命令行参数

控制台程序经常需要接收参数。例如：

dotnet run -- hello

在 dotnet run 后使用 --，可以将后面的内容作为应用程序参数传递，而不是交给 dotnet run 自身处理。程序入口参数通常是字符串数组；在顶级语句中，可以使用 args 访问它。

下面的程序接收一个姓名参数。将 Program.cs 替换为：

if (args.Length == 0)
{
    Console.Error.WriteLine("用法：HelloConsole <姓名>");
    return 2;
}

string name = args[0].Trim();

if (name.Length == 0)
{
    Console.Error.WriteLine("姓名不能为空。");
    return 2;
}

Console.WriteLine($"你好，{name}！");
return 0;

运行：

dotnet run -- 小林

预期会输出：

你好，小林！

这个例子同时展示了几个常见做法：

• 先检查参数数量，再访问 args[0]，避免索引越界。
• 对用户输入进行基本校验，不假设参数一定有效。
• 把正常结果写到标准输出，把错误说明写到标准错误。
• 用返回码表示程序执行结果。通常 0 表示成功，非零值表示发生了某类失败；具体含义由程序约定。

也可以在启动程序时检查退出码。在类 Unix shell 中，程序退出码常可通过 $? 查看；在 PowerShell 中，可以查看 $LASTEXITCODE。不同 shell 的语法和行为有所差异，应以当前环境为准。

如果参数表示数字，不要直接假设它可以转换。例如，下面的程序接收一个整数并将其加一：

if (args.Length != 1)
{
    Console.Error.WriteLine("用法：程序名 <整数>");
    return 2;
}

if (!int.TryParse(args[0], out int value))
{
    Console.Error.WriteLine("参数必须是有效的 32 位整数。");
    return 2;
}

Console.WriteLine(value + 1);
return 0;

int.TryParse 会在转换失败时返回 false，不会因为格式错误而抛出格式转换异常。这里限定的是 C# 的 int 类型范围，不是命令行参数本身的通用长度限制。

六、命令行参数有哪些限制

命令行参数以字符串形式进入程序。参数由谁拆分、引号如何解释、允许多长，都与操作系统、启动方式、shell 和具体进程创建 API 有关，不能简单概括成一个适用于所有环境的固定上限。

例如，在 shell 中输入带空格的参数时，通常需要使用引号：

dotnet run -- "小林 同学"

应用程序收到的通常是一个包含空格的参数，而不是两个参数。不过，引号规则会因 shell 而异；复制命令到 PowerShell、Windows 命令提示符和 Bash 时，必要时应分别测试。

参数适合传递少量配置值、选项、路径或标识符，不适合传递大量数据。很长的参数可能触及平台或启动方式的限制，也可能被日志、自动化工具或 shell 的规则影响。需要处理大量文本时，优先考虑从文件或标准输入读取，并为文件大小、编码和失败情况制定明确策略。

参数通常会以明文形式出现在命令行中，可能被进程查看工具、系统审计记录、自动化平台日志或操作历史记录收集。具体可见范围取决于操作系统和运行环境。因此，不应将密码、访问令牌、私钥等机密直接放在命令行参数里。可以使用权限受控的凭据管理机制，或按应用场景使用标准输入、操作系统凭据服务和安全的密钥管理方案。标准输入也不是自动安全的：输入可能被记录、重定向或暴露给其他组件，仍需谨慎评估。

七、交互式输入与非交互式运行

需要与人交互时，可以从控制台读取输入。不过，并非每次运行都有可供用户操作的终端。例如，程序可能运行在计划任务、容器、持续集成流水线或标准输入已被重定向的环境中。在这些场景里，等待用户输入可能导致任务挂起。

下面是一个读取一行输入并处理输入结束的示例：

Console.Write("请输入一行文字：");
string? line = Console.ReadLine();

if (line is null)
{
    Console.Error.WriteLine("没有可读取的输入。");
    return 1;
}

Console.WriteLine($"你输入了：{line}");
return 0;

当用户正常输入后按回车，程序会得到一行内容；当输入流到达末尾时，ReadLine 返回 null。输入流可能因文件结束、管道关闭或其他原因结束，不一定代表程序出错。如何处理应由业务需求决定。

如果程序必须支持自动化，通常应提供非交互模式：通过参数或配置指定必要信息，输入缺失或无效时及时报错并退出，而不是永远等待交互。也可以设计超时或明确的取消机制，避免长期占用执行资源。

八、标准输出、标准错误与退出码

把正常结果和错误信息分别输出，有利于用户阅读，也方便其他程序处理。正常数据写入标准输出，诊断信息写入标准错误。下面的示例展示了基本区分：

if (args.Length == 0)
{
    Console.Error.WriteLine("缺少必要参数。");
    return 2;
}

Console.WriteLine($"收到参数：{args[0]}");
return 0;

在支持重定向的终端环境中，标准输出和标准错误可以分别处理。shell 的重定向语法并不完全一致，编写脚本时应检查目标平台的文档。无论如何，不要把“写到了控制台”理解为“只会被当前用户看到”；服务日志、容器日志和自动化系统都可能收集这些内容。

退出码对自动化尤其重要。只向屏幕打印“失败”，却仍以成功状态退出，会让调用方误以为任务已经完成。反过来，错误码也不应随意变化：如果程序会被脚本调用，建议把返回码约定写入帮助信息或文档中。

九、添加帮助信息和参数检查

当参数变多时，先明确参数的语法，再处理其值。下面的例子接受 --name 选项，未提供姓名时显示用法：

if (args.Length == 0 ||
    args[0] == "--help" ||
    args[0] == "-h")
{
    Console.WriteLine("用法：程序名 --name <姓名>");
    Console.WriteLine("示例：dotnet run -- --name 小林");
    return 0;
}

if (args.Length != 2 || args[0] != "--name")
{
    Console.Error.WriteLine("参数无效。使用 --help 查看用法。");
    return 2;
}

string name = args[1].Trim();

if (name.Length == 0)
{
    Console.Error.WriteLine("姓名不能为空。");
    return 2;
}

Console.WriteLine($"你好，{name}！");
return 0;

用 dotnet run 测试该示例时，传给应用程序的第一个参数是 --name，因此命令写作：

dotnet run -- --name 小林

这段代码适用于只有少数选项的小程序。参数较多时，手工处理顺序、重复项、可选值和组合规则很容易出错。可以考虑使用成熟的命令行解析库，或采用适合项目目标框架的命令行 API。无论选哪种方式，都要定义重复参数、未知参数、缺少参数值和帮助选项的行为。

十、文件路径与当前工作目录

文件操作是控制台程序的常见用途，也很容易产生“换个目录就找不到文件”的问题。相对路径通常是相对于进程的当前工作目录解析的，不一定相对于 Program.cs 所在目录或可执行文件所在目录。

可以在开发时打印当前工作目录以便排查：

Console.WriteLine($"当前工作目录：{Environment.CurrentDirectory}");

如果程序接收输入路径，应检查文件是否存在，并对错误进行说明。例如：

if (args.Length != 1)
{
    Console.Error.WriteLine("用法：程序名 <文件路径>");
    return 2;
}

string path = args[0];

if (!File.Exists(path))
{
    Console.Error.WriteLine($"找不到文件：{path}");
    return 1;
}

try
{
    string text = File.ReadAllText(path);
    Console.WriteLine(text);
}
catch (IOException ex)
{
    Console.Error.WriteLine($"读取文件失败：{ex.Message}");
    return 1;
}
catch (UnauthorizedAccessException)
{
    Console.Error.WriteLine("没有权限读取该文件。");
    return 1;
}

return 0;

这里展示的是适合小文件的简单读取方式。File.ReadAllText 会将内容整体读入内存，不适合不受控的大文件或持续数据流。处理大文件时，应考虑逐行读取或流式处理，并明确字符编码、文件大小和资源释放策略。对外部输入路径也不应盲目拼接成敏感目录中的目标路径；涉及写入时尤其要防止覆盖不该修改的文件。

十一、常见错误及排查方法

1. 提示找不到 dotnet

这通常意味着 SDK 未安装，或者终端找不到 SDK 命令。先确认安装的是 SDK 而非仅运行时，再检查 PATH，并重新启动终端。企业设备可能还有软件安装权限或网络策略限制，需要遵守组织环境要求。

2. 在错误目录执行命令

dotnet run 通常需要在项目目录中执行，或者明确指定项目文件。若提示找不到项目，请检查当前目录下是否有 .csproj 文件。可以用 pwd、cd 等命令确认当前位置；具体命令因 shell 和操作系统而异。

3. 把应用参数传给了 SDK 命令

使用 dotnet run 时，应用程序参数通常放在分隔符 -- 后面。例如：

dotnet run -- --help

没有分隔符时，某些内容可能被解释为 dotnet run 的选项，而非应用程序参数。

4. 访问不存在的参数下标

直接读取 args[0]，但未检查 args.Length，在没有传入参数时会发生越界异常。先验证参数数量，再读取数组内容。

5. 参数带空格却被拆开

检查启动命令中的引号是否符合当前 shell 的语法，并通过程序打印每个参数确认实际接收结果。不要想当然地把某个 shell 的引用规则应用到所有终端。

6. 文件路径只在一个目录下有效

相对路径取决于当前工作目录。通过绝对路径或明确的工作目录减少歧义；如果程序需要基于配置文件位置寻找资源，应把基准目录设计清楚并写进文档。

7. 程序没有输出但看起来“卡住”

程序可能正在等待标准输入，也可能在执行耗时操作。检查是否调用了 Console.ReadLine，输入是否被重定向，以及是否存在未完成的网络或文件操作。自动化环境中不应依赖无人值守任务可以弹出交互提示。

8. 输出乱码或编码不一致

终端、输入文件和程序采用的字符编码可能不同。先确认终端支持所需字符，再检查读取和写入文件时指定的编码。不要把乱码一概归因于源代码文件；问题也可能发生在终端、重定向目标或文件编码上。

十二、控制台程序的安全边界

控制台程序和其他应用程序一样，需要把命令行参数、标准输入、文件内容、环境变量和网络响应视为可能不可信的数据。输入验证不能只依赖“正常用户会按说明操作”。参数校验应与实际用途一致：限制允许的格式、路径范围、数据大小和可执行操作，并在失败时安全退出。

不要用字符串拼接的方式将外部输入直接构造成 shell 命令或 SQL 语句。调用外部程序时，尽量使用不经过 shell 的进程启动接口，并按目标框架的 API 规则分别传递可执行文件和参数。构造数据库查询时使用参数化查询。不同平台上的可执行文件查找、参数传递和路径规则存在差异，安全相关代码应针对部署平台进行测试。

此外，还要留意文件权限和错误信息。程序不应在没有必要时以管理员或 root 身份运行；日志也不应记录密码、令牌或完整的敏感输入。异常消息有助于排查问题，但直接向最终用户泄露内部路径、堆栈或凭据也可能造成风险。是否显示详细诊断信息，应结合程序运行环境和日志访问控制来决定。

控制台程序不是安全边界。把程序改成命令行工具，不能替代操作系统权限、服务端授权、加密传输或安全的凭据管理。它可以实现安全功能，但这些能力来自正确的设计、依赖库和部署配置，而不是来自“控制台”这个应用类型。

十三、构建、发布与分发

开发期间使用 dotnet run 最方便。准备发布时，可以先进行发布构建：

dotnet publish -c Release

发布产物会输出到项目的发布目录，具体路径通常包含目标框架和运行标识符等信息。仅执行上述命令，并不意味着一定生成了适用于所有操作系统的独立可执行文件。

部署方式有两类常见取舍。依赖框架的发布产物通常需要目标环境安装匹配的 .NET 运行时；自包含发布则将相应运行时一并带上，文件会更大，并且需要针对目标操作系统和架构发布。是否启用单文件等发布选项，也要结合项目依赖和目标环境验证。跨平台运行不是只把一个平台编译出的文件复制到另一个平台就能保证实现的，发布时要明确操作系统与处理器架构。

发布后应在接近真实部署环境的机器或容器中测试，特别检查运行时、文件权限、工作目录、路径分隔符、编码、网络访问和环境变量。开发机上能运行，并不等于生产环境一定具备相同条件。

十四、什么时候应该选控制台程序

控制台程序尤其适合以下情况：

• 功能集中、交互步骤少，文本输入输出足以表达结果。
• 需要被脚本、计划任务或持续集成流程调用。
• 主要处理文件、数据、命令或后台任务，不需要图形界面。
• 需要提供可组合的小工具，并以输入、输出和退出码连接其他工具。

如果程序面向需要图形操作的普通用户，或需要持续显示复杂状态、管理大量配置、提供可视化反馈，控制台可能不是合适的主要界面。如果任务长时间运行，需要考虑进度、取消、日志和无人值守行为；如果程序要作为长期服务运行，还要进一步设计服务管理、健康检查、并发、资源限制和部署方式。控制台入口本身不会自动提供这些能力。

十五、从第一个程序开始的实践建议

一个可靠的小型控制台程序，通常至少要明确四件事：它接受什么输入，输入无效时怎么办，正常结果从哪里输出，失败时如何告知调用方。接下来再考虑帮助信息、日志、配置来源、路径规则和退出码。把这些约定设计清楚，往往比一开始增加很多功能更有价值。

可以按下面的顺序练习：

1. 创建项目并运行 Console.WriteLine。
2. 用 Console.ReadLine 读取一行输入，并处理 null。
3. 通过 args 接收参数，先验证数量再使用。
4. 用 TryParse 等方法检查格式，避免把不可信输入当成有效数据。
5. 区分标准输出、标准错误和退出码。
6. 加入文件或其他 I/O 时，考虑路径、权限、编码、数据大小和异常。
7. 执行发布构建，并在目标运行环境中实际测试。

到这里，一个可运行的控制台应用程序就从创建、输入输出和参数处理扩展到了基本的工程实践。它没有图形界面，却可以清晰地与用户、脚本和其他程序协作。理解其参数、路径、运行环境和安全边界后，再按实际需求选择依赖、配置方式和发布策略，便能让这个小小的程序成为可维护、可自动化的工具。