stahování souborů ASP.NET Core Blazor

Tento článek vysvětluje, jak stahovat soubory v Blazor aplikacích.

Stažení souborů

Soubory je možné stáhnout z vlastních statických prostředků aplikace nebo z libovolného jiného umístění:

• ASP.NET základní aplikace používají statický middleware k poskytování souborů klientům aplikací na straně serveru.
• Pokyny v tomto článku platí také pro jiné typy souborových serverů, které nepoužívají .NET, jako jsou sítě PRO doručování obsahu (CDN).

Tento článek popisuje přístupy pro následující scénáře, kdy by se soubor neměl otevírat v prohlížeči, ale stahovat a ukládat do klienta:

• Streamování obsahu souboru do nezpracované binární datové vyrovnávací paměti klienta: Obvykle se tento přístup používá pro relativně malé soubory (< 250 MB).
• Stáhněte si soubor přes adresu URL bez streamování: Tento přístup se obvykle používá pro relativně velké soubory (> 250 MB).

Při stahování souborů z jiného původu než aplikace platí důležité informace o sdílení prostředků mezi zdroji (CORS). Další informace najdete v části Sdílení prostředků mezi zdroji (CORS).

Bezpečnostní aspekty

Při poskytování uživatelů s možností stahovat soubory ze serveru buďte opatrní. Útočníci můžou spouštět útoky doS (DoS), útoky na zneužití rozhraní API nebo se pokoušet o napadení sítí a serverů jinými způsoby.

Bezpečnostní kroky, které snižují pravděpodobnost úspěšného útoku:

• Stáhněte si soubory z vyhrazené oblasti pro stahování souborů na serveru, nejlépe z nesystémové jednotky. Použití vyhrazeného umístění usnadňuje ukládání bezpečnostních omezení pro soubory ke stažení. Zakažte oprávnění ke spuštění v oblasti pro stahování souborů.
• Kontroly zabezpečení na straně klienta se dají snadno obejít škodlivými uživateli. Na serveru vždy proveďte také kontroly zabezpečení na straně klienta.
• Nepřijmete soubory od uživatelů nebo jiných nedůvěryhodných zdrojů a pak soubory zpřístupníte k okamžitému stažení, aniž byste u souborů provedli kontroly zabezpečení. Další informace najdete v tématu Nahrání souborů v ASP.NET Core.

Stažení ze streamu

Tato část se týká souborů, které mají obvykle velikost až 250 MB.

Doporučeným přístupem ke stažení relativně malých souborů (<250 MB) je streamování obsahu souboru do nezpracované binární vyrovnávací paměti dat v klientovi pomocí interoperability JavaScriptu (JS).

Upozorňující

Přístup v této části přečte obsah souboru do JS ArrayBuffersouboru . Tento přístup načte celý soubor do paměti klienta, což může ovlivnit výkon. Pokud chcete stáhnout relativně velké soubory (>= 250 MB), doporučujeme postupovat podle pokynů v části Stažení z adresy URL .

downloadFileFromStreamJS Následující funkce:

• Načte zadaný datový proud do objektu ArrayBuffer.
• Blob Vytvoří pro zabalení objektu ArrayBuffer.
• Vytvoří adresu URL objektu, která bude sloužit jako adresa pro stažení souboru.
• Vytvoří ( HTMLAnchorElement<a> element).
• Přiřadí název souboru () a adresu URL (fileNameurl) ke stažení.
• Aktivuje stahování spuštěním click události na elementu ukotvení.
• Odebere prvek ukotvení.
• Odvolá adresu URLurl objektu voláním URL.revokeObjectURL. Jedná se o důležitý krok k zajištění nevracení paměti v klientovi.

<script>
  window.downloadFileFromStream = async (fileName, contentStreamReference) => {
    const arrayBuffer = await contentStreamReference.arrayBuffer();
    const blob = new Blob([arrayBuffer]);
    const url = URL.createObjectURL(blob);
    const anchorElement = document.createElement('a');
    anchorElement.href = url;
    anchorElement.download = fileName ?? '';
    anchorElement.click();
    anchorElement.remove();
    URL.revokeObjectURL(url);
  }
</script>

Poznámka:

Obecné pokyny k JS umístění a doporučení pro produkční aplikace najdete v tématu o umístění JavaScriptu v aplikacích ASP.NET CoreBlazor.

Následující komponenta:

• Používá nativní interoperabilitu bajtů streamování k zajištění efektivního přenosu souboru do klienta.
• Má metodu pojmenovanou GetFileStreamStream k načtení souboru, který se stáhne do klientů. Mezi alternativní přístupy patří načtení souboru z úložiště nebo dynamické generování souboru v kódu jazyka C#. Pro tuto ukázku aplikace vytvoří soubor 50 kB náhodných dat z nového bajtového pole (new byte[]). Bajty jsou zabalené jako MemoryStream dynamicky vygenerovaný binární soubor příkladu.
• Metoda DownloadFileFromStream :
  • Načte Stream z GetFileStream.
  • Určuje název souboru, když je soubor uložen na počítači uživatele. Následující příklad pojmenuje soubor quote.txt.
  • Zabalí soubor do objektu StreamDotNetStreamReference, který umožňuje streamování dat souboru do klienta.
  • downloadFileFromStreamJS Vyvolá funkci pro přijetí dat v klientovi.

FileDownload1.razor:

@page "/file-download-1"
@using System.IO
@inject IJSRuntime JS

<PageTitle>File Download 1</PageTitle>

