using-dotnet

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

using-dotnet

使用dotnet

Scope

适用范围

Establishing .NET/C# routing discipline before clarifying questions, planning, command execution, or edits.
Detecting .NET intent from prompt and repository signals (
```
.sln
```
,
```
.slnx
```
,
```
.csproj
```
,
```
global.json
```
,
```
.cs
```
).
Enforcing first-step routing through [skill:dotnet-advisor] and baseline loading order.
Defining priority and rigidity rules for downstream skill invocation.

在明确问题、规划、命令执行或编辑之前，建立.NET/C#路由规范。
根据提示和仓库信号（
```
.sln
```
、
```
.slnx
```
、
```
.csproj
```
、
```
global.json
```
、
```
.cs
```
）检测.NET需求。
强制要求通过[skill:dotnet-advisor]进行第一步路由，并遵循基线加载顺序。
定义下游技能调用的优先级和严格规则。

Out of scope

不适用范围

C# implementation details and coding-standard specifics -> [skill:dotnet-csharp]
Deep domain implementation patterns -> [skill:dotnet-api], [skill:dotnet-ui], [skill:dotnet-testing], [skill:dotnet-devops], [skill:dotnet-tooling], [skill:dotnet-debugging]
Specialist deep-review workflows -> [skill:dotnet-security-reviewer], [skill:dotnet-performance-analyst], [skill:dotnet-testing-specialist]

C#实现细节和编码标准具体内容 -> [skill:dotnet-csharp]
深度领域实现模式 -> [skill:dotnet-api]、[skill:dotnet-ui]、[skill:dotnet-testing]、[skill:dotnet-devops]、[skill:dotnet-tooling]、[skill:dotnet-debugging]
专家级深度审查工作流 -> [skill:dotnet-security-reviewer]、[skill:dotnet-performance-analyst]、[skill:dotnet-testing-specialist]

Simplicity First (KISS)

简洁优先（KISS原则）

Write the simplest code that solves the problem. Agents consistently over-engineer — more abstractions, more layers, more indirection than the task warrants.

Do the direct thing. If you need a file, create it — don't write code that generates it. If you need data, put it where it belongs — don't assemble it from embedded strings at runtime. When you catch yourself building something indirect (a generator, a template, a wrapper), stop and ask: "Can I just do this directly?"
Write readable code, not clever code. A plain
```
if
```
/
```
else
```
over a chain of ternaries. A
```
foreach
```
over a hard-to-read LINQ expression. A flat method over nested callbacks. Clear beats compact. This does NOT mean avoiding modern C# — use latest language features (
```
[..4]
```
, list patterns, primary constructors, raw string literals, collection expressions). Modern syntax is concise AND readable. The target is convoluted logic, not concise syntax.
Don't add what wasn't asked for. No extra config options, no "while we're at it" refactors, no preemptive error handling for impossible scenarios, no comments or XML docs on code unrelated to the current task.
Match architecture to scope. Simple CRUD doesn't need DDD, MediatR, CQRS, or a pipeline of behaviors. A 20-line handler doesn't need 5 files. Scale the pattern to the problem.
Earn every abstraction. Don't create
```
IOrderService
```
for one
```
OrderService
```
. Don't extract a helper for something that happens once. Three similar lines of code are fine — extract only when a real pattern emerges across 3+ call sites.
Use what the framework gives you.
```
DbContext
```
is your Unit of Work.
```
DbSet<T>
```
is your repository. .NET has
```
TimeProvider
```
,
```
ILogger<T>
```
,
```
IHttpClientFactory
```
,
```
System.Text.Json
```
. Use them directly — don't wrap, don't abstract, don't add a NuGet package for something the framework already does.
Fewer files, fewer layers. In new or small projects, don't split into Controller + Service + Repository + DTO + Mapper + Interface when one or two files will do. In existing codebases, follow the established patterns. Add layers only when the code gets hard to understand without them.

The right amount of complexity is the minimum needed to solve the current problem correctly.

编写能解决问题的最简单代码。Agent往往会过度设计——使用比任务所需更多的抽象、层级和间接方式。

