ASP.NET Core 中的 Razor 文件编译

项目
2025-05-28

扩展名为 Razor 的 .cshtml 文件是在生成和发布时使用 Razor SDK 编译的。通过配置项目，可以选择启用运行时编译。

注意

运行时编译：

不受 Razor 应用的 Blazor 组件支持。
不支持全局使用指令。
不支持隐式使用指令。
禁用 .NET 热重载。
建议用于开发，而不是生产。

Razor 编译

Razor SDK 默认启用 Razor 文件的生成时和发布时编译。启用后，运行时编译将会对生成时编译进行补充，从而允许更新 Razor 文件（如果在应用运行时对其进行编辑）。

使用 Razor还支持在应用程序运行的同时在开发过程中更新 Razor 视图和页面。

注意

启用后，运行时编译将禁用 .NET 热重载。建议在开发期间使用热重载而不是 Razor 运行时编译。

为所有环境启用运行时编译

要为所有环境启用运行时编译，请：

安装 Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation NuGet 包。

在 AddRazorRuntimeCompilation 中调用 Program.cs：

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages()
    .AddRazorRuntimeCompilation();

有条件地启用运行时编译

运行时编译可以有条件地启用，这可确保发布的输出：

使用编译视图。
不会在生产环境中启用文件观察程序。

如果要仅在开发环境中启用运行时编译：

安装 Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation NuGet 包。

在当前环境设置为开发时，代用 AddRazorRuntimeCompilation 中的 Program.cs：

var builder = WebApplication.CreateBuilder(args);

var mvcBuilder = builder.Services.AddRazorPages();

if (builder.Environment.IsDevelopment())
{
    mvcBuilder.AddRazorRuntimeCompilation();
}

还可以使用托管启动程序集来启用运行时编译。要在开发环境中为特定启动配置文件启用运行时编译，请执行以下操作：

安装 Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation NuGet 包。

在 environmentVariables 中修改启动配置文件的launchSettings.json 部分：

验证 ASPNETCORE_ENVIRONMENT 是否设置为 "Development"。

将 ASPNETCORE_HOSTINGSTARTUPASSEMBLIES 设置为 "Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation"。例如，以下 launchSettings.json 可为 ViewCompilationSample 和 IIS Express 启动配置文件启用运行时编译：

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:7098",
      "sslPort": 44332
    }
  },
  "profiles": {
    "ViewCompilationSample": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7173;http://localhost:5251",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "ASPNETCORE_HOSTINGSTARTUPASSEMBLIES": "Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "ASPNETCORE_HOSTINGSTARTUPASSEMBLIES": "Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation"
      }
    }
  }
}

使用此方法时，无需在 Program.cs 中更改代码。在运行时，ASP.NET Core 在中搜索 Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation。属性 HostingStartup 指定了要执行的应用启动代码，并且该启动代码会启用运行时编译。

为 Razor 类库启用运行时编译

考虑一个方案，其中 Razor Pages 项目将会引用名为 Razor 的 类库 (RCL)。该 RCL 包含由 MVC 和 _Layout.cshtml Pages 项目使用的 Razor 文件。要对该 RCL 中的 _Layout.cshtml 文件启用运行时编译，请在 Razor Pages 项目中进行以下更改：

按照有条件地启用运行时编译中的说明启用运行时编译。

在 MvcRazorRuntimeCompilationOptions 中配置 Program.cs：

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.Configure<MvcRazorRuntimeCompilationOptions>(options =>
{
    var libraryPath = Path.GetFullPath(
        Path.Combine(builder.Environment.ContentRootPath, "..", "MyClassLib"));

    options.FileProviders.Add(new PhysicalFileProvider(libraryPath));
});

前面的代码生成了指向 MyClassLib RCL 的绝对路径。 PhysicalFileProvider API 用于查找该绝对路径中的目录和文件。最后，将 PhysicalFileProvider 实例添加到文件提供程序集合，该集合支持访问 RCL 的 .cshtml 文件。

其他资源

扩展名为 Razor 的 .cshtml 文件是在生成和发布时使用 Razor SDK 编译的。通过配置项目，可以选择启用运行时编译。

Razor 编译

