Inicialização do Blazor do ASP.NET Core

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 de um Blazor Web App
• server para um aplicativo Blazor Server
• webassembly para um aplicativo Blazor WebAssembly

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 * é:

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

Blazor Web App:

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

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 Blazor Web Apps:

• beforeWebStart(options): chamado antes de Blazor Web App começar. 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.

<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 Blazor Web Apps:

O exemplo a seguir demonstra os inicializadores JS que carregam scripts personalizados antes e depois de o Blazor Web App ter começado 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.

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 Web App do ASP.NET Core
• Aplicativo de Teste Básico no repositório do GitHub do ASP.NET Core (BasicTestApp.lib.module.js)

• 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)
• Layout de implantação para aplicativos hospedados no ASP.NET Core Blazor WebAssembly
• Aplicativo de Teste Básico no repositório do GitHub do ASP.NET Core (BasicTestApp.lib.module.js)

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.

Blazor Web App:

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

Blazor Web App:

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

No arquivo Program:

No Startup.Configure do Startup.cs:

Desenvolvimento do lado do cliente sem pré-renderização

Passe StaticFileOptions para MapFallbackToFile que especifica os cabeçalhos de resposta no estágio OnPrepareResponse.

No arquivo Program do lado do servidor:

No Startup.Configure do Startup.cs:

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

...

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

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 de carregamento do Blazor Web App

Um indicador de progresso de carregamento usado em aplicativos do Blazor WebAssembly não está presente em um aplicativo criado a partir do modelo de projeto do Blazor Web App. Normalmente, um indicador de progresso de carregamento não é desejável para componentes WebAssembly interativos porque os Blazor Web Apps 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 .NET 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 Blazor Web App.

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.142 * 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 Blazor Web App.

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

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.

Quanto aos espaços reservados 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.

Blazor Web App:

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

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

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

Para desabilitar a navegação e o manuseio aprimorados de formulários, defina disableDomPreservation como true para 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.