C# on 为霜的博客

注解如何工作的 C#

Wed, 23 Apr 2025 19:50:52 +0000

1. MongoDB .Net Driver

不禁好奇为什么当存储对象到 mongodb 序列化为 BSON 或者序列化为 json 时, 如果字段上有一些注解, 他们就会自动被对应的序列化框架识别, 这是怎么实现的呢:

using MongoDB.Bson;
using Newtonsoft.Json;

public class MessageModel
{
    // MongoDB .Net Driver 相关注解
    [BsonId]
    [BsonRepresentation(BsonType.ObjectId)]
    public string Id { get; set; }
  
    // JSON 注解
    [JsonConverter(typeof(CustomDateTimeConverter))]
    public DateTime CreateTime { get; set; } = DateTime.Now;
}

1.1. MongoDB 注解

反射（Reflection）：MongoDB .Net Driver 在序列化或反序列化对象时，会通过反射检查类的结构，识别是否有特定的属性（如 [BsonId]、[BsonRepresentation]）
序列化器（Serializer）：MongoDB .Net Driver 内置了一套序列化器（IBsonSerializer），它们会根据注解动态调整序列化行为
- [BsonId]：标记某个字段为主键（MongoDB 中的 _id 字段），驱动会确保这个字段被正确映射到 _id
- [BsonRepresentation(BsonType.ObjectId)]：指定字段在 MongoDB 中存储为 ObjectId 类型，而不是普通的字符串

具体流程：

创建一个 MessageModel 实例
当你调用 MongoDB 驱动的插入方法（如 collection.InsertOneAsync(model)）
驱动通过反射读取 MessageModel 类的元数据，发现 Id 字段有 [BsonId] 和 [BsonRepresentation(BsonType.ObjectId)]
驱动将 Id 字段映射为 MongoDB 文档的 _id 字段，并确保其值符合 ObjectId 格式
其他字段（如 CreateTime）也会根据默认或自定义的序列化规则转换为 BSON 格式

1.2. JSON 注解

反射（Reflection）：Json.NET 在序列化或反序列化对象时，会通过反射检查类的属性，查找是否有 [JsonConverter] 等注解

自定义转换器（JsonConverter）：[JsonConverter(typeof(CustomDateTimeConverter))] 告诉 Json.NET 在序列化 CreateTime 字段时，使用 CustomDateTimeConverter 类来控制输出格式（例如，格式化日期时间为特定的字符串格式）

2. Json.NET (Newtonsoft.Json)

非常流行的开源 .NET 库，用于处理 JSON 数据，它在 .NET 社区中广为人知，因此很多人直接称它为 Json.NET，而不是完整的命名空间 Newtonsoft.Json，它提供了一组类和方法，用于：

序列化：将 C# 对象转换为 JSON 字符串
反序列化：将 JSON 字符串转换回 C# 对象
自定义序列化：通过特性（如 [JsonConverter] 注解）或配置，允许开发者控制 JSON 的格式和行为

var person = new { Name = "Alice", Age = 30 };
string json = JsonConvert.SerializeObject(person);
// 输出: {"Name":"Alice","Age":30}

string json = "{\"Name\":\"Alice\",\"Age\":30}";
var person = JsonConvert.DeserializeObject<dynamic>(json);
// person.Name == "Alice"

JsonConvert 是 Newtonsoft.Json 命名空间中的一个静态类，属于 Json.NET 库

Extension Namespaces C#

Fri, 18 Apr 2025 21:07:20 +0000

In C#, extension namespaces are essentially used to organize extension methods. Extension methods were introduced in C# 3.0 as a feature that allows you to add new methods to existing types without modifying the original type, deriving from it, or using the decorator pattern.

Extension methods must be defined in static classes
The methods themselves must be static
The first parameter is preceded by the this keyword, indicating the type being extended

using System;
using System.Collections.Generic;
using System.Linq;

