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

De Rick Anderson

Modos de exibição do Razor, páginas, controladores, modelos de página, Razor componentes, Componentes de exibição e modelos de dados podem ser inseridos em uma RCL (biblioteca de classes Razor). A RCL pode ser e empacotada e reutilizada. Os aplicativos podem incluir a RCL e substituir as exibições e as páginas que ela contém. Quando uma exibição, uma exibição parcial ou uma página Razor for encontrada no aplicativo Web e na RCL, a marcação Razor (arquivo .cshtml) no aplicativo Web terá precedência.

Para obter informações sobre como integrar o npm e o webpack ao processo de build de uma Biblioteca de Classes Razor, consulte Criar ativos web cliente para sua Biblioteca de Classes Razor.

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

Visual Studio

• No Visual Studio, selecione Criar um projeto.
• Selecione Biblioteca de Classes Razor>Avançar.
• Dê um nome à biblioteca (por exemplo, "RazorClassLib"), >Criar. 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 Suporte a páginas e exibições se precisar que a biblioteca contenha páginas e/ou exibições. Por padrão, somente componentes Razor é compatível. Selecione Criar.

O modelo de RCL (biblioteca de classes) Razor usa o desenvolvimento de componentes Razor por padrão. A opção Páginas e exibições de suporte dá suporte a páginas e exibições. Para obter mais informações sobre o suporte à RCL em Blazor, confira Consumir componentes do ASP.NET Core Razor de uma biblioteca de classes (RCL) Razor.

CLI do .NET Core

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

dotnet new razorclasslib -o RazorUIClassLib

O modelo de RCL (biblioteca de classes) Razor usa o desenvolvimento de componentes Razor por padrão. Passe a opção --support-pages-and-views (dotnet new razorclasslib --support-pages-and-views) para dar suporte a páginas e exibições.

Para obter mais informações, confira 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 arquivos Razor na RCL.

Os modelos de ASP.NET Core pressupõem que o conteúdo RCL esteja na pasta Areas. Veja o layout da RCL Pages abaixo para criar uma RCL que expõe o conteúdo no ~/Pages em vez de ~/Areas/Pages.

Referenciar conteúdo RCL

A RCL pode ser referenciada por:

• Pacote do NuGet. Confira Criando pacotes do NuGet, dotnet add package e Criar e publicar um pacote do NuGet.
• {ProjectName}.csproj. Confira dotnet-add reference.

Substituir exibições, exibições parciais e páginas

Quando uma exibição, uma exibição parcial ou uma página Razor for encontrada no aplicativo Web e na RCL, a marcação Razor (arquivo .cshtml) no aplicativo Web terá 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 como WebApp1/Areas/MyFeature para testar a precedência.

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

Se a RCL usar Razor Pages, habilite os serviços e os pontos de extremidade do Razor Pages no aplicativo de hospedagem:

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 da RCL Pages

Para fazer referência ao conteúdo da RCL como se fosse parte da pasta Pages do aplicativo Web, crie o projeto da RCL com a seguinte estrutura de arquivos:

• RazorUIClassLib/Pages
• RazorUIClassLib/Pages/Shared

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

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

Adicione o arquivo _ViewStart.cshtml à pasta do Pages projeto RCL para usar o arquivo _Layout.cshtml do aplicativo Web de host:

@{
    Layout = "_Layout";
}

Criar uma RCL com ativos estáticos

Uma RCL pode exigir ativos estáticos complementares que podem ser referenciados pela RCL ou pelo aplicativo de consumo da RCL. O ASP.NET Core permite a criação de RCLs que incluem ativos estáticos disponíveis para um aplicativo de consumo.

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 empacotar uma RCL, todos os ativos complementares na pasta wwwroot são incluídos automaticamente no pacote.

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

Adicionar ativos Web do cliente ao processo de build

A integração de ativos Web do cliente ao pipeline de build não é trivial. Confira Criar ativos da Web do cliente para a 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 entradas com ponto e vírgula (;).

No exemplo a seguir, a folha de estilos 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 com Typescript

Para incluir arquivos TypeScript em uma RCL:

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

   Observação

   Para obter diretrizes sobre como adicionar pacotes a aplicativos .NET, consulte os artigos em Instalar e gerenciar pacotes no Fluxo de trabalho de consumo de pacotes (documentação do NuGet). Confirme as versões corretas de 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 build 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 arquivos incluídos na pasta wwwroot da RCL são expostos à RCL ou ao aplicativo de consumo no 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 é o mesmo que a ID do pacote (<PackageId> no arquivo de projeto da biblioteca), use a ID do pacote conforme especificado no arquivo 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 marcas 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 o aplicativo de consumo da saída de build (dotnet run), os ativos da Web estáticos são habilitados por padrão no ambiente de desenvolvimento. Para dar suporte a ativos em outros ambientes ao executar a partir da saída de build, 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();

A chamada de UseStaticWebAssets não é necessária ao executar um aplicativo da saída publicada (dotnet publish).

Fluxo de desenvolvimento de vários projetos

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 da RCL é refletida no aplicativo de consumo depois que a RCL é reconstruída e sem recriar o aplicativo de consumo.

Quando a RCL é criada, um manifesto é produzido que descreve os locais de ativos da Web estáticos. O aplicativo de consumo lê o manifesto em runtime para consumir os ativos de projetos e pacotes referenciados. Quando um novo ativo é adicionado a uma RCL, a RCL deve ser recriada para atualizar seu manifesto antes que um aplicativo de consumo possa acessar o novo ativo.

Publicação

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

Recursos adicionais

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

• Consumir componentes do Razor de uma Razor biblioteca de classes (RCL)

• Isolamento da CSS Blazor do ASP.NET Core