如何标记C# API下一版本中即将过时的方法

C# 及 .NET 生态内置了标准的弃用标记特性，不需要自定义实现，也没有必要单独设计特殊标注规则。

官方标准特性：ObsoleteAttribute #

这个特性是 .NET 基类库原生提供的，作用就是标记即将过时或已经弃用的代码成员（包括方法、类、属性、接口、枚举等所有可访问的代码结构），是整个生态统一遵循的标准。

• 基础使用方式：直接在目标成员上方添加[Obsolete]标记即可，所有主流IDE（Visual Studio、Rider、VS Code等）都会自动识别，在调用处给被标记的成员显示删除线提示，编译时也会抛出对应警告。
• 自定义提示信息：可以传入字符串参数，明确说明弃用原因、替代方案、计划移除的版本，方便调用方直接看到升级指引，示例代码：

/// <summary>
/// 旧的业务处理方法
/// </summary>
[Obsolete("该方法将在v2.0版本正式移除，请替换为NewProcessMethod方法使用")]
public void OldProcessMethod()
{
    // 旧版本实现
}

public void NewProcessMethod()
{
    // 新版本实现
}

• 强制阻断使用：如果传入第二个布尔类型参数且值为true，编译器会直接将调用该成员的代码判定为编译错误，而不只是警告，适合已经到移除节点、不允许继续调用的场景：

[Obsolete("该方法已在v1.8版本移除，禁止继续调用，请使用NewProcessMethod替代", true)]
public void OldProcessMethod()
{
    // 保留仅为兼容极老版本逻辑，新代码禁止调用
}

配套的文档标注建议 #

虽然ObsoleteAttribute已经能在编码、编译阶段给调用方强提示，还是建议配合XML文档注释做信息补充：

• 在成员的<remarks>注释块中补充更完整的弃用说明，比如旧方法存在的缺陷、新方法的使用差异、过渡版本的兼容策略等
• 对外发布的公开API需要在版本更新日志中单独列出所有被标记为弃用的成员，明确版本迭代节奏，给下游调用方留足升级缓冲时间

不要自己造Deprecated这类自定义特性用来标记弃用，自定义特性默认不会被IDE、编译器识别，既不会在写代码时给调用方弹提示，也不会在编译时出警告，等于白标。ObsoleteAttribute就是全生态通用的标准答案，所有官方类库、第三方开源组件全是用它做弃用标记的。

内容的提问来源于stack exchange，提问作者Hugo