Inicio de Blazor en ASP.NET Core

  • Artículo

Nota:

Esta no es la versión más reciente de este artículo. Para la versión actual, consulte 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.

Este artículo explica Blazor la configuración de inicio de la aplicación.

Para obtener orientación general sobre la configuración de aplicaciones ASP.NET Core para el desarrollo del lado del servidor, consulte Configuración en ASP.NET Core.

Proceso de inicio y configuración

El proceso de inicio Blazor es automático y asincrónico a través del script Blazor (blazor.*.js), donde el marcador de posición * es:

  • web para una aplicación web Blazor
  • server para una aplicación Blazor Server
  • webassembly para una aplicación Blazor WebAssembly

El proceso de inicio Blazor es automático y asincrónico a través del script Blazor (blazor.*.js), donde el marcador de posición * es:

  • server para una aplicación Blazor Server
  • webassembly para una aplicación Blazor WebAssembly

Para obtener la ubicación del script, consulte la estructura del proyecto ASP.NET CoreBlazor.

Para iniciar Blazormanualmente:

Aplicación web Blazor:

  • Agregue un atributo autostart="false" y un valor a la etiqueta Blazor<script>.
  • Coloque un script que llame a Blazor.start() después de la etiqueta <script> de Blazor y dentro de la etiqueta de cierre </body>.
  • Coloque las opciones estáticas de representación del lado servidor (SSR estático) en la propiedad ssr.
  • Coloque las opciones de circuito Blazor-SignalR en la propiedad circuit.
  • Coloque las opciones de WebAssembly del lado cliente en la propiedad webAssembly.
<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  ...
  Blazor.start({
    ssr: {
      ...
    },
    circuit: {
      ...
    },
    webAssembly: {
      ...
    }
  });
  ...
</script>

Blazor WebAssembly independiente y Blazor Server:

  • Agregue un atributo autostart="false" y un valor a la etiqueta Blazor<script>.
  • Coloque un script que llame a Blazor.start() después de la etiqueta <script> de Blazor y dentro de la etiqueta de cierre </body>.
  • Puede proporcionar opciones adicionales en el parámetro Blazor.start().
<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  ...
  Blazor.start({
    ...
  });
  ...
</script>

En el ejemplo anterior, el marcador de posición {BLAZOR SCRIPT} es la ruta de acceso del script y el nombre de archivo Blazor. Para obtener la ubicación del script, consulte la estructura del proyecto ASP.NET CoreBlazor.

Inicializadores de JavaScript

Los inicializadores de JavaScript (JS) ejecutan lógica antes y después de que se cargue una aplicación Blazor. Los inicializadores de JS son útiles en los siguientes escenarios:

  • Personalización de cómo se carga una aplicación Blazor.
  • Inicialización de bibliotecas antes de que se inicie Blazor.
  • Configuración de valores Blazor.

JS se detectan como parte del proceso de compilación y se importan automáticamente. El uso de inicializadores de JS a menudo elimina la necesidad de desencadenar manualmente funciones de script desde la aplicación cuando se utilizan bibliotecas de clases de Razor (RCL).

Para definir un inicializador de JS, agregue un módulo de JS al proyecto con el nombre {NAME}.lib.module.js, donde el marcador de posición {NAME} es el nombre del ensamblado, el nombre de la biblioteca o el identificador del paquete. Coloque el archivo en la raíz web del proyecto, que suele ser la carpeta wwwroot.

Para Blazor Web Apps:

  • beforeWebStart(options): se llama antes de que se inicie la aplicación web de Blazor. Por ejemplo, beforeWebStart se usa para personalizar el proceso de carga, el nivel de registro y otras opciones. Recibe las opciones web de Blazor (options).
  • afterWebStarted(blazor): se llama después de que se resuelvan todas las promesas de beforeWebStart. Por ejemplo, afterWebStarted se pueden usar para registrar Blazor agentes de escucha de eventos y tipos de eventos personalizados. La instancia de Blazor se pasa a afterWebStarted como argumento (blazor).
  • beforeServerStart(options, extensions): se llama antes de iniciar el primer tiempo de ejecución del servidor. Recibe SignalR opciones de inicio del circuito (options) y las extensiones (extensions) agregadas durante la publicación.
  • afterServerStarted(blazor): se llama después de iniciar el primer runtime del servidor interactivo.
  • beforeWebAssemblyStart(options, extensions): se llama antes de iniciar el runtime de WebAssembly interactivo. Recibe las opciones de Blazor (options) y las extensiones (extensions) agregadas durante la publicación. Por ejemplo, las opciones pueden especificar el uso de un cargador de recursos de arranque personalizado.
  • afterWebAssemblyStarted(blazor): se llama después de iniciar el runtime de WebAssembly interactivo.

Nota:

Los inicializadores de JS heredados (beforeStart, afterStarted) no se invocan de forma predeterminada en una aplicación web de Blazor. Puede habilitar los inicializadores heredados para que se ejecuten con la opción enableClassicInitializers. Sin embargo, la ejecución del inicializador heredado es impredecible.

<script>
  Blazor.start({ enableClassicInitializers: true });
</script>

Para las aplicaciones de Blazor Server, Blazor WebAssemblyy Blazor Hybrid :

  • beforeStart(options, extensions): se llama ante de que se inicie Blazor. Por ejemplo, se usa beforeStart para personalizar el proceso de carga, el nivel de registro y otras opciones específicas del modelo de hospedaje.
    • El lado cliente beforeStart recibe las opciones de Blazor (options) y las extensiones (extensions) agregadas durante la publicación. Por ejemplo, las opciones pueden especificar el uso de un cargador de recursos de arranque personalizado.
    • El lado servidor beforeStart recibe SignalR opciones de inicio del circuito (options).
    • En un BlazorWebView, no se pasan opciones.
  • afterStarted(blazor): se llama después de que Blazor esté listo para recibir llamadas de JS. Por ejemplo, se usa afterStarted para inicializar bibliotecas realizando llamadas de interoperabilidad de JS y registrando elementos personalizados. La instancia de Blazor se pasa a afterStarted como argumento (blazor).

Devoluciones de llamada adicionales en runtime de WebAssembly de .NET:

  • onRuntimeConfigLoaded(config): se llama cuando se descarga la configuración de arranque. Permite que la aplicación modifique parámetros (config) antes de que se inicie el runtime (el parámetro se MonoConfig desde dotnet.d.ts):

    export function onRuntimeConfigLoaded(config) {
  // Sample: Enable startup diagnostic logging when the URL contains 
  // parameter debug=1
  const params = new URLSearchParams(location.search);
  if (params.get("debug") == "1") {
    config.diagnosticTracing = true;
  }
}

  • onRuntimeReady({ getAssemblyExports, getConfig }): se llama después de que se haya iniciado el runtime de WebAssembly de .NET (el parámetro se RuntimeAPI desde dotnet.d.ts):

    export function onRuntimeReady({ getAssemblyExports, getConfig }) {
  // Sample: After the runtime starts, but before Main method is called, 
  // call [JSExport]ed method.
  const config = getConfig();
  const exports = await getAssemblyExports(config.mainAssemblyName);
  exports.Sample.Greet();
}

Ambas devoluciones de llamada pueden devolver un Promise, y la promesa se espera antes de que continúe el inicio.

Para el nombre de archivo:

  • Si los inicializadores JS se consumen como un recurso estático en el proyecto, use el formato {ASSEMBLY NAME}.lib.module.js, donde el marcador de posición {ASSEMBLY NAME} es el nombre del ensamblado de la aplicación. Por ejemplo, asigne el nombre BlazorSample.lib.module.js al archivo para un proyecto con un nombre de ensamblado de BlazorSample. Coloque el archivo en la carpeta wwwroot de la aplicación.
  • Si los inicializadores JS se consumen desde una RCL, use el formato {LIBRARY NAME/PACKAGE ID}.lib.module.js, donde el marcador de posición {LIBRARY NAME/PACKAGE ID} es el nombre de la biblioteca o el identificador de paquete del proyecto. Por ejemplo, asigne al archivo RazorClassLibrary1.lib.module.js el nombre para una RCL con un identificador de paquete de RazorClassLibrary1. Coloque el archivo en la carpeta wwwroot de la biblioteca.

Para Blazor Web Apps:

En el ejemplo siguiente se muestranJS inicializadores que cargan scripts personalizados antes y después de que se haya iniciado la aplicación web de Blazor anexarlos a <head> en beforeWebStart y afterWebStarted:

export function beforeWebStart() {
  var customScript = document.createElement('script');
  customScript.setAttribute('src', 'beforeStartScripts.js');
  document.head.appendChild(customScript);
}

export function afterWebStarted() {
  var customScript = document.createElement('script');
  customScript.setAttribute('src', 'afterStartedScripts.js');
  document.head.appendChild(customScript);
}

En el ejemplo beforeWebStart anterior solo se garantiza que el script personalizado se cargue antes de que Blazor comience. No garantiza que las promesas esperadas en el script completen su ejecución antes de que Blazor comience.

Para las aplicaciones de Blazor Server, Blazor WebAssemblyy Blazor Hybrid :

En el ejemplo siguiente se muestran los inicializadores JS que cargan scripts personalizados antes y después de haberse iniciado Blazor anexándolos a <head> en beforeStart y afterStarted:

export function beforeStart(options, extensions) {
  var customScript = document.createElement('script');
  customScript.setAttribute('src', 'beforeStartScripts.js');
  document.head.appendChild(customScript);
}

export function afterStarted(blazor) {
  var customScript = document.createElement('script');
  customScript.setAttribute('src', 'afterStartedScripts.js');
  document.head.appendChild(customScript);
}

En el ejemplo beforeStart anterior solo se garantiza que el script personalizado se cargue antes de que Blazor comience. No garantiza que las promesas esperadas en el script completen su ejecución antes de que Blazor comience.

Nota

Las aplicaciones MVC y Razor Pages no cargan los inicializadores de JS de forma automática. Pero el código para desarrolladores puede incluir un script para capturar el manifiesto de la aplicación y desencadenar la carga de los inicializadores de JS.

Para obtener ejemplos de inicializadores de JS, consulte los siguientes recursos:

Nota

Los vínculos de la documentación al origen de referencia de .NET cargan normalmente la rama predeterminada del repositorio, que representa el desarrollo actual para la próxima versión de .NET. Para seleccionar una etiqueta de una versión específica, use la lista desplegable Cambiar ramas o etiquetas. Para obtener más información, vea Procedimientos para seleccionar una etiqueta de versión de código fuente de ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Verificación de que las bibliotecas se cargan en un orden específico

Anexe scripts personalizados a <head> en beforeStart y afterStarted en el orden en que deben cargarse.

En el ejemplo siguiente se carga script1.js antes de script2.js y script3.js antes de script4.js:

export function beforeStart(options, extensions) {
    var customScript1 = document.createElement('script');
    customScript1.setAttribute('src', 'script1.js');
    document.head.appendChild(customScript1);

    var customScript2 = document.createElement('script');
    customScript2.setAttribute('src', 'script2.js');
    document.head.appendChild(customScript2);
}

export function afterStarted(blazor) {
    var customScript1 = document.createElement('script');
    customScript1.setAttribute('src', 'script3.js');
    document.head.appendChild(customScript1);

    var customScript2 = document.createElement('script');
    customScript2.setAttribute('src', 'script4.js');
    document.head.appendChild(customScript2);
}

Importación de módulos adicionales

Use instrucciones import de nivel superior en el archivo de inicializadores JS para importar módulos adicionales.

additionalModule.js:

export function logMessage() {
  console.log('logMessage is logging');
}

En el archivo JS de inicializadores (.lib.module.js):

import { logMessage } from "/additionalModule.js";

export function beforeStart(options, extensions) {
  ...

  logMessage();
}

Importación de mapa

Las asignaciones de importación son compatibles con ASP.NET Core y Blazor.

Inicialización de Blazor cuando el documento está listo

En el ejemplo siguiente se inicia Blazor cuando el documentación está listo:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  document.addEventListener("DOMContentLoaded", function() {
    Blazor.start();
  });
</script>

En el ejemplo anterior, el marcador de posición {BLAZOR SCRIPT} es la ruta de acceso del script y el nombre de archivo Blazor. Para obtener la ubicación del script, consulte la estructura del proyecto ASP.NET CoreBlazor.

Cadena al elemento Promise resultante de un inicio manual

Para realizar más tareas, como la inicialización de interoperabilidad de JS, use then como cadena al elemento Promise resultante de un inicio manual de la aplicación Blazor:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start().then(function () {
    ...
  });
</script>

En el ejemplo anterior, el marcador de posición {BLAZOR SCRIPT} es la ruta de acceso del script y el nombre de archivo Blazor. Para obtener la ubicación del script, consulte la estructura del proyecto ASP.NET CoreBlazor.

Nota:

Para que una biblioteca ejecute automáticamente tareas adicionales después de que Blazor se haya iniciado, use un inicializador de JavaScript. El uso de un inicializador de JS no requiere que el consumidor de la biblioteca encadene llamadas de JS al inicio manual de Blazor.

Cargar recursos de arranque del lado del cliente

Cuando una aplicación se carga en el navegador, descarga recursos de arranque del servidor:

  • Código JavaScript para arrancar la aplicación
  • Runtime y ensamblados de .NET
  • Datos específicos de la configuración regional

Personalice la forma en que se cargan estos recursos de arranque mediante la API loadBootResource. La función loadBootResource invalida el mecanismo de carga de recursos de arranque integrado. Use loadBootResource en los siguientes escenarios:

  • Para cargar los recursos estáticos, como datos de zona horaria o dotnet.wasm, desde una red CDN.
  • Para cargar los ensamblados comprimidos mediante una solicitud HTTP y descomprimirlos en el cliente para aquellos hosts que no admiten la captura de contenido comprimido del servidor.
  • Para asignar otro alias a los recursos mediante el redireccionamiento de cada solicitud fetch a un nuevo nombre.

Nota:

Los orígenes externos deben devolver los encabezados de Uso compartido de recursos entre orígenes (CORS) necesarios para que los exploradores permitan la carga de recursos entre orígenes. Normalmente, las redes CDN proporcionan los encabezados necesarios de forma predeterminada.

Los parámetros loadBootResource aparecen en la tabla siguiente.

Parámetro Descripción
type Tipo de recurso. Los tipos permitidos son: assembly, pdb, dotnetjs, dotnetwasm y timezonedata. Solo tiene que especificar tipos para los comportamientos personalizados. Los tipos no especificados en loadBootResource se cargan mediante el marco de trabajo según sus comportamientos de carga predeterminados. El recurso de arranque de dotnetjs (dotnet.*.js) debe devolver null el comportamiento de carga predeterminado o un URI para el origen del recurso de arranque dotnetjs.
name Nombre del recurso.
defaultUri URI relativo o absoluto del recurso.
integrity Cadena de integridad que representa el contenido esperado de la respuesta.

La función loadBootResource puede devolver una cadena de URI para invalidar el proceso de carga. En el ejemplo siguiente, los siguientes archivos de bin/Release/{TARGET FRAMEWORK}/wwwroot/_framework se atienden desde una red CDN en https://cdn.example.com/blazorwebassembly/{VERSION}/:

  • dotnet.*.js
  • dotnet.wasm
  • Datos de zona horaria

El marcador de posición {TARGET FRAMEWORK} es el moniker de la plataforma de destino (por ejemplo, net7.0). El marcador de posición {VERSION} es la versión de la plataforma compartida (por ejemplo, 7.0.0).

Aplicación web Blazor:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    webAssembly: {
      loadBootResource: function (type, name, defaultUri, integrity) {
        console.log(`Loading: '${type}', '${name}', '${defaultUri}', '${integrity}'`);
        switch (type) {
          case 'dotnetjs':
          case 'dotnetwasm':
          case 'timezonedata':
            return `https://cdn.example.com/blazorwebassembly/{VERSION}/${name}`;
        }
      }
    }
  });
</script>

Blazor WebAssembly independiente:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    loadBootResource: function (type, name, defaultUri, integrity) {
      console.log(`Loading: '${type}', '${name}', '${defaultUri}', '${integrity}'`);
      switch (type) {
        case 'dotnetjs':
        case 'dotnetwasm':
        case 'timezonedata':
          return `https://cdn.example.com/blazorwebassembly/{VERSION}/${name}`;
      }
    }
  });
</script>

En el ejemplo anterior, el marcador de posición {BLAZOR SCRIPT} es la ruta de acceso del script y el nombre de archivo Blazor. Para obtener la ubicación del script, consulte la estructura del proyecto ASP.NET CoreBlazor.

Para personalizar algo más que las direcciones URL de los recursos de arranque, la función loadBootResource puede llamar directamente a fetch y devolver el resultado. En el ejemplo siguiente, se agrega un encabezado HTTP personalizado a las solicitudes salientes. Para conservar el comportamiento de comprobación de integridad predeterminado, pase el parámetro integrity.

Aplicación web Blazor:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    webAssembly: {
      loadBootResource: function (type, name, defaultUri, integrity) {
        if (type == 'dotnetjs') {
          return null;
        } else {
          return fetch(defaultUri, {
            cache: 'no-cache',
            integrity: integrity,
            headers: { 'Custom-Header': 'Custom Value' }
          });
        }
      }
    }
  });
</script>

Blazor WebAssembly independiente:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    loadBootResource: function (type, name, defaultUri, integrity) {
      if (type == 'dotnetjs') {
        return null;
      } else {
        return fetch(defaultUri, {
          cache: 'no-cache',
          integrity: integrity,
          headers: { 'Custom-Header': 'Custom Value' }
        });
      }
    }
  });
</script>

En el ejemplo anterior, el marcador de posición {BLAZOR SCRIPT} es la ruta de acceso del script y el nombre de archivo Blazor. Para obtener la ubicación del script, consulte la estructura del proyecto ASP.NET CoreBlazor.

Cuando la función loadBootResource devuelve null, Blazor usa el comportamiento de carga predeterminado para el recurso. Por ejemplo, el código anterior devuelve null para el recurso de arranque dotnetjs (dotnet.*.js) porque el recurso de arranque dotnetjs debe devolver null para el comportamiento de carga predeterminado o un URI para el origen del recurso de arranque dotnetjs.

La función loadBootResource también puede devolver una promesa de Response. Para obtener un ejemplo, vea Hospedaje e implementación de ASP.NET Core Blazor WebAssembly.

Para obtener más información, consulte Runtime de ASP.NET Core Blazor WebAssembly .NET y almacenamiento en caché del lote de aplicaciones.

Control de encabezados en código C#

Controle los encabezados en el inicio en código C# mediante los enfoques siguientes.

En los ejemplos siguientes, se aplica una directiva de seguridad de contenido (CSP) a la aplicación a través de un encabezado CSP. El marcador de posición {POLICY STRING} es la cadena de directiva de CSP.

Escenarios del lado del servidor y del lado del cliente pre renderizados

Utilice ASP.NET Core Middleware para controlar la colección de encabezados.

En el archivo Program:

En Startup.Configure de Startup.cs:

app.Use(async (context, next) =>
{
    context.Response.Headers.Append("Content-Security-Policy", "{POLICY STRING}");
    await next();
});

El ejemplo anterior utiliza middleware en línea, pero también puede crear una clase de middleware personalizada y llamar al middleware con un método de extensión en el archivo Program. Para obtener más información, vea Escritura de middleware de ASP.NET Core personalizado.

Desarrollo del lado del cliente sin representación previa

Pase StaticFileOptions a MapFallbackToFile que especifica los encabezados de respuesta en la etapa OnPrepareResponse.

En el archivo Program del lado servidor:

En Startup.Configure de Startup.cs:

var staticFileOptions = new StaticFileOptions
{
    OnPrepareResponse = context =>
    {
        context.Context.Response.Headers.Append("Content-Security-Policy", 
            "{POLICY STRING}");
    }
};

...

app.MapFallbackToFile("index.html", staticFileOptions);

Para más información sobre los CSP, vea Aplicación de una directiva de seguridad de contenido para Blazor de ASP.NET Core.

Indicadores de progreso de carga en el cliente

Un indicador de progreso de carga muestra el progreso de carga de la aplicación a los usuarios, lo que indica que la aplicación se está cargando normalmente y que el usuario debe esperar hasta que finalice la carga.

Blazor Progreso de carga de aplicaciones web

El indicador de progreso de carga usado en aplicaciones Blazor WebAssembly no está presente en una aplicación creada a partir de la plantilla de proyecto de aplicación web Blazor. Normalmente, un indicador de progreso de carga no es deseable para los componentes interactivos de WebAssembly, ya que Web Apps Blazor rendizará previamente los componentes del lado cliente en el servidor para tiempos de carga iniciales rápidos. Para situaciones en modo de representación mixta, el marco o el código de desarrollador también deben tener cuidado para evitar los siguientes problemas:

  • Mostrar varios indicadores de carga en la misma página representada.
  • Descartar accidentalmente el contenido creado previamente mientras se carga el runtime de WebAssembly.

Una versión futura de .NET podría proporcionar un indicador de progreso de carga basado en el marco. Mientras tanto, puede agregar un indicador de progreso de carga personalizado a una aplicación web Blazor.

Cree un componente LoadingProgress en la aplicación .Client que llame a OperatingSystem.IsBrowser:

  • Cuando false, muestre un indicador de progreso de carga mientras se descarga la agrupación Blazor y antes de que el runtime Blazor se active en el cliente.
  • Cuando true, represente el contenido del componente solicitado.

En la siguiente demostración se usa el indicador de progreso de carga que se encuentra en las aplicaciones creadas a partir de la plantilla Blazor WebAssembly, incluida una modificación de los estilos que proporciona la plantilla. El componente HeadContent carga los estilos en el contenido <head> de la aplicación. Para más información, vea Control del contenido principal en aplicaciones Blazor de ASP.NET Core.

LoadingProgress.razor:

@if (!OperatingSystem.IsBrowser())
{
    <HeadContent>
        <style>
            .loading-progress {
                position: relative;
                display: block;
                width: 8rem;
                height: 8rem;
                margin: 20vh auto 1rem auto;
            }

                .loading-progress circle {
                    fill: none;
                    stroke: #e0e0e0;
                    stroke-width: 0.6rem;
                    transform-origin: 50% 50%;
                    transform: rotate(-90deg);
                }

                    .loading-progress circle:last-child {
                        stroke: #1b6ec2;
                        stroke-dasharray: 
                            calc(3.141 * var(--blazor-load-percentage, 0%) * 0.8), 
                            500%;
                        transition: stroke-dasharray 0.05s ease-in-out;
                    }

            .loading-progress-text {
                position: relative;
                text-align: center;
                font-weight: bold;
                top: -90px;
            }

                .loading-progress-text:after {
                    content: var(--blazor-load-percentage-text, "Loading");
                }

            code {
                color: #c02d76;
            }
        </style>
    </HeadContent>
    <svg class="loading-progress">
        <circle r="40%" cx="50%" cy="50%" />
        <circle r="40%" cx="50%" cy="50%" />
    </svg>
    <div class="loading-progress-text"></div>
}
else
{
    @ChildContent
}

@code {
    [Parameter]
    public RenderFragment? ChildContent { get; set; }
}

En un componente que adopta la representación interactiva de WebAssembly, encapsule el marcado del componente Razor con el componente LoadingProgress. En el siguiente ejemplo se muestra el enfoque con el componente Counter de una aplicación creada a partir de la plantilla de proyecto de aplicación web Blazor.

Pages/Counter.razor:

@page "/counter"
@rendermode InteractiveWebAssembly

<PageTitle>Counter</PageTitle>

<LoadingProgress>
    <h1>Counter</h1>

    <p role="status">Current count: @currentCount</p>

    <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
</LoadingProgress>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

Progreso de carga de la aplicación Blazor WebAssembly

La plantilla del proyecto contiene gráficos vectoriales escalables (SVG) e indicadores de texto que muestran el progreso de carga de la aplicación.

Los indicadores de progreso se implementan con HTML y CSS mediante dos propiedades personalizadas de CSS (variables) proporcionadas por Blazor:

  • --blazor-load-percentage: El porcentaje de archivos de la aplicación cargados.
  • --blazor-load-percentage-text: El porcentaje de archivos de la aplicación cargados, redondeado al número entero más cercano.

Con las variables CSS anteriores, puedes crear indicadores de progreso personalizados que coincidan con el estilo de la aplicación.

En el ejemplo siguiente:

  • resourcesLoaded es un recuento instantáneo de los recursos cargados durante el inicio de la aplicación.
  • totalResources Es el número total de recursos que se van a cargar.
const percentage = resourcesLoaded / totalResources * 100;
document.documentElement.style.setProperty(
  '--blazor-load-percentage', `${percentage}%`);
document.documentElement.style.setProperty(
  '--blazor-load-percentage-text', `"${Math.floor(percentage)}%"`);

El indicador de progreso redondo predeterminado se implementa en HTML en el archivo wwwroot/index.html:

<div id="app">
    <svg class="loading-progress">
        <circle r="40%" cx="50%" cy="50%" />
        <circle r="40%" cx="50%" cy="50%" />
    </svg>
    <div class="loading-progress-text"></div>
</div>

Para revisar el marcado y el estilo de la plantilla de proyecto de para los indicadores de progreso predeterminados, consulte el origen de referencia de ASP.NET Core:

Nota

Los vínculos de la documentación al origen de referencia de .NET cargan normalmente la rama predeterminada del repositorio, que representa el desarrollo actual para la próxima versión de .NET. Para seleccionar una etiqueta de una versión específica, use la lista desplegable Cambiar ramas o etiquetas. Para obtener más información, vea Procedimientos para seleccionar una etiqueta de versión de código fuente de ASP.NET Core (dotnet/AspNetCore.Docs #26205).

En lugar de usar el indicador de progreso redondo predeterminado, en el ejemplo siguiente se muestra cómo implementar un indicador de progreso lineal.

Agregue los estilos siguientes a wwwroot/css/app.css:

.linear-progress {
    background: silver;
    width: 50vw;
    margin: 20% auto;
    height: 1rem;
    border-radius: 10rem;
    overflow: hidden;
    position: relative;
}

.linear-progress:after {
    content: '';
    position: absolute;
    inset: 0;
    background: blue;
    scale: var(--blazor-load-percentage, 0%) 100%;
    transform-origin: left top;
    transition: scale ease-out 0.5s;
}

Se usa una variable CSS (var(...)) para pasar el valor de --blazor-load-percentage a la propiedad scale de un pseudoelemento azul que indica el progreso de carga de los archivos de la aplicación. A medida que se carga la aplicación, --blazor-load-percentage se actualiza automáticamente, lo que cambia dinámicamente la representación visual del indicador de progreso.

En wwwroot/index.html, quite el indicador redondo SVG predeterminado en <div id="app">...</div> y reemplácelo por el marcado siguiente:

<div class="linear-progress"></div>

Configuración del tiempo de ejecución de WebAssembly de .NET

En escenarios de programación avanzados, se usa la función configureRuntime con el generador de hosts en tiempo de ejecución dotnet para configurar el entorno de ejecución de WebAssembly de .NET. Por ejemplo, dotnet.withEnvironmentVariable establece una variable de entorno que:

  • Configura el tiempo de ejecución de WebAssembly de .NET
  • Cambia el comportamiento de una biblioteca de C.

La función configureRuntime también se puede usar para habilitar la integración con un generador de perfiles de explorador.

En los ejemplos siguientes que establecen una variable de entorno:

  • El marcador de posición {BLAZOR SCRIPT} es la ruta de acceso del script y el nombre de archivo de Blazor. Para obtener la ubicación del script, consulte la estructura del proyecto ASP.NET CoreBlazor.
  • El marcador de posición {NAME} es el nombre de la variable de entorno.
  • El marcador de posición {VALUE} es el valor de la variable de entorno.

Aplicación web Blazor:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    webAssembly: {
      configureRuntime: dotnet => {
        dotnet.withEnvironmentVariable("{NAME}", "{VALUE}");
      }
    }
  });
</script>

Blazor WebAssembly independiente:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    configureRuntime: dotnet => {
      dotnet.withEnvironmentVariable("{NAME}", "{VALUE}");
    }
  });
</script>

Nota:

Se puede acceder a la instancia del entorno de ejecución de .NET mediante la API en tiempo de ejecución Blazor WebAssembly (Blazor.runtime). Por ejemplo, la configuración de compilación de la aplicación se puede obtener mediante Blazor.runtime.runtimeBuildInfo.buildConfiguration.

Para obtener más información sobre la configuración del tiempo de ejecución de WebAssembly de .NET, consulte el archivo de definición TypeScript del tiempo de ejecución (dotnet.d.ts) en el dotnet/runtime repositorio de GitHub.

Nota:

Los vínculos de la documentación al origen de referencia de .NET cargan normalmente la rama predeterminada del repositorio, que representa el desarrollo actual para la próxima versión de .NET. Para seleccionar una etiqueta de una versión específica, use la lista desplegable Cambiar ramas o etiquetas. Para obtener más información, vea Procedimientos para seleccionar una etiqueta de versión de código fuente de ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Deshabilitar la navegación mejorada y el control de formularios

Esta sección se aplica a Blazor Web Apps.

Para deshabilitar la navegación mejorada y el control de formularios, establezca disableDomPreservation en true para Blazor.start.

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    ssr: { disableDomPreservation: true }
  });
</script>

En el ejemplo anterior, el marcador de posición {BLAZOR SCRIPT} es la ruta de acceso del script y el nombre de archivo Blazor. Para obtener la ubicación del script, consulte la estructura del proyecto ASP.NET CoreBlazor.

Recursos adicionales