Back to Details

dotnet-best-practices

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

.NET/C# Best Practices

.NET/C#最佳实践

Your task is to ensure .NET/C# code in ${selection} meets the best practices specific to this solution/project. This includes:
你的任务是确保${selection}中的.NET/C#代码符合本解决方案/项目特有的最佳实践，具体包括：

Documentation & Structure

文档与结构

  • Create comprehensive XML documentation comments for all public classes, interfaces, methods, and properties
  • Include parameter descriptions and return value descriptions in XML comments
  • Follow the established namespace structure: {Core|Console|App|Service}.{Feature}
  • 为所有公共类、接口、方法和属性创建全面的XML文档注释
  • 在XML注释中包含参数说明和返回值说明
  • 遵循既定的命名空间结构：{Core|Console|App|Service}.{Feature}

Design Patterns & Architecture

设计模式与架构

  • Use primary constructor syntax for dependency injection (e.g., 
    public class MyClass(IDependency dependency)
    )
  • Implement the Command Handler pattern with generic base classes (e.g., 
    CommandHandler<TOptions>
    )
  • Use interface segregation with clear naming conventions (prefix interfaces with 'I')
  • Follow the Factory pattern for complex object creation.
  • 使用主构造函数语法实现依赖注入（例如：
    public class MyClass(IDependency dependency)
    ）
  • 结合泛型基类实现命令处理程序模式（例如：
    CommandHandler<TOptions>
    ）
  • 遵循接口隔离原则并使用清晰的命名规范（接口以'I'为前缀）
  • 对于复杂对象的创建，使用工厂模式

Dependency Injection & Services

依赖注入与服务

  • Use constructor dependency injection with null checks via ArgumentNullException
  • Register services with appropriate lifetimes (Singleton, Scoped, Transient)
  • Use Microsoft.Extensions.DependencyInjection patterns
  • Implement service interfaces for testability
  • 通过构造函数实现依赖注入，并使用ArgumentNullException进行空值检查
  • 为服务注册合适的生命周期（Singleton、Scoped、Transient）
  • 遵循Microsoft.Extensions.DependencyInjection模式
  • 实现服务接口以提升可测试性

Resource Management & Localization

资源管理与本地化

  • Use ResourceManager for localized messages and error strings
  • Separate LogMessages and ErrorMessages resource files
  • Access resources via 
    _resourceManager.GetString("MessageKey")
  • 使用ResourceManager处理本地化消息和错误字符串
  • 分离LogMessage和ErrorMessage资源文件
  • 通过
    _resourceManager.GetString("MessageKey")
    访问资源

Async/Await Patterns

Async/Await模式

  • Use async/await for all I/O operations and long-running tasks
  • Return Task or Task<T> from async methods
  • Use ConfigureAwait(false) where appropriate
  • Handle async exceptions properly
  • 对所有I/O操作和长时间运行的任务使用async/await
  • 异步方法返回Task或Task<T>
  • 在合适的场景下使用ConfigureAwait(false)
  • 正确处理异步异常

Testing Standards

测试标准

  • Use MSTest framework with FluentAssertions for assertions
  • Follow AAA pattern (Arrange, Act, Assert)
  • Use Moq for mocking dependencies
  • Test both success and failure scenarios
  • Include null parameter validation tests
  • 使用MSTest框架结合FluentAssertions进行断言
  • 遵循AAA模式（Arrange、Act、Assert）
  • 使用Moq模拟依赖项
  • 测试成功和失败两种场景
  • 包含空参数验证测试

Configuration & Settings

配置与设置

  • Use strongly-typed configuration classes with data annotations
  • Implement validation attributes (Required, NotEmptyOrWhitespace)
  • Use IConfiguration binding for settings
  • Support appsettings.json configuration files
  • 使用带有数据注解的强类型配置类
  • 实现验证属性（Required、NotEmptyOrWhitespace）
  • 使用IConfiguration绑定配置项
  • 支持appsettings.json配置文件

Semantic Kernel & AI Integration

Semantic Kernel与AI集成

  • Use Microsoft.SemanticKernel for AI operations
  • Implement proper kernel configuration and service registration
  • Handle AI model settings (ChatCompletion, Embedding, etc.)
  • Use structured output patterns for reliable AI responses
  • 使用Microsoft.SemanticKernel执行AI操作
  • 实现正确的内核配置和服务注册
  • 处理AI模型设置（ChatCompletion、Embedding等）
  • 使用结构化输出模式确保AI响应的可靠性

Error Handling & Logging

错误处理与日志

  • Use structured logging with Microsoft.Extensions.Logging
  • Include scoped logging with meaningful context
  • Throw specific exceptions with descriptive messages
  • Use try-catch blocks for expected failure scenarios
  • 使用Microsoft.Extensions.Logging实现结构化日志
  • 包含带有有意义上下文的作用域日志
  • 抛出带有描述性消息的特定异常
  • 对预期的失败场景使用try-catch块

Performance & Security

性能与安全

  • Use C# 12+ features and .NET 8 optimizations where applicable
  • Implement proper input validation and sanitization
  • Use parameterized queries for database operations
  • Follow secure coding practices for AI/ML operations
  • 适当时使用C# 12+特性和.NET 8优化
  • 实现正确的输入验证和清理
  • 对数据库操作使用参数化查询
  • 遵循AI/ML操作的安全编码规范

Code Quality

代码质量

  • Ensure SOLID principles compliance
  • Avoid code duplication through base classes and utilities
  • Use meaningful names that reflect domain concepts
  • Keep methods focused and cohesive
  • Implement proper disposal patterns for resources
  • 确保符合SOLID原则
  • 通过基类和工具类避免代码重复
  • 使用能反映领域概念的有意义命名
  • 保持方法的聚焦性和内聚性
  • 为资源实现正确的释放模式",