// 定义包含扩展方法的命名空间
namespace ProjectUtils
{
    // 扩展方法所在的静态类
    public static class CollectionExtensions
    {
        // 为IEnumerable<T>添加一个扩展方法，用于安全地获取第一个元素
        // 与FirstOrDefault不同，这个方法可以指定默认值
        public static T GetFirstOrDefault<T>(this IEnumerable<T> source, T defaultValue)
        {
            // 检查集合是否为空
            if (source == null || !source.Any())
                return defaultValue;
                
            return source.First();
        }
    }
}

namespace SampleApp
{
    using ProjectUtils; // 导入包含扩展方法的命名空间
    
    class Program
    {
        static void Main()
        {
            // 从数据库或API获取的用户列表
            List<User> users = GetUsersFromDatabase();
            
            // 尝试获取第一个管理员用户，如果没有则返回默认的系统管理员
            User adminUser = users
                .Where(u => u.IsAdmin)
                .GetFirstOrDefault(new User { Name = "系统管理员", IsAdmin = true });
                
            Console.WriteLine($"当前管理员: {adminUser.Name}");
        }
        
        // 模拟从数据库获取用户的方法
        static List<User> GetUsersFromDatabase()
        {
            // 实际项目中，这里会连接数据库或调用API
            return new List<User>
            {
                new User { Name = "张三", IsAdmin = false },
                new User { Name = "李四", IsAdmin = false },
                // 假设今天没有管理员登录，列表中没有管理员
            };
        }
    }
    
    class User
    {
        public string Name { get; set; }
        public bool IsAdmin { get; set; }
    }
}

IMapper & Model Binding

Thu, 17 Apr 2025 21:15:52 +0000

1. `IMapper`

[Route("inventory")]
[ApiController]
public class InventoryController : ControllerBase
{
    private readonly InventoryService _inventoryService;
    private readonly IMapper _mapper;

    public InventoryController(
        InventoryService inventoryService, IMapper mapper)
    {
        _mapper = mapper;
        _inventoryService = inventoryService;
    }

    [HttpGet("stocklist")]
    public async Task<ActionResult<ResultDto>> ListAllStock()
    {
        var stockList = await _inventoryService.FindAllStock();
        return new ResultDto(200, "查询成功", _mapper.Map<List<InventoryModelDto>>(stockList));
    }
}

public class InventoryModelDto
{
    public string Id { get; set; }
    public int StockLevel { get; set; }
    public string ItemName { get; set; }
    public string LastUpdated { get; set; }
}

public class InventoryModel
{
    [BsonId]
    [BsonRepresentation(BsonType.ObjectId)]
    public string Id { get; set; }
    public int StockLevel { get; set; }
    public string ItemName { get; set; }
    [JsonConverter(typeof(CustomDateTimeConverter))]
    public DateTime LastUpdated { get; set; }
}

AutoMapper 是一个 .NET 库, 用于简化对象之间的映射, 它可以自动将一个对象的属性值复制到另一个对象的对应属性上, 减少手动编写繁琐的映射代码, 通常用于将数据库实体（如 InventoryModel）映射到 DTO（Data Transfer Object, 如 InventoryModelDto）, 以便在 API 返回数据时使用更轻量或特定格式的对象:

为什么需要映射？

InventoryModel 通常是数据库实体, 可能包含敏感字段或不适合直接暴露给客户端的数据, InventoryModelDto 是一个专为 API 响应设计的对象, 可能只包含客户端需要的字段
DTO 可以调整数据的结构或格式, 使其更适合前端使用

代码中的具体流程

_inventoryService.FindAllStock() 返回一个 List<InventoryModel>
_mapper.Map<List<InventoryModelDto>>(processlist) 将这个列表中的每个 InventoryModel 对象转换为 InventoryModelDto 对象
最终结果被包装在 ResultDto 中，作为 API 的响应返回，状态码为 200，消息为“查询成功”

类型不同会发生什么？ DateTime LastUpdated 到 string LastUpdated 的映射会发生什么?

AutoMapper 支持 DateTime 到 string 的转换, 默认调用 DateTime.ToString()
[JsonConverter(typeof(CustomDateTimeConverter))] 只在 JSON 序列化/反序列化时生效（例如，API 响应）
AutoMapper 的映射是对象层面的操作，不会调用 CustomDateTimeConverter，除非在 AutoMapper 配置中显式指定