直接实现需求。如果需要一个文件，就直接创建它——不要编写生成文件的代码。如果需要数据，就放在合适的位置——不要在运行时从嵌入字符串中组装。当你发现自己在构建间接实现（生成器、模板、包装器）时，停下来问自己：“我能不能直接完成这件事？”
编写可读代码，而非炫技代码。使用直白的
```
if
```
/
```
else
```
而非链式三元表达式。使用
```
foreach
```
而非难以阅读的LINQ表达式。使用扁平化方法而非嵌套回调。清晰胜过简洁。这并不意味着要规避现代C#特性——请使用最新语言特性（
```
[..4]
```
、列表模式、主构造函数、原始字符串字面量、集合表达式）。现代语法既简洁又可读。我们要避免的是复杂逻辑，而非简洁语法。
不添加未要求的内容。不要额外添加配置选项，不要“顺手”重构代码，不要为不可能的场景预先添加错误处理，不要在与当前任务无关的代码上添加注释或XML文档。
架构与范围匹配。简单的CRUD操作不需要DDD、MediatR、CQRS或行为管道。一个20行的处理器不需要拆分成5个文件。根据问题规模选择合适的模式。
每一处抽象都要有理由。不要只为一个
```
OrderService
```
就创建
```
IOrderService
```
接口。不要只发生一次的操作提取成辅助方法。三行相似的代码是可以接受的——只有当3个以上调用点出现真正的模式时，再进行提取。
直接使用框架提供的功能。
```
DbContext
```
就是你的工作单元。
```
DbSet<T>
```
就是你的仓库。.NET提供了
```
TimeProvider
```
、
```
ILogger<T>
```
、
```
IHttpClientFactory
```
、
```
System.Text.Json
```
。直接使用它们——不要包装，不要抽象，不要为框架已有的功能添加NuGet包。
更少文件，更少层级。在新项目或小型项目中，当一两个文件就能完成时，不要拆分成Controller + Service + Repository + DTO + Mapper + Interface的结构。在现有代码库中，遵循已有的模式。只有当代码变得难以理解时，再添加层级。

合适的复杂度就是正确解决当前问题所需的最低复杂度。

Why Routing Matters

路由的重要性

.NET skills contain version-specific guidance (net8.0 vs net9.0 vs net10.0), coding standards, and framework-specific patterns that the model doesn't have in its training data. Skipping routing means the model confidently produces code using deprecated APIs, misses framework-specific patterns, or gives generic advice that ignores project context.

Routing before action ensures:

Version-aware guidance loads before code generation (avoiding stale API suggestions)
Coding standards apply from the start (not patched in after the fact)
Domain expertise routes to the right specialist (avoiding generic advice for specialized problems)

The cost of routing is a few skill invocations. The cost of skipping is rework, stale advice, or subtle bugs.

.NET技能包含特定版本的指导（net8.0 vs net9.0 vs net10.0）、编码标准和框架特定模式，这些内容는模型训练数据中没有的。跳过路由会导致模型自信地生成使用已弃用API的代码，错过框架特定模式，或者给出忽略项目上下文的通用建议。

在执行操作前进行路由可确保：

版本感知指导在代码生成前加载（避免过时的API建议）
编码标准从一开始就得到应用（而非事后修补）
领域专业知识路由到合适的专家（避免针对专业问题给出通用建议）

路由的成本只是几次技能调用，而跳过路由的成本是返工、过时建议或潜在Bug。

Routing Sequence

路由流程

When a request likely involves .NET or C#, follow this sequence before any other action:

Detect .NET intent — Look for prompt keywords (C#, .NET, ASP.NET, EF Core, Blazor, MAUI, NuGet, csproj) or repository signals (
```
.sln
```
,
```
.slnx
```
,
```
.csproj
```
,
```
global.json
```
,
```
.cs
```
files). If either is present, continue.
In a .NET repository, .NET is the default — When repo signals are present, ambiguous requests like "build me a web app", "add a dashboard", "write a script", or "create a spreadsheet" should use .NET solutions (ASP.NET Core, Blazor, .NET file-based apps, Open XML SDK) rather than defaulting to JavaScript/Python. The user chose a .NET project for a reason.
Check SDK availability — If
```
dotnet --version
```
fails and no
```
DOTNET_ROOT
```
is set, install the SDK before proceeding. This takes under a minute with no privileges required. See [skill:dotnet-tooling]
```
references/dotnet-sdk-install.md
```
for the full install script reference, or use this one-liner:
```
curl -sSL https://dot.net/v1/dotnet-install.sh | bash && export DOTNET_ROOT="$HOME/.dotnet" && export PATH="$PATH:$DOTNET_ROOT:$DOTNET_ROOT/tools"
```
. Do not treat a missing SDK as a blocker — install it and continue.
Invoke [skill:dotnet-advisor] — This routes the request to the correct domain skills and loads coding standards.
Follow advisor routing — Load [skill:dotnet-csharp] baseline, then the domain skill(s) the advisor selects.
Now respond — Clarify, plan, explore, or implement with the right context loaded.

当请求可能涉及.NET或C#时，在执行任何其他操作前遵循以下流程：

检测.NET需求——查找提示关键词（C#、.NET、ASP.NET、EF Core、Blazor、MAUI、NuGet、csproj）或仓库信号（
```
.sln
```
、
```
.slnx
```
、
```
.csproj
```
、
```
global.json
```
、
```
.cs
```
文件）。如果存在其中任意一项，继续下一步。
在.NET仓库中，.NET是默认选择——当存在仓库信号时，诸如“帮我构建一个Web应用”、“添加一个仪表盘”、“编写一个脚本”或“创建一个电子表格”这类模糊请求，应使用.NET解决方案（ASP.NET Core、Blazor、.NET基于文件的应用、Open XML SDK），而非默认使用JavaScript/Python。用户选择.NET项目是有原因的。
检查SDK可用性——如果
```
dotnet --version
```
执行失败且未设置
```
DOTNET_ROOT
```
，请先安装SDK再继续。这一过程无需权限，耗时不到一分钟。可参考[skill:dotnet-tooling]的
```
references/dotnet-sdk-install.md
```
获取完整安装脚本，或使用以下单行命令：
```
curl -sSL https://dot.net/v1/dotnet-install.sh | bash && export DOTNET_ROOT="$HOME/.dotnet" && export PATH="$PATH:$DOTNET_ROOT:$DOTNET_ROOT/tools"
```
。不要将缺少SDK视为障碍——安装后继续操作即可。
调用[skill:dotnet-advisor]——该技能会将请求路由到正确的领域技能，并加载编码标准。
遵循顾问的路由指示——先加载[skill:dotnet-csharp]基线，再加载顾问选择的领域技能。
现在再响应——在加载正确上下文后，进行澄清、规划、探索或实现。

