Compartir vía

Hospedaje e implementación de ASP.NET Core Blazor

  • Artículo

Nota

Esta no es la versión más reciente de este artículo. Para la versión actual, consulta la versión .NET 8 de este artículo.

Advertencia

Esta versión de ASP.NET Core ya no se admite. Para obtener más información, consulta la Directiva de soporte técnico de .NET y .NET Core. Para la versión actual, consulta la versión .NET 8 de este artículo.

Importante

Esta información hace referencia a un producto en versión preliminar, el cual puede sufrir importantes modificaciones antes de que se publique la versión comercial. Microsoft no proporciona ninguna garantía, expresa o implícita, con respecto a la información proporcionada aquí.

Para la versión actual, consulte la versión .NET 8 de este artículo.

En este artículo se explica cómo hospedar e implementar aplicaciones de Blazor.

Publicar la aplicación

Las aplicaciones se publican para implementación en la configuración de versión.

Nota:

Publique una solución Blazor WebAssembly hospedada del proyecto Server.

  1. Seleccione el comando Publicar {APPLICATION} en el menú Compilar, donde el marcador {APPLICATION} de posición nombre de la aplicación.
  2. Seleccione el destino de publicación. Para publicar localmente, seleccione Carpeta.
  3. Acepte la ubicación predeterminada del campo Elegir una carpeta o especifique una ubicación diferente. Haga clic en el botón Publish.

Al publicar la aplicación se desencadena una restauración de las dependencias del proyecto y se compila el proyecto antes de crear los recursos para la implementación. Como parte del proceso de compilación, se quitan los ensamblados y métodos que no se usan para reducir los tiempos de carga y el tamaño de descarga de la aplicación.

Ubicaciones de publicación:

  • Blazor Web App: La aplicación se publica en la carpeta /bin/Release/{TARGET FRAMEWORK}/publish. Implemente el contenido de la carpeta publish en el host.
  • Blazor WebAssembly: La aplicación se publica en la carpeta bin\Release\net8.0\browser-wasm\publish\. Para implementar la aplicación como un sitio estático, copie el contenido de la carpeta wwwroot en el host del sitio estático.
  • Blazor Server: La aplicación se publica en la carpeta /bin/Release/{TARGET FRAMEWORK}/publish. Implemente el contenido de la carpeta publish en el host.
  • Blazor WebAssembly
    • Independiente: la aplicación se publica en la carpeta /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot o bin\Release\{TARGET FRAMEWORK}\browser-wasm\publish, en función de la versión del SDK que se usa para publicar la aplicación. Para implementar la aplicación como un sitio estático, copie el contenido de la carpeta wwwroot en el host del sitio estático.
    • Hospedado: La aplicación cliente de Blazor WebAssembly se publica en la carpeta /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot de la aplicación de servidor, junto con cualquier otro recurso web estático de la aplicación de servidor. Implemente el contenido de la carpeta publish en el host.

El valor {TARGET FRAMEWORK} de las rutas de acceso anteriores es el marco de destino (por ejemplo, net8.0).

IIS

Para hospedar una aplicación Blazor en IIS, consulte los siguientes recursos:

No se admite el uso compartido de grupos de aplicaciones entre aplicaciones de ASP.NET Core, incluidas las aplicaciones Blazor. Use un grupo de aplicaciones por aplicación al hospedar con IIS y evite el uso de directorios virtuales de IIS para hospedar varias aplicaciones.

Se admiten una o varias aplicaciones Blazor WebAssembly hospedadas por una aplicación de ASP.NET Core conocida como una solución Blazor WebAssembly hospedada, para un grupo de aplicaciones. Pero no se recomienda ni se admite la asignación de un único grupo de aplicaciones a varias soluciones Blazor WebAssembly hospedadas o en escenarios de hospedaje de subaplicaciones.

Para más información sobre las soluciones, consulte Herramientas para ASP.NET Core Blazor.

Ruta de acceso base de la aplicación

La ruta de acceso base de la aplicación es la de la dirección URL raíz de la aplicación. El éxito del enrutamiento en las aplicaciones Blazor requiere la configuración del marco para cualquier ruta URL raíz que no se encuentre en la ruta base predeterminada de la aplicación /.

Tenga en cuenta la siguiente aplicación de ASP.NET Core y la subaplicación de Blazor:

  • La aplicación de ASP.NET Core se denomina MyApp:
    • La aplicación reside físicamente en d:/MyApp.
    • Las solicitudes se reciben en https://www.contoso.com/{MYAPP RESOURCE}.
  • Una aplicación de Blazor denominada CoolApp es una subaplicación de MyApp:
    • La aplicación reside físicamente en d:/MyApp/CoolApp.
    • Las solicitudes se reciben en https://www.contoso.com/CoolApp/{COOLAPP RESOURCE}.

Sin especificar una configuración adicional para CoolApp, la subaplicación de este escenario desconoce dónde reside en el servidor. Por ejemplo, la aplicación no puede construir URL relativas correctas para sus recursos sin saber que reside en la ruta de acceso URL relativa /CoolApp/. Este escenario también se aplica en varios escenarios de hospedaje y proxy inverso cuando una aplicación no está hospedada en una ruta de dirección URL raíz.

Información previa

El destino de una etiqueta de anclaje (href) se puede componer con cualquiera de los dos puntos de conexión:

  • Ubicaciones absolutas que incluyen un esquema (el valor predeterminado es el esquema de la página si se omite), host, puerto y ruta de acceso o simplemente una barra diagonal (/) seguida de la ruta de acceso.

    Ejemplos: https://example.com/a/b/c o /a/b/c

  • Ubicaciones relativas que contienen solo una ruta de acceso y no comienzan con una barra diagonal (/). Se resuelven en relación con la dirección URL del documento actual o el valor de la <base> etiqueta, si se especifica.

    Ejemplo: a/b/c

La presencia de una barra diagonal final (/) en una ruta base de aplicación configurada es significativa para calcular la ruta de acceso base de las direcciones URL de la aplicación. Por ejemplo, https://example.com/a tiene una ruta base de https://example.com/, mientras que https://example.com/a/ con una barra al final tiene una ruta base de https://example.com/a.

Hay tres orígenes de vínculos que pertenecen a Blazor en ASP.NET aplicaciones principales:

  • Las direcciones URL de los componentes de Razor (.razor) suelen ser relativas.
  • Las direcciones URL en scripts, como los scripts Blazor (blazor.*.js), son relativas al documento.
  • Las direcciones URL escritas manualmente en el _Host.cshtml archivo (Blazor Server), que si se representa dentro de documentos diferentes siempre deben ser absolutas.
  • Las direcciones URL de los componentes de Razor (.razor) suelen ser relativas.
  • Las direcciones URL en scripts, como los scripts Blazor (blazor.*.js), son relativas al documento.

Si va a representar una aplicación Blazor de documentos diferentes (por ejemplo, /Admin/B/C/ y /Admin/D/E/), debe tener en cuenta la ruta de acceso base de la aplicación o la ruta de acceso base es diferente cuando la aplicación se representa en cada documento y los recursos se capturan de las direcciones URL incorrectas.

Hay dos enfoques para abordar el desafío de resolver los vínculos relativos correctamente:

  • Asigne los recursos dinámicamente mediante el documento en el que se representaron como raíz.
  • Establezca una ruta de acceso base coherente para el documento y asigne los recursos de esa ruta de acceso base.

La primera opción es más complicada y no es el enfoque más típico, ya que hace que la navegación sea diferente para cada documento. Considere el ejemplo siguiente para representar una página /Something/Else:

  • Representado en /Admin/B/C/, la página se representa con una ruta de acceso de /Admin/B/C/Something/Else.
  • Representado en /Admin/D/E/, la página se representa en la misma ruta de acceso de /Admin/B/C/Something/Else.

En el primer enfoque, las ofertas de enrutamiento IDynamicEndpointMetadata y MatcherPolicy, que en combinación pueden ser la base para implementar una solución completamente dinámica que determina en tiempo de ejecución cómo se enrutan las solicitudes.

Para la segunda opción, que es el enfoque habitual adoptado, la aplicación establece la ruta de acceso base en el documento y asigna los puntos de conexión del servidor a rutas de acceso en la base. Las instrucciones siguientes adoptan este enfoque.

Blazor del lado servidor

Asigne el centro de SignalR de una aplicación de Blazor del lado servidor pasando la ruta de acceso a MapBlazorHub en el archivo Program:

app.MapBlazorHub("base/path");

La ventaja de usar MapBlazorHub es que puede asignar patrones, como "{tenant}" y no solo rutas de acceso concretas.

También puede asignar el centro SignalR cuando la aplicación se encuentra en una carpeta virtual con una canalización de middleware bifurcado. En el ejemplo siguiente, el centro SignalR de Blazor controla las solicitudes a /base/path/:

app.Map("/base/path/", subapp => {
    subapp.UsePathBase("/base/path/");
    subapp.UseRouting();
    subapp.UseEndpoints(endpoints => endpoints.MapBlazorHub());
});

Configure la <base> etiqueta según las instrucciones de la sección Configurar la ruta de acceso base de la aplicación.

Hospedada Blazor WebAssembly

Si la aplicación es una aplicación hospedada Blazor WebAssembly:

  • En el Server proyecto (Program.cs):
    • Ajuste la ruta de acceso de UseBlazorFrameworkFiles (por ejemplo, app.UseBlazorFrameworkFiles("/base/path");).
    • Configure llamadas a UseStaticFiles (por ejemplo, app.UseStaticFiles("/base/path");).
  • En el proyecto Client:
    • Configure <StaticWebAssetBasePath> en el archivo de proyecto para que coincida con la ruta de acceso para atender recursos web estáticos (por ejemplo, <StaticWebAssetBasePath>base/path</StaticWebAssetBasePath> ).
    • Configure la <base> etiqueta según las instrucciones de la sección Configurar la ruta de acceso base de la aplicación.

Para obtener un ejemplo de hospedaje de varias aplicaciones Blazor WebAssembly en una solución hospedada Blazor WebAssembly, consulte Varias aplicaciones Blazor WebAssembly hospedadas ASP.NET Core, donde se explican los enfoques para el hospedaje de dominios o puertos y el hospedaje de subrutas de varias aplicaciones cliente Blazor WebAssembly.

Independiente Blazor WebAssembly

En una aplicación independiente Blazor WebAssembly, solo se configura la <base> etiqueta según las instrucciones de la sección Configurar la ruta de acceso base de la aplicación.

Configuración de la ruta de acceso base de la aplicación

Para proporcionar configuración para la ruta de acceso base de la Blazor aplicación de , establezca la ruta de https://www.contoso.com/CoolApp/acceso base de la aplicación (<base>), que también se denomina ruta de acceso raíz relativa.

Al proporcionar la ruta de acceso URL relativa, un componente que no se encuentre en el directorio raíz puede construir direcciones URL relativas a la ruta de acceso raíz de la aplicación. Los componentes que se encuentran en diferentes niveles de la estructura de directorios pueden compilar vínculos a otros recursos en ubicaciones de toda la aplicación. La ruta de acceso base de la aplicación también se usa para interceptar hipervínculos seleccionados en los que el destino href del vínculo está dentro del espacio de URI de la ruta de acceso base de la aplicación. El componente Router controla la navegación interna.

Coloque la <base> etiqueta en <head> el marcado (ubicación del <head> contenido) antes de cualquier elemento con valores de atributo que sean direcciones URL, como los href atributos de <link> los elementos.

En muchos escenarios de hospedaje, la ruta de acceso URL relativa a la aplicación es la raíz de la aplicación. En estos casos predeterminados, la ruta de acceso base de dirección URL relativa de la aplicación es / configurada como <base href="/" /> en <head> contenido.