2. POST API 如何限制前端表单传递的数据字段

[Route("api/users")]
[ApiController]
public class UserController : ControllerBase
{
    private readonly UserService _userService;
    private readonly IMapper _mapper;

    public UserController(UserService userService, IMapper mapper)
    {
        _userService = userService;
        _mapper = mapper;
    }

    [HttpPost("create")]
    public async Task<ActionResult<UserDto>> CreateUser([FromBody] UserCreateDto userCreateDto)
    {
        if (!ModelState.IsValid)
        {
            return BadRequest(ModelState);
        }

        var user = _mapper.Map<User>(userCreateDto);
        var createdUser = await _userService.CreateUserAsync(user);
        return Ok(_mapper.Map<UserDto>(createdUser));
    }
}

假设 UserCreateDto 定义如下：

public class UserCreateDto
{
    [Required(ErrorMessage = "用户名是必填项")]
    [StringLength(50, ErrorMessage = "用户名长度不能超过50个字符")]
    public string Username { get; set; }

    [Required(ErrorMessage = "邮箱是必填项")]
    [EmailAddress(ErrorMessage = "邮箱格式不正确")]
    public string Email { get; set; }

    [Range(18, 100, ErrorMessage = "年龄必须在18到100岁之间")]
    public int Age { get; set; }
}

前端通过 POST 请求发送以下 JSON 数据到 /api/users/create：

{
    "Username": "john_doe",
    "Email": "john@example.com",
    "Age": 25,
    "ExtraField": "some_value"
}

2.1. 如何限制前端表单字段？

DTO 定义限制字段：

UserCreateDto 类定义了 API 接受的字段：Username、Email 和 Age
前端发送的 JSON 数据中，只有这些字段会被绑定到 UserCreateDto 对象的相应属性
额外的字段（如 ExtraField）不会被绑定，因为 UserCreateDto 中没有对应的属性, 这种限制是通过 DTO 的结构实现的

处理前端数据的机制：

当前端发送 POST 请求时，ASP.NET Core 使用 模型绑定（Model Binding） 机制将请求体中的 JSON 数据反序列化为 UserCreateDto 对象
由于 UserCreateDto 只有 Username、Email 和 Age 三个属性，ExtraField 会被忽略，不影响 API 的处理

验证数据的有效性：

UserCreateDto 使用了数据注解（如 [Required]、[StringLength]、[EmailAddress]、[Range]）来定义验证规则
例如，如果前端发送的 JSON 缺少 Username 或 Email，或者 Email 格式不正确，ASP.NET Core 会将这些错误记录在 ModelState 中
代码中检查 if (!ModelState.IsValid)，如果验证失败，会返回 400 Bad Request 响应，包含具体的错误信息

ModelState 很重要, 我们可以在 controller 中判断是否数据反序列化成功等:
[HttpPost("user")]
public async Task<IActionResult> CreateUser([FromBody] UserCreateDto userCreateDto) {
 if (!ModelState.IsValid) {
     ...
 }
}

2.2. ASP.NET 的机制

模型绑定：将请求数据映射到 DTO，仅绑定 DTO 定义的属性
模型验证：通过数据注解（如 [Required]、[EmailAddress]）和 [ApiController] 特性验证数据有效性
绑定属性：如 [FromBody]，控制数据来源

这种机制类似于 Spring 框架的 @RequestBody 和 @Valid，但 ASP.NET Core 的 [ApiController] 提供了更自动化的验证流程

2.3. 默认检查哪些数据来源进行反序列化？

当不显式指定绑定源（如 [FromBody]、[FromQuery] 等）时，ASP.NET Core 的模型绑定系统会根据参数类型和上下文按以下优先级检查数据来源：

复杂类型（如 DTO、类）：

