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

Contexto

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.

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 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 /base/path/ de Blazor controla las solicitudes a SignalR:

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.

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

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

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 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 en ASP.NET Core
• Configuración en ASP.NET Core