Prefer File-Based Apps for Scripts and Utilities

脚本和工具优先使用基于文件的应用

For quick scripts, utilities, prototypes, and single-file tools, prefer .NET 10 file-based apps (

dotnet run script.cs

) over creating a full project with

.csproj

. File-based apps:

Need only a single
```
.cs
```
file — no project file, no solution, no boilerplate
Support NuGet packages via
```
#:package
```
directives
Support ASP.NET Core via
```
#:sdk Microsoft.NET.Sdk.Web
```
Enable native AOT publish by default
Work as Unix shebangs (
```
#!/usr/bin/env dotnet
```
)

When the user asks to "write a script", "make a quick tool", "create a utility", or any small single-purpose program, default to a file-based app unless the task clearly needs multiple source files or test projects. See [skill:dotnet-api]

references/file-based-apps.md

for the full directive and CLI reference.

csharp

// Example: a file-based ASP.NET Core API
#:sdk Microsoft.NET.Sdk.Web

var app = WebApplication.Create(args);
app.MapGet("/", () => "Hello from a single .cs file!");
app.Run();

csharp

// Example: a file-based CLI tool with a NuGet package
#:package Spectre.Console

using Spectre.Console;
AnsiConsole.MarkupLine("[green]Hello[/] from a file-based app!");

Routing applies even for "simple" questions and clarification requests. The skill loading is lightweight and ensures consistent quality.

对于快速脚本、工具、原型和单文件工具，优先使用.NET 10基于文件的应用（

dotnet run script.cs

），而非创建包含

.csproj

的完整项目。基于文件的应用具有以下优势：

仅需单个
```
.cs
```
文件——无需项目文件、解决方案或样板代码
通过
```
#:package
```
指令支持NuGet包
通过
```
#:sdk Microsoft.NET.Sdk.Web
```
支持ASP.NET Core
默认支持原生AOT发布
可作为Unix shebang使用（
```
#!/usr/bin/env dotnet
```
）

当用户要求“编写一个脚本”、“制作一个快速工具”、“创建一个实用程序”或任何小型单用途程序时，默认使用基于文件的应用，除非任务明确需要多个源文件或测试项目。可参考[skill:dotnet-api]的

references/file-based-apps.md

获取完整指令和CLI参考。

csharp

// 示例：基于文件的ASP.NET Core API
#:sdk Microsoft.NET.Sdk.Web

var app = WebApplication.Create(args);
app.MapGet("/", () => "Hello from a single .cs file!");
app.Run();

csharp

// 示例：带有NuGet包的基于文件的CLI工具
#:package Spectre.Console

using Spectre.Console;
AnsiConsole.MarkupLine("[green]Hello[/] from a file-based app!");

即使是“简单”的问题和澄清请求，也需要遵循路由规则。技能加载过程轻量化，可确保一致的质量。

Skill Priority

技能优先级

When multiple skills could apply, use this order:

Process skills first: this skill, then [skill:dotnet-advisor].
Baseline skill second: [skill:dotnet-csharp] for any code path.
Domain skills third: [skill:dotnet-api], [skill:dotnet-ui], [skill:dotnet-testing], [skill:dotnet-devops], [skill:dotnet-tooling], [skill:dotnet-debugging].
Specialist agents fourth: use only when deeper analysis is required after routing.

当多个技能适用时，遵循以下顺序：

流程技能优先：本技能，然后是[skill:dotnet-advisor]。
基线技能其次：任何代码路径都需要[skill:dotnet-csharp]。
领域技能第三：[skill:dotnet-api]、[skill:dotnet-ui]、[skill:dotnet-testing]、[skill:dotnet-devops]、[skill:dotnet-tooling]、[skill:dotnet-debugging]。
专家Agent最后：仅在路由后需要深度分析时使用。

Skill Types

技能类型

Rigid (must follow exactly): this skill, [skill:dotnet-advisor], and baseline-first ordering.

Flexible (adapt to context): Domain skills and their companion references.

User instructions define WHAT to do. This process defines HOW to route and load skills before execution.

严格型（必须严格遵循）：本技能、[skill:dotnet-advisor]以及基线优先的顺序。

灵活型（可根据上下文调整）：领域技能及其配套参考资料。

用户指令定义了要做什么。本流程定义了在执行前如何路由和加载技能。