默认来源：在 [ApiController] 控制器中，默认从请求体（[FromBody]）绑定，通常期望 Content-Type 为 application/json 或 application/xml
如果请求体不可用（例如，Content-Type 为 application/x-www-form-urlencoded 或 multipart/form-data），也可能尝试从表单数据（[FromForm]）绑定
如果没有 [ApiController]，ASP.NET Core 可能不会自动从请求体绑定复杂类型，导致参数为 null，除非显式指定 [FromBody] 或 [FromForm]

简单类型（如 string、int、bool）：

默认来源
1. 路由参数（[FromRoute]）：如果参数名称匹配路由模板中的占位符（例如，[Route("api/users/{id}")])
2. 查询字符串（[FromQuery]）：从 URL 的查询参数绑定（例如，?name=john）
3. 表单数据（[FromForm]）：如果请求是 application/x-www-form-urlencoded 或 multipart/form-data
简单类型不会默认从请求体绑定，除非显式使用 [FromBody]

当控制器方法期望一个复杂类型（如 UserCreateDto）并使用 [FromBody]（或 [ApiController] 默认推断为 [FromBody]），ASP.NET Core 期望请求体的 Content-Type 是 application/json 或 application/xml，因为这些格式可以直接反序列化为 C# 对象

如果请求的 Content-Type 是 application/x-www-form-urlencoded 或 multipart/form-data，ASP.NET Core 的 JSON 反序列化器无法解析这些格式，导致绑定失败（参数可能为 null 或抛出异常）

application/x-www-form-urlencoded 表示请求的内容在 HTTP 请求的 Body 中，但它不是 JSON 格式，而是一串以键值对形式编码的字符串（格式如 key1=value1&key2=value2）

与 application/json 不同：

application/x-www-form-urlencoded：数据是扁平的键值对字符串，适合简单表单数据

application/json：数据是结构化的 JSON 对象，支持复杂嵌套结构

2.4. 查询字符串如何绑定到后端方法?

后端代码:

[HttpPost("user")]
public async Task<ActionResult<ResultDto>> CreateNewUser(UserModelDto user, string currentuser)

前端代码:

export const registerUser = (currentuser: string, data?: object) => {
  const _currentuser = encodeURIComponent(currentuser);
  return http.request<any>(
      "post", 
       myApi(`/user?currentuseruser=${_currentuser}`), {data});
};

上面我们说到, 在 [ApiController] 控制器中, 对于复杂类型如 Dto, 若不指定参数的数据来源, 则默认从请求体（[FromBody]）绑定, 因此 UserModelDto user 肯定是从请求体中反序列化得到, 那 string currentuser 参数怎么办?

答案也很简单: string currentuser 是简单类型，且没有显式指定 [FromBody], 所以默认从查询字符串绑定, 也就是前端的 /user?currentuseruser=${_currentuser}

2.5. 如果想上传文件，需要怎么办？

在 ASP.NET Core 中，文件上传通常通过 multipart/form-data 格式实现，结合 [FromForm] 和 IFormFile 类型来处理文件和表单数据

定义 DTO 和控制器方法：

使用 [FromForm] 绑定表单数据
使用 IFormFile 或 IFormFileCollection 接收上传的文件
确保方法支持 multipart/form-data 请求

前端发送文件：

使用 HTML 表单（enctype="multipart/form-data"）或 AJAX 请求（如 FormData）发送文件和相关数据

public class UserCreateDto
{
    [Required(ErrorMessage = "用户名是必填项")]
    public string Username { get; set; }

    [Required(ErrorMessage = "邮箱是必填项")]
    [EmailAddress(ErrorMessage = "邮箱格式不正确")]
    public string Email { get; set; }

    public int Age { get; set; }
}

[Route("api/users")]
[ApiController]
public class UserController : ControllerBase
{
    private readonly IWebHostEnvironment _environment;

    public UserController(IWebHostEnvironment environment)
    {
        _environment = environment;
    }

