Statische Blazor Hybrid-Dateien in ASP.NET Core

Hinweis

Dies ist nicht die neueste Version dieses Artikels. Die aktuelle Version finden Sie in der .NET 9-Version dieses Artikels.

Warnung

Diese Version von ASP.NET Core wird nicht mehr unterstützt. Weitere Informationen finden Sie in der .NET- und .NET Core-Supportrichtlinie. Die aktuelle Version finden Sie in der .NET 9-Version dieses Artikels.

Wichtig

Diese Informationen beziehen sich auf ein Vorabversionsprodukt, das vor der kommerziellen Freigabe möglicherweise noch wesentlichen Änderungen unterliegt. Microsoft gibt keine Garantie, weder ausdrücklich noch impliziert, hinsichtlich der hier bereitgestellten Informationen.

Die aktuelle Version finden Sie in der .NET 9-Version dieses Artikels.

Dieser Artikel beschreibt, wie Sie statische Ressourcendateien in Blazor Hybrid Apps verarbeiten.

In einer Blazor Hybrid App sind statische Dateien App-Ressourcen, auf welche Razor Komponenten unter Verwendung der folgenden Ansätze zugreifen:

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

Wenn statische Ressourcen nur in den Razor Komponenten verwendet werden, können sie vom Webroot (wwwroot Ordner) auf ähnliche Weise verarbeitet werden wie Blazor WebAssembly und Blazor Server Apps. Weitere Informationen finden Sie im Abschnitt Statische Ressourcen, welche auf RazorKomponenten beschränkt sind.

.NET MAUI

In .NET MAUI Apps werden Roh-Ressourcen, welche die MauiAsset Buildaktion und .NET MAUI file system helpers verwenden, für statische Ressourcen genutzt.

Hinweis

Schnittstellen, Klassen und unterstützende Typen zum Arbeiten mit Speicher auf Geräten auf allen unterstützten Plattformen für Features wie das Auswählen einer Datei, das Speichern von Einstellungen und die Verwendung von sicherem Speicher befinden sich im Microsoft.Maui.Storage-Namespace. Der Namespace ist in einer MAUI Blazor Hybrid-App verfügbar, daher muss keine using-Anweisung in einer Klassendatei oder einer @usingRazor-Anweisung in einer Razor-Komponente für den Namespace angegeben werden.

Legen Sie Roh-Ressourcen in den Resources/Raw Ordner der App. Das Beispiel in diesem Abschnitt nutzt eine statische Textdatei.

Resources/Raw/Data.txt:

This is text from a static text file resource.

Die folgende Razor-Komponente:

• Ruft OpenAppPackageFileAsync auf, um eine Stream für die Ressource zu erhalten.
• Liest die Stream mit einem StreamReader.
• Ruft StreamReader.ReadToEndAsync auf, um die Datei zu lesen.

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.");
        }
    }
}

Weitere Informationen finden Sie in den folgenden Ressourcen:

