Compartilhar via


Compilação de arquivo do Razor no ASP.NET Core

Os arquivos do Razor com uma extensão .cshtml são compilados em tempo de build e de publicação por meio do Razor SDK. A compilação do runtime pode ser opcionalmente habilitada através da configuração do aplicativo.

Observação

Compilação de runtime:

Compilação do Razor

A compilação em tempo de build e de publicação de arquivos do Razor está habilitada por padrão pelo SDK do Razor. Quando habilitada, a compilação de runtime complementa a compilação de tempo de build, permitindo que os arquivos do Razor sejam atualizados se forem editados.

Também há suporte para a atualização de exibições do Razor e páginas do Razor durante o desenvolvimento enquanto o aplicativo está em execução usando a Recarga Dinâmica do .NET.

Observação

Quando habilitada, a compilação de runtime desabilita a Recarga Dinâmica do .NET. É recomendável usar a Recarga Dinâmica em vez da compilação Razor de runtime durante o desenvolvimento.

Habilitar a compilação de runtime para todos os ambientes

Para habilitar a compilação de runtime para todos os ambientes:

  1. Instalar o pacote do NuGet Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation.

  2. Chame AddRazorRuntimeCompilation em Program.cs:

    var builder = WebApplication.CreateBuilder(args);
    
    builder.Services.AddRazorPages()
        .AddRazorRuntimeCompilation();
    

Habilitar a compilação de runtime condicionalmente

A compilação de runtime pode ser habilitada condicionalmente, o que garante que a saída publicada:

  • Usa exibições compiladas.
  • Não habilita observadores de arquivos em produção.

Para habilitar a compilação de runtime somente para o ambiente de desenvolvimento:

  1. Instalar o pacote do NuGet Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation.

  2. Chame AddRazorRuntimeCompilation em Program.cs quando o ambiente atual estiver definido como Desenvolvimento:

    var builder = WebApplication.CreateBuilder(args);
    
    var mvcBuilder = builder.Services.AddRazorPages();
    
    if (builder.Environment.IsDevelopment())
    {
        mvcBuilder.AddRazorRuntimeCompilation();
    }
    

A compilação de runtime também pode ser habilitada com um assembly de inicialização de hospedagem. Para habilitar a compilação de runtime no ambiente de desenvolvimento para perfis de inicialização específicos:

  1. Instalar o pacote do NuGet Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation.
  2. Modifique a seção environmentVariables do perfil de inicialização em launchSettings.json:
    • Verifique se ASPNETCORE_ENVIRONMENT está definido como "Development".

    • Defina ASPNETCORE_HOSTINGSTARTUPASSEMBLIES como "Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation". Por exemplo, o seguinte launchSettings.json habilita a compilação de runtime para os perfis de inicialização ViewCompilationSample e 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"
            }
          }
        }
      }
      

Com essa abordagem, nenhuma alteração de código é necessária no Program.cs. No runtime, o ASP.NET Core pesquisa um atributo HostingStartup no nível do assembly no Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation. O atributo HostingStartup especifica o código de inicialização do aplicativo a ser executado e esse código de inicialização habilita a compilação de runtime.

Habilite a compilação de runtime de uma biblioteca de classes do Razor

Considere um cenário em que um projeto de Páginas do Razor faz referência a uma RCL (biblioteca de classes) Razor chamada MyClassLib. A RCL contém um arquivo _Layout.cshtml consumido por projetos MVC e Páginas do Razor. Para habilitar a compilação de runtime para o arquivo _Layout.cshtml nessa RCL, faça as seguintes alterações no projeto das Páginas do Razor:

  1. Habilite a compilação de runtime com as instruções em Habilitar a compilação de runtime condicionalmente.

  2. Configurar MvcRazorRuntimeCompilationOptions em 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));
    });
    

    O código anterior cria um caminho absoluto para a RCL MyClassLib . A API PhysicalFileProvider é usada para localizar diretórios e arquivos nesse caminho absoluto. Por fim, a instância PhysicalFileProvider é adicionada a uma coleção de provedores de arquivos, que permite o acesso aos arquivos .cshtml da RCL.