    [HttpPost("upload")]
    public async Task<IActionResult> UploadUser([FromForm] UserCreateDto userCreateDto, [FromForm] IFormFile file)
    {
        if (!ModelState.IsValid)
        {
            return BadRequest(ModelState);
        }

        if (file == null || file.Length == 0)
        {
            return BadRequest("No file uploaded.");
        }

        // 验证文件类型（例如，只允许图片）
        var allowedExtensions = new[] { ".jpg", ".jpeg", ".png" };
        var extension = Path.GetExtension(file.FileName).ToLowerInvariant();
        if (!allowedExtensions.Contains(extension))
        {
            return BadRequest("Invalid file type. Only JPG and PNG are allowed.");
        }

        // 保存文件到服务器（例如，wwwroot/uploads 目录）
        var uploadsFolder = Path.Combine(_environment.WebRootPath, "uploads");
        ...

        // 假设保存用户信息到数据库
        // var user = new User { Username = userCreateDto.Username, Email = userCreateDto.Email, Age = userCreateDto.Age };
        // await _userService.SaveUserAsync(user);

        return Ok(new { Message = "User and file uploaded successfully", FilePath = filePath });
    }
}

NuGet Package Management

Tue, 03 Dec 2024 19:42:36 +0000

Create new project with dotnet CLI

$dotnet new list

$dotnet new <template> -n <project-name>

# -n project name
$dotnet new console -n tts-service-csharp
$ls 
Program.cs                obj                       tts-service-csharp.sln
bin                       tts-service-csharp.csproj
# install a package for current project
$ dotnet add package Microsoft.CognitiveServices.Speech

Program.cs: contains the Main method where your program starts executing
bin folder (binary): contains the compiled output of your program, after building, you’ll find your executable (.exe) and other compiled files here.
obj folder (objects): contains temporary files used during compilation, these files can be safely deleted and will be recreated during the next build.
tts-service-csharp.csproj: the project file that defines your project settings, contains project configuration, dependencies, target framework
ts-service-csharp.sln (solution): a solution file that can contain multiple related projects, useful when your application grows and needs to be split into multiple projects.

tts-service-csharp.csproj:

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

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

  <ItemGroup>
    <PackageReference Include="Microsoft.CognitiveServices.Speech" Version="1.41.1" />
  </ItemGroup>

</Project>

All .NET projects list their dependencies in the .csproj file. If you have worked with JavaScript before, think of it like a package.json file.

The .csproj file also contains all the information that .NET tooling needs to build the project. It includes the type of the project being built (console, web, desktop, etc.), the platform this project targets and any dependencies on other projects or 3rd party libraries.

<OutputType>Exe</OutputType> stands for: Console application

$dotnet add package Microsoft.CognitiveServices.Speech

The dotnet CLI first checks if the current directory contains a valid .NET project file *.csproj
It then connects to the default package source (nuget.org) to erify the package exists
The CLI resolves dependencies by creating a dependency graph to ensure version compatibility
It then:
- Downloads the package and its dependencies to the Global NuGet cache (typically in ~/.nuget/packages)
- Adds a PackageReference element to your project file like:
```
<PackageReference Include="Microsoft.CognitiveServices.Speech" Version="x.x.x" />
```
- Updates the project’s obj/project.assets.json file which tracks all package references
Finally, it performs a restore operation to ensure all dependencies are available locally

The package gets installed in Global NuGet cache: ~/.nuget/packages/, this is shared across all projects on your machine, packages here don’t get deleted when you delete a project, if you want to clean up unused packages from the global cache, you can:

$dotnet nuget locals all --clear

# Or manually delete packages from:
~/.nuget/packages/microsoft.cognitiveservices.speech

类属性和构造方法

Sun, 21 Jul 2024 19:36:36 +0000

1. 属性和 Backing Field

1.1. Backing Field

在 C# 中, 当你创建一个类的属性时, 你实际上是在创建一种访问类内部数据的方式, 而这个内部数据就存储在 backing field 中:

public class Person {
    // 这是 backing field
    private string _name;
    
    // 这是属性
    public string Name {
        get { return _name; }
        set { _name = value; }
    }
}

对于backing field的命名, C#中有几种常见的约定:

private string _name; // 对应 Name 属性
private string m_name; // 对应 Name 属性, m 代表 member
private string name; // 对应 Name 属性

