> For the complete documentation index, see [llms.txt](https://docs.zongsoft.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zongsoft.com/framework/core/common/annotation-utility.md).

# 注解工具

AnnotationUtility 成员注解读取工具。

`AnnotationUtility` 用于从类型成员读取显示相关注解，包括分类、显示名称和描述。

| 方法               | 说明                                                                                                                                                                                                                                              |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GetCategory`    | 读取 [`CategoryAttribute`](https://learn.microsoft.com/zh-cn/dotnet/api/system.componentmodel.categoryattribute) [*源码*](https://source.dot.net/#System.ComponentModel.Primitives/CategoryAttribute.cs)。                                           |
| `GetDisplayName` | 读取 [`DisplayNameAttribute`](https://learn.microsoft.com/zh-cn/dotnet/api/system.componentmodel.displaynameattribute) [*源码*](https://source.dot.net/#System.ComponentModel.Primitives/DisplayNameAttribute.cs) 或 `DisplayAttribute.Name`。        |
| `GetDescription` | 读取 [`DescriptionAttribute`](https://learn.microsoft.com/zh-cn/dotnet/api/system.componentmodel.descriptionattribute) [*源码*](https://source.dot.net/#System.ComponentModel.Primitives/DescriptionAttribute.cs) 或 `DisplayAttribute.Description`。 |

来源：[framework/externals/aliyun/src/Telecom/PhoneTransmitter.cs](https://github.com/Zongsoft/framework/blob/main/externals/aliyun/src/Telecom/PhoneTransmitter.cs#L71)（节选；上下文见源文件）。

{% code title="PhoneTransmitter.cs" %}

```csharp
_descriptor = new TransmitterDescriptor(this.Name, AnnotationUtility.GetDisplayName(this.GetType()), AnnotationUtility.GetDescription(this.GetType()));
```

{% endcode %}

## 从注解到显示元数据

上面是框架 Aliyun PhoneTransmitter 创建发送器描述符的实际代码。该类型使用 DisplayName 和 Description 特性声明资源键，AnnotationUtility 读取注解并配合资源机制得到标题与说明。完整示例见[模板发送器](/framework/core/communication/transmitter.md)，资源查找见[资源管理](/framework/core/resources.md)。Discussions 的模型字段和枚举也依赖资源描述，但没有这段发送器代码。

## 什么时候使用

当模型、命令或配置项的说明由类型声明统一维护时，读取注解能避免在每个界面重复保存名称。注解负责展示元数据，不参与数据库列名匹配，也不能代替参数验证。缺失注解或资源时应按调用方显示约定处理，不要把返回的标题用于权限键或持久标识。

## 相关资源

* [AnnotationUtility.cs](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Core/src/Common/AnnotationUtility.cs)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.zongsoft.com/framework/core/common/annotation-utility.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.