Статические файлы Blazor Hybrid в ASP.NET Core

В этой статье собраны сведения о том, как использовать статические файлы ресурсов в приложениях Blazor Hybrid.

В приложении Blazor Hybrid статические файлы представляют собой ресурсы приложения, к которым обращаются компоненты Razor, используя следующие методы:

• .NET MAUI: .NET MAUI file system helpers
• WPF и Windows Forms: ResourceManager

Если статические ресурсы используются только в компонентах Razor, их можно получать из корневого каталога веб-проекта (папки wwwroot), как в обычных приложениях Blazor WebAssembly и Blazor Server. Дополнительные сведения см. в разделе Статические ресурсы, ограниченные компонентами Razor.

.NET MAUI

В приложениях .NET MAUI в качестве статических ресурсов используются необработанные ресурсы с действием сборки MauiAsset и .NET MAUI file system helpers.

Поместите необработанные ресурсы в папку Resources/Raw для приложения. В примере для этого раздела используется статический текстовый файл.

Resources/Raw/Data.txt:

This is text from a static text file resource.

Приведенный ниже компонент Razor делает следующее.

• Вызывает OpenAppPackageFileAsync для получения ресурса Stream.
• Считывает Stream с помощью StreamReader.
• Вызывает StreamReader.ReadToEndAsync, чтобы прочитать файл.

Pages/StaticAssetExample.razor:

@page "/static-asset-example"
@using System.IO
@using Microsoft.Extensions.Logging
@inject ILogger<StaticAssetExample> Logger

<h1>Static Asset Example</h1>

<p>@dataResourceText</p>

@code {
    public string dataResourceText = "Loading resource ...";

    protected override async Task OnInitializedAsync()
    {
        try
        {
            using var stream = 
                await FileSystem.OpenAppPackageFileAsync("Data.txt");
            using var reader = new StreamReader(stream);

            dataResourceText = await reader.ReadToEndAsync();
        }
        catch (FileNotFoundException ex)
        {
            dataResourceText = "Data file not found.";
            Logger.LogError(ex, "'Resource/Raw/Data.txt' not found.");
        }
    }
}

Дополнительные сведения см. на следующих ресурсах:

• Выбор нескольких платформ из .NET MAUI одного проекта (документация .NET MAUI)
• Повышение согласованности с помощью средства изменения размера (dotnet/maui #4367)

WPF

Поместите ресурс в папку приложения, обычно для этого используется папка Resources или с другим именем в корневом каталоге проекта. В примере для этого раздела используется статический текстовый файл.

Resources/Data.txt:

This is text from a static text file resource.

Если папка Properties не существует в приложении, создайте папку Properties в корневом каталоге приложения.

Если папка Properties не содержит файл ресурсов (Resources.resx), создайте файл в обозревателе решений. Для этого вызовите контекстное меню и выберите Добавить>Новый элемент.

Дважды щелкните файл Resource.resx.

Выберите Strings, Files (Строки — Файлы) из раскрывающегося списка.

Выберите Add Resource, Add Existing File (Добавить ресурс — Добавить существующий файл). Если в Visual Studio появится запрос на подтверждение редактирования файла, нажмите кнопку Yes (Да). Перейдите в папку Resources, выберите файл Data.txt и нажмите кнопку Open (Открыть).

В следующем примере компонента ResourceManager.GetString получает текст строкового ресурса для отображения.

StaticAssetExample.razor:

@page "/static-asset-example"
@using System.Resources

<h1>Static Asset Example</h1>

<p>@dataResourceText</p>

@code {
    public string dataResourceText = "Loading resource ...";

    protected override void OnInitialized()
    {
        var resources = 
            new ResourceManager(typeof(WpfBlazor.Properties.Resources));

        dataResourceText = resources.GetString("Data") ?? "'Data' not found.";
    }
}

Windows Forms

Поместите ресурс в папку приложения, обычно для этого используется папка Resources или с другим именем в корневом каталоге проекта. В примере для этого раздела используется статический текстовый файл.

Resources/Data.txt:

This is text from a static text file resource.

Изучите файлы, связанные с Form1, в обозревателе решений. Если Form1 не содержит файл ресурсов (.resx), добавьте файл Form1.resx с помощью контекстного меню, нажав Добавить>Новый элемент.

Дважды щелкните файл Form1.resx.

Выберите Strings, Files (Строки — Файлы) из раскрывающегося списка.

Выберите Add Resource, Add Existing File (Добавить ресурс — Добавить существующий файл). Если в Visual Studio появится запрос на подтверждение редактирования файла, нажмите кнопку Yes (Да). Перейдите в папку Resources, выберите файл Data.txt и нажмите кнопку Open (Открыть).

В следующем примере компонента имеет следующие характеристики.

• Имя сборки приложения — WinFormsBlazor. Базовое имя ResourceManager совпадает с именем сборки Form1 (WinFormsBlazor.Form1).
• ResourceManager.GetString получает текст строкового ресурса для отображения.

StaticAssetExample.razor:

@page "/static-asset-example"
@using System.Resources

<h1>Static Asset Example</h1>

<p>@dataResourceText</p>

@code {
    public string dataResourceText = "Loading resource ...";

    protected override async Task OnInitializedAsync()
    {   
        var resources = 
            new ResourceManager("WinFormsBlazor.Form1", this.GetType().Assembly);

        dataResourceText = resources.GetString("Data") ?? "'Data' not found.";
    }
}

Статические ресурсы, ограниченные компонентами Razor

Элемент BlazorWebView управления имеет настроенный файл узла (HostPageобычно wwwroot/index.html). HostPage Путь относительно проекта. Все статические веб-ресурсы (скрипты, CSS-файлы, изображения и другие файлы), на которые ссылается ссылка, BlazorWebView относятся к настроенной.HostPage

Статические веб-ресурсы из Razor библиотеки классов (RCL) используют специальные пути: _content/{PACKAGE ID}/{PATH AND FILE NAME} Заполнитель {PACKAGE ID} — это идентификатор пакета библиотеки. Идентификатор пакета по умолчанию имеет имя сборки проекта, если значение <PackageId> не указано в файле проекта. Заполнитель {PATH AND FILE NAME} — это путь и имя файла в разделе wwwroot. Эти пути логически подпаты к папке приложения wwwroot , хотя они фактически приходят из других пакетов или проектов. Пакеты стилей CSS для конкретного компонента также создаются в корне wwwroot папки.

Веб-корневой HostPage каталог определяет, какой подмножество статических ресурсов доступно:

• wwwroot/index.html(рекомендуется): все ресурсы в папке приложения wwwroot доступны (например, доступны из /image.png), включая вложенные папки (например, wwwroot/image.png wwwroot/subfolder/image.png доступны из /subfolder/image.png). Статические ресурсы RCL в папке RCL wwwroot доступны (например, доступны из пути_content/{PACKAGE ID}/image.png), включая вложенные папки (например, wwwroot/image.png wwwroot/subfolder/image.png доступны из пути_content/{PACKAGE ID}/subfolder/image.png).
• wwwroot/{PATH}/index.html: все ресурсы в папке приложения wwwroot/{PATH} доступны с помощью относительных путей веб-приложения. Статические ресурсы wwwroot/{PATH} RCL не являются потому, что они будут находиться в несуществующем теоретическим расположении, например ../../_content/{PACKAGE ID}/{PATH}, который не является поддерживаемым относительным путем.
• wwwroot/_content/{PACKAGE ID}/index.html: все ресурсы в папке RCL доступны с помощью относительных путей к веб-корню RCL wwwroot/{PATH} . Статические ресурсы wwwroot/{PATH} приложения не являются потому, что они будут находиться в несуществующем теоретическим расположении, например ../../{PATH}, который не поддерживает относительный путь.

Для большинства приложений рекомендуется разместить HostPage в корне wwwroot папки приложения, которая обеспечивает большую гибкость для предоставления статических ресурсов из приложения, RCLs и вложенных папок приложения и RC-адресов.

В следующих примерах показано, как ссылаться на статические ресурсы из веб-корневого каталога приложения (wwwroot папка) с HostPage корнем в папке wwwroot .

wwwroot/data.txt:

This is text from a static text file resource.

wwwroot/scripts.js:

export function showPrompt(message) {
  return prompt(message, 'Type anything here');
}

В этом примере раздела также используется следующее изображение Jeep®. Щелкните правой кнопкой мыши следующее изображение, чтобы сохранить его локально для использования в локальном тестовом приложении.

wwwroot/jeep-yj.png:

В компоненте Razor:

• Содержимое статического текстового файла можно считывать с помощью следующих методов:
  • .NET MAUI: .NET MAUI file system helpers (OpenAppPackageFileAsync)
  • WPF и Windows Forms: StreamReader.ReadToEndAsync
• Файлы JavaScript доступны в логических подпатах wwwroot по пути использования ./ .
• Изображение может быть исходным атрибутом (src) тега изображения (<img>).

StaticAssetExample2.razor:

@page "/static-asset-example-2"
@using Microsoft.Extensions.Logging
@implements IAsyncDisposable
@inject IJSRuntime JS
@inject ILogger<StaticAssetExample2> Logger

<h1>Static Asset Example 2</h1>

<h2>Read a file</h2>

<p>@dataResourceText</p>

<h2>Call JavaScript</h2>

<p>
    <button @onclick="TriggerPrompt">Trigger browser window prompt</button>
</p>

<p>@result</p>

<h2>Show an image</h2>

<p><img alt="1991 Jeep YJ" src="/jeep-yj.png" /></p>

<p>
    <em>Jeep</em> and <em>Jeep YJ</em> are registered trademarks of 
    <a href="https://www.stellantis.com">FCA US LLC (Stellantis NV)</a>.
</p>

@code {
    private string dataResourceText = "Loading resource ...";
    private IJSObjectReference? module;
    private string result;

    protected override async Task OnInitializedAsync()
    {   
        try
        {
            dataResourceText = await ReadData();
        }
        catch (FileNotFoundException ex)
        {
            dataResourceText = "Data file not found.";
            Logger.LogError(ex, "'wwwroot/data.txt' not found.");
        }
    }

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            module = await JS.InvokeAsync<IJSObjectReference>("import",
                "./scripts.js");
        }
    }

    private async Task TriggerPrompt()
    {
        result = await Prompt("Provide some text");
    }

    public async ValueTask<string> Prompt(string message) =>
        module is not null ?
            await module.InvokeAsync<string>("showPrompt", message) : null;

    async ValueTask IAsyncDisposable.DisposeAsync()
    {
        if (module is not null)
        {
            try
            {
                await module.DisposeAsync();
            }
            catch (JSDisconnectedException)
            {
            }
        }
    }
}

В приложениях .NET MAUI добавьте следующий метод ReadData в блок @code описанного выше компонента:

private async Task<string> ReadData()
{
    using var stream = await FileSystem.OpenAppPackageFileAsync("wwwroot/data.txt");
    using var reader = new StreamReader(stream);

    return await reader.ReadToEndAsync();
}

В приложениях WPF и Windows Forms добавьте следующий метод ReadData в блок @code описанного выше компонента:

private async Task<string> ReadData()
{
    using var reader = new StreamReader("wwwroot/data.txt");

    return await reader.ReadToEndAsync();
}

Файлы JavaScript с сортировкой также доступны в логических подпатах wwwroot. Вместо использования скрипта, описанного ранее для функции, wwwroot/scripts.jsследующий коллакуированный файл JavaScript для showPrompt StaticAssetExample2 компонента также делает функцию доступной.

Pages/StaticAssetExample2.razor.js:

export function showPrompt(message) {
  return prompt(message, 'Type anything here');
}

Измените ссылку на объект модуля в компоненте StaticAssetExample2 , чтобы использовать путь к файлу JavaScript с сортировкой (./Pages/StaticAssetExample2.razor.js):

module = await JS.InvokeAsync<IJSObjectReference>("import", 
    "./Pages/StaticAssetExample2.razor.js");

Товарные знаки

Jeep и Jeep YJ являются зарегистрированными товарными знаками FCA US LLC (Stellantis NV).

Дополнительные ресурсы

• ResourceManager
• Создание файлов ресурсов для приложений .NET (документация по основам .NET)
• Практическое руководство. Использование ресурсов в локализуемых приложениях (документация по WPF)