微软官方推荐使用下划线前缀（⁠_name）的命名方式，这也是.NET社区中最广泛采用的规范。

1.2. Auto-implemented Properties

C# 3.0引入了自动实现的属性, 编译器会自动生成 backing field:

public class Person {
    // 编译器会自动为属性 Name 生成一个 backing field
    public string Name { get; set; }
}

常见的例子:

public class Person {
    private int _age;
    
    public int Age {
        get { return _age; }
        set { 
            if (value < 0)
                throw new ArgumentException("Age cannot be negative");
            _age = value; 
        }
    }
}

Backing Field 是一个私有字段, 用于存储属性的实际数据

⁠value 是 C# 中的一个特殊关键字, 它只能在属性或索引器的 ⁠set 访问器中使用, 它代表调用者尝试分配给属性的值
Person person = new Person();
person.Name = "John"; // 这里的 "John" 就是 set 访问器中的 value

1.3. 只声明 get 访问器

Declare only the [get] accessor, which makes the property immutable everywhere except in the type’s constructor.

public class Person
{
    public string Name { get; } // 只声明 get

    public Person(string name)
    {
        Name = name; // 只能在构造函数中设置
    }
}

var person = new Person("Alice");
// person.Name = "Bob"; // 错误！无法修改，因为没有 set
Console.WriteLine(person.Name); // 输出: Alice

这种方式适合需要保护数据不被外部修改的场景, 比如表示一个对象的固有属性（例如身份证号）

2. 构造函数

2.1. 对象初始化器

在 C# 中, 如果一个类没有显式定义任何构造函数, 编译器会自动为该类提供一个 无参的默认构造函数, 这个默认构造函数的作用是创建一个类的实例, 并将所有字段或属性初始化为它们的默认值（例如，string 初始化为 null，int 初始化为 0）

class Person {
    public string Name { get; set; }
    public int Age { get; set; }

    public void SayHello() {
        Console.WriteLine($"Hello, I am {Name}, {Age} years old.");
    }
}

Person p = new Person { Name = "Bob", Age = 30 };

可是这里是什么意思呢, 创建实例的时候不是传了参数吗?

new Person() 确实调用了默认构造函数, 创建一个 Person 对象, 此时 Name 是 null, Age 是 0, 但紧随其后的 { Name = "Bob", Age = 30 } 是 对象初始化器 的语法, 它允许你在对象创建后立即设置属性的值, 这实际上是 C# 提供的一种简洁写法, 相当于以下代码:
Person p = new Person(); // 调用默认构造函数
p.Name = "Bob";          // 设置 Name 属性
p.Age = 30;              // 设置 Age 属性

对象初始化器的工作原理是:

先调用类的构造函数（这里是隐式的默认构造函数）
然后按照初始化器中指定的顺序, 依次设置对象的公共属性或字段

EF Core Basics

Sun, 21 Jul 2024 09:42:36 +0000

1. Rider EF Core - Migrations

Install Microsoft.EntityFrameworkCore.Design, which requires Microsoft.EntityFrameworkCore.Relational, so you need install both. I think the reason is I use MySQL: Pomelo.EntityFrameworkCore.MySql not Microsoft.EntityFrameworkCore.SqlServer which is for SqlServer.

Note that because the dependency of Pomelo.EntityFrameworkCore.MySql , the version of design and relational an other should be <= 1.xxxx. So I choose 9.0.0-preview.1.24081.2

Everytime update database with migrations, there is warning:

The Entity Framework tools version '8.0.7' is older than that of the runtime '9.0.0-preview.1.24081.2'. Update the tools for the latest features and bug fixes. See https://aka.ms/AAc1fbw for more information.

To resolve this issue:

❯ dotnet tool update --global dotnet-ef
Tool 'dotnet-ef' was reinstalled with the stable version (version '8.0.7').

~
❯ dotnet tool update --global dotnet-ef --version 9.0.0-preview.1.24081.2
Tool 'dotnet-ef' was successfully updated from version '8.0.7' to version '9.0.0-preview.1.24081.2'.