Creación de una interfaz de usuario reutilizable con el proyecto de biblioteca de clases de Razor en ASP.NET Core

Por Rick Anderson

Las vistas, páginas, controladores y modelos de página de Razor, los componentes de Razor, los componentes de vista y los modelos de datos se pueden integrar en una biblioteca de clases de Razor (RCL). Las RCL se pueden empaquetar y reutilizar. Las aplicaciones pueden incluir la RCL y reemplazar las vistas y páginas que contienen. Si existe una vista,una vista parcial o una página de Razor tanto en la aplicación web como en la RCL, tiene prioridad el marcado de Razor (archivo .cshtml) de la aplicación web.

Para obtener información sobre cómo integrar npm y webpack en el proceso de compilación de una biblioteca de clases Razor (RCL), consulta Compilación de recursos web cliente para la Biblioteca de clases Razor.

Creación de una biblioteca de clases que contenga interfaz de usuario de Razor

Visual Studio

• En Visual Studio, selecciona Crear un proyecto nuevo.
• Selecciona Biblioteca de clases de Razor>Siguiente.
• Asigna un nombre a la biblioteca (por ejemplo, "RazorClassLib"), >Crear. Para evitar un conflicto de nombres de archivo con la biblioteca de vistas generada, asegúrate de que el nombre de la biblioteca no acaba en .Views.
• Selecciona Páginas y vistas de soporte técnico si necesitas que la biblioteca contenga páginas o vistas. Solo se admiten componentes de Razor de forma predeterminada. Selecciona Crear.

De forma predeterminada, la plantilla de la biblioteca de clases Razor usa el desarrollo de componentes de Razor. La opción Admitir páginas y vistas proporciona compatibilidad con páginas y vistas. Para obtener más información sobre la compatibilidad con RCL en Blazor, consulta Consumo de componentes Razor de ASP.NET Core a partir de una biblioteca de clases de Razor (RCL).

CLI de .NET

Ejecuta dotnet new razorclasslib desde la línea de comandos. Por ejemplo:

dotnet new razorclasslib -o RazorUIClassLib

De forma predeterminada, la plantilla de la biblioteca de clases Razor usa el desarrollo de componentes de Razor. Pasa la opción --support-pages-and-views (dotnet new razorclasslib --support-pages-and-views) para proporcionar compatibilidad con páginas y vistas.

Para obtener más información, consulta dotnet new. Para evitar un conflicto de nombres de archivo con la biblioteca de vistas generada, asegúrate de que el nombre de la biblioteca no acaba en .Views.

Agrega archivos de Razor a la RCL.

Las plantillas de ASP.NET Core dan por sentado que el contenido de la RCL se encuentra en la carpeta Areas. Consulta la sección Diseño de páginas de RCL a continuación para crear una RCL que exponga el contenido en ~/Pages en lugar de ~/Areas/Pages.

Referencias al contenido de la RCL

Los siguientes elementos pueden hacer referencia a la RCL:

• Paquete NuGet. Consulta Creación de paquetes NuGet, dotnet add package y Creación y publicación de un paquete NuGet.
• {ProjectName}.csproj. Consulta dotnet-add reference.

Reemplazar vistas, vistas parciales y páginas

Si existe una vista, una vista parcial o una página de Razor tanto en la aplicación web como en la RCL, tiene prioridad el marcado de Razor (archivo .cshtml) de la aplicación web. Por ejemplo, si agregas WebApp1/Areas/MyFeature/Pages/Page1.cshtml a WebApp1, Page1 en WebApp1 prevalecerá sobre Page1 en la RCL.

En la descarga de ejemplo, cambia el nombre WebApp1/Areas/MyFeature2 por WebApp1/Areas/MyFeature para comprobar la prioridad.

Copia la vista parcial RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml en WebApp1/Areas/MyFeature/Pages/Shared/_Message.cshtml. Actualiza el marcado para señalar la nueva ubicación. Compila y ejecuta la aplicación para comprobar si se está usando la versión de la vista parcial de la aplicación.

Si la RCL usa Razor Pages, habilita los servicios y puntos de conexión de Razor Pages en la aplicación de hospedaje:

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();

Diseño de páginas de RCL

Para hacer referencia al contenido de la RCL como si formara parte de la carpeta Pages de la aplicación web, crea el proyecto RCL con la siguiente estructura de archivos:

• RazorUIClassLib/Pages
• RazorUIClassLib/Pages/Shared

Imagina que RazorUIClassLib/Pages/Shared contiene dos archivos parciales: _Header.cshtml y _Footer.cshtml. En ese caso, se podrían agregar etiquetas <partial> al archivo _Layout.cshtml:

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

Agrega el archivo _ViewStart.cshtml a la carpeta Pages del proyecto RCL para usar el archivo _Layout.cshtml de la aplicación web host:

@{
    Layout = "_Layout";
}

Creación de una RCL con recursos estáticos

Una RCL puede requerir recursos estáticos complementarios a los que puede hacer referencia la RCL o la aplicación de consumo de la RCL. ASP.NET Core permite crear bibliotecas de clases de Razor que incluyan recursos estáticos que estén disponibles para una aplicación de consumo.

