Shimakaze.ComponentModel.SourceGenerator 0.0.2

dotnet add package Shimakaze.ComponentModel.SourceGenerator --version 0.0.2

NuGet\Install-Package Shimakaze.ComponentModel.SourceGenerator -Version 0.0.2

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="Shimakaze.ComponentModel.SourceGenerator" Version="0.0.2" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="Shimakaze.ComponentModel.SourceGenerator" Version="0.0.2" />
                    

                            Directory.Packages.props

<PackageReference Include="Shimakaze.ComponentModel.SourceGenerator" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add Shimakaze.ComponentModel.SourceGenerator --version 0.0.2

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: Shimakaze.ComponentModel.SourceGenerator, 0.0.2"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package Shimakaze.ComponentModel.SourceGenerator@0.0.2

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=Shimakaze.ComponentModel.SourceGenerator&version=0.0.2
                    

                            Install as a Cake Addin

#tool nuget:?package=Shimakaze.ComponentModel.SourceGenerator&version=0.0.2
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Shimakaze.ComponentModel.SourceGenerator

一个 C# Roslyn 增量源代码生成器 (Incremental Source Generator)，为 DynamicDescriptionAttribute 提供编译时资源解析支持，替代运行时反射，实现强类型、高性能的描述字符串查找。

功能

编译时资源解析：通过 nameof(Resource.Member) 表达式在编译期解析资源键，生成高效的 switch 映射代码。
零反射开销：生成的代码直接访问资源属性，无需运行时反射。
诊断提示：内建多项 Roslyn 分析器诊断（DESC001–DESC004），引导正确使用 Attribute。

安装

<PackageReference Include="Shimakaze.ComponentModel.SourceGenerator" Version="1.0.0">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
</PackageReference>

此包为 Source Generator，无需在运行时引用，建议标记为 PrivateAssets="all"。

使用方式

在任意类或成员上应用 [DynamicDescription(nameof(MyResources.SomeKey))]：

using Shimakaze.ComponentModel;

public enum Status
{
    [DynamicDescription(nameof(Resources.Active))]
    Active,

    [DynamicDescription(nameof(Resources.Inactive))]
    Inactive
}

如果资源文件中定义了 Resources.Active 和 Resources.Inactive，Source Generator 将自动生成以下代码：

internal sealed partial class DynamicDescriptionAttribute : DescriptionAttribute
{
    private static partial string GetDescription(string description) => description switch
    {
        "Active" => Resources.Active,
        "Inactive" => Resources.Inactive,
        _ => description,
    };
}

运行时调用 Description 属性即可直接返回解析后的资源字符串。

诊断规则

规则 ID	严重级别	说明
DESC001	Info	建议使用 `nameof(Resource.Member)` 表达式以启用强类型资源解析。
DESC002	Warning	`nameof` 表达式无效，必须是 `nameof(Resource.Member)` 格式。
DESC003	Warning	无法从 `nameof` 表达式中解析资源类型。
DESC004	Warning	`DynamicDescriptionAttribute` 至少需要一个参数。

工作原理

graph LR
    A[标注 DynamicDescriptionAttribute] --> B[IncrementalGenerator 收集所有使用点]
    B --> C[解析 nameof 表达式 - 提取类型和成员名]
    C --> D[生成 GetDescription 方法]
    D --> E[编译时 switch 映射]

DynamicDescriptionGenerator 是一个 IIncrementalGenerator：

初始化阶段 – 生成 DynamicDescriptionAttribute 的 partial 类骨架（带 GetDescription 部分方法声明）。
收集阶段 – 通过 ForAttributeWithMetadataName 收集所有 [DynamicDescription] 的使用点，解析 nameof 表达式提取资源类型和成员名。
生成阶段 – 将所有映射聚合为 switch 表达式，写入 DynamicDescriptionAttribute.GetDescription 的实现。