Inicialização do Blazor do ASP.NET Core

Esse artigo explica a configuração de inicialização do aplicativo Blazor.

Para obter diretrizes gerais sobre a configuração do aplicativo ASP.NET para desenvolvimento do lado do servidor, consulte Configuração no ASP.NET Core.

Processo de inicialização e configuração

O processo de inicialização do Blazor é automático e assíncrono por meio do script Blazor (blazor.*.js), em que o espaço reservado * é:

• web para um aplicativo Web Blazor
• server para um aplicativo Blazor Server
• webassembly para um aplicativo Blazor WebAssembly

Para obter a localização do script, confira a estrutura do projeto ASP.NET Core Blazor.

Para iniciar o Blazormanualmente :

Aplicativo Web Blazor:

• Adicione um atributo autostart="false" e um valor à marca Blazor<script>.
• Coloque um script que chame Blazor.start() após a marca do Blazor<script> e dentro da marca de fechamento </body>.
• Coloque as opções de renderização do lado do servidor estática (SSR estática) na propriedade ssr.
• Coloque as opções de circuito Blazor-SignalR do servidor na propriedade circuit.
• Coloque as opções de WebAssembly do lado do cliente na propriedade webAssembly.

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

Autônomo Blazor WebAssembly e Blazor Server:

• Adicione um atributo autostart="false" e um valor à marca Blazor<script>.
• Coloque um script que chame Blazor.start() após a marca do Blazor<script> e dentro da marca de fechamento </body>.
• Você pode fornecer opções adicionais no parâmetro Blazor.start().

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

No exemplo anterior, o espaço reservado {BLAZOR SCRIPT} é o caminho de script Blazor e o nome do arquivo. Para obter a localização do script, confira a estrutura do projeto ASP.NET Core Blazor.

Inicializadores de JavaScript

Inicializadores de JavaScript (JS) executam a lógica antes e depois do carregamento de um aplicativo Blazor. Inicializadores de JS são úteis nos seguintes cenários:

• Personalizar como um aplicativo Blazor é carregado.
• Inicializar bibliotecas antes de iniciar Blazor.
• Definir configurações de Blazor.

Os inicializadores de JS são detectados como parte do processo de build e importados automaticamente. O uso de inicializadores de JS geralmente remove a necessidade de disparar manualmente funções de script do aplicativo ao usar RCLs (bibliotecas de classes) de Razor.

Para definir um inicializador de JS, adicione um módulo JS ao projeto chamado {NAME}.lib.module.js, em que o espaço reservado {NAME} é o nome do assembly, o nome da biblioteca ou o identificador do pacote. Coloque o arquivo na raiz da Web do projeto, que normalmente é a pasta wwwroot.

Para aplicativos Web Blazor:

• beforeWebStart(options): chamado antes do aplicativo Web Blazor ser iniciado. Por exemplo, beforeWebStart é usado para personalizar o processo de carregamento, o nível de registros em log e outras opções. Recebe as opções Blazor Web (options).
• afterWebStarted(blazor): chamado depois que todas as dependências de beforeWebStart são resolvidas. Por exemplo, afterWebStarted pode ser usado para registrar ouvintes de eventos Blazor e tipos de eventos personalizados. A instância do Blazor é passada para afterWebStarted como um argumento (blazor).
• beforeServerStart(options, extensions): chamado antes do primeiro runtime do servidor ser iniciado. Recebe as opções de início do circuito do SignalR (options) e extensões (extensions) adicionadas durante a publicação.
• afterServerStarted(blazor): chamado após o primeiro runtime do Servidor Interativo ser iniciado.
• beforeWebAssemblyStart(options, extensions): chamado antes do runtime do WebAssembly Interativo ser iniciado. Recebe as opções do Blazor (options) e extensões (extensions) adicionadas durante a publicação. Por exemplo, as opções podem especificar o uso de um carregador de recursos de inicialização personalizado.
• afterWebAssemblyStarted(blazor): chamado após o runtime do WebAssembly interativo ser iniciado.

Observação

Inicializadores JS herdados (beforeStart, afterStarted) não são invocados por padrão em um aplicativo Web Blazor. Você pode habilitar os inicializadores herdados para serem executados com a opção enableClassicInitializers. No entanto, a execução de inicializadores herdados é imprevisível.

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

Para aplicativos Blazor Server, Blazor WebAssembly e Blazor Hybrid:

• beforeStart(options, extensions): chamado antes de Blazor começar. Por exemplo, beforeStart é usado para personalizar o processo de carregamento, o nível de registros em log e outras opções específicas para o modelo de hospedagem.
  • No lado do cliente, beforeStart recebe as opções do Blazor (options) e as extensões (extensions) adicionadas durante a publicação. Por exemplo, as opções podem especificar o uso de um carregador de recursos de inicialização personalizado.
  • No lado do servidor, beforeStart recebe as opções de início do circuito do SignalR (options).
  • Em um BlazorWebView, nenhuma opção é passada.
• afterStarted(blazor): chamado após Blazor estar pronto para receber chamadas de JS. Por exemplo, afterStarted é usado para inicializar bibliotecas fazendo chamadas de interoperabilidade de JS e registrando elementos personalizados. A instância Blazor é passada para o afterStarted como um argumento (blazor).

Retornos de chamada adicionais de runtime do .NET WebAssembly:

• onRuntimeConfigLoaded(config): chamada quando é feito o download da configuração de inicialização. Permite que o aplicativo modifique parâmetros (configuração) antes do início do runtime (o parâmetro é MonoConfig de 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 }): chamada após o início do runtime do .NET WebAssembly (o parâmetro é RuntimeAPI de 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();
  }
  

Ambos os retornos de chamada podem retornar Promise, e a promessa é aguardada antes que a inicialização continue.

Para o nome do arquivo:

• Se os inicializadores JS forem consumidos como um ativo estático no projeto, use o formato {ASSEMBLY NAME}.lib.module.js, em que o espaço reservado {ASSEMBLY NAME} é o nome do assembly do aplicativo. Por exemplo, nomeie o arquivo BlazorSample.lib.module.js para um projeto com o nome de assembly BlazorSample. Coloque o arquivo na pasta wwwroot do aplicativo.
• Se os inicializadores JS forem consumidos de uma RCL, use o formato {LIBRARY NAME/PACKAGE ID}.lib.module.js, em que o espaço reservado {LIBRARY NAME/PACKAGE ID} é o nome da biblioteca ou o identificador de pacote do projeto. Por exemplo, nomeie o arquivo RazorClassLibrary1.lib.module.js para uma RCL com um identificador de pacote RazorClassLibrary1. Coloque o arquivo na pasta wwwroot da biblioteca.

Para aplicativos Web Blazor:

O exemplo a seguir demonstra os inicializadores JS que carregam scripts personalizados antes e depois do aplicativo Web Blazor ter iniciado, acrescentando-os ao <head> em beforeWebStart e 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);
}

O exemplo anterior beforeWebStart garante apenas que o script personalizado seja carregado antes de o Blazor ser iniciado. Ele não garante que as promessas aguardadas no script concluam sua execução antes de o Blazor começar.

Para aplicativos Blazor Server, Blazor WebAssembly e Blazor Hybrid:

O exemplo a seguir demonstra os inicializadores JS que carregam scripts personalizados antes e depois de o Blazor ter começado, acrescentando-os ao <head> em beforeStart e 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);
}

O exemplo anterior beforeStart garante apenas que o script personalizado seja carregado antes de o Blazor ser iniciado. Ele não garante que as promessas aguardadas no script concluam sua execução antes de o Blazor começar.

Observação

Aplicativos MVC e Razor Pages não carregam inicializadores JS automaticamente. No entanto, o código do desenvolvedor pode incluir um script para buscar o manifesto do aplicativo e disparar a carga dos inicializadores JS.

Para obter exemplos de inicializadores JS, consulte os seguintes recursos:

• JavaScript do Blazor do ASP.NET Core com renderização do lado do servidor estática (SSR estática)
• Usar componentes do Razor em aplicativos JavaScript e estruturas SPA ( quoteContainer2exemplo)
• Manipulação de eventos do Blazor para ASP.NET Core (Exemplo de evento de colagem de área de transferência personalizada)
• Habilitar a geração de código QR para aplicativos autenticadores TOTP em um Blazor Aplicativo Web ASP.NET Core
• Aplicativo de Teste Básico no repositório do GitHub do ASP.NET Core (BasicTestApp.lib.module.js)

Observação

Os links de documentação para a fonte de referência do .NET geralmente carregam o branch padrão do repositório, que representa o desenvolvimento atual da próxima versão do .NET. Para selecionar uma marca para uma versão específica, use a lista suspensa para Alternar branches ou marcas. Para saber mais, confira Como selecionar uma marca de versão do código-fonte do ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Garantir que as bibliotecas sejam carregadas em uma ordem específica

Acrescente scripts personalizados ao <head> no beforeStart e afterStarted na ordem que eles devem carregar.

O exemplo a seguir carrega script1.js antes de script2.js e 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);
}

Importar módulos adicionais

Use instruções import de nível superior no arquivo de inicializadores JS para importar módulos adicionais.

additionalModule.js:

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

No arquivo de inicializadores JS (.lib.module.js):

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

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

  logMessage();
}

Importar mapa

Os mapas de importação são compatíveis com ASP.NET Core e Blazor.

Inicializar o Blazor quando o documento estiver pronto

O exemplo a seguir inicia o Blazor quando o documento está pronto:

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

No exemplo anterior, o espaço reservado {BLAZOR SCRIPT} é o caminho de script Blazor e o nome do arquivo. Para obter a localização do script, confira a estrutura do projeto ASP.NET Core Blazor.

Encadear para o Promise que resulta de um início manual

Para executar tarefas adicionais, como a inicialização de interoperabilidade JS, use then para encadear o Promise que resulta de um início manual do aplicativo Blazor:

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

No exemplo anterior, o espaço reservado {BLAZOR SCRIPT} é o caminho de script Blazor e o nome do arquivo. Para obter a localização do script, confira a estrutura do projeto ASP.NET Core Blazor.

Observação

Para que uma biblioteca execute automaticamente tarefas adicionais após oBlazor iniciar, use um inicializador JavaScript. O uso de um inicializador JS não exige que o consumidor da biblioteca encadeie JS nas chamadas para o início manual do Blazor.

Carregar recursos de inicialização do lado do cliente

Quando um aplicativo é carregado no navegador, o aplicativo baixa recursos de inicialização do servidor:

• Código JavaScript para inicializar o aplicativo
• Runtime e assemblies do .NET
• Dados específicos da localidade

Personalize a forma como os recursos de inicialização são carregados usando a API loadBootResource. A função loadBootResource substitui o mecanismo interno de carregamento de recursos de inicialização. Use loadBootResource para os seguintes cenários:

• Carregue recursos estáticos, como dados de fuso horário ou dotnet.wasm, a partir de uma CDN.
• Carregue assemblies compactados usando uma solicitação HTTP e descompacte-os no cliente para hosts que não dão suporte ao fetch de conteúdo compactado do servidor.
• Recursos de alias para um nome diferente redirecionando cada fetch solicitação para um novo nome.

Observação

As fontes externas devem retornar os cabeçalhos CORS (compartilhamento de recursos entre origens) necessários para navegadores para permitir o carregamento de recursos entre origens. Normalmente, as CDNs fornecem os cabeçalhos necessários por padrão.

Os parâmetros loadBootResource aparecem na tabela a seguir.

Parâmetro	Descrição
type	O tipo do recurso. Os tipos permitidos incluem: assembly, pdb, dotnetjs, dotnetwasm e timezonedata. Você só precisa especificar tipos para comportamentos personalizados. Os tipos não especificados para loadBootResource são carregados pela estrutura de acordo com seus comportamentos de carregamento padrão. O recurso de inicialização dotnetjs (dotnet.*.js) deve retornar null para o comportamento de carregamento padrão ou um URI para a origem do recurso de inicialização dotnetjs.
name	O nome do recurso.
defaultUri	O URI relativo ou absoluto do recurso.
integrity	A cadeia de caracteres de integridade que representa o conteúdo esperado na resposta.

A função loadBootResource pode retornar uma cadeia de caracteres de URI para substituir o processo de carregamento. No exemplo a seguir, os seguintes arquivos de bin/Release/{TARGET FRAMEWORK}/wwwroot/_framework são fornecidos de uma CDN em https://cdn.example.com/blazorwebassembly/{VERSION}/:

• dotnet.*.js
• dotnet.wasm
• Dados de fuso horário

O espaço reservado {TARGET FRAMEWORK} é o moniker da estrutura de destino por exemplo, net7.0). O espaço reservado {VERSION} é a versão da estrutura compartilhada (por exemplo, 7.0.0).

Aplicativo 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 autônomo:

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

No exemplo anterior, o espaço reservado {BLAZOR SCRIPT} é o caminho de script Blazor e o nome do arquivo. Para obter a localização do script, confira a estrutura do projeto ASP.NET Core Blazor.

Para personalizar mais do que apenas as URLs para recursos de inicialização, a função loadBootResource pode chamar fetch diretamente e retornar o resultado. O exemplo a seguir adiciona um cabeçalho HTTP personalizado às solicitações de saída. Para manter o comportamento de verificação de integridade padrão, passe o parâmetro integrity.

Aplicativo 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 autônomo:

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

No exemplo anterior, o espaço reservado {BLAZOR SCRIPT} é o caminho de script Blazor e o nome do arquivo. Para obter a localização do script, confira a estrutura do projeto ASP.NET Core Blazor.

Quando a função loadBootResource retorna null, Blazor usa o comportamento de carregamento padrão para o recurso. Por exemplo, o código anterior retorna null para o recurso de inicialização dotnetjs (dotnet.*.js) porque o recurso de inicialização dotnetjs deve retornar null para o comportamento de carregamento padrão ou um URI para a origem do recurso de inicialização dotnetjs.

A função loadBootResource também pode retornar uma Response promessa. Para obter um exemplo, confira Hospedar e implantar o ASP.NET Core Blazor WebAssembly.

Para obter mais informações, consulte ASP.NET Blazor WebAssembly Runtime do .NET e o cache do lote de aplicativo.

Cabeçalhos de controle no código C#

Controle cabeçalhos na inicialização no código C# usando as abordagens a seguir.

Nos exemplos a seguir, uma CSP (Política de Segurança de Conteúdo) é aplicada ao aplicativo por meio de um cabeçalho CSP. O espaço reservado {POLICY STRING} é a cadeia de caracteres de política do CSP.

Cenários do lado do cliente do lado do servidor e pré-renderizados do lado do cliente

Use Middleware do ASP.NET para controlar a coleção de cabeçalhos.

No arquivo Program:

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

O exemplo anterior usa middleware embutido, mas você também pode criar uma classe de middleware personalizada e chamar o middleware com um método de extensão no arquivo Program. Para obter mais informações, confira Escrever middleware do ASP.NET Core personalizado.

Para obter mais informações sobre CSPs, confira Impor uma política de segurança de conteúdo para o ASP.NET Core Blazor.

Indicadores de progresso de carregamento do lado do cliente

Um indicador de progresso de carregamento mostra o progresso do carregamento do aplicativo para os usuários, indicando que o aplicativo está sendo carregado normalmente e que o usuário deve esperar até que o carregamento seja concluído.

Progresso do carregamento do aplicativo Web Blazor

Um indicador de progresso de carregamento usado em aplicativos Blazor WebAssembly não está presente em um aplicativo criado a partir do modelo de projeto de Aplicativo Web Blazor. Normalmente, um indicador de progresso de carregamento não é desejável para componentes WebAssembly interativos porque os Aplicativos Web Blazor pré-renderizam componentes do lado do cliente no servidor para tempos de carregamento iniciais rápidos. Para situações de modo de renderização mista, também é preciso ter cuidado com a estrutura ou o código do desenvolvedor para evitar os seguintes problemas:

• Mostrando vários indicadores de carregamento na mesma página renderizada.
• Descartando inadvertidamente conteúdo pré-renderizado enquanto o runtime do WebAssembly está sendo carregado.

Uma versão futura do .NET pode fornecer um indicador de progresso de carregamento baseado em estrutura. Enquanto isso, você pode adicionar um indicador de progresso de carregamento personalizado a um aplicativo Web Blazor.

Crie um componente LoadingProgress no aplicativo .Client que chama OperatingSystem.IsBrowser:

• Quando false, exiba um indicador de progresso de carregamento enquanto o pacote Blazor é baixado e antes que o runtime Blazor seja ativado no cliente.
• Quando true, renderize o conteúdo do componente solicitado.

A demonstração a seguir usa o indicador de progresso de carregamento encontrado em aplicativos criados a partir do modelo Blazor WebAssembly, incluindo uma modificação dos estilos fornecidos pelo modelo. Os estilos são carregados no conteúdo <head> do aplicativo pelo componente HeadContent. Para mais informações, confira oControle de Conteúdo de CabeçalhoBlazor em aplicativos do 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; }
}

Em um componente que adota a renderização do Interactive WebAssembly, encapsule a marcação Razor do componente com o componente LoadingProgress. O exemplo a seguir demonstra a abordagem com o componente Counter de um aplicativo criado a partir do modelo de projeto do Aplicativo 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++;
    }
}

Progresso do carregamento do aplicativo Blazor WebAssembly

O modelo de projeto do contém gráficos vetoriais escalonáveis (SVG) e indicadores de texto que mostram o progresso do carregamento do aplicativo.

Os indicadores de progresso são implementados com HTML e CSS usando duas propriedades personalizadas CSS (variáveis) fornecidas pelo Blazor:

• --blazor-load-percentage: o percentual de arquivos de aplicativo carregados.
• --blazor-load-percentage-text: o percentual de arquivos de aplicativo carregados, arredondados para o número inteiro mais próximo.

Usando as variáveis CSS anteriores, você pode criar indicadores de progresso personalizados que correspondam ao estilo do seu aplicativo.

No exemplo a seguir:

• resourcesLoaded é uma contagem instantânea dos recursos carregados durante a inicialização do aplicativo.
• totalResources é o número total de recursos a serem carregados.

const percentage = resourcesLoaded / totalResources * 100;
document.documentElement.style.setProperty(
  '--blazor-load-percentage', `${percentage}%`);
document.documentElement.style.setProperty(
  '--blazor-load-percentage-text', `"${Math.floor(percentage)}%"`);

O indicador de progresso redondo padrão é implementado em HTML no arquivo 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 examinar a marcação e o estilo do modelo de projeto para os indicadores de progresso padrão, confira a fonte de referência do ASP.NET Core:

• wwwroot/index.html
• app.css

Observação

Os links de documentação para a fonte de referência do .NET geralmente carregam o branch padrão do repositório, que representa o desenvolvimento atual da próxima versão do .NET. Para selecionar uma marca para uma versão específica, use a lista suspensa para Alternar branches ou marcas. Para saber mais, confira Como selecionar uma marca de versão do código-fonte do ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Em vez de usar o indicador de progresso redondo padrão, o exemplo a seguir mostra como implementar um indicador de progresso linear.

Adicione os seguintes estilos 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;
}

Uma variável CSS (var(...)) é usada para passar o valor de --blazor-load-percentage para a propriedade scale de um pseudo-elemento azul que indica o progresso do carregamento dos arquivos do aplicativo. Conforme o aplicativo é carregado, --blazor-load-percentage é atualizado automaticamente, o que altera dinamicamente a representação visual do indicador de progresso.

No wwwroot/index.html, remova o indicador de rodada SVG padrão em <div id="app">...</div> e substitua-o pela seguinte marcação:

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

Configurar o runtime do .NET WebAssembly

Em cenários avançados de programação, a função configureRuntime com o construtor de host de runtime dotnet é usada para configurar o runtime do .NET WebAssembly. Por exemplo, dotnet.withEnvironmentVariable define uma variável de ambiente que:

• Configura o runtime do WebAssembly do .NET.
• Altera o comportamento de uma biblioteca C.

A função configureRuntime também pode ser usada para habilitar a integração com um criador de perfil do navegador.

Nos exemplos a seguir que definem uma variável de ambiente:

• O espaço reservado {BLAZOR SCRIPT} é o caminho do script Blazor e o nome do arquivo. Para obter a localização do script, confira a estrutura do projeto ASP.NET Core Blazor.
• O espaço reservado {NAME} é o nome da variável de ambiente.
• O espaço reservado {VALUE} é o valor da variável de ambiente.

Aplicativo Web Blazor:

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

Blazor WebAssembly autônomo:

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

Observação

A instância de runtime do .NET pode ser acessada usando a API do runtime Blazor WebAssembly (Blazor.runtime). Por exemplo, a configuração de build do aplicativo pode ser obtida usando Blazor.runtime.runtimeBuildInfo.buildConfiguration.

Para obter mais informações sobre a configuração de runtime do .NET WebAssembly, confira o arquivo de definição TypeScript do runtime (dotnet.d.ts) no repositório GitHub dotnet/runtime.

Observação

Os links de documentação para a fonte de referência do .NET geralmente carregam o branch padrão do repositório, que representa o desenvolvimento atual da próxima versão do .NET. Para selecionar uma marca para uma versão específica, use a lista suspensa para Alternar branches ou marcas. Para saber mais, confira Como selecionar uma marca de versão do código-fonte do ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Desabilitar a navegação e o manuseio de formulários aprimorados

Esta seção aplica-se a Aplicativos Web Blazor.

Para desabilitar a navegação e o tratamento de formulários aprimorados, configure disableDomPreservation como true em Blazor.start.

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

No exemplo anterior, o espaço reservado {BLAZOR SCRIPT} é o caminho de script Blazor e o nome do arquivo. Para obter a localização do script, confira a estrutura do projeto ASP.NET Core Blazor.

Recursos adicionais

• Ambientes: definir o ambiente do aplicativo
• SignalR (inclui seções sobre a configuração de inicialização do SignalR)
• Globalização e localização: defina estaticamente a cultura com Blazor.start() (somente lado do cliente)
• Hospedar e implantar: Blazor WebAssembly: Compactação