Recursos adicionais

Os arquivos do Razor com uma extensão .cshtml são compilados em tempo de build e de publicação por meio do Razor SDK. A compilação do runtime pode ser opcionalmente habilitada através da configuração do aplicativo.

Compilação do Razor

A compilação em tempo de build e de publicação de arquivos do Razor está habilitada por padrão pelo SDK do Razor. Quando habilitada, a compilação de runtime complementa a compilação de tempo de build, permitindo que os arquivos do Razor sejam atualizados se eles editados.

Habilitar a compilação de runtime na criação do projeto

Os modelos de projeto Páginas do Razor e MVC incluem uma opção para habilitar a compilação de runtime quando o projeto é criado. Essa opção tem suporte no ASP.NET Core 3.1 e posterior.

Na caixa de diálogo Criar um novo Aplicativo Web ASP.NET Core:

  1. Selecione o modelo de projeto Aplicativo Web ou Aplicativo Web (Model-View-Controller).
  2. Marque a caixa de seleção Habilitar Razor compilação de runtime .

Habilitar a compilação de runtime em um projeto existente

Para habilitar a compilação de runtime para todos os ambientes em um projeto existente:

  1. Instalar o pacote do NuGet Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation.

  2. Atualize o método Startup.ConfigureServices do projeto para incluir uma chamada para AddRazorRuntimeCompilation. Por exemplo:

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddRazorPages()
            .AddRazorRuntimeCompilation();
    
        // code omitted for brevity
    }
    

Habilitar condicionalmente a compilação de runtime em um projeto existente

A compilação de runtime pode ser habilitada de modo que só esteja disponível para desenvolvimento local. Habilitar condicionalmente dessa maneira garante que a saída publicada:

  • Usa exibições compiladas.
  • Não habilita observadores de arquivos em produção.

Para habilitar a compilação de runtime somente no ambiente de desenvolvimento:

  1. Instalar o pacote do NuGet Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation.
  2. Modifique a seção environmentVariables do perfil de inicialização em launchSettings.json:
    • Se ASPNETCORE_ENVIRONMENT estiver definido como "Development".
    • Defina ASPNETCORE_HOSTINGSTARTUPASSEMBLIES como "Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation".

No exemplo a seguir, a compilação de runtime está habilitada no ambiente de desenvolvimento para os IIS Express perfis de inicialização e 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"
        }
      }
    }
  }

Nenhuma alteração de código é necessária na classe do Startup projeto. No runtime, o ASP.NET Core pesquisa um atributo HostingStartup no nível do assembly no Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation. O HostingStartup atributo especifica o código de inicialização do aplicativo a ser executado. Esse código de inicialização habilita a compilação de runtime.

Habilite a compilação de runtime de uma biblioteca de classes do Razor

Considere um cenário em que um projeto de Páginas do Razor faz referência a uma RCL (biblioteca de classes) Razor chamada MyClassLib. A RCL contém um arquivo _Layout.cshtml que todos os projetos MVC e Páginas do Razor da sua equipe consomem. Você deseja habilitar a compilação de runtime para o arquivo _Layout.cshtml nessa RCL. Faça as seguintes alterações no projeto das Páginas do Razor:

  1. Habilite a compilação de runtime com as instruções em Habilitar a compilação de runtime condicionalmente em projeto existente.

  2. Configure as opções de compilação de runtime em 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));
        });
    }
    

    No código anterior, um caminho absoluto para a RCL MyClassLib é construído. A API PhysicalFileProvider é usada para localizar diretórios e arquivos nesse caminho absoluto. Por fim, a instância PhysicalFileProvider é adicionada a uma coleção de provedores de arquivos, que permite o acesso aos arquivos .cshtml da RCL.

Recursos adicionais