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). O RCL pode ser empacotado e reutilizado. 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 RCL, consulte Criar ativos web cliente para sua Razor Biblioteca de Classes .

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 os componentes Razor são compatíveis. Selecione Criar.

O modelo de 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

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

dotnet new razorclasslib -o RazorUIClassLib

O modelo de 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 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 projeto RCL para usar o arquivo Pages do aplicativo web 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 do Typescript

Para incluir arquivos TypeScript em uma RCL:

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

  Note

  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.

• 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 build do TypeScript para a pasta wwwroot usando a propriedade TypescriptOutDir.
  • Inclua o destino TypeScript como uma dependência do destino PrepareForBuildDependsOn.
  • Remover 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 de uma RCL referenciada

Os arquivos incluídos na pasta wwwroot da RCL são expostos à RCL ou ao aplicativo consumidor 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 é 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 a partir 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 é construída, é produzido um manifesto que descreve as localizações dos ativos de 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.

Publish

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 ASP.NET Core Razor de uma Razor biblioteca de classes (RCL)

• Isolamento de CSS Blazor no ASP.NET Core