使用C#、Xunit和NetArchTest检测异步控制器方法中await的正确使用

一、排查NetArchTest规则的常见误区 #

• 过滤非async标记的Task返回方法：有些方法直接返回Task.FromResult或Task.CompletedTask，这类场景不需要await，如果你的规则没排除这类无async关键字的方法，会导致误判。调整规则，只针对标记了async的方法做检测。
• 排除基类方法：比如ControllerBase自带的异步方法，不要纳入检测范围，避免无关触发。
• 注意嵌套代码的识别：如果await写在lambda或局部函数里，NetArchTest默认规则可能识别不到，需要更精细的语法分析逻辑。

二、用Roslyn直接解析语法树（精准检测） #

绕过NetArchTest的限制，直接用Roslyn分析项目语法树，精准判断async方法内的await使用情况，兼容所有Task返回场景：

using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.CSharp;
using Xunit;
using System.IO;
using System.Linq;

public class AsyncControllerAwaitTests
{
    [Fact]
    public void AllAsyncControllerMethods_MustUseAwait_OrReturnCompletedTask()
    {
        // 加载目标WebAPI项目
        var projectPath = Path.Combine(Directory.GetCurrentDirectory(), "../../../YourWebApiProject.csproj");
        var workspace = MSBuildWorkspace.Create();
        var project = workspace.OpenProjectAsync(projectPath).Result;
        var compilation = project.GetCompilationAsync().Result;

        // 筛选所有控制器类（继承ControllerBase/Controller）
        var controllerClasses = compilation.SyntaxTrees
            .SelectMany(tree => tree.GetRoot().DescendantNodes().OfType<ClassDeclarationSyntax>())
            .Where(cls => cls.BaseList?.Types.Any(t => 
                t.Type.ToString() is "ControllerBase" or "Controller") ?? false);

        foreach (var controller in controllerClasses)
        {
            // 获取所有标记async且返回Task的方法
            var asyncTaskMethods = controller.Members
                .OfType<MethodDeclarationSyntax>()
                .Where(m => m.Modifiers.Any(SyntaxKind.AsyncKeyword)
                    && m.ReturnType.ToString().StartsWith("Task"));

            foreach (var method in asyncTaskMethods)
            {
                // 检查方法体内是否存在await表达式
                var hasAwait = method.Body?.DescendantNodes().Any(SyntaxKind.AwaitExpression) ?? false;
                // 排除合法场景：直接返回Task.CompletedTask
                var returnsCompletedTask = method.Body?.Statements
                    .OfType<ReturnStatementSyntax>()
                    .Any(s => s.Expression?.ToString() == "Task.CompletedTask") ?? false;

                if (!hasAwait && !returnsCompletedTask)
                {
                    Assert.Fail($"控制器 {controller.Identifier.Text} 的方法 {method.Identifier.Text} 为异步方法，但未使用await且未返回Task.CompletedTask");
                }
            }
        }
    }
}

• 需引用Microsoft.CodeAnalysis和Microsoft.CodeAnalysis.CSharp NuGet包，版本与项目一致。
• 此方案直接解析代码语法，不会遗漏嵌套在lambda、局部函数里的await。

三、自定义NetArchTest规则（兼容现有测试流程） #

如果想保留NetArchTest的现有检测流程，可以扩展它的自定义条件，结合Roslyn语法分析：

using NetArchTest.Rules;
using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.CSharp;

public static class CustomArchRuleExtensions
{
    public static ConditionList MustUseAwaitInAsyncTaskMethods(this ConditionList conditions)
    {
        return conditions.MeetCustomCondition(type =>
        {
            var syntaxRef = type.DeclaringSyntaxReferences.FirstOrDefault();
            if (syntaxRef == null) return true;

            var methodNodes = syntaxRef.SyntaxTree.GetRoot().DescendantNodes()
                .OfType<MethodDeclarationSyntax>()
                .Where(m => m.Modifiers.Any(SyntaxKind.AsyncKeyword)
                    && m.ReturnType.ToString().StartsWith("Task")
                    && m.Identifier.Text == type.Name);

            foreach (var method in methodNodes)
            {
                var hasAwait = method.Body?.DescendantNodes().Any(SyntaxKind.AwaitExpression) ?? false;
                var returnsCompletedTask = method.Body?.Statements
                    .OfType<ReturnStatementSyntax>()
                    .Any(s => s.Expression?.ToString() == "Task.CompletedTask") ?? false;
                
                if (!hasAwait && !returnsCompletedTask)
                {
                    return false;
                }
            }
            return true;
        });
    }
}

测试中调用自定义规则：

[Fact]
public void AsyncControllerMethods_ComplyWithAwaitRules()
{
    var result = Types.InAssembly(typeof(WeatherForecastController).Assembly)
        .That()
        .Inherit(typeof(ControllerBase))
        .And()
        .AreClasses()
        .MustUseAwaitInAsyncTaskMethods()
        .GetResult();
    
    Assert.True(result.IsSuccessful, string.Join("\n", result.FailingTypeNames.Select(name => $"{name} 不符合异步方法规范")));
}

四、替代方案：编译时检测（Roslyn分析器） #

如果想在开发阶段就实时发现问题，可编写自定义Roslyn分析器：

• 分析器可在编译时扫描所有async+Task返回的控制器方法，检查是否包含await表达式，或是否返回Task.CompletedTask。
• 开发时直接在IDE中显示警告/错误，比单元测试更及时。

内容的提问来源于stack exchange，提问作者santosh kumar patro