• Visieren Sie mehrere Plattformen aus einem .NET MAUI einzelnen Projekt (.NET MAUI Dokumentation) an.
• Verbessern Sie die Konsistenz mit der Größenanpassung (dotnet/maui #4367).

WPF

Legen Sie das Objekt in einen Ordner der App, in der Regel im Stammverzeichnis des Projekts, z. B. in einen Resources Ordner. Das Beispiel in diesem Abschnitt nutzt eine statische Textdatei.

Resources/Data.txt:

This is text from a static text file resource.

Wenn ein Properties Ordner in der App nicht vorhanden ist, erstellen Sie einen Properties Ordner im Stammverzeichnis der App.

Wenn der Ordner Properties keine Ressourcendatei (Resources.resx) enthält, erstellen Sie die Datei im Projektmappen-Explorer mit dem Kontextmenübefehl Hinzufügen>Neues Element.

Doppelklicken Sie auf die Resource.resx-Datei.

Wählen Sie Zeichenfolgen>Dateien im Dropdown- Menü aus.

Wählen Sie Ressource hinzufügen>Vorhandene Datei hinzufügen aus. Wenn Sie von Visual Studio aufgefordert werden, die Bearbeitung der Datei zu bestätigen, wählen Sie Ja aus. Gehen Sie zum Resources Ordner, wählen Sie die Data.txt Datei aus, und wählen Sie Öffnen aus.

In der folgenden Beispielkomponente ruft ResourceManager.GetString den Text der Zeichenfolgenressource zur Anzeige ab.

Warnung

Verwenden Sie ResourceManager Methoden nie mit nicht vertrauenswürdigen Daten.

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

Legen Sie das Objekt in einen Ordner der App, in der Regel im Stammverzeichnis des Projekts, z. B. in einen Resources Ordner. Das Beispiel in diesem Abschnitt nutzt eine statische Textdatei.

Resources/Data.txt:

This is text from a static text file resource.

Überprüfen Sie die Dateien, welche Form1 im Projektmappen-Explorer zugeordnet sind. Wenn Form1 keine Ressourcendatei (.resx) enthält, fügen Sie eine Datei vom Typ Form1.resx mit dem Kontextmenübefehl Hinzufügen>Neues Element hinzu.

Doppelklicken Sie auf die Form1.resx-Datei.

Wählen Sie Zeichenfolgen>Dateien im Dropdown- Menü aus.

Wählen Sie Ressource hinzufügen>Vorhandene Datei hinzufügen aus. Wenn Sie von Visual Studio aufgefordert werden, die Bearbeitung der Datei zu bestätigen, wählen Sie Ja aus. Gehen Sie zum Resources Ordner, wählen Sie die Data.txt Datei aus, und wählen Sie Öffnen aus.

In der folgenden Beispielkomponente:

• Ist WinFormsBlazor der Assemblyname der App. Der Basisname von ResourceManager wird auf den Assemblynamen von Form1( WinFormsBlazor.Form1) festgelegt.
• ResourceManager.GetString ruft den Text der Zeichenfolgenressource zur Anzeige ab.

Warnung

Verwenden Sie ResourceManager Methoden nie mit nicht vertrauenswürdigen Daten.

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

Auf Razor Komponenten beschränkte statische Ressourcen

Ein BlazorWebView-Steuerelement umfasst eine konfigurierte Hostdatei (HostPage), in der Regel wwwroot/index.html. Der Pfad HostPage ist relativ zum Projekt angegeben. Alle mit BlazorWebView referenzierten statischen Webressourcen (Skripts, CSS-Dateien, Bilder und andere Dateien) werden relativ zur zugehörigen konfigurierten HostPage angegeben.

Statische Webressourcen aus einer Razor-Klassenbibliothek (RCL) verwenden spezielle Pfade: _content/{PACKAGE ID}/{PATH AND FILE NAME}. Der Platzhalter {PACKAGE ID} ist diePaket-IDder Bibliothek. Die Paket-ID wird standardmäßig auf den Assemblynamen des Projekts festgelegt, wenn <PackageId> nicht in der Projektdatei angegeben ist. Der Platzhalter {PATH AND FILE NAME} entspricht dem Pfad und Dateinamen unter wwwroot. Diese Pfade sind logisch Unterpfade des Ordners wwwroot der App, obwohl sie tatsächlich aus anderen Paketen oder Projekten stammen. Komponentenspezifische CSS-Formatvorlagenpakete werden ebenfalls im Stammverzeichnis des Ordners wwwroot erstellt.

Der Webstamm von HostPage bestimmt, welche Teilmenge der statischen Ressourcen verfügbar ist:

• wwwroot/index.html (empfohlen): Alle Ressourcen im Ordner wwwroot der App sind verfügbar (Beispiel: wwwroot/image.png ist über /image.png verfügbar), einschließlich der Unterordner (Beispiel: wwwroot/subfolder/image.png ist über /subfolder/image.png verfügbar). Die statischen RCL-Ressourcen im RCL-Ordner wwwroot sind verfügbar (Beispiel: wwwroot/image.png ist über den Pfad _content/{PACKAGE ID}/image.png verfügbar), einschließlich der Unterordner (Beispiel: wwwroot/subfolder/image.png ist über den Pfad _content/{PACKAGE ID}/subfolder/image.png verfügbar).
• wwwroot/{PATH}/index.html: Alle Ressourcen im Ordner wwwroot/{PATH} der App sind über die relativen Pfade des App-Webstamms verfügbar. Die statischen RCL-Assets in wwwroot/{PATH} sind es nicht, weil sie sich an einem theoretisch nicht existierenden Ort befinden würden, wie z. B. ../../_content/{PACKAGE ID}/{PATH}, was kein unterstützter relativer Pfad ist.
• wwwroot/_content/{PACKAGE ID}/index.html: Alle Ressourcen im RCL-Ordner wwwroot/{PATH} sind über die relativen Pfade des RCL-Webstamms verfügbar. Die statischen Elemente der App in wwwroot/{PATH} werden nicht angezeigt, weil sie sich an einem nicht existierenden theoretischen Ort wie ../../{PATH} befinden würden, der kein unterstützter relativer Pfad ist.

Für die meisten Apps empfiehlt es sich, HostPage im Stammordner des App-Ordners wwwroot zu platzieren. Dies bietet die größte Flexibilität für die Bereitstellung statischer Ressourcen aus der App, aus RCLs sowie über Unterordner von App und RCLs.

Die folgenden Beispiele veranschaulichen das Verweisen auf statische Ressourcen aus dem Webstamm (Ordner wwwroot) der App, bei der sich der Stamm von HostPage im Ordner wwwroot befindet.

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

Das folgende Jeep®-Bild wird ebenso im Beispiel dieses Abschnitts verwendet. Sie können mit der rechten Maustaste auf das folgende Bild klicken, um es lokal zur Verwendung in einer lokalen Test-App zu speichern.

wwwroot/jeep-yj.png:

In einer Razor-Komponente:

• Der statische Textdateiinhalt kann mithilfe der folgenden Verfahren ausgelesen werden:
  • .NET MAUI: .NET MAUI file system helpers (OpenAppPackageFileAsync)
  • WPF und Windows Forms: StreamReader.ReadToEndAsync
• JavaScript-Dateien sind in logischen Unterpfaden von wwwroot über ./-Pfade verfügbar.
• Das Bild kann das Quellattribut (src) eines Bildtags (<img>) sein.

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)
            {
            }
        }
    }
}

Fügen Sie in .NET MAUI Apps die folgende ReadData Methode zum @code Block der vorherigen Komponente hinzu:

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

    return await reader.ReadToEndAsync();
}

Fügen Sie in WPF und Windows Forms-Apps die folgende ReadData Methode zum @code Block der vorherigen Komponente hinzu:

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

    return await reader.ReadToEndAsync();
}

Auch kombinierte JavaScript-Dateien sind in logischen Unterpfaden von wwwroot vorhanden. Anstatt das zuvor beschriebene Skript für die showPrompt-Funktion in wwwroot/scripts.js zu verwenden, macht die folgende kombinierte JavaScript-Datei für die StaticAssetExample2-Komponente auch die Funktion verfügbar.

Pages/StaticAssetExample2.razor.js:

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

Ändern Sie den Modulobjektverweis in der StaticAssetExample2-Komponente, damit der Pfad der kombinierten JavaScript-Datei (./Pages/StaticAssetExample2.razor.js) verwendet wird:

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

Marken

Jeep und Jeep YJ sind eingetragene Marken von FCA US LLC (Stellantis NV).

Zusätzliche Ressourcen

• ResourceManager
• Erstellen von Ressourcendateien für .NET-Apps (.NET-Grundlagendokumentation)
• So wird‘s gemacht: Verwenden von Ressourcen in lokalisierbaren Apps (WPF Dokumentation)