Partilhar via

Criar interface do usuário reutilizável usando o projeto de biblioteca de classes Razor no ASP.NET Core

  • Artigo

Por Rick Anderson

Razor modos de exibição, páginas, controladores, modelos de página Razor componentes, Exibir componentese modelos de dados podem ser criados em uma biblioteca de classes Razor (RCL). O RCL pode ser embalado e reutilizado. As aplicações podem incluir a RCL e substituir as visualizações e páginas que contêm. Quando uma vista, vista parcial ou Página Razor é encontrada na aplicação Web e na RCL, a marcação Razor (ficheiro.cshtml) na aplicação Web tem precedência.

Para obter informações sobre como integrar npm e webpack no processo de compilação de uma RCL, consulte Build client web assets for your Razor Class Library.

Criar uma biblioteca de classes contendo a interface de usuário Razor

  • No Visual Studio, selecione Criar um novo projeto.
  • Selecione Razor Biblioteca de Classes>Próximo.
  • Nomeie a biblioteca (por exemplo, "RazorClassLib") >Crie. Para evitar uma colisão de nome de arquivo com a biblioteca de exibição gerada, verifique se o nome da biblioteca não termina em .Views.
  • Selecione páginas e exibições de suporte se precisar que a biblioteca contenha páginas e/ou exibições. Por padrão, apenas Razor componentes são suportados. Selecione Criar.

O modelo Biblioteca de Classes Razor assume o desenvolvimento de componentes Razor como padrão. A opção páginas e visualizações de suporte suporta páginas e exibições. Para mais informações sobre o suporte para bibliotecas de componentes reutilizáveis (RCL) no Blazor, consulte e aprenda a consumir componentes ASP.NET Core Razor a partir de uma biblioteca de classes Razor (RCL).

Adicione Razor ficheiros à RCL.

Os modelos ASP.NET Core assumem que o conteúdo RCL está na pasta Areas. Veja o layout de Páginas RCL abaixo para criar uma RCL que exponha conteúdo em ~/Pages em vez de ~/Areas/Pages.

Conteúdo RCL de referência

O RCL pode ser referenciado por:

Substituir vistas, vistas parciais e páginas

Quando uma vista, vista parcial ou Página Razor é encontrada na aplicação Web e na RCL, a marcação Razor (ficheiro.cshtml) na aplicação Web tem precedência. Por exemplo, adicione WebApp1/Areas/MyFeature/Pages/Page1.cshtml ao WebApp1 e Page1 no WebApp1 terá precedência sobre Page1 na RCL.

No download de exemplo, renomeie WebApp1/Areas/MyFeature2 para WebApp1/Areas/MyFeature para testar a precedência.

Copiar a visualização parcial RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml para WebApp1/Areas/MyFeature/Pages/Shared/_Message.cshtml. Atualize a marcação para indicar o novo local. Construa e execute a aplicação para verificar se está a ser utilizada a versão fragmentada da aplicação.

Se a RCL utilizar Razor Páginas, ative os serviços e pontos finais do Razor Pages na aplicação de alojamento:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();
builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Home/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.MapRazorPages();
app.Run();

Layout de páginas RCL

Para fazer referência ao conteúdo RCL como se fizesse parte da pasta Pages da aplicação Web, crie o projeto RCL com a seguinte estrutura de ficheiros:

  • RazorUIClassLib/Pages
  • RazorUIClassLib/Pages/Shared

Suponha que RazorUIClassLib/Pages/Shared contém dois arquivos parciais: _Header.cshtml e _Footer.cshtml. As <partial> tags podem ser adicionadas ao _Layout.cshtml arquivo:

<body>
  <partial name="_Header">
  @RenderBody()
  <partial name="_Footer">
</body>

Adicione o ficheiro _ViewStart.cshtml à pasta Pages do projeto RCL para utilizar o ficheiro _Layout.cshtml da aplicação Web anfitrião:

@{
    Layout = "_Layout";
}

Criar um RCL com ativos estáticos

Uma RCL pode exigir ativos estáticos complementares que podem ser referenciados pela RCL ou pela aplicação consumidora da RCL. ASP.NET Core permite criar RCLs que incluem ativos estáticos que estão disponíveis para um aplicativo consumidor.

Para incluir ativos complementares como parte de uma RCL, crie uma pasta wwwroot na biblioteca de classes e inclua todos os arquivos necessários nessa pasta.

Ao embalar um RCL, todos os ativos complementares na pasta wwwroot são automaticamente incluídos no pacote.

Use o comando dotnet pack em vez da versão NuGet.exe nuget pack.

Adicionar ativos da Web do cliente ao processo de compilação

A integração dos ativos web do cliente no pipeline de compilação não é uma tarefa trivial. Consulte criar ativos da Web de cliente para sua biblioteca de classes Razor para obter mais informações.

Excluir ativos estáticos

Para excluir ativos estáticos, adicione o caminho de exclusão desejado ao grupo de propriedades $(DefaultItemExcludes) no arquivo de projeto. Separe as entradas com ponto e vírgula (;).

No exemplo a seguir, a folha de estilo lib.css na pasta wwwroot não é considerada um ativo estático e não está incluída na RCL publicada:

<PropertyGroup>
  <DefaultItemExcludes>$(DefaultItemExcludes);wwwroot\lib.css</DefaultItemExcludes>
</PropertyGroup>

Integração Typescript