Razor SDK 默认启用 Razor 文件的生成时和发布时编译。启用后，运行时编译将补充生成时编译，允许更新 Razor 文件（如果对其进行编辑）。

在创建项目时启用运行时编译

Razor Pages 和 MVC 项目模板包括一个选项，用于在创建项目时启用运行时编译。 ASP.NET Core 3.1 或更高版本支持此选项。

Visual Studio
.NET CLI

在“创建新的 ASP.NET Core Web 应用程序”对话框中：

选择“Web 应用程序”或“Web 应用程序(模型-视图-控制器)”项目模板。
选择“启用 Razor 运行时编译”复选框。

使用 -rrc 或 --razor-runtime-compilation 模板选项。例如，以下命令创建启用了运行时编译的新 Razor Pages 项目：

dotnet new webapp --razor-runtime-compilation

在现有项目中启用运行时编译

为现有项目中的所有环境启用运行时编译：

安装 Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation NuGet 包。

更新项目的 Startup.ConfigureServices 方法以包含对 AddRazorRuntimeCompilation 的调用。例如：

public void ConfigureServices(IServiceCollection services)
{
    services.AddRazorPages()
        .AddRazorRuntimeCompilation();

    // code omitted for brevity
}

在现有项目中有条件地启用运行时编译

启用运行时编译时可使其仅用于本地开发。以这种方式有条件地启用可确保已发布的输出：

使用编译视图。
不会在生产环境中启用文件观察程序。

仅在开发环境中启用运行时编译：

安装 Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation NuGet 包。
在 environmentVariables 中修改启动配置文件的launchSettings.json 部分：
- 验证 ASPNETCORE_ENVIRONMENT 是否设置为 "Development"。
- 将 ASPNETCORE_HOSTINGSTARTUPASSEMBLIES 设置为 "Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation"。

在以下示例中，在开发环境中为 IIS Express 和 RazorPagesApp 启动配置文件启用了运行时编译：

{
    "iisSettings": {
      "windowsAuthentication": false,
      "anonymousAuthentication": true,
      "iisExpress": {
        "applicationUrl": "http://localhost:57676",
        "sslPort": 44364
      }
    },
    "profiles": {
      "IIS Express": {
        "commandName": "IISExpress",
        "launchBrowser": true,
        "environmentVariables": {
          "ASPNETCORE_ENVIRONMENT": "Development",
          "ASPNETCORE_HOSTINGSTARTUPASSEMBLIES": "Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation"
        }
      },
      "RazorPagesApp": {
        "commandName": "Project",
        "launchBrowser": true,
        "applicationUrl": "https://localhost:5001;http://localhost:5000",
        "environmentVariables": {
          "ASPNETCORE_ENVIRONMENT": "Development",
          "ASPNETCORE_HOSTINGSTARTUPASSEMBLIES": "Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation"
        }
      }
    }
  }

项目的 Startup 类中不需要更改代码。在运行时，ASP.NET Core 在中搜索 Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation。 HostingStartup 属性指定要执行的应用启动代码。该启动代码可实现运行时编译。

为 Razor 类库启用运行时编译

考虑一个方案，其中 Razor Pages 项目将会引用名为 Razor 的 类库 (RCL)。 RCL 包含一个团队中所有 MVC 和 _Layout.cshtml Pages 项目都会使用的 Razor 文件。你希望为 RCL 中的 _Layout.cshtml 文件启用运行时编译。在 Pages 项目 Razor 中做以下更改：

按照在现有项目中有条件地启用运行时编译中的说明启用运行时编译。

在 Startup.ConfigureServices 中配置运行时编译选项：

public void ConfigureServices(IServiceCollection services)
{
    services.AddRazorPages();

    services.Configure<MvcRazorRuntimeCompilationOptions>(options =>
    {
        var libraryPath = Path.GetFullPath(
            Path.Combine(HostEnvironment.ContentRootPath, "..", "MyClassLib"));
        options.FileProviders.Add(new PhysicalFileProvider(libraryPath));
    });
}

在前面的代码中，构造了 MyClassLib RCL 的绝对路径。 PhysicalFileProvider API 用于查找该绝对路径中的目录和文件。最后，将 PhysicalFileProvider 实例添加到文件提供程序集合，该集合支持访问 RCL 的 .cshtml 文件。