CA1831:在合适的情况下，为字符串使用 AsSpan 而不是基于范围的索引器

属性	值
规则 ID	CA1831
标题	在合适的情况下，为字符串使用 AsSpan 而不是基于范围的索引器
类别	“性能”
修复是中断修复还是非中断修复	非中断
在 .NET 8 中默认启用	作为警告

原因

对字符串使用了范围索引器，并将值隐式分配给了 ReadOnlySpan<char>。

规则说明

对字符串使用范围索引器并将其分配给范围类型时，将触发此规则。 Span<T> 上的范围索引器是非复制的 Slice 操作，但对于字符串中的范围索引器，将使用方法 Substring 而不是 Slice。 这会生成字符串所请求部分的副本。 此副本在隐式用作 ReadOnlySpan<T> 或 ReadOnlyMemory<T> 值时常常是不必要的。 如果不需要副本，请使用 AsSpan 方法来避免不必要的副本。 如果需要副本，请先将其分配给本地变量，或者添加显式强制转换。 仅在对范围索引器操作的结果使用隐式强制转换时，分析器才会报告。

检测

隐式转换：

ReadOnlySpan<char> slice = str[a..b];

不检测

显式转换：

ReadOnlySpan<char> slice = (ReadOnlySpan<char>)str[a..b];

如何解决冲突

若要解决此规则的冲突，请对字符串使用 AsSpan 而不是基于 Range 的索引器，以避免创建不必要的数据副本。

public void TestMethod(string str)
{
    // The violation occurs
    ReadOnlySpan<char> slice = str[1..3];
    ...
}

public void TestMethod(string str)
{
    // The violation fixed with AsSpan extension method
    ReadOnlySpan<char> slice = str.AsSpan()[1..3];
    ...
}

提示

Visual Studio 中为此规则提供了代码修补程序。 若要使用它，请将光标置于冲突上，然后按“Ctrl+.(句点)”。 从显示的选项列表中选择“对字符串使用 AsSpan 而不是基于范围的索引器”。

还可以通过添加显式强制转换来避免此警告。

public void TestMethod(string str)
{
    // The violation occurs.
    ReadOnlySpan<char> slice = str[1..3];
    ...
}

public void TestMethod(string str)
{
    // The violation avoided with explicit casting.
    ReadOnlySpan<char> slice = (ReadOnlySpan<char>)str[1..3];
    ...
}

何时禁止显示警告

如果需要创建副本，则可禁止显示此规则的冲突。

抑制警告

如果只想抑制单个冲突，请将预处理器指令添加到源文件以禁用该规则，然后重新启用该规则。

#pragma warning disable CA1831
// The code that's violating the rule is on this line.
#pragma warning restore CA1831

若要对文件、文件夹或项目禁用该规则，请在配置文件中将其严重性设置为 none。

[*.{cs,vb}]
dotnet_diagnostic.CA1831.severity = none

若要禁用此整个规则类别，请在配置文件中将此类别的严重性设置为 none。

[*.{cs,vb}]
dotnet_analyzer_diagnostic.category-Performance.severity = none

有关详细信息，请参阅如何禁止显示代码分析警告。

相关规则

• CA1832:使用 AsSpan 或 AsMemory 而不是基于范围的索引器来获取数组的 ReadOnlySpan 或 ReadOnlyMemory 部分
• CA1833:使用 AsSpan 或 AsMemory 而不是基于范围的索引器来获取数组的 Span 或 Memory 部分

另请参阅

• 性能规则