Para incluir ficheiros TypeScript numa RCL:

  • Faça referência ao pacote NuGet Microsoft.TypeScript.MSBuild no projeto.

    Observação

    Para obter orientação sobre como adicionar pacotes a aplicações .NET, consulte os artigos em Instalar e gerir pacotes no fluxo de trabalho de consumo de pacotes (documentação do NuGet). Confirme as versões corretas do pacote em NuGet.org.

  • Coloque os arquivos TypeScript (.ts) fora da pasta wwwroot. Por exemplo, coloque os arquivos em uma pasta Client.

  • Adicione a seguinte marcação ao arquivo de projeto:

    • Configure a saída de compilação TypeScript para a pasta wwwroot com a propriedade TypescriptOutDir.
    • Inclua o destino TypeScript como uma dependência do destino PrepareForBuildDependsOn.
    • Remova a saída no wwwroot folder.
<Project Sdk="Microsoft.NET.Sdk.Razor">
  <Project Sdk="Microsoft.NET.Sdk.Razor">

    <PropertyGroup>
      // Markup removed for brevity.
      <TypescriptOutDir>wwwroot</TypescriptOutDir>
      <PrepareForBuildDependsOn>
        CompileTypeScriptWithTSConfig;
        GetTypeScriptOutputForPublishing;$(PrepareForBuildDependsOn)
      </PrepareForBuildDependsOn>
    </PropertyGroup>

    <ItemGroup>
      <Content Remove="wwwroot\{path-to-typescript-outputs}" />
    </ItemGroup>

  </Project>

Consumir conteúdo de uma RCL referenciada

Os ficheiros incluídos na pasta wwwroot da RCL são expostos à RCL ou à aplicação consumidora sob o prefixo _content/{PACKAGE ID}/. Por exemplo, uma biblioteca com um nome de assembly de Razor.Class.Lib e sem um <PackageId> especificado no seu ficheiro de projeto resulta num caminho para o conteúdo estático em _content/Razor.Class.Lib/. Durante a produção de um pacote NuGet, se o nome do assembly não for o mesmo que o ID do pacote (<PackageId> no ficheiro de projeto da biblioteca), use o ID do pacote conforme especificado no ficheiro de projeto para {PACKAGE ID}.

O aplicativo de consumo faz referência a ativos estáticos fornecidos pela biblioteca com <script>, <style>, <img>e outras tags HTML. O aplicativo de consumo deve ter suporte a arquivos estáticos habilitado em:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();
builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Home/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.MapRazorPages();
app.Run();

Ao executar a app de consumo a partir da saída de compilação (dotnet run), os ativos web estáticos são habilitados por padrão no ambiente de Desenvolvimento. Para oferecer suporte a ativos em outros ambientes ao executar a partir da saída de compilação, chame UseStaticWebAssets no construtor de host em Program.cs:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.UseWebRoot("wwwroot");
builder.WebHost.UseStaticWebAssets();

builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Chamar UseStaticWebAssets não é necessário ao executar um aplicativo a partir da saída publicada (dotnet publish).

Fluxo de desenvolvimento multi-projeto

Quando a aplicação de consumo entra em execução:

  • Os ativos na RCL permanecem em suas pastas originais. Os ativos não são movidos para o aplicativo de consumo.
  • Qualquer alteração dentro da pasta wwwroot da RCL é refletida na aplicação consumidora depois de a RCL ser reconstruída e sem reconstruir a aplicação consumidora.

Quando o RCL é construído, é produzido um manifesto que descreve os locais dos ativos Web estáticos. A aplicação consumidora lê o manifesto durante a execução para consumir os recursos de projetos e pacotes referenciados. Quando um novo ativo é adicionado a uma RCL, a RCL deve ser reconstruída para atualizar seu manifesto antes que um aplicativo consumidor possa acessar o novo ativo.

Publicar

Quando a aplicação é publicada, os ativos complementares de todos os projetos e pacotes referenciados são copiados para a pasta wwwroot da aplicação publicada sob _content/{PACKAGE ID}/. Ao produzir um pacote NuGet e o nome do assembly não for o mesmo que o ID do pacote (<PackageId> no arquivo de projeto da biblioteca), use o ID do pacote conforme especificado no arquivo de projeto para {PACKAGE ID} ao examinar a pasta wwwroot para os ativos publicados.

Recursos adicionais

Razor modos de exibição, páginas, controladores, modelos de página Razor componentes, Exibir componentese modelos de dados podem ser criados em uma biblioteca de classes Razor (RCL). O RCL pode ser embalado e reutilizado. As aplicações podem incluir a RCL e substituir as vistas e páginas que contém. Quando uma vista, vista parcial ou página Razor é encontrada na aplicação web e na RCL, a marcação Razor (ficheiro.cshtml) da aplicação web tem precedência.

Para obter informações sobre como integrar npm e webpack no processo de compilação de uma Biblioteca de Classes Razor, consulte Construir recursos web do cliente para a sua Biblioteca de Classes Razor.

Crie uma biblioteca de classes contendo a interface de utilizador Razor UI

  • No Visual Studio, selecione Criar um novo projeto.
  • Selecione Razor Biblioteca de Classes>Seguinte.
  • Nomeie a biblioteca (por exemplo, "RazorClassLib") >Crie. Para evitar uma colisão de nome de arquivo com a biblioteca de exibição gerada, verifique se o nome da biblioteca não termina em .Views.
  • Selecione páginas e modos de exibição de suporte se precisar oferecer suporte a modos de exibição. Por padrão, apenas Razor páginas são suportadas. Selecione Criar.

O modelo RCL (Biblioteca de Classes Razor) assume por padrão o desenvolvimento de componentes Razor. A opção de páginas e visualizações de suporte suporta páginas e visualizações.

Adicione Razor ficheiros à RCL.

Os modelos ASP.NET Core assumem que o conteúdo RCL está na pasta Areas. Consulte o layout de Páginas RCL abaixo para criar uma RCL que revele conteúdo em ~/Pages em substituição a ~/Areas/Pages.

Conteúdo RCL de referência

O RCL pode ser referenciado por:

Sobrescrever vistas, vistas parciais e páginas

Quando uma vista, vista parcial ou Página Razor é encontrada na aplicação Web e na RCL, a marcação Razor (ficheiro.cshtml) na aplicação Web tem precedência. Por exemplo, adicione WebApp1/Areas/MyFeature/Pages/Page1.cshtml ao WebApp1 e Page1 no WebApp1 terá precedência sobre Page1 na RCL.

No download de exemplo, renomeie WebApp1/Areas/MyFeature2 para WebApp1/Areas/MyFeature para testar a precedência.

Copie a visualização parcial RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml para WebApp1/Areas/MyFeature/Pages/Shared/_Message.cshtml. Atualize o código para indicar o novo local. Crie e execute o aplicativo para verificar se a versão do aplicativo da parcial está sendo usada.

Se a RCL utilizar Razor Pages, ative os serviços e endpoints das Razor Pages na aplicação de alojamento.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();
builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Home/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.MapRazorPages();
app.Run();

Layout de páginas RCL

Para fazer referência ao conteúdo RCL como se fizesse parte da pasta Pages da aplicação Web, crie o projeto RCL com a seguinte estrutura de ficheiros:

  • RazorUIClassLib/Pages
  • RazorUIClassLib/Pages/Shared

Suponha que RazorUIClassLib/Pages/Shared contém dois arquivos parciais: _Header.cshtml e _Footer.cshtml. As <partial> tags podem ser adicionadas ao ficheiro _Layout.cshtml:

<body>
  <partial name="_Header">
  @RenderBody()
  <partial name="_Footer">
</body>

Adicione o ficheiro _ViewStart.cshtml à pasta Pages do projeto RCL para utilizar o ficheiro _Layout.cshtml da aplicação Web anfitrião:

@{
    Layout = "_Layout";
}

Criar um RCL com ativos estáticos

Uma RCL pode exigir ativos estáticos complementares que podem ser referenciados pela RCL ou pela aplicação consumidora da RCL. ASP.NET Core permite criar RCLs que incluem ativos estáticos que estão disponíveis para um aplicativo consumidor.

Para incluir ativos complementares como parte de uma RCL, crie uma pasta wwwroot na biblioteca de classes e inclua todos os arquivos necessários nessa pasta.

Ao embalar um RCL, todos os ativos complementares na pasta wwwroot são automaticamente incluídos no pacote.

Use o comando dotnet pack em vez da versão NuGet.exe nuget pack.

Excluir ativos estáticos

Para excluir ativos estáticos, adicione o caminho de exclusão desejado ao grupo de propriedades $(DefaultItemExcludes) no arquivo de projeto. Separe as entradas com ponto e vírgula (;).

No exemplo a seguir, a folha de estilo lib.css na pasta wwwroot não é considerada um ativo estático e não está incluída na RCL publicada:

<PropertyGroup>
  <DefaultItemExcludes>$(DefaultItemExcludes);wwwroot\lib.css</DefaultItemExcludes>
</PropertyGroup>

Integração Typescript

Para incluir ficheiros TypeScript numa RCL:

  1. Faça referência ao pacote NuGet Microsoft.TypeScript.MSBuild no projeto.

    Observação

    Para obter orientação sobre como adicionar pacotes a aplicativos .NET, consulte os artigos em Instalar e gerenciar pacotes em Fluxo de trabalho de consumo de pacotes (documentação do NuGet). Confirme as versões corretas do pacote em NuGet.org.

  2. Coloque os arquivos TypeScript (.ts) fora da pasta wwwroot. Por exemplo, coloque os arquivos em uma pasta Client.

  3. Configure o resultado de compilação do TypeScript para a pasta wwwroot. Defina a propriedade TypescriptOutDir dentro de um PropertyGroup no arquivo de projeto:

    <TypescriptOutDir>wwwroot</TypescriptOutDir>

  4. Inclua o destino TypeScript como uma dependência do destino PrepareForBuildDependsOn adicionando o seguinte destino dentro de um PropertyGroup no arquivo de projeto:

    <PrepareForBuildDependsOn>
  CompileTypeScript;
  GetTypeScriptOutputForPublishing;$(PrepareForBuildDependsOn)
</PrepareForBuildDependsOn>

Consumir conteúdo de uma RCL referenciada

Os ficheiros incluídos na pasta wwwroot da RCL são expostos à RCL ou à aplicação consumidora sob o prefixo _content/{PACKAGE ID}/. Por exemplo, uma biblioteca com um nome de assembly de Razor.Class.Lib e sem um <PackageId> especificado em seu arquivo de projeto resulta em um caminho para o conteúdo estático em _content/Razor.Class.Lib/. Ao produzir um pacote NuGet e o nome do assembly não for o mesmo que o ID do pacote (<PackageId> no ficheiro de projeto da biblioteca), utilize o ID do pacote conforme especificado no ficheiro de projeto para {PACKAGE ID}.

A aplicação consumidora refere-se a ativos estáticos fornecidos pela biblioteca com <script>, <style>, <img>e outras tags HTML. A aplicação consumidora deve ter suporte a arquivos estáticos habilitado em:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();
builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Home/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.MapRazorPages();
app.Run();

Ao executar a aplicação consumidora a partir da saída de compilação (dotnet run), os ativos web estáticos são habilitados por padrão no ambiente de desenvolvimento. Para oferecer suporte a ativos em outros ambientes ao executar a partir da saída de compilação, chame UseStaticWebAssets no construtor de host em Program.cs:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.UseWebRoot("wwwroot").UseStaticWebAssets();

builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Nota: .NET 6 requer apenas chamar builder.WebHost.UseWebRoot("wwwroot").UseStaticWebAssets. Para obter mais informações, consulte o problema do GitHub.

Chamar UseStaticWebAssets não é necessário ao executar um aplicativo a partir da saída publicada (dotnet publish).

Fluxo de desenvolvimento multi-projeto

Quando a aplicação de consumo é executada:

  • Os ativos na RCL permanecem em suas pastas originais. Os ativos não são movidos para o aplicativo de consumo.
  • Qualquer alteração dentro da pasta wwwroot da RCL fica refletida na aplicação de consumo após a reconstrução do RCL e sem reconstruir a aplicação de consumo.

Quando o RCL é construído, é produzido um manifesto que descreve os locais de recursos web estáticos. A aplicação consumidora lê o manifesto em tempo-de-execução para consumir os recursos de projetos e pacotes referenciados. Quando um novo ativo é adicionado a uma RCL, a RCL deve ser reconstruída para atualizar seu manifesto antes que um aplicativo consumidor possa acessar o novo ativo.

Publicar

Quando a aplicação é publicada, os ativos complementares de todos os projetos e pacotes referenciados são copiados para a pasta wwwroot da aplicação publicada em _content/{PACKAGE ID}/. Ao produzir um pacote NuGet e o nome do assembly não for o mesmo que o ID do pacote (<PackageId> no arquivo de projeto da biblioteca), use o ID do pacote conforme especificado no arquivo de projeto para {PACKAGE ID} ao examinar a pasta wwwroot para os ativos publicados.

Recursos adicionais

Razor modos de exibição, páginas, controladores, modelos de página Razor componentes, Exibir componentese modelos de dados podem ser criados em uma biblioteca de classes Razor (RCL). O RCL pode ser embalado e reutilizado. As aplicações podem incluir a RCL e substituir as vistas e páginas que contém. Quando uma vista, vista parcial ou Página Razor é encontrada na aplicação Web e na RCL, a marcação Razor (ficheiro.cshtml) na aplicação Web tem precedência.

Ver ou baixar código de exemplo (como baixar)

Criar uma biblioteca de classes contendo Razor UI

  • No Visual Studio, selecione Criar um novo projeto.
  • Selecione Razor Biblioteca de Classes>Próximo.
  • Nomeie a biblioteca (por exemplo, "RazorClassLib") >Create>Next. Para evitar uma colisão de nome de arquivo com a biblioteca de exibição gerada, verifique se o nome da biblioteca não termina em .Views.
  • Selecione o Target Framework. Verifique ☑ páginas de suporte e visualizações para oferecer suporte a visualizações. Por padrão, apenas Razor componentes são suportados. Selecione Criar.

O modelo de biblioteca de classes Razor (RCL) define como padrão o desenvolvimento de componentes Razor. A opção páginas e visualizações de suporte suporta páginas e exibições.

Adicione ficheiros Razor à RCL.

Os modelos ASP.NET Core assumem que o conteúdo RCL está na pasta Areas. Consulte o esquema de Páginas RCL em para criar uma RCL que exponha conteúdo em ~/Pages em detrimento de ~/Areas/Pages.

Conteúdo RCL de referência

O RCL pode ser referenciado por:

Sobrescrever vistas, vistas parciais e páginas

Quando uma vista, vista parcial ou Página Razor é encontrada na aplicação web e na RCL, o código Razor (ficheiro.cshtml) na aplicação web tem preferência. Por exemplo, adicione WebApp1/Areas/MyFeature/Pages/Page1.cshtml ao WebApp1 e Page1 no WebApp1 terá precedência sobre Page1 na RCL.

No download de exemplo, renomeie WebApp1/Areas/MyFeature2 para WebApp1/Areas/MyFeature para testar a precedência.

Copie a visualização parcial RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml para WebApp1/Areas/MyFeature/Pages/Shared/_Message.cshtml. Atualize o markup para indicar o novo local. Crie e execute a aplicação para verificar se a versão da parcial da aplicação está a ser usada.

Layout de páginas RCL

Para fazer referência ao conteúdo RCL como se fizesse parte da pasta Pages da aplicação Web, crie o projeto RCL com a seguinte estrutura de ficheiros:

  • RazorUIClassLib/Pages
  • RazorUIClassLib/Pages/Shared

Suponha que RazorUIClassLib/Pages/Shared contém dois arquivos parciais: _Header.cshtml e _Footer.cshtml. As <partial> tags podem ser adicionadas ao _Layout.cshtml arquivo.

<body>
  <partial name="_Header">
  @RenderBody()
  <partial name="_Footer">
</body>

Adicione o ficheiro _ViewStart.cshtml à pasta Pages do projeto RCL para utilizar o ficheiro _Layout.cshtml da aplicação Web anfitrião:

@{
    Layout = "_Layout";
}

Criar um RCL com ativos estáticos

Uma RCL pode exigir ativos estáticos complementares que podem ser referenciados pela RCL ou pela aplicação consumidora da RCL. ASP.NET Core permite criar RCLs que incluem ativos estáticos que estão disponíveis para um aplicativo consumidor.

Para incluir ativos complementares como parte de uma RCL, crie uma pasta wwwroot na biblioteca de classes e inclua todos os arquivos necessários nessa pasta.

Ao embalar um RCL, todos os ativos complementares na pasta wwwroot são automaticamente incluídos no pacote.

Use o comando dotnet pack em vez da versão NuGet.exe nuget pack.

Excluir ativos estáticos

Para excluir ativos estáticos, adicione o caminho de exclusão desejado ao grupo de propriedades $(DefaultItemExcludes) no arquivo de projeto. Separe as entradas com ponto e vírgula (;).

No exemplo a seguir, a folha de estilo lib.css na pasta wwwroot não é considerada um ativo estático e não está incluída na RCL publicada:

<PropertyGroup>
  <DefaultItemExcludes>$(DefaultItemExcludes);wwwroot\lib.css</DefaultItemExcludes>
</PropertyGroup>

Integração Typescript

Para incluir ficheiros TypeScript numa RCL:

  1. Faça referência ao pacote NuGet Microsoft.TypeScript.MSBuild no projeto.

    Observação

    Para obter orientação sobre como adicionar pacotes a aplicativos .NET, consulte os artigos em Instalar e gerenciar pacotes em Fluxo de trabalho de consumo de pacotes (documentação do NuGet). Confirme as versões corretas do pacote em NuGet.org.

  2. Coloque os arquivos TypeScript (.ts) fora da pasta wwwroot. Por exemplo, coloque os arquivos em uma pasta Client.

  3. Configure a saída de compilação TypeScript para a pasta wwwroot. Defina a propriedade TypescriptOutDir dentro de um PropertyGroup no arquivo de projeto:

    <TypescriptOutDir>wwwroot</TypescriptOutDir>

  4. Inclua o destino TypeScript como uma dependência do destino ResolveCurrentProjectStaticWebAssets adicionando o seguinte destino dentro de um PropertyGroup no arquivo de projeto:

    <ResolveCurrentProjectStaticWebAssetsInputsDependsOn>
  CompileTypeScript;
  $(ResolveCurrentProjectStaticWebAssetsInputs)
</ResolveCurrentProjectStaticWebAssetsInputsDependsOn>

Consumir conteúdo de uma RCL referenciada

Os ficheiros incluídos na pasta wwwroot da RCL são expostos tanto à RCL como à aplicação consumidora sob o prefixo _content/{PACKAGE ID}/. Por exemplo, uma biblioteca com um nome de assembly de Razor.Class.Lib e sem um <PackageId> especificado no seu ficheiro de projeto resulta num caminho para o conteúdo estático em _content/Razor.Class.Lib/. Ao produzir um pacote NuGet, e caso o nome do assembly não seja o mesmo que o ID do pacote (<PackageId> no ficheiro de projeto da biblioteca), utilize o ID do pacote conforme especificado no ficheiro de projeto para {PACKAGE ID}.

A aplicação consumidora faz referência a recursos estáticos fornecidos pela biblioteca com <script>, <style>, <img>e outras tags HTML. O aplicativo de consumo deve ter suporte a arquivos estáticos habilitado em Startup.Configure:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    ...

    app.UseStaticFiles();

    ...
}

Ao executar a aplicação de consumo a partir da saída de compilação (dotnet run), os recursos web estáticos são habilitados por padrão no ambiente de desenvolvimento. Para oferecer suporte a ativos em outros ambientes ao executar a partir da saída de compilação, chame UseStaticWebAssets no construtor de host em Program.cs:

using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Hosting;

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStaticWebAssets();
                webBuilder.UseStartup<Startup>();
            });
}

Chamar UseStaticWebAssets não é necessário ao executar um aplicativo a partir da saída publicada (dotnet publish).

Fluxo de desenvolvimento multi-projeto

Quando o aplicativo de consumo é executado:

  • Os ativos na RCL permanecem em suas pastas originais. Os ativos não são movidos para o aplicativo de consumo.
  • Qualquer alteração dentro da pasta wwwroot da RCL é refletida na aplicação consumidora depois de o RCL ser reconstruído e sem reconstruir a aplicação consumidora.

Quando o RCL é construído, é produzido um manifesto que descreve os locais de recursos web estáticos. O aplicativo consumidor lê o manifesto em tempo de execução para consumir os ativos de projetos e pacotes referenciados. Quando um novo ativo é adicionado a uma RCL, a RCL deve ser reconstruída para atualizar seu manifesto antes que um aplicativo consumidor possa acessar o novo ativo.

Publicar

Quando a aplicação é publicada, os ativos complementares de todos os projetos e pacotes referenciados são copiados para a pasta wwwroot da aplicação publicada em _content/{PACKAGE ID}/. Ao produzir um pacote NuGet e o nome do assembly não for o mesmo que o ID do pacote (<PackageId> no arquivo de projeto da biblioteca), use o ID do pacote conforme especificado no arquivo de projeto para {PACKAGE ID} ao examinar a pasta wwwroot para os ativos publicados.

Recursos adicionais

Razor modos de exibição, páginas, controladores, modelos de página Razor componentes, Exibir componentese modelos de dados podem ser criados em uma biblioteca de classes Razor (RCL). O RCL pode ser embalado e reutilizado. As aplicações podem incluir a RCL e substituir as vistas e páginas que contém. Quando uma vista, vista parcial ou Página Razor é encontrada na aplicação Web e na RCL, a marcação Razor (ficheiro.cshtml) na aplicação Web tem precedência.

Ver ou descarregar código de exemplo (como descarregar)

Criar uma biblioteca de classes contendo Razor UI

  • No menu Visual Studio Ficheiro, selecione Novo>Projeto.
  • Selecione Aplicação Web ASP.NET Core.
  • Nomeie a biblioteca (por exemplo, "RazorClassLib") >OK. Para evitar uma colisão de nome de arquivo com a biblioteca de exibição gerada, verifique se o nome da biblioteca não termina em .Views.
  • Verifique se ASP.NET Core 2.1 ou posterior está selecionado.
  • Selecione Razor Biblioteca de Classes>OK.

Um RCL tem o seguinte ficheiro de projeto:

<Project Sdk="Microsoft.NET.Sdk.Razor">

    <PropertyGroup>
        <TargetFramework>netcoreapp3.1</TargetFramework>
        <AddRazorSupportForMvc>true</AddRazorSupportForMvc>
    </PropertyGroup>

    <ItemGroup>
        <FrameworkReference Include="Microsoft.AspNetCore.App" />
    </ItemGroup>


</Project>

Adicione os ficheiros etiquetados Razor à RCL.

Os modelos ASP.NET Core assumem que o conteúdo RCL está na pasta Areas. Consulte o esquema de Páginas RCL em para criar uma RCL que exponha conteúdo em ~/Pages em vez de em ~/Areas/Pages.

Conteúdo RCL de referência

O RCL pode ser referenciado por:

Guia passo a passo: Criar um projeto RCL e utilizar a partir de um projeto Razor Pages

Você pode baixar o projeto completo e testá-lo em vez de criá-lo. O download de exemplo contém código adicional e links que tornam o projeto fácil de testar. Você pode deixar comentários em este problema do GitHub com seus comentários sobre amostras de download versus instruções passo a passo.

Testar o aplicativo de download

Se você não baixou o aplicativo concluído e prefere criar o projeto passo a passo, pule para a próxima seção .

Abra o arquivo .sln no Visual Studio. Execute o aplicativo.

Siga as instruções em Test WebApp1

Criar uma RCL

Nesta secção, é criada uma RCL. Os ficheiros Razor são adicionados à RCL.

Crie o projeto RCL:

  • No menu Visual Studio Ficheiro, selecione Novo>Projeto.
  • Selecione Aplicação Web ASP.NET Core.
  • Nomeie o aplicativo RazorUIClassLib>OK.
  • Verifique se ASP.NET Core 2.1 ou posterior está selecionado.
  • Selecione Razor Biblioteca de Classes>OK.
  • Adicione um arquivo de exibição parcial Razor chamado RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml.

Adicionar Razor arquivos e pastas ao projeto

  • Substitua a marcação no RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml pelo seguinte código:

    <h3>_Message.cshtml partial view.</h3>

<p>RazorUIClassLib\Areas\MyFeature\Pages\Shared\_Message.cshtml</p>

  • Substitua a marcação no RazorUIClassLib/Areas/MyFeature/Pages/Page1.cshtml pelo seguinte código:

    @page
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

<h2>Hello from a Razor UI class library!</h2>
<p> From  RazorUIClassLib\Areas\MyFeature\Pages\Page1.cshtml</p>

<partial name="_Message" />

    É necessário utilizar @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers para a visualização parcial (<partial name="_Message" />). Em vez de incluir a diretiva @addTagHelper, você pode adicionar um arquivo _ViewImports.cshtml. Por exemplo:

    dotnet new viewimports -o RazorUIClassLib/Areas/MyFeature/Pages

    Para obter mais informações sobre _ViewImports.cshtml, consulte Importando diretivas compartilhadas

  • Crie a biblioteca de classes para verificar se não há erros do compilador:

    dotnet build RazorUIClassLib

A saída de compilação contém RazorUIClassLib.dll e RazorUIClassLib.Views.dll. RazorUIClassLib.Views.dll contém o conteúdo Razor compilado.

Utilizar a biblioteca de IU do Razor num projeto do Razor Pages

Crie a aplicação web Razor Pages:

  • No Gerenciador de Soluções , clique com o botão direito do mouse na solução >Adicionar>Novo Projeto.

  • Selecione Aplicação Web ASP.NET Core.

  • Nomeie o aplicativo WebApp1.

  • Verifique se ASP.NET Core 2.1 ou posterior está selecionado.

  • Selecione Aplicativo Web>OK.

  • No Gerenciador de Soluções , clique com o botão direito do mouse em WebApp1 e selecione Configurar como Projeto de Inicialização.

  • A partir do Explorador de Soluções , clique com o botão direito em WebApp1 e selecione Dependências de Compilação>Dependências do Projeto.

  • Verifique RazorUIClassLib como uma dependência de WebApp1.

  • No Explorador de Soluções , clique com o botão direito do rato em WebApp1 e selecione Adicionar>Referência.

  • Na caixa de diálogo do Reference Manager, verifique RazorUIClassLibOK.

Execute o aplicativo.

Testar WebApp1

Navegue até /MyFeature/Page1 para verificar se a biblioteca de classes da interface do usuário do Razor está em uso.

Sobrescrever vistas, vistas parciais e páginas

Quando uma vista, vista parcial ou Página Razor é encontrada na aplicação web e na RCL, o código de marcação Razor (ficheiro.cshtml) na aplicação web tem precedência. Por exemplo, adicione WebApp1/Areas/MyFeature/Pages/Page1.cshtml ao WebApp1 e Page1 no WebApp1 terá precedência sobre Page1 na RCL.

No download de exemplo, renomeie WebApp1/Areas/MyFeature2 para WebApp1/Areas/MyFeature para testar a precedência.

Copie vista parcial RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml para WebApp1/Areas/MyFeature/Pages/Shared/_Message.cshtml. Atualize a marcação para indicar o novo local. Construa e execute a aplicação para verificar se está a ser utilizada a versão parcial da aplicação.

Layout de páginas RCL

Para fazer referência ao conteúdo RCL como se fizesse parte da pasta Pages da aplicação Web, crie o projeto RCL com a seguinte estrutura de ficheiros:

  • RazorUIClassLib/Pages
  • RazorUIClassLib/Pages/Shared

Suponha que RazorUIClassLib/Pages/Shared contém dois arquivos parciais: _Header.cshtml e _Footer.cshtml. As <partial> tags podem ser adicionadas ao _Layout.cshtml arquivo.

<body>
  <partial name="_Header">
  @RenderBody()
  <partial name="_Footer">
</body>

Razor vistas, páginas, controladores, modelos de página Razor componentes, Componentes de exibiçãoe modelos de dados podem ser criados numa biblioteca de classes Razor (RCL). O RCL pode ser embalado e reutilizado. As aplicações podem incluir a RCL e substituir as vistas e páginas que ela contém. Quando uma vista, vista parcial ou Página Razor é encontrada na aplicação Web e na RCL, a marcação Razor (ficheiro.cshtml) na aplicação Web tem precedência.

Exibir ou baixar código de exemplo (como baixar)

Criar uma biblioteca de classes contendo a interface de utilizador Razor

  • No Visual Studio, selecione Criar um novo projeto.
  • Selecione Razor Biblioteca de Classe>Próximo.
  • Dê um nome à biblioteca (por exemplo, "RazorClassLib") >Crie. Para evitar uma colisão de nome de arquivo com a biblioteca de exibição gerada, verifique se o nome da biblioteca não termina em .Views.
  • Selecione páginas de suporte e visões se precisar oferecer suporte a visões. Por padrão, apenas páginas Razor são suportadas. Selecione Criar.

O modelo de biblioteca de classes Razor (RCL) assume como padrão o desenvolvimento de componentes Razor. A opção suporta páginas e visualizações da funcionalidade .

Adicione ficheiros Razor à RCL.

Os modelos ASP.NET Core assumem que o conteúdo RCL está na pasta Areas. Consulte RCL Páginas layout abaixo para criar uma RCL que exponha conteúdo em ~/Pages em vez de ~/Areas/Pages.

Conteúdo RCL de referência

O RCL pode ser referenciado por:

Substituir vistas, vistas parciais e páginas

Quando uma vista, vista parcial ou Página Razor é encontrada na aplicação Web e na RCL, a marcação Razor (ficheiro.cshtml) na aplicação Web tem precedência. Por exemplo, adicione WebApp1/Areas/MyFeature/Pages/Page1.cshtml ao WebApp1 e Page1 no WebApp1 terá precedência sobre Page1 na RCL.

No download de exemplo, renomeie WebApp1/Areas/MyFeature2 para WebApp1/Areas/MyFeature para testar a precedência.

Copie a visualização parcial RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml para WebApp1/Areas/MyFeature/Pages/Shared/_Message.cshtml. Atualize as marcações para indicar o novo local. Execute a aplicação para verificar se a versão parcial da aplicação está a ser usada.

Se a RCL utilizar Razor Páginas, ative os serviços e pontos finais do Razor Pages na aplicação de alojamento:

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

public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles();
    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllerRoute(
            name: "default",
            pattern: "{controller=Home}/{action=Index}/{id?}");

        endpoints.MapRazorPages();
    });
}

Layout de páginas RCL

Para fazer referência ao conteúdo RCL como se fizesse parte da pasta Pages da aplicação Web, crie o projeto RCL com a seguinte estrutura de ficheiros:

  • RazorUIClassLib/Pages
  • RazorUIClassLib/Pages/Shared

Suponha que RazorUIClassLib/Pages/Shared contém dois arquivos parciais: _Header.cshtml e _Footer.cshtml. As <partial> tags podem ser adicionadas ao _Layout.cshtml arquivo.

<body>
  <partial name="_Header">
  @RenderBody()
  <partial name="_Footer">
</body>

Adicione o ficheiro _ViewStart.cshtml à pasta Pages do projeto RCL para utilizar o ficheiro _Layout.cshtml da aplicação Web anfitrião:

@{
    Layout = "_Layout";
}

Criar um RCL com ativos estáticos

Uma RCL pode exigir ativos estáticos complementares que podem ser referenciados pela RCL ou pela aplicação consumidora da RCL. ASP.NET Core permite criar RCLs que incluem ativos estáticos que estão disponíveis para um aplicativo consumidor.

Para incluir ativos complementares como parte de uma RCL, crie uma pasta wwwroot na biblioteca de classes e inclua todos os arquivos necessários nessa pasta.

Ao embalar um RCL, todos os ativos complementares na pasta wwwroot são automaticamente incluídos no pacote.

Use o comando dotnet pack em vez da versão NuGet.exe nuget pack.

Excluir ativos estáticos

Para excluir ativos estáticos, adicione o caminho de exclusão desejado ao grupo de propriedades $(DefaultItemExcludes) no arquivo de projeto. Separe as entradas com ponto e vírgula (;).

No exemplo a seguir, a folha de estilo lib.css na pasta wwwroot não é considerada um ativo estático e não está incluída na RCL publicada:

<PropertyGroup>
  <DefaultItemExcludes>$(DefaultItemExcludes);wwwroot\lib.css</DefaultItemExcludes>
</PropertyGroup>

Integração Typescript

Para incluir ficheiros TypeScript numa RCL:

  1. Faça referência ao pacote NuGet Microsoft.TypeScript.MSBuild no projeto.

    Observação

    Para obter orientação sobre como adicionar pacotes a aplicativos .NET, consulte os artigos em Instalar e gerenciar pacotes em Fluxo de trabalho de consumo de pacotes (documentação do NuGet). Confirme as versões corretas do pacote em NuGet.org.

  2. Coloque os arquivos TypeScript (.ts) fora da pasta wwwroot. Por exemplo, coloque os arquivos em uma pasta Client.

  3. Configure a saída de compilação TypeScript para a pasta wwwroot. Defina a propriedade TypescriptOutDir dentro de um PropertyGroup no arquivo de projeto:

    <TypescriptOutDir>wwwroot</TypescriptOutDir>

  4. Inclua o destino TypeScript como uma dependência do destino ResolveCurrentProjectStaticWebAssets adicionando o seguinte destino dentro de um PropertyGroup no arquivo de projeto:

    <ResolveCurrentProjectStaticWebAssetsInputsDependsOn>
  CompileTypeScript;
  $(ResolveCurrentProjectStaticWebAssetsInputs)
</ResolveCurrentProjectStaticWebAssetsInputsDependsOn>

Consumir conteúdo de uma RCL referenciada

Os ficheiros incluídos na pasta wwwroot da RCL são expostos à RCL ou à aplicação consumidora sob o prefixo _content/{PACKAGE ID}/. Por exemplo, uma biblioteca com um nome de assembly de Razor.Class.Lib e sem um <PackageId> especificado em seu arquivo de projeto resulta em um caminho para o conteúdo estático em _content/Razor.Class.Lib/. Ao produzir um pacote NuGet e o nome do assembly não for o mesmo que o ID do pacote (<PackageId> no arquivo de projeto da biblioteca), use o ID do pacote conforme especificado no arquivo de projeto para {PACKAGE ID}.

A aplicação consumidora refere-se a ativos estáticos fornecidos pela biblioteca com <script>, <style>, <img>e outras etiquetas HTML. A aplicação de consumo deve ter suporte a ficheiros estáticos ativado em Startup.Configure:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    ...

    app.UseStaticFiles();

    ...
}

Ao executar o aplicativo de consumo a partir da saída de compilação (dotnet run), os ativos da Web estáticos são habilitados por padrão no ambiente de desenvolvimento. Para oferecer suporte a ativos em outros ambientes ao executar a partir da saída de compilação, chame UseStaticWebAssets no construtor de host em Program.cs:

using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Hosting;

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStaticWebAssets();
                webBuilder.UseStartup<Startup>();
            });
}

Chamar UseStaticWebAssets não é necessário ao executar um aplicativo a partir da saída publicada (dotnet publish).

Fluxo de desenvolvimento multi-projeto

Quando o aplicativo de consumo é executado:

  • Os ativos na RCL permanecem em suas pastas originais. Os ativos não são movidos para o aplicativo de consumo.
  • Qualquer alteração na pasta wwwroot do RCL é refletida na aplicação de consumo após a reconstrução do RCL e sem a necessidade de reconstruir a aplicação de consumo.

Quando o RCL é construído, é produzido um manifesto que descreve locais de recursos web estáticos. A aplicação consumidora lê o manifesto em tempo de execução para consumir os recursos de projetos e pacotes referenciados. Quando um novo ativo é adicionado a uma RCL, a RCL deve ser reconstruída para atualizar seu manifesto antes que um aplicativo consumidor possa acessar o novo ativo.

Publicar

Quando a aplicação é publicada, os ativos complementares de todos os projetos e pacotes referenciados são copiados para a pasta wwwroot da aplicação publicada em _content/{PACKAGE ID}/. Ao produzir um pacote NuGet, se o nome do assembly não for igual ao ID do pacote (<PackageId> no arquivo de projeto da biblioteca), utilize o ID do pacote conforme especificado no arquivo de projeto para {PACKAGE ID} ao examinar a pasta wwwroot para os ativos publicados.

Recursos adicionais