<h1>File Download Example 1</h1>

<button @onclick="DownloadFileFromStream">
    Download File From Stream
</button>

@code {
    private Stream GetFileStream()
    {
        var randomBinaryData = new byte[50 * 1024];
        var fileStream = new MemoryStream(randomBinaryData);

        return fileStream;
    }

    private async Task DownloadFileFromStream()
    {
        var fileStream = GetFileStream();
        var fileName = "log.bin";

        using var streamRef = new DotNetStreamReference(stream: fileStream);

        await JS.InvokeVoidAsync("downloadFileFromStream", fileName, streamRef);
    }
}

Pro komponentu v aplikaci na straně serveru, která musí vrátit Stream pro fyzický soubor, může komponenta volat File.OpenRead, jak ukazuje následující příklad:

private Stream GetFileStream()
{
    return File.OpenRead(@"{PATH}");
}

V předchozím příkladu {PATH} je zástupný symbol cestou k souboru. Předpona @ označuje, že řetězec je doslovný řetězcový literál, který umožňuje použití zpětných lomítek (\) v cestě operačního systému Windows a vložené dvojité uvozovky ("") pro jednu uvozovku v cestě. Případně se vyhněte řetězcovém literálu (@) a použijte některý z následujících přístupů:

• Použijte uvozovky (\\) a uvozovky (\").
• Použijte lomítka (/) v cestě, které jsou podporovány napříč platformami v aplikacích ASP.NET Core a uvozovky (\").

Stažení z adresy URL

Tato část se týká souborů, které jsou relativně velké, obvykle 250 MB nebo větší.

Příklad v této části používá soubor ke stažení s názvem quote.txt, který se umístí do složky pojmenované files ve webovém kořenovém adresáři aplikace (wwwroot složce). Použití files složky je pouze pro demonstrační účely. Soubory ke stažení můžete uspořádat v libovolném rozložení složek v kořenovém adresáři webu (wwwroot složce), které chcete, včetně poskytování souborů přímo ze wwwroot složky.

wwwroot/files/quote.txt:

When victory is ours, we'll wipe every trace of the Thals and their city from the face of this land. We will avenge the deaths of all Kaleds who've fallen in the cause of right and justice and build a peace which will be a monument to their sacrifice. Our battle cry will be "Total extermination of the Thals!"

- General Ravon (Guy Siner, http://guysiner.com/)
  Dr. Who: Genesis of the Daleks (https://www.bbc.co.uk/programmes/p00pq2gc)
  ©1975 BBC (https://www.bbc.co.uk/)

triggerFileDownloadJS Následující funkce:

• Vytvoří ( HTMLAnchorElement<a> element).
• Přiřadí název souboru () a adresu URL (fileNameurl) ke stažení.
• Aktivuje stahování spuštěním click události na elementu ukotvení.
• Odebere prvek ukotvení.

<script>
  window.triggerFileDownload = (fileName, url) => {
    const anchorElement = document.createElement('a');
    anchorElement.href = url;
    anchorElement.download = fileName ?? '';
    anchorElement.click();
    anchorElement.remove();
  }
</script>

Poznámka:

Obecné pokyny k JS umístění a doporučení pro produkční aplikace najdete v tématu o umístění JavaScriptu v aplikacích ASP.NET CoreBlazor.

Následující ukázková komponenta stáhne soubor ze stejného původu, který aplikace používá. Pokud se o stažení souboru pokusíte z jiného zdroje, nakonfigurujte sdílení prostředků mezi zdroji (CORS). Další informace najdete v části Sdílení prostředků mezi zdroji (CORS).

Změňte port v následujícím příkladu tak, aby odpovídal vývojovému portu localhost vašeho prostředí.

FileDownload2.razor:

@page "/file-download-2"
@inject IJSRuntime JS

<PageTitle>File Download 2</PageTitle>

<h1>File Download Example 2</h1>

<button @onclick="DownloadFileFromURL">
    Download File From URL
</button>

@code {
    private async Task DownloadFileFromURL()
    {
        var fileName = "quote.txt";
        var fileURL = "/files/quote.txt";
        await JS.InvokeVoidAsync("triggerFileDownload", fileName, fileURL);
    }
}

Cross-Origin Resource Sharing (CORS)

Bez dalších kroků povolení sdílení prostředků mezi zdroji (CORS) pro soubory, které nemají stejný zdroj jako aplikace, stahování souborů neprojde kontrolami CORS provedenými prohlížečem.

Další informace o CORS s aplikacemi ASP.NET Core a dalšími produkty a službami Microsoftu, které hostují soubory ke stažení, najdete v následujících zdrojích informací:

• Povolení žádostí mezi zdroji (CORS) v ASP.NET Core
• Použití Azure CDN s CORS (dokumentace k Azure)
• Podpora sdílení prostředků mezi zdroji (CORS) pro Azure Storage (REST dokumentace)
• Základní cloudové služby – Nastavení CORS pro prostředky webu a úložiště (modul Learn)
• Referenční informace ke konfiguraci modulu CORS služby IIS (dokumentace ke službě IIS)

Další materiály

• Blazor ASP.NET základní interoperabilita JavaScriptu (JSinteroperabilita)
• <a>: Element Anchor: Zabezpečení a ochrana osobních údajů (dokumentace k MDN)
• nahrávání souborů ASP.NET Core Blazor
• Blazor Přehled základních formulářů ASP.NET
• Blazorukázky úložiště GitHub () (dotnet/blazor-samplespostup stažení)