Para incluir los recursos complementarios como parte de una RCL, crea una carpeta wwwroot en la biblioteca de clases e incluya en ella los archivos necesarios.

Al empaquetar una RCL, todos los recursos complementarios de la carpeta wwwroot se incluyen automáticamente en el paquete.

Use el comando dotnet pack en vez de la versión de NuGet.exe nuget pack.

Adición de recursos web de cliente al proceso de compilación

La integración de recursos web de cliente en la canalización de compilación no es trivial. Consulte Compilación de recursos web de cliente para la biblioteca de clases Razor para obtener más información.

Exclusión de recursos estáticos

Para excluir recursos estáticos, agregue la ruta de exclusión deseada al grupo de propiedades $(DefaultItemExcludes) en el archivo del proyecto. Separe las entradas con un punto y coma (;).

En el ejemplo siguiente, la hoja de estilos lib.css de la carpeta wwwroot no se considera un recurso estático y no se incluye en la RCL publicada:

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

Integración de TypeScript

Para incluir archivos TypeScript en una RCL:

1. Haga referencia al paquete NuGet Microsoft.TypeScript.MSBuild en el proyecto.

   Nota

   Para obtener instrucciones sobre cómo agregar paquetes a aplicaciones .NET, consulta los artículos de Instalación y administración de paquetes en Flujo de trabajo de consumo de paquetes (documentación de NuGet). Confirme las versiones correctas del paquete en NuGet.org.

2. Coloque los archivos TypeScript ( .ts) fuera de la carpeta wwwroot. Por ejemplo, coloque los archivos en una carpeta de Client.

3. Configure la salida de la compilación de TypeScript para la carpeta wwwroot. Establezca la propiedad TypescriptOutDir dentro de un PropertyGroup en el archivo del proyecto:

   <TypescriptOutDir>wwwroot</TypescriptOutDir>
   

4. Incluya el destino de TypeScript como una dependencia del destino PrepareForBuildDependsOn; para ello, agregue el siguiente destino dentro de un objeto PropertyGroup en el archivo del proyecto:

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

Consumo de contenido de una RCL a la que se hace referencia

Los archivos incluidos en la carpeta wwwroot de la RCL se exponen a la RCL o a la aplicación de consumo en el prefijo _content/{PACKAGE ID}/. Por ejemplo, una biblioteca con un nombre de ensamblado de Razor.Class.Lib y sin un objeto <PackageId> especificado en su archivo de proyecto da como resultado una ruta al contenido estático en _content/Razor.Class.Lib/. Al generar un paquete NuGet, si el nombre del ensamblado no es igual que el del identificador del paquete (<PackageId> en el archivo de proyecto de la biblioteca), use el identificador de paquete tal como se especifica en el archivo del proyecto para {PACKAGE ID}.

La aplicación de consumo hace referencia a los recursos estáticos proporcionados por la biblioteca con <script>, <style>, <img> y otras etiquetas HTML. La aplicación de consumo debe tener habilitada la compatibilidad con archivos estáticos en:

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();

Al ejecutar la aplicación de consumo desde la salida de la compilación (dotnet run), los activos web estáticos están habilitados de forma predeterminada en el entorno de desarrollo. Para admitir recursos en otros entornos al ejecutar la aplicación desde la salida de la compilación, llame a UseStaticWebAssets en el generador de hosts en 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();

No es necesario llamar a UseStaticWebAssets si se ejecuta una aplicación desde la salida publicada (dotnet publish).

Flujo de desarrollo de varios proyectos

Al ejecutar la aplicación de consumo:

• Los recursos de la biblioteca de clases de Razor permanecen en sus carpetas originales. Los recursos no se mueven a la aplicación de consumo.
• Cualquier cambio dentro de la carpeta wwwroot de la RCL se refleja en la aplicación de consumo después de que se vuelva a compilar la RCL y sin tener que recompilar la aplicación de consumo.

Cuando se compila la biblioteca de clases de Razor, se genera un manifiesto que describe las ubicaciones de los recursos web estáticos. La aplicación de consumo lee el manifiesto en tiempo de ejecución para consumir los recursos de los proyectos y paquetes a los que se hace referencia. Cuando se agrega un nuevo recurso a una RCL, esta se debe recompilar para actualizar el manifiesto antes de que una aplicación de consumo pueda acceder al nuevo recurso.

Publicar

Cuando se publica la aplicación, los recursos complementarios de todos los proyectos y paquetes a los que se hace referencia se copian en la carpeta wwwroot de la aplicación publicada en _content/{PACKAGE ID}/. Al generar un paquete NuGet, si el nombre del ensamblado no igual que el del identificador del paquete (<PackageId> en el archivo de proyecto de la biblioteca), use el identificador de paquete tal como se especifica en el archivo del proyecto para {PACKAGE ID} al examinar la carpeta wwwroot de los recursos publicados.

Recursos adicionales

• Vea o descargue el código de ejemplo (cómo descargarlo)

• Consumo de componentes Razor de ASP.NET Core de bibliotecas de clases Razor (RCL)

• Aislamiento de CSS de Blazor de ASP.NET Core