En muchos escenarios de hospedaje, la ruta de acceso URL relativa a la aplicación es la raíz de la aplicación. En estos casos predeterminados, la ruta de acceso base de la dirección URL relativa de la aplicación es la siguiente en <head> contenido:

  • Blazor Server: ~/ configurado como <base href="~/" />.
  • Blazor WebAssembly: / configurado como <base href="/" />.

Nota:

En otros escenarios de hospedaje, como las subaplicaciones de IIS y GitHub Pages, la ruta de acceso base de la aplicación debe establecerse en la ruta de acceso URL relativa del servidor de la aplicación.

  • En una aplicación de Blazor del lado servidor, use cualquiera de los enfoques siguientes:

    • Opción 1: Use la etiqueta para establecer la <base> ruta de acceso base de la aplicación (ubicación del <head> contenido):

      <base href="/CoolApp/">

      Se requiere la barra diagonal.

    • Opción 2: Llame a UsePathBase primero en la canalización de procesamiento de solicitudes de la aplicación (Program.cs) inmediatamente después de que se construya WebApplicationBuilder (builder.Build()) para configurar la ruta base para cualquier middleware siguiente que interactúe con la ruta de solicitud:

      app.UsePathBase("/CoolApp");

      Se recomienda llamar a UsePathBase si también desea ejecutar la aplicación Blazor Server de forma local. Por ejemplo, proporcione la dirección URL de inicio en Properties/launchSettings.json:

      "launchUrl": "https://localhost:{PORT}/CoolApp",

      El marcador de posición {PORT} del ejemplo anterior es el puerto que coincide con el puerto seguro en la ruta de acceso de configuración de applicationUrl. En el ejemplo siguiente se muestra el perfil de inicio completo de una aplicación en el puerto 7279:

      "BlazorSample": {
  "commandName": "Project",
  "dotnetRunMessages": true,
  "launchBrowser": true,
  "applicationUrl": "https://localhost:7279;http://localhost:5279",
  "launchUrl": "https://localhost:7279/CoolApp",
  "environmentVariables": {
    "ASPNETCORE_ENVIRONMENT": "Development"
}

      Para obtener más información sobre el archivo launchSettings.json, consulte Utilizar varios entornos en ASP.NET Core. Para obtener información adicional sobre las rutas de acceso base de la aplicación y el Blazor hospedaje, consulte <base href="/" /> o alternativa de etiqueta base para la Blazor integración de MVC (dotnet/aspnetcore #43191).

  • Independiente Blazor WebAssembly (wwwroot/index.html):

    <base href="/CoolApp/">

    Se requiere la barra diagonal.

  • Hospedado Blazor WebAssembly (Client proyecto, wwwroot/index.html):

    <base href="/CoolApp/">

    Se requiere la barra diagonal.

    En el proyecto Server, llame a UsePathBase primero en la canalización de procesamiento de solicitudes de la aplicación (Program.cs) inmediatamente después de que se construya el WebApplicationBuilder (builder.Build()) para configurar la ruta base para cualquier middleware siguiente que interactúe con la ruta de solicitud:

    app.UsePathBase("/CoolApp");

Nota:

Al usar WebApplication (consulte Migración de ASP.NET Core 5.0 a 6.0), app.UseRouting debe llamarse después de UsePathBase para que el middleware de enrutamiento pueda observar la ruta de acceso modificada antes de hacer coincidir las rutas. De lo contrario, las rutas coinciden antes de que UsePathBase reescriba la ruta de acceso, como se describe en los artículos Orden del middleware y Enrutamiento.

No agregues prefijos a los vínculos de la aplicación con una barra diagonal. Evite el uso de un separador de segmento de trazado o use la notación de ruta de acceso relativa de barra diagonal de puntos (./):

  • Incorrecto: <a href="/account">
  • Correcto: <a href="account">
  • Correcto: <a href="./account">

En las solicitudes de API web Blazor WebAssembly con el servicio HttpClient, confirma que los asistentes de JSON (HttpClientJsonExtensions) no agregan prefijos a las direcciones URL con una barra diagonal (/):

  • Incorrecto: var rsp = await client.GetFromJsonAsync("/api/Account");
  • Correcto: var rsp = await client.GetFromJsonAsync("api/Account");

No agregues prefijos a los vínculos relativos del Administrador de navegación con una barra diagonal. Evite el uso de un separador de segmentos de ruta o utilice la notación de ruta relativa barra de puntos (./) (Navigation es un inyectado NavigationManager):

  • Incorrecto: Navigation.NavigateTo("/other");
  • Correcto: Navigation.NavigateTo("other");
  • Correcto: Navigation.NavigateTo("./other");

En las configuraciones típicas para el hospedaje de Azure/IIS, normalmente no se requiere ninguna configuración adicional. En algunos escenarios de hospedaje que no son IIS y de hospedaje de proxy inverso, es posible que se requiera una configuración adicional de middleware de archivos estáticos:

  • Para proporcionar archivos estáticos correctamente (por ejemplo, app.UseStaticFiles("/CoolApp");).
  • Para servir el script Blazor (_framework/blazor.*.js). Para obtener más información, consulte Archivos estáticos Blazor en ASP.NET Core.

En el caso de una aplicación de Blazor WebAssembly con una ruta de acceso URL relativa que no sea raíz (por ejemplo, <base href="/CoolApp/">), la aplicación no puede encontrar sus recursos cuando se ejecuta de forma local. Para solucionar este problema durante la fase de desarrollo y pruebas local, puede proporcionar un argumento de ruta de acceso base que coincida con el valor href de la etiqueta <base> en tiempo de ejecución. No incluya una barra diagonal final. Para pasar el argumento base de ruta de acceso al ejecutar la aplicación localmente, ejecute el comando dotnet watch (o dotnet run) desde el directorio de la aplicación con la opción --pathbase:

dotnet watch --pathbase=/{RELATIVE URL PATH (no trailing slash)}

En el caso de una aplicación de Blazor WebAssembly con una ruta de acceso a una URL relativa de /CoolApp/ (<base href="/CoolApp/">), el comando es el siguiente:

dotnet watch --pathbase=/CoolApp

Si prefiere configurar el perfil de inicio de la aplicación para especificar el pathbase automáticamente en lugar de manualmente con dotnet watch (o dotnet run), establezca la propiedad commandLineArgs en Properties/launchSettings.json. Lo siguiente también configura la dirección URL de inicio (launchUrl):

"commandLineArgs": "--pathbase=/{RELATIVE URL PATH (no trailing slash)}",
"launchUrl": "{RELATIVE URL PATH (no trailing slash)}",

Uso de CoolApp como ejemplo:

"commandLineArgs": "--pathbase=/CoolApp",
"launchUrl": "CoolApp",

Con dotnet watch (o dotnet run) con la opción --pathbase o una configuración de perfil de inicio que establece la ruta de acceso base, la aplicación Blazor WebAssembly responde localmente en http://localhost:port/CoolApp.

Para obtener más información sobre el archivo launchSettings.json, consulte Utilizar varios entornos en ASP.NET Core. Para obtener información adicional sobre las rutas de acceso base de la aplicación y el Blazor hospedaje, consulte <base href="/" /> o alternativa de etiqueta base para la Blazor integración de MVC (dotnet/aspnetcore #43191).

Obtención de la ruta de acceso base de la aplicación de la configuración

En las instrucciones siguientes se explica cómo obtener la ruta de acceso de la etiqueta <base> de un archivo de configuración de la aplicación para distintos entornos.

Agregue el archivo de configuración de aplicación a la aplicación. El ejemplo siguiente es para el entorno de Staging (appsettings.Staging.json):

{
  "AppBasePath": "staging/"
}

En una aplicación de Blazor del lado servidor, cargue la ruta de acceso base desde la configuración en Contenido de <head>:

@inject IConfiguration Config

...

<head>
    ...
    <base href="/@(Config.GetValue<string>("AppBasePath"))" />
    ...
</head>

Como alternativa, una aplicación del lado servidor puede obtener el valor de la configuración de UsePathBase. Coloque el siguiente código primero en la canalización de procesamiento de solicitudes de la aplicación (Program.cs) inmediatamente después de la compilación de WebApplicationBuilder (builder.Build()). El siguiente ejemplo usa la clave de configuración AppBasePath:

app.UsePathBase($"/{app.Configuration.GetValue<string>("AppBasePath")}");

En una aplicación Blazor WebAssembly del lado cliente:

  • Quite la etiqueta <base> de wwwroot/index.html:

    - <base href="..." />

  • Proporcione la ruta de acceso base de la aplicación a través de un componente HeadContent en el componente App (App.razor):

    @inject IConfiguration Config

...

<HeadContent>
    <base href="/@(Config.GetValue<string>("AppBasePath"))" />
</HeadContent>

Si no hay ningún valor de configuración que cargar, por ejemplo en entornos que no son de ensayo, el href precedente resuelve a la ruta de acceso raíz /.

Los ejemplos de esta sección se centran en proporcionar la ruta de acceso base de la aplicación desde la configuración de la aplicación, pero el enfoque de leer la ruta de acceso desde IConfiguration es válido para cualquier proveedor de configuración. Para obtener más información, consulte los siguientes recursos:

Configuración de Blazor ServerMapFallbackToPage

Esta sección solo se aplica a las aplicaciones Blazor Server. MapFallbackToPage no se es compatible con Blazor Web App ni en aplicaciones de Blazor WebAssembly.

En escenarios en los que una aplicación requiere un área independiente con componentes y recursos de Razor personalizados:

  • Cree una carpeta dentro de la carpeta Pages de la aplicación para contener los recursos. Por ejemplo, se crea una sección de administrador de una aplicación en una nueva carpeta denominada Admin (Pages/Admin).

  • Cree una página raíz (_Host.cshtml) para el área. Por ejemplo, cree un archivo Pages/Admin/_Host.cshtml desde la página raíz principal de la aplicación (Pages/_Host.cshtml). No proporcione una directiva @page en la página _Host de administración.

  • Agregue un diseño a la carpeta del área (por ejemplo, Pages/Admin/_Layout.razor). En el diseño del área independiente, establezca el href de la etiqueta <base> para que coincida con la carpeta del área (por ejemplo, <base href="/Admin/" />). Para fines de demostración, agregue ~/ a los recursos estáticos de la página. Por ejemplo:

    • ~/css/bootstrap/bootstrap.min.css
    • ~/css/site.css
    • ~/BlazorSample.styles.css (el espacio de nombres de la aplicación de ejemplo es BlazorSample)
    • ~/_framework/blazor.server.js (script Blazor)

  • Si el área debe tener su propia carpeta de recursos estáticos, agregue la carpeta y especifique su ubicación en Middleware de archivos estáticos en Program.cs (por ejemplo, app.UseStaticFiles("/Admin/wwwroot")).

  • Se agregan componentes Razor a la carpeta del área. Como mínimo, agregue un componente Index a la carpeta de área con la directiva @page correcta para el área. Por ejemplo, agregue un archivo Pages/Admin/Index.razor basado en el archivo Pages/Index.razor predeterminado de la aplicación. Indique el área de administración como plantilla de ruta en la parte superior del archivo (@page "/admin"). Agregue componentes adicionales según sea necesario. Por ejemplo, Pages/Admin/Component1.razor con una directiva @page y una plantilla de ruta de @page "/admin/component1.

  • En Program.cs, llame a MapFallbackToPage para la ruta de acceso de solicitud del área inmediatamente antes de la ruta de acceso de la página raíz de reserva a la página _Host:

    ...
app.UseRouting();

app.MapBlazorHub();
app.MapFallbackToPage("~/Admin/{*clientroutes:nonfile}", "/Admin/_Host");
app.MapFallbackToPage("/_Host");

app.Run();

Aloje varias aplicaciones Blazor WebAssembly

Para más información sobre cómo hospedar varias aplicaciones Blazor WebAssembly en una soluciónBlazor hospedada, consulte Varias aplicaciones ASP.NET Core Blazor WebAssembly hospedadas.

Implementación

Para una guía sobre la implementación, consulte los temas siguientes: