使用内容而非文件编译Razor文档时触发ArgumentNullException

操作代码 #

尝试直接读取Razor文件内容并编译，代码如下：

var content = File.ReadAllText("RazorComponent.razor");
var document = RazorSourceDocument.Create(content, (string?)null);
var engine = RazorProjectEngine.Create(
    RazorConfiguration.Default,
    RazorProjectFileSystem.Create("."),
    builder =>
    {
        builder.ConfigureClass((doc, node) =>
        {
            node.BaseType = typeof(ComponentBase).FullName;
        });
    });

// 触发ArgumentNullException: 'Value cannot be null. (Parameter 'value')'
var codeDocument = engine.Process(source: document, fileKind: null, importSources: [], tagHelpers: []);

错误堆栈跟踪 #

at Microsoft.AspNetCore.Razor.Language.CodeGeneration.CodeWriter.Write(String value)
at Microsoft.AspNetCore.Razor.Language.CodeGeneration.DefaultDocumentWriter.Visitor.VisitDocument(DocumentIntermediateNode node)
at Microsoft.AspNetCore.Razor.Language.CodeGeneration.DefaultDocumentWriter.WriteDocument(RazorCodeDocument codeDocument, DocumentIntermediateNode documentNode)
at Microsoft.AspNetCore.Razor.Language.DefaultRazorCSharpLoweringPhase.ExecuteCore(RazorCodeDocument codeDocument)
at Microsoft.AspNetCore.Razor.Language.RazorEnginePhaseBase.Execute(RazorCodeDocument codeDocument)
at Microsoft.AspNetCore.Razor.Language.DefaultRazorEngine.Process(RazorCodeDocument document)
at Microsoft.AspNetCore.Razor.Language.DefaultRazorProjectEngine.ProcessCore(RazorCodeDocument codeDocument)
at Microsoft.AspNetCore.Razor.Language.DefaultRazorProjectEngine.Process(RazorSourceDocument source, String fileKind, IReadOnlyList`1 importSources, IReadOnlyList`1 tagHelpers)
at ...Test() in C:\...\Program.cs:line 43
at ...Program.<Main>d__1.MoveNext() in C:\...\Program.cs:line 65

补充信息 #

• RazorComponent.razor文件存在且有效，仅包含HTML标记
• 直接从文件系统加载文件时（少量修改）可成功执行

问题原因 #

核心问题是创建RazorSourceDocument时传入了null的文件路径参数。Razor引擎在代码生成阶段，需要使用文件路径推导命名空间、生成类名等关键信息，空路径会导致后续代码写入逻辑调用CodeWriter.Write(null)，触发ArgumentNullException。

直接从文件系统加载文件时，Razor会自动获取文件的完整路径，因此不会出现该空引用问题。

解决方法 #

1. 传入真实文件路径 #

即使是读取内容后创建RazorSourceDocument，也可以传入原文件的真实路径：

var content = File.ReadAllText("RazorComponent.razor");
// 替换null为原文件路径
var document = RazorSourceDocument.Create(content, "RazorComponent.razor");

2. 使用虚拟路径 #

如果不需要真实路径，可传入一个非null的虚拟路径（格式符合Razor引擎预期即可）：

var document = RazorSourceDocument.Create(content, "~/VirtualComponents/RazorComponent.razor");

3. 显式指定FileKind #

调用engine.Process时，建议显式指定fileKind为FileKinds.Component（对应Blazor组件场景），避免默认逻辑的潜在问题：

var codeDocument = engine.Process(
    source: document, 
    fileKind: FileKinds.Component, 
    importSources: [], 
    tagHelpers: []);

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