- Razor Pages ofrece un modelo centrado en páginas sobre ASP.NET Core, compartiendo el mismo potente enrutamiento, middleware y motor de vistas Razor que MVC.
- Los proyectos reales se centran en la carpeta Pages, wwwroot, appsettings.json y Program.cs, donde se configuran los servicios, el middleware y el manejo de errores.
- Herramientas como Visual Studio, Rider y VS Code simplifican el desarrollo, la depuración, la navegación y la refactorización de modelos, vistas y sintaxis Razor.
- ASP.NET Core simplifica la publicación de aplicaciones Razor en IIS, Azure, servidores personalizados o Docker, lo que permite implementaciones escalables y repetibles.
Si vienes de Angular y ASP.NET Web API y estás empezando a disfrutar de C# en el backend, Razor Pages es una forma increíblemente natural de trasladar esa satisfacción al frontend sin abandonar tus conocimientos de JavaScript. En lugar de lanzarse de cabeza a una pila de interfaz de usuario completamente diferente, puede permanecer en el terreno familiar de ASP.NET Core, usar la sintaxis Razor para la representación del lado del servidor y seguir incorporando JavaScript donde tenga sentido.
ASP.NET Core Razor Pages es el método recomendado por Microsoft para crear aplicaciones web modernas en .NET, ya que ofrece un modelo limpio basado en páginas que se ejecuta sobre la potente arquitectura de ASP.NET Core. Es multiplataforma, se integra a la perfección con herramientas como Visual Studio, Visual Studio Code y JetBrains Rider, y se adapta desde pequeños prototipos hasta aplicaciones de producción con bases de datos. En esta guía, explicaremos cómo se estructuran las aplicaciones Razor Pages reales, cómo Program.cs conecta todos los componentes, cómo funcionan los archivos estáticos y la configuración, y cómo entran en juego las herramientas, la depuración y la implementación.
Qué son realmente las páginas Razor de ASP.NET Core (y cómo se comparan con MVC)
Razor Pages es una característica de ASP.NET Core que permite crear aplicaciones web basadas en páginas en lugar de controladores, ofreciendo un modelo mental más sencillo sin dejar de utilizar el mismo marco subyacente que MVC. Internamente, funciona con la misma infraestructura de enrutamiento, middleware y alojamiento que los controladores y las vistas, pero cada página gestiona su propio comportamiento en lugar de centralizarlo todo en las clases del controlador.
Cada página Razor suele estar representada por un par de archivos: un archivo .cshtml para el marcado y un archivo .cshtml.cs para la lógica C# de la página. El archivo .cshtml contiene tu HTML mezclado con sintaxis Razor (por ejemplo, bucles, condiciones y funciones auxiliares de HTML), mientras que el archivo de código subyacente .cshtml.cs contiene métodos de controlador como OnGet, OnPost, propiedades del modelo y cualquier lógica necesaria para renderizar o procesar la página.
Antes de Razor Pages, el patrón dominante en ASP.NET era MVC, donde los controladores devolvían vistas y enrutaban todas las solicitudes a través de métodos de acción. MVC sigue siendo totalmente compatible y es un patrón probado con convenciones sólidas, pero en muchos casos, Razor Pages es más rápido de entender porque el código que carga y procesa una página está físicamente junto a su marcado en lugar de estar oculto en un controlador separado.
Aunque Razor Pages deja de centrarse en los controladores, sigue utilizando el mismo motor de vistas Razor y admite tanto HtmlHelpers como TagHelpers para generar HTML dinámico. Los TagHelpers son particularmente útiles: extienden las etiquetas HTML normales con atributos como asp-action, asp-controller or asp-route De esta forma, puedes conectar enlaces y formularios a los puntos finales del servidor sin tener que escribir un montón de URL manuales ni código JavaScript en línea.
Para los desarrolladores que ya conocen JavaScript y han trabajado con frameworks SPA, Razor Pages ofrece un enfoque híbrido: HTML renderizado en el servidor para una carga inicial rápida y SEO, con JavaScript y bibliotecas de front-end añadidas donde sea necesario. No estás obligado a usar ningún framework de JavaScript en particular, y puedes mantener el backend y el frontend en la misma solución, lo que simplifica la implementación y el mantenimiento.
Creación y ejecución de una aplicación web Razor Pages
Cuando creas un nuevo proyecto de ASP.NET Core Razor Pages usando Visual Studio, Visual Studio Code o Rider, la plantilla configura una aplicación mínima pero completa, que incluye Program.cs, la carpeta Pages, los archivos de configuración y la raíz web estática. De entrada, obtienes un sitio web funcional que puedes poner en marcha inmediatamente y que luego puedes evolucionar hacia algo más sofisticado, como un catálogo de películas o cualquier otra aplicación basada en datos.
Antes de ejecutar la aplicación en HTTPS, ASP.NET Core necesita usar un certificado de desarrollo en el que confíe su sistema operativo, y la primera vez que ejecute el proyecto es posible que vea un cuadro de diálogo que le pida que confíe en él. Cuando aparezca ese cuadro de diálogo, elija Sí Esto indica que usted está de acuerdo con que se utilice el certificado de desarrollo local para el tráfico HTTPS en su máquina, lo cual es necesario para probar correctamente los puntos finales seguros sin advertencias del navegador.
En Windows, macOS o Linux, Visual Studio Code te permite iniciar la aplicación pulsando Ctrl+F5 para ejecutar sin depuración, o usar el panel Ejecutar y depurar si desea conectar el depurador. La primera vez, VS Code puede solicitarle que seleccione un tipo de depurador como C#, .NET 5+ y .NET Core o una configuración de lanzamiento específica como C#: RazorPagesMovie [https] RazorPagesMovie dependiendo de la versión de .NET y la configuración de su espacio de trabajo.
Después de iniciarse, su navegador predeterminado se abrirá en una URL similar a https://localhost:<port>donde el puerto se asigna aleatoriamente o se especifica en launchSettings.json, y estás viendo la página de inicio servida por la aplicación Razor Pages. En algunas plantillas, verá en su lugar: http://localhost:5001 o otro puerto; lo fundamental es que localhost indica que se trata de tu propia máquina y no de un host externo.
Una vez que haya terminado de realizar las pruebas, puede detener la aplicación en ejecución desde su IDE: en Visual Studio Code use el menú Ejecutar y seleccione Detener depuración o presione Shift+F5, mientras que en Visual Studio para Mac se usa Depurar > Detener depuración. Esto finaliza la instancia del servidor web Kestrel que se inició para la sesión y libera el puerto para que pueda utilizarse en otras ocasiones.
Comprender la estructura del proyecto: carpetas y archivos clave
Las aplicaciones reales de Razor Pages se organizan en torno a unas pocas carpetas y archivos de configuración importantes con los que trabajarás constantemente: Pages, wwwroot, appsettings.json y Program.cs (y en versiones anteriores, Startup.cs). Es fundamental familiarizarse con estas piezas, ya que prácticamente todos los tutoriales, ejemplos o proyectos de producción utilizan las mismas convenciones.
La carpeta Pages es el núcleo de un proyecto Razor Pages, ya que contiene todas las páginas .cshtml y sus archivos de código subyacente .cshtml.cs, junto con el diseño compartido y las vistas parciales. Cada par de páginas (por ejemplo Index.cshtml e Index.cshtml.cs) representa un punto final invocable en su aplicación, y los archivos especiales que comienzan con un guion bajo, como _Layout.cshtml, definir el contenido reutilizado en varias páginas.
El archivo de diseño, generalmente llamado _Layout.cshtmlDefine la apariencia de tu sitio, como la barra de navegación superior, el pie de página y el aviso de derechos de autor, y proporciona un lugar para mostrar el cuerpo de cada página individual. Al cambiar el diseño, se modifica instantáneamente la apariencia de todas las páginas Razor que lo utilizan, por lo que es el lugar ideal para editar menús, la imagen de marca y los scripts o estilos compartidos.
La carpeta wwwroot es la raíz web designada donde se almacenan los recursos estáticos, incluidos archivos CSS, JavaScript, imágenes y archivos HTML simples que pueden ser servidos directamente por el servidor web. Todo lo que se encuentre dentro de wwwroot puede ser accedido por el navegador (sujeto a la configuración de sus archivos estáticos), lo que lo convierte en el lugar adecuado para las hojas de estilo del sitio, las bibliotecas del lado del cliente y las imágenes a las que se hace referencia en su marcado.
La configuración de la aplicación normalmente se almacena en appsettings.json (y variantes específicas del entorno, como appsettings.Development.json), que contienen configuraciones como cadenas de conexión e indicadores de funciones. El sistema de configuración de ASP.NET Core carga estos archivos y los combina con variables de entorno y otros proveedores, lo que facilita la vinculación de secciones a clases de opciones fuertemente tipadas en su código.
Program.cs y la canalización de ASP.NET Core
El archivo Program.cs contiene el punto de entrada de su aplicación Razor Pages y define cómo se configuran el servidor web, los servicios y la canalización de middleware antes de que la primera solicitud llegue a su sitio. En las versiones modernas de ASP.NET Core, Program.cs utiliza un modelo de "alojamiento mínimo" optimizado con una instrucción de nivel superior que crea un WebApplicationBuilder y luego construye y configura el WebApplication ejemplo.
El patrón típico en Program.cs comienza con var builder = WebApplication.CreateBuilder(args); que configura un host con valores predeterminados comunes y luego llama builder.Services.AddRazorPages(); para registrar las páginas Razor con el contenedor de inyección de dependencias. Después de configurar los servicios, var app = builder.Build(); crea el objeto de aplicación que luego se conecta con middleware y puntos finales.
El manejo de errores y el comportamiento de seguridad dependen en gran medida del entorno, por lo que normalmente verá una comprobación del entorno como if (!app.Environment.IsDevelopment()) para habilitar funciones de nivel de producción. Dentro de esa condición normalmente encontrará app.UseExceptionHandler("/Error"); que envía los errores no controlados a una página de error dedicada, y app.UseHsts(); que activa la seguridad de transporte estricta HTTP (HSTS) para indicar a los navegadores que utilicen siempre HTTPS para su dominio.
Luego se ensambla la canalización de middleware con llamadas como app.UseHttpsRedirection();, app.UseStaticFiles(); or app.MapStaticAssets();, app.UseRouting(); y opcionalmente app.UseAuthorization(); seguido de las asignaciones de puntos finales. La redirección HTTPS obliga a que las solicitudes HTTP no seguras se actualicen a HTTPS, el middleware de archivos estáticos (o la asignación de recursos estáticos más reciente en .NET 9) permite servir recursos directamente desde wwwroot, y el enrutamiento decide qué punto final maneja cada URL entrante.
Finalmente, las páginas Razor están conectadas al enrutamiento con app.MapRazorPages(); opcionalmente encadenado con .WithStaticAssets(); en plantillas más recientes para integrar la optimización de activos estáticos y la aplicación se inicia utilizando app.Run();. En ese momento, la aplicación está escuchando en los puertos configurados y el servidor Kestrel está listo para gestionar las solicitudes reales, ya sea localmente en desarrollo o en un host de producción como IIS, Azure App Service o Docker.
Páginas Razor, modelos y modelos de vista en aplicaciones reales
Detrás de cada aplicación Razor Pages que no sea trivial, hay un conjunto de modelos de dominio y modelos de vista que representan sus datos y cómo se muestran, ya sea que esté administrando un catálogo de películas, un blog o un panel de control empresarial. Los modelos suelen corresponderse estrechamente con las entidades de la base de datos, mientras que los modelos de vista pueden adaptarse a una pantalla o flujo de usuario específico, combinando varios modelos o valores preformateados para facilitar la representación.
Un flujo de trabajo de desarrollo común consiste en comenzar con clases simples de C# que utilizan campos y firmas de métodos como esbozos, y gradualmente evolucionarlas hasta convertirlas en modelos adecuados con propiedades encapsuladas, atributos de validación y lógica. Herramientas como JetBrains Rider facilitan esa evolución mediante acciones intencionadas que convierten automáticamente campos en propiedades, crean tipos derivados para jerarquías de herencia y aplican otras refactorizaciones a medida que se perfecciona el modelo de objetos.
La herencia y las interfaces ayudan a imponer una estructura coherente para sus modelos, alineándolos con las reglas de negocio reales y permitiendo el polimorfismo, donde ciertos comportamientos se comparten pero las implementaciones difieren. Por ejemplo, podrías tener una base ContentItem tipo con derivado Movie, Series además Documentary clases, cada una con sutiles diferencias pero con un contrato común que se utiliza en toda la aplicación.
Una vez que los modelos estén listos, se pueden crear páginas Razor o vistas MVC, ya sea manualmente o mediante herramientas de andamiaje que generan páginas para listar, crear, editar y eliminar entidades. El andamiaje acelera drásticamente las primeras etapas del desarrollo y garantiza que el enrutamiento, la vinculación de modelos y la validación estén conectados correctamente, lo que permite personalizarlos posteriormente con su propio marcado y estilo.
La sintaxis Razor utilizada en los archivos .cshtml se combina a la perfección con los modelos y modelos de vista fuertemente tipados, lo que permite mostrar datos, ejecutar bucles y condicionales, y generar enlaces y formularios utilizando HtmlHelpers o TagHelpers sin perder la seguridad en tiempo de compilación. Esta combinación de C# y lenguaje de marcado mantiene gran parte de la lógica en el servidor, pero aun así genera un HTML limpio en el navegador que funciona bien con CSS y JavaScript.
Trabajar con la sintaxis Razor, TagHelpers y la navegación en Rider
La sintaxis Razor es una capa ligera sobre HTML que entra en acción siempre que... @ Aparece el símbolo, lo que facilita la inserción de expresiones, instrucciones o llamadas auxiliares de C# directamente en el código. Puedes recorrer listas de elementos, mostrar u ocultar elementos según ciertas condiciones, o mostrar valores y fechas formateadas sin necesidad de escribir un lenguaje de plantillas aparte ni de incluir código JavaScript por todas partes.
TagHelpers se sienten como una extensión natural de HTML donde los atributos especiales que comienzan con asp- Modifican el comportamiento o la salida de los elementos, a menudo reemplazando los métodos antiguos de HtmlHelper y eliminando la necesidad de usar código de script en línea. Los ejemplos incluyen asp-action además asp-controller para enrutar etiquetas de anclaje y formularios a acciones específicas, o atributos de ruta como asp-route-id para pasar parámetros de forma limpia en las URL.
El soporte del IDE es muy importante cuando se trabaja con HTML, y Rider ofrece funciones útiles como las migas de pan en la parte inferior del editor para mostrar la ubicación actual en la estructura del documento. Las migas de pan se pueden personalizar en Preferencias u Opciones, en la sección Editor, y hacen que navegar por archivos Razor largos con etiquetas anidadas sea mucho menos engorroso.
En los proyectos MVC, Rider también entiende las convenciones que vinculan controladores, acciones y vistas, por lo que al pasar el cursor sobre los resultados de las acciones puede mostrarle las posibles rutas de vista y Ctrl + clic (o Cmd-clic (en macOS) salta directamente al archivo .cshtml correspondiente. Atajos como Ctrl + B or Comando-B Proporciona una forma rápida de navegar por tu código base sin tener que buscar en los exploradores de soluciones.
Además de las herramientas específicas de Razor, Rider incluye un amplio conjunto de sugerencias y soluciones rápidas para HTML, CSS y JavaScript que te ayudan a escribir código del lado del cliente limpio y bien estructurado dentro del mismo IDE que tu backend de C#. Esta estrecha integración puede ahorrar muchos cambios de contexto al crear interfaces de usuario interactivas y complejas que aún dependen de vistas o páginas Razor renderizadas en el servidor.
Depuración de aplicaciones Razor Pages y ASP.NET Core
La depuración es una actividad diaria en el desarrollo web, y las aplicaciones ASP.NET Core que ejecutan Razor Pages no son una excepción, por lo que contar con un sólido soporte de depuración en su IDE es esencial. Tanto Visual Studio como Rider ofrecen depuradores interactivos que pueden adjuntarse al proceso de Kestrel, recorrer el código C# paso a paso, inspeccionar variables y evaluar expresiones mientras la aplicación se está ejecutando.
El depurador de Rider en Windows admite la función Editar y Continuar, que permite modificar el código mientras la aplicación está en pausa en un punto de interrupción y aplicar los cambios sin reiniciar toda la sesión de depuración. Esa capacidad para corregir pequeños errores o experimentar durante una ejecución de depuración acelera significativamente la resolución de problemas, especialmente en proyectos grandes con tiempos de inicio considerables.
La página de excepciones para desarrolladores predeterminada en ASP.NET Core se habilita automáticamente cuando el entorno se configura en Desarrollo, lo que le proporciona un seguimiento detallado de la pila, información de la solicitud y diagnósticos cada vez que se producen excepciones no controladas. Esta vista resulta extremadamente útil durante la depuración local, pero es peligrosa en producción porque puede revelar detalles internos sobre la aplicación y el entorno.
Para proteger la información confidencial, los entornos de producción y prueba suelen deshabilitar la página de excepciones del desarrollador y, en su lugar, utilizan la ruta del controlador de excepciones configurada, a menudo /Error, para mostrar una pantalla de error fácil de usar mientras se registran los detalles reales en el servidor. Este comportamiento se controla en Program.cs a través de la comprobación del entorno y las llamadas a UseExceptionHandler además UseHsts.
Cuando las cosas se complican de verdad y los tutoriales no se ajustan a tu comportamiento, suele ser útil comparar tu proyecto con un ejemplo conocido y correcto proporcionado por Microsoft u otras fuentes autorizadas. Muchos tutoriales oficiales de Razor Pages publican un proyecto de ejemplo completo que puedes ver o descargar para compararlo con tu propio código y detectar configuraciones faltantes, errores tipográficos o archivos mal ubicados.
Publicación e implementación de aplicaciones ASP.NET Core Razor reales
El lanzamiento de tu aplicación Razor Pages es donde toda la estructura y configuración previas dan sus frutos, porque ASP.NET Core admite varias opciones de implementación que se adaptan a diferentes entornos de alojamiento y flujos de trabajo. Tanto si prefiere IIS en Windows, como si prefiere contenedores Linux en Docker o una plataforma gestionada como Azure App Service, el proceso de publicación puede gestionarse mediante MSBuild e integrarse en sus canalizaciones de CI/CD.
Tanto Visual Studio como Rider ofrecen perfiles de publicación que permiten empaquetar la aplicación e implementarla en IIS mediante Web Deploy (MSDeploy), copiarla a una carpeta local o de red, o enviarla directamente a un servidor remoto a través de FTP, FTPS o SFTP. Al crear un perfil de publicación, se codifican los ajustes de implementación para que las futuras publicaciones sean tan sencillas como elegir el perfil y hacer clic en un botón o ejecutar un comando.
Para escenarios en la nube, Azure App Service es una opción popular, y los IDE integran las herramientas de Azure para crear y publicar aplicaciones web directamente desde el proyecto, aprovechando nuevamente MSBuild y MSDeploy internamente. Este enfoque mantiene la coherencia en la compilación y el despliegue entre los entornos locales y en la nube, y se puede automatizar en Azure DevOps, GitHub Actions u otros sistemas de integración continua.
Docker es otra opción de primera clase para ASP.NET Core, que permite contenerizar tu aplicación Razor Pages para que pueda ejecutarse de forma predecible en cualquier entorno que admita contenedores. Rider y Visual Studio pueden ayudarte a generar Dockerfiles y configuraciones de docker-compose, lo que permite un flujo de trabajo en el que desarrollas, depuras e implementas tu aplicación dentro de contenedores, ya sea localmente o en orquestadores como Kubernetes.
Independientemente del destino, el paso de publicación compila el código C#, agrupa las vistas Razor, copia los recursos estáticos y, según la configuración, también puede generar un entorno de ejecución autónomo para que la máquina host no necesite una instalación compartida de .NET. Este proceso de agrupación es lo que convierte tu proyecto de desarrollo en un artefacto desplegable listo para ser utilizado por usuarios reales.
Al combinar todos estos elementos —desde los certificados de desarrollo y Program.cs, pasando por Pages y wwwroot, hasta la depuración y la publicación— Razor Pages ofrece una forma pragmática de crear aplicaciones web ASP.NET Core reales que sean fáciles de mantener, de alto rendimiento y cómodas para los desarrolladores que ya disfrutan trabajando en C# y no están listos para apostar completamente por un marco de trabajo de una sola página para cada situación.
