ruta de acceso base de la aplicación ASP.NET Core Blazor

En este artículo se explica la ruta de acceso base en las aplicaciones de ASP.NET Core Blazor, incluida la orientación sobre configuració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 subaplicació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 contextos de alojamiento y proxy inverso cuando una aplicación no está alojada en una ruta URL raíz.

Contexto

El destino de un anchor (href) se puede componer con cualquiera de dos extremos:

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

  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.

Para los orígenes de vínculos relacionados con Blazor en aplicaciones de ASP.NET Core:

• Las direcciones URL de los componentes de Razor (.razor) suelen ser relativas.
• Las direcciones URL en scripts, como los de 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.

Elija una de las siguientes estrategias para que los vínculos relativos se resuelvan correctamente.

• Mapear recursos dinámicamente utilizando el documento como raíz en el que fueron representados. Esto requiere lógica de enrutamiento personalizada (por ejemplo, IDynamicEndpointMetadata o ) MatcherPolicyy normalmente está reservada para sitios altamente dinámicos.

• Establezca una ruta de acceso base coherente para el documento y asigne todos los recursos de la aplicación debajo de esa ruta de acceso. Configure la etiqueta literal <base> en la página de host tanto para aplicaciones del lado del servidor Blazor como para aplicaciones del lado del cliente Blazor WebAssembly (o para escenarios que siempre utilizan un valor fijo).

El resto de este artículo se centra en implementar una ruta de acceso base coherente.

Blazor del lado servidor

Asigne el SignalR centro de una aplicación del lado del servidor pasando la ruta de acceso a Blazor en el archivo MapBlazorHub. La ruta de acceso del centro predeterminada Blazor es /_blazory en el ejemplo siguiente se establece la ruta de acceso base del centro predeterminado en base/path:

app.MapBlazorHub("base/path/_blazor");

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

También puede mapear el hub SignalR cuando la aplicación se encuentra en una carpeta virtual con una canalización de middleware ramificada. En el siguiente ejemplo, las solicitudes a /base/path/ son gestionadas por el centro SignalR de Blazor.

app.Map("/base/path", subapp => {
    subapp.UsePathBase("/base/path");
    subapp.UseRouting();
	  subapp.UseAntiforgery();
    subapp.UseEndpoints(endpoints => {
        endpoints.MapBlazorHub("/base/path/_blazor");
        endpoints.MapStaticAssets();
		    endpoints.MapRazorComponents<App>()
				.AddInteractiveServerRenderMode();
	});
});

Nota:

La ruta de acceso predeterminada del concentrador Blazor es /_blazor.

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

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 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 aplicación Blazor, establezca la ruta de acceso base de la aplicación https://www.contoso.com/CoolApp/ (<base>), que también se denomina ruta de acceso raíz relativa.

Al configurar la ruta base de la aplicación, un componente que no se encuentre en el directorio raíz puede construir direcciones URL relativas al camino raíz de la aplicación. Los componentes que se encuentran en diferentes niveles de la estructura de directorios pueden establecer enlaces a otros recursos en ubicaciones dentro de 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 etiqueta <base> en el marcado <head> (ubicación de contenido <head>) antes de cualquier elemento con valores de atributo que sean URL, como los atributos href de los elementos <link>.

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 base relativa de la URL de la aplicación está configurada como <base href="/" /> en el contenido <head>.

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 del servidor Blazor, utilice el siguiente enfoque:

• 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 final.

• Opción 2: Llame a UsePathBaseprimero 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 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 entornos de tiempo de ejecución de ASP.NET Core. Para obtener información adicional sobre las Blazor rutas base de la aplicación y el hospedaje, consulte <base href="/" /> o la alternativa de etiqueta base para la integración de Blazor MVC (dotnet/aspnetcore #43191).

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

  <base href="/CoolApp/">
  

  Se requiere la barra diagonal.

Nota:

Al usar WebApplication (consulte Migración de ASP.NET Core en .NET 5 a .NET 6), app.UseRouting se debe llamar después 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 se emparejan antes de que la ruta de acceso se reescriba UsePathBase tal como se describe en el middleware de ASP.NET Core y el enrutamiento en ASP.NET Core.

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 precedas 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 punto-barra (./) (Navigation es un elemento 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 servir 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 de ruta base 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 Blazor WebAssembly con una ruta de acceso a una URL relativa de /CoolApp/ (<base href="/CoolApp/">), el comando es:

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",

Utilizando dotnet watch (o dotnet run) con la opción --pathbase o mediante una configuración de perfil de inicio que define la ruta 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 entornos de tiempo de ejecución de 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).

Obtener la ruta de acceso base de la aplicación desde 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 no de ensayo, el href antes mencionado se resuelve en 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 en ASP.NET Core
• Configuración en ASP.NET Core