Запуск Blazor ASP.NET Core

Процесс Blazor запуска является автоматическим и асинхронным с помощью скрипта Blazor (blazor.*.js), где * заполнитель:

• web для a Blazor Web App
• serverBlazor Server для приложения
• webassemblyBlazor WebAssembly для приложения

Процесс Blazor запуска является автоматическим и асинхронным с помощью скрипта Blazor (blazor.*.js), где * заполнитель:

• serverBlazor Server для приложения
• webassemblyBlazor WebAssembly для приложения

Blazor Web App:

• autostart="false" Добавьте атрибут и значение в Blazor<script> тег.
• Разместите скрипт, который вызывает Blazor.start(), после тега Blazor <script> и внутри закрывающего тега </body>.
• Поместите параметры отрисовки на стороне сервера (статический ssr SSR) в свойство.
• Размещение сервера на стороне Blazorсервера —SignalR параметры канала в свойстве circuit .
• Поместите параметры WebAssembly на стороне webAssembly клиента в свойство.

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

Автономный Blazor WebAssembly и Blazor Server:

Инициализаторы JavaScript

Инициализаторы JavaScript (JS) выполняют логику до и после загрузки приложения Blazor. Инициализаторы JS полезны в следующих сценариях:

• Настройка загрузки приложения Blazor.
• Инициализация библиотек перед запуском Blazor.
• Настройка параметров Blazor.

JS инициализаторы обнаруживаются в процессе сборки и импортируются автоматически. При использовании инициализаторов JS часто не приходится вручную активировать функции скриптов из приложения, если используются библиотеки классов Razor (RCL).

Чтобы определить инициализатор JS, добавьте в проект модуль JS с именем {NAME}.lib.module.js, где заполнитель {NAME} — это имя сборки, имя библиотеки или идентификатор пакета. Поместите файл в корневой каталог проекта. Обычно это папка wwwroot.

Для Blazor Web Apps:

• beforeWebStart(options): вызывается до Blazor Web App начала. Например, beforeWebStart используется для настройки процесса загрузки, уровня ведения журнала и других параметров. Blazor Получает веб-параметры (options).
• afterWebStarted(blazor): Вызывается после разрешения всех beforeWebStart обещаний. Например, afterWebStarted можно использовать для регистрации Blazor прослушивателей событий и пользовательских типов событий. Экземпляр Blazor передается в afterWebStarted качестве аргумента (blazor).
• beforeServerStart(options, extensions): вызывается до запуска первой среды выполнения сервера. SignalR Получает параметры запуска канала () и любые расширения (optionsextensions), добавленные во время публикации.
• afterServerStarted(blazor): вызывается после запуска первой интерактивной среды выполнения сервера.
• beforeWebAssemblyStart(options, extensions): вызывается до запуска интерактивной среды выполнения WebAssembly. Blazor Получает параметры () и любые расширения (optionsextensions), добавленные во время публикации. Например, параметры могут определять использование настраиваемого загрузчика ресурсов.
• afterWebAssemblyStarted(blazor): вызывается после запуска интерактивной среды выполнения WebAssembly.

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

Для Blazor Server, Blazor WebAssemblyи Blazor Hybrid приложений:

• beforeStart(options, extensions): вызывается до запуска Blazor. Например, beforeStart используется для настройки процесса загрузки, уровня ведения журнала и других параметров, относящихся к модели размещения.
  • beforeStart Клиент получает Blazor параметры () и любые расширения (optionsextensions), добавленные во время публикации. Например, параметры могут определять использование настраиваемого загрузчика ресурсов.
  • Серверная сторона beforeStart получает SignalR параметры запуска канала (options).
  • BlazorWebViewВ окне без параметров не передаются.
• afterStarted(blazor): вызывается после того, как Blazor будет готов к получению вызовов из JS. Например, afterStarted используется для инициализации библиотек путем выполнения вызовов взаимодействия сJS и регистрации пользовательских элементов. Экземпляр Blazor передается в afterStarted качестве аргумента (blazor).

Дополнительные обратные вызовы среды выполнения .NET WebAssembly:

• onRuntimeConfigLoaded(config): вызывается при загрузке конфигурации загрузки. Позволяет приложению изменять параметры (конфигурацию) перед запуском среды выполнения (параметр из MonoConfig 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 }): вызывается после запуска среды выполнения .NET WebAssembly (параметр из RuntimeAPI 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();
  }
  

Оба обратных вызова могут возвращать Promise, и обещание ожидается до продолжения запуска.

Имя файла:

• JS Если инициализаторы используются в качестве статического ресурса в проекте, используйте формат{ASSEMBLY NAME}.lib.module.js, в котором {ASSEMBLY NAME} заполнитель — имя сборки приложения. Например, назовите файл BlazorSample.lib.module.js для проекта с именем сборки BlazorSample. Поместите файл в папку wwwroot приложения.
• JS Если инициализаторы используются из RCL, используйте формат{LIBRARY NAME/PACKAGE ID}.lib.module.js, в котором {LIBRARY NAME/PACKAGE ID} заполнитель является именем библиотеки проекта или идентификатором пакета. Например, присвойте файлу имя RazorClassLibrary1.lib.module.js для RCL с идентификатором пакета RazorClassLibrary1. Поместите файл в папку wwwroot библиотеки.

Для Blazor Web Apps:

В следующем примере показаны JS инициализаторы, загружающие пользовательские скрипты до и после Blazor Web App запуска, добавляя их в beforeWebStart <head> и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);
}

В предыдущем beforeWebStart примере гарантируется, что пользовательский скрипт загружается до Blazor запуска. Это не гарантирует, что ожидаемые обещания в скрипте завершают выполнение перед Blazor началом работы.

Для Blazor Server, Blazor WebAssemblyи Blazor Hybrid приложений:

В следующем примере показаны JS инициализаторы, которые загружают пользовательские скрипты до и после Blazor запуска, добавляя их в <head> beforeStart и 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);
}

В предыдущем beforeStart примере гарантируется, что пользовательский скрипт загружается до Blazor запуска. Это не гарантирует, что ожидаемые обещания в скрипте завершают выполнение перед Blazor началом работы.

Примеры инициализаторов JS см. в следующих ресурсах:

• ASP.NET Core Blazor JavaScript со статическим отображением на стороне сервера (статический SSR)
• Использование Razor компонентов в приложениях JavaScript и платформах SPA (quoteContainer2 пример)
• ASP.NET Обработка событий Core Blazor (пример события пользовательской вставки буфера обмена)
• Включение создания QR-кода для приложений проверки подлинности TOTP в ASP.NET Core Blazor Web App
• Базовое тестовое приложение в репозитории GitHub ASP.NET Core (BasicTestApp.lib.module.js)

• Использование Razor компонентов в приложениях JavaScript и платформах SPA (quoteContainer2 пример)
• ASP.NET Обработка событий Core Blazor (пример события пользовательской вставки буфера обмена)
• Макет развертывания для размещенных Blazor WebAssembly приложений ASP.NET Core
• Базовое тестовое приложение в репозитории GitHub ASP.NET Core (BasicTestApp.lib.module.js)

Убедитесь, что библиотеки загружаются в определенном порядке

Добавьте пользовательские скрипты в <head> и afterStarted beforeStart в том порядке, в который они должны загружаться.

Следующий пример загружается script1.js до script2.js и script3.js до 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);
}

Импорт дополнительных модулей

Используйте инструкции верхнего уровня import в JS файле инициализаторов для импорта дополнительных модулей.

additionalModule.js:

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

JS В файле инициализаторов (.lib.module.js):

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

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

  logMessage();
}

Карта импорта

Карты импорта поддерживаются ASP.NET Core и 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:

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:

В файле Program:

В методе Startup.Configure в файле Startup.cs:

Разработка на стороне клиента без предварительной подготовки

Передайте StaticFileOptions в MapFallbackToFile нее заголовки ответа на OnPrepareResponse этапе.

В серверном Program файле:

В методе Startup.Configure в файле Startup.cs:

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

...

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

Индикаторы хода загрузки на стороне клиента

Индикатор хода загрузки показывает ход загрузки приложения пользователям, указывая, что приложение загружается обычно и что пользователь должен ждать завершения загрузки.

Blazor Web App Ход загрузки

Индикатор хода загрузки, используемый в приложениях, отсутствует в Blazor WebAssembly приложении, созданном Blazor Web App на основе шаблона проекта. Как правило, индикатор хода загрузки не является желательным для интерактивных компонентов WebAssembly, так как Blazor Web Appпредопределенные клиентские компоненты на сервере для быстрого начального времени загрузки. Для ситуаций в смешанном режиме отрисовки код платформы или разработчика также должен быть осторожным, чтобы избежать следующих проблем:

• Отображение нескольких индикаторов загрузки на одной отрисованной странице.
• Непреднамеренно отменяя предварительно созданное содержимое во время загрузки среды выполнения .NET WebAssembly.

Будущий выпуск .NET может предоставить индикатор хода загрузки на основе платформы. В то же время можно добавить в нее Blazor Web Appпользовательский индикатор хода загрузки.

LoadingProgress Создайте компонент в .Client приложении, который вызываетOperatingSystem.IsBrowser:

• При falseпоявлении индикатора хода загрузки во время Blazor скачивания пакета и перед Blazor активацией среды выполнения на клиенте.
• Когда trueотрисуйте содержимое запрошенного компонента.

В следующей демонстрации используется индикатор хода загрузки, найденный в приложениях, созданных на основе Blazor WebAssembly шаблона, включая изменение стилей, которые предоставляет шаблон. Стили загружаются в содержимое приложения <head> компонентом HeadContent . Дополнительные сведения см. в статье Управление содержимым head в приложениях ASP.NET Core Blazor.

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

В компоненте, который использует интерактивную отрисовку WebAssembly, обтекайте разметку компонента Razor компонентом LoadingProgress . В следующем примере демонстрируется подход с Counter компонентом приложения, созданного 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++;
    }
}

Blazor WebAssembly Ход загрузки приложения

Шаблон проекта содержит индикаторы масштабируемой векторной графики (SVG) и текстовые индикаторы, показывающие ход загрузки приложения.

Индикаторы хода выполнения реализуются с помощью HTML и каскадных таблиц стилей (CSS) с использованием двух настраиваемых свойств CSS (переменных), которые предоставляются с помощью Blazor:

• --blazor-load-percentage — процент загруженных файлов приложения.
• --blazor-load-percentage-text — процент загруженных файлов приложения, округленный до ближайшего целого числа.

Переменные каскадных таблицы стилей выше позволяют создавать пользовательские индикаторы хода выполнения согласно стилю приложения.

В следующем примере :

• resourcesLoaded — это текущее число ресурсов, загруженных во время запуска приложения.
• totalResources — общее количество ресурсов для загрузки.

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

Индикатор хода выполнения по умолчанию реализуется в HTML-файле 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>

Разметку шаблона проекта и стили для индикаторов хода выполнения по умолчанию см. в справочном ресурсе по ASP.NET Core:

• wwwroot/index.html
• app.css

Вместо использования индикатора хода выполнения по умолчанию в следующем примере показано, как реализовать линейный индикатор хода выполнения.

Добавьте следующие стили 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;
}

Переменная CSS (var(...)) используется для передачи значения --blazor-load-percentage scale свойству синего псевдо-элемента, указывающего ход загрузки файлов приложения. По мере загрузки приложения обновляется автоматически, --blazor-load-percentage что динамически изменяет визуальное представление индикатора хода выполнения.

В wwwroot/index.htmlудалите индикатор <div id="app">...</div> раунда SVG по умолчанию и замените его следующим разметкой:

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

Настройка среды выполнения .NET WebAssembly

В расширенных сценариях configureRuntime программирования функция с dotnet построителем узлов среды выполнения используется для настройки среды выполнения .NET WebAssembly. Например, задает переменную среды, dotnet.withEnvironmentVariable которая:

• Настраивает среду выполнения .NET WebAssembly.
• Изменяет поведение библиотеки C.

Функцию configureRuntime также можно использовать для включения интеграции с профилировщиком браузера.

Для заполнителей в следующих примерах, которые задают переменную среды:

• Заполнитель {BLAZOR SCRIPT} — это путь к скрипту Blazor и имя файла. Сведения о расположении скрипта см. в разделе ASP.NET Структура проекта CoreBlazor.
• Заполнитель {NAME} — это имя переменной среды.
• Заполнитель {VALUE} — это значение переменной среды.

Blazor Web App:

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

Изолированное решение Blazor WebAssembly:

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

Отключение расширенной навигации и обработки форм

Этот раздел относится к Blazor Web Apps.

Чтобы отключить расширенную навигацию и обработку форм, установите для следующих значений true disableDomPreservation Blazor.start:

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

В предыдущем примере {BLAZOR SCRIPT} заполнитель — это путь к скрипту Blazor и имя файла. Сведения о расположении скрипта см. в разделе ASP.NET Структура проекта CoreBlazor.