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

Por Rick Anderson

Razor vistas, páginas, controladores, modelos de página Razor componentes, componentes de exibição, e 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 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

Estúdio Visual

• 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 visualizaçõ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).

CLI do .NET

Na linha de comando, execute dotnet new razorclasslib. Por exemplo:

dotnet new razorclasslib -o RazorUIClassLib

O modelo Biblioteca de Classes Razor assume o desenvolvimento de componentes Razor como padrão. Passe a opção --support-pages-and-views (dotnet new razorclasslib --support-pages-and-views) para fornecer suporte para páginas e visualizações.

Para obter mais informações, consulte dotnet new. 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.

Adicione Razor arquivos à 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:

• Pacote NuGet. Consulte Criação de pacotes NuGet e dotnet adicionar pacote e Criar e publicar um pacote NuGet.
• {ProjectName}.csproj. Veja dotnet-add referência.

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.

Copiar 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. Construa e execute a aplicação para verificar se está a ser utilizada a versão fragmentada da aplicação.

Se a RCL utilizar os Razor Pages, ative os serviços e pontos finais do Razor Pages na aplicação anfitriã.

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 Desenvolver ativos Web de cliente para Razor a sua Biblioteca de Classes para 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.

  Note

  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 o resultado da 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">

  <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 a partir 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 recursos 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.

Publish

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}/. Quando estiver a 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}, ao examinar a pasta wwwroot para os ativos publicados.

Recursos adicionais

• Visualizar ou baixar código de exemplo (como descarregar)

• Consumir componentes do ASP.NET Core Razor a partir de uma biblioteca de classes (RCL) Razor

• ASP.NET Core Blazor isolamento CSS