ASP.NET Core Blazor 檔案上傳

本文說明如何在 Blazor 中使用 InputFile 元件上傳檔案。

檔案上傳

警告

允許使用者上傳檔案時一律遵循安全性最佳做法。 如需詳細資訊，請參閱在 ASP.NET Core 中上傳檔案。

使用 InputFile 元件將瀏覽器檔案資料讀入 .NET 程式碼。 InputFile 元件會在上傳單個檔案時轉譯型別為 file 的 HTML <input> 元素。 新增 multiple 屬性以允許使用者一次上傳多個檔案。

使用 InputFile 元件或其基礎 HTML <input type="file"> 時，檔案選取項目不會累積，因此您無法將檔案新增至現有的檔案選取項目。 元件一律會取代使用者的初始檔案選取項目，因此來自先前選取項目的檔案參考會無法使用。

下列 InputFile 元件會在發生 OnChange (change) 事件時執行 LoadFiles 方法。 InputFileChangeEventArgs 可讓您存取選取的檔案清單，以及關於每個檔案的詳細資料：

<InputFile OnChange="LoadFiles" multiple />

@code {
    private void LoadFiles(InputFileChangeEventArgs e)
    {
        ...
    }
}

轉譯的 HTML：

<input multiple="" type="file" _bl_2="">

注意

在上述範例中，<input> 元素的 _bl_2 屬性會用於 Blazor 的內部處理。

若要從使用者選取的檔案讀取資料，請在檔案上呼叫 IBrowserFile.OpenReadStream，並從傳回的串流讀取。 如需詳細資訊，請參閱檔案串流一節。

OpenReadStream 會強制其 Stream 大小上限 (以位元組為單位)。 讀取一個或多個大於 500 KB 的檔案會導致例外狀況。 此限制可防止開發人員不慎將大型檔案讀入記憶體。 OpenReadStream 的 maxAllowedSize 參數可用來指定較大的大小 (如必要)。

如果您需要存取代表檔案位元組的 Stream，請使用 IBrowserFile.OpenReadStream。 避免一次直接將傳入檔案串流讀取到記憶體中。 例如，請勿將所有檔案的位元組複製到 MemoryStream，或一次全部讀取整個串流到位元組陣列中。 這些方法可能會導致應用程式效能降低，以及潛在的阻斷服務 (DoS) 風險，尤其是伺服器端元件。 相反地，請考慮採用下列其中一種方法：

• 將串流直接複製到磁碟上的檔案，而不將它讀取到記憶體中。 請注意，在伺服器上執行程式碼的 Blazor 應用程式無法直接存取用戶端的檔案系統。
• 將檔案從用戶端直接上傳至外部服務。 如需詳細資訊，請參閱將檔案上傳至外部服務一節。

在下列範例中，browserFile 表示上傳的檔案並實作 IBrowserFile。 本文稍後的檔案上傳元件會說明 IBrowserFile 的工作實作。

✔️支援：建議下列方法，因為檔案的 Stream 會直接提供給取用者，即會在提供的路徑上建立檔案的 FileStream：

await using FileStream fs = new(path, FileMode.Create);
await browserFile.OpenReadStream().CopyToAsync(fs);

✔️支援：針對 Microsoft Azure Blob 儲存體，建議下列方法，因為檔案的 Stream 會直接提供給 UploadBlobAsync：

await blobContainerClient.UploadBlobAsync(
    trustedFileName, browserFile.OpenReadStream());

❌不建議使用：下列方法不建議使用，因為檔案的 Stream 內容會讀入記憶體 (reader) 中的 String ：

var reader = 
    await new StreamReader(browserFile.OpenReadStream()).ReadToEndAsync();

❌不建議使用：對於 Microsoft Azure Blob 儲存體，下列方法不建議使用，因為檔案的 Stream 內容會在呼叫 UploadBlobAsync 之前，複製到記憶體 (memoryStream) 中的 MemoryStream：

var memoryStream = new MemoryStream();
await browserFile.OpenReadStream().CopyToAsync(memoryStream);
await blobContainerClient.UploadBlobAsync(
    trustedFileName, memoryStream));

接收影像檔案的元件可以呼叫檔案上的 BrowserFileExtensions.RequestImageFileAsync 便利方法，在將影像串流至應用程式之前，在瀏覽器的 JavaScript 執行階段內調整影像資料的大小。 呼叫 RequestImageFileAsync 的使用案例最適合 Blazor WebAssembly 應用程式。

檔案大小讀取和上傳限制

伺服器端或用戶端，InputFile 元件沒有特別的檔案讀取或上傳大小限制。 不過，用戶端 Blazor 會在將資料從 JavaScript 封送處理到 C# 時，將檔案的位元組讀入單一 JavaScript 陣列緩衝區，其限制為 2 GB 或裝置的可用記憶體。 使用 InputFile 元件進行用戶端上傳時，大型檔案上傳 (> 250 MB) 可能會失敗。 如需詳細資訊，請參閱下列討論：

• 上傳檔案時，Blazor InputFile 元件應該處理區塊處理 (dotnet/runtime #84685)
• 透過 HTTP 處理常式要求串流上傳 (dotnet/runtime #36634)

對於在嘗試使用 InputFile 元件時失敗的大型用戶端檔案上傳，我們建議使用多個 HTTP 範圍要求而不是使用 InputFile 元件，使用自訂元件將大型檔案區塊化。

工作目前是針對 .NET 9 (2024 年底) 排程，以解決用戶端檔案大小上傳限制。

範例

下列範例示範元件中的多個檔案上傳。 InputFileChangeEventArgs.GetMultipleFiles 會允許讀取多個檔案。 指定檔案數目上限，以防止惡意使用者上傳比應用程式預期更多的檔案。 如果檔案上傳不支援多個檔案，InputFileChangeEventArgs.File 會允許讀取第一個且唯一的一個檔案。

InputFileChangeEventArgs 位於 Microsoft.AspNetCore.Components.Forms 命名空間中，其通常是應用程式 _Imports.razor 檔案中的其中一個命名空間。 當命名空間存在於 _Imports.razor 檔案中，它會提供應用程式元件的 API 成員存取權。

_Imports.razor 檔案中的命名空間不會套用至 C# 檔案 (.cs)。 C# 檔案需要類別檔案頂端有明確的 using 指示詞：

using Microsoft.AspNetCore.Components.Forms;

若要測試檔案上傳元件，您可以使用 PowerShell 建立任何大小的測試檔案：

$out = new-object byte[] {SIZE}; (new-object Random).NextBytes($out); [IO.File]::WriteAllBytes('{PATH}', $out)

在上述命令中：

• {SIZE} 預留位置是檔案大小 (位元組為單位) (例如，2097152 表示 2 MB 檔案)。
• {PATH} 預留位置是路徑和檔案與副檔名 (例如，D:/test_files/testfile2MB.txt)。

伺服器端檔案上傳範例

若要使用下列程式碼，請在 Development 環境中執行的應用程式根目錄建立 Development/unsafe_uploads 資料夾。

由於範例使用應用程式的環境做為檔案儲存路徑的一部分，如果測試及生產環境使用其他環境，則需要其他資料夾。 例如，建立 Staging 環境的 Staging/unsafe_uploads 資料夾。 建立 Production 環境的 Production/unsafe_uploads 資料夾。

警告

範例會儲存檔案而不掃描其內容，本文中的指導不會考慮上傳檔案的其他安全性最佳做法。 在預備和生產系統上，停用上傳資料夾上的執行權限，並在上傳後立即使用防毒/反惡意程式碼掃描器 API 掃描檔案。 如需詳細資訊，請參閱在 ASP.NET Core 中上傳檔案。

FileUpload1.razor：

@page "/file-upload-1"
@using System 
@using System.IO
@using Microsoft.AspNetCore.Hosting
@inject ILogger<FileUpload1> Logger
@inject IWebHostEnvironment Environment

<PageTitle>File Upload 1</PageTitle>

<h1>File Upload Example 1</h1>

<p>
    <label>
        Max file size:
        <input type="number" @bind="maxFileSize" />
    </label>
</p>

<p>
    <label>
        Max allowed files:
        <input type="number" @bind="maxAllowedFiles" />
    </label>
</p>

<p>
    <label>
        Upload up to @maxAllowedFiles of up to @maxFileSize bytes:
        <InputFile OnChange="LoadFiles" multiple />
    </label>
</p>

@if (isLoading)
{
    <p>Uploading...</p>
}
else
{
    <ul>
        @foreach (var file in loadedFiles)
        {
            <li>
                <ul>
                    <li>Name: @file.Name</li>
                    <li>Last modified: @file.LastModified.ToString()</li>
                    <li>Size (bytes): @file.Size</li>
                    <li>Content type: @file.ContentType</li>
                </ul>
            </li>
        }
    </ul>
}

@code {
    private List<IBrowserFile> loadedFiles = new();
    private long maxFileSize = 1024 * 15;
    private int maxAllowedFiles = 3;
    private bool isLoading;

    private async Task LoadFiles(InputFileChangeEventArgs e)
    {
        isLoading = true;
        loadedFiles.Clear();

        foreach (var file in e.GetMultipleFiles(maxAllowedFiles))
        {
            try
            {
                var trustedFileName = Path.GetRandomFileName();
                var path = Path.Combine(Environment.ContentRootPath,
                    Environment.EnvironmentName, "unsafe_uploads",
                    trustedFileName);

                await using FileStream fs = new(path, FileMode.Create);
                await file.OpenReadStream(maxFileSize).CopyToAsync(fs);

                loadedFiles.Add(file);

                Logger.LogInformation(
                    "Unsafe Filename: {UnsafeFilename} File saved: {Filename}",
                    file.Name, trustedFileName);
            }
            catch (Exception ex)
            {
                Logger.LogError("File: {Filename} Error: {Error}", 
                    file.Name, ex.Message);
            }
        }

        isLoading = false;
    }
}

用戶端檔案上傳範例

下列範例會處理檔案位元組，且不會將檔案傳送至應用程式外部的目的地。 如需將檔案傳送至伺服器或服務的 Razor 元件範例，請參閱下列各節：

• 使用用戶端轉譯 (CSR) 將檔案上傳至伺服器
• 將檔案上傳至外部服務

此元件會假設互動式 WebAssembly 轉譯模式 (InteractiveWebAssembly) 繼承自父代元件，或全域套用至應用程式。

@page "/file-upload-1"
@inject ILogger<FileUpload1> Logger

<PageTitle>File Upload 1</PageTitle>

<h1>File Upload Example 1</h1>

<p>
    <label>
        Max file size:
        <input type="number" @bind="maxFileSize" />
    </label>
</p>

<p>
    <label>
        Max allowed files:
        <input type="number" @bind="maxAllowedFiles" />
    </label>
</p>

<p>
    <label>
        Upload up to @maxAllowedFiles of up to @maxFileSize bytes:
        <InputFile OnChange="LoadFiles" multiple />
    </label>
</p>

@if (isLoading)
{
    <p>Uploading...</p>
}
else
{
    <ul>
        @foreach (var file in loadedFiles)
        {
            <li>
                <ul>
                    <li>Name: @file.Name</li>
                    <li>Last modified: @file.LastModified.ToString()</li>
                    <li>Size (bytes): @file.Size</li>
                    <li>Content type: @file.ContentType</li>
                </ul>
            </li>
        }
    </ul>
}

@code {
    private List<IBrowserFile> loadedFiles = new();
    private long maxFileSize = 1024 * 15;
    private int maxAllowedFiles = 3;
    private bool isLoading;

    private void LoadFiles(InputFileChangeEventArgs e)
    {
        isLoading = true;
        loadedFiles.Clear();

        foreach (var file in e.GetMultipleFiles(maxAllowedFiles))
        {
            try
            {
                loadedFiles.Add(file);
            }
            catch (Exception ex)
            {
                Logger.LogError("File: {FileName} Error: {Error}", 
                    file.Name, ex.Message);
            }
        }

        isLoading = false;
    }
}

IBrowserFile 會傳回由瀏覽器公開為屬性的中繼資料。 使用此中繼資料進行初步驗證。

• Name
• Size
• LastModified
• ContentType

永遠不要信任上述屬性的值，尤其是用於在 UI 中顯示的 Name 屬性。將所有使用者提供的資料視為應用程式、伺服器和網路的重大安全性風險。 如需詳細資訊，請參閱在 ASP.NET Core 中上傳檔案。

使用伺服器端轉譯將檔案上傳至伺服器

本節適用 Blazor Web App 或 Blazor Server 應用程式中的互動式伺服器元件。

下列範例示範將檔案從伺服器端應用程式上傳至個別應用程式 (可能位於不同的伺服器上) 中的後端 Web API 控制器。

在伺服器端應用程式的 Program 檔案中，新增 IHttpClientFactory 和相關服務，以允許應用程式建立 HttpClient 執行個體：

builder.Services.AddHttpClient();

如需詳細資訊，請參閱在 ASP.NET Core 中使用 IHttpClientFactory 發出 HTTP 要求。

針對本節中的範例：

• Web API 會在 URL 上執行：https://localhost:5001
• 伺服器端應用程式會在 URL 上執行：https://localhost:5003

針對測試，上述 URL 會在專案的 Properties/launchSettings.json 檔案中設定。

下列 UploadResult 類別會維護已上傳檔案的結果。 當檔案無法在伺服器上上傳時，會在 ErrorCode 中傳回錯誤碼，以向使用者顯示。 在伺服器上針對每個檔案產生安全檔案名稱，並傳回給 StoredFileName 中的用戶端供顯示。 檔案在用戶端和伺服器之間會具有索引鍵，在 FileName 中使用不安全/不受信任的檔案名稱。

UploadResult.cs：

public class UploadResult
{
    public bool Uploaded { get; set; }
    public string? FileName { get; set; }
    public string? StoredFileName { get; set; }
    public int ErrorCode { get; set; }
}

生產應用程式的安全性最佳做法是避免將錯誤訊息傳送給可能會顯示應用程式、伺服器或網路相關敏感性資訊的用戶端。 提供詳細的錯誤訊息可協助惡意使用者設計對應用程式、伺服器或網路的攻擊。 本節中的範例程式碼只會在發生伺服器端錯誤時，傳回供元件用戶端顯示的錯誤碼編號 (int)。 如果使用者需要檔案上傳的協助，他們會提供錯誤碼給支援人員以進行支援票證解析，而不需要知道錯誤的確切原因。

下列 LazyBrowserFileStream 類別定義自訂資料流類型，此類型會在要求資料流的第一個位元組之前延遲呼叫 OpenReadStream。 在 .NET 中開始讀取資料流之前，不會將資料流從瀏覽器傳輸至伺服器。

LazyBrowserFileStream.cs：

using Microsoft.AspNetCore.Components.Forms;
using System.Diagnostics.CodeAnalysis;

namespace BlazorSample;

internal sealed class LazyBrowserFileStream(IBrowserFile file, int maxAllowedSize) 
    : Stream
{
    private readonly IBrowserFile file = file;
    private readonly int maxAllowedSize = maxAllowedSize;
    private Stream? underlyingStream;
    private bool isDisposed;

    public override bool CanRead => true;

    public override bool CanSeek => false;

    public override bool CanWrite => false;

    public override long Length => file.Size;

    public override long Position
    {
        get => underlyingStream?.Position ?? 0;
        set => throw new NotSupportedException();
    }

    public override void Flush() => underlyingStream?.Flush();

    public override Task<int> ReadAsync(byte[] buffer, int offset, int count, 
        CancellationToken cancellationToken)
    {
        EnsureStreamIsOpen();

        return underlyingStream.ReadAsync(buffer, offset, count, cancellationToken);
    }

    public override ValueTask<int> ReadAsync(Memory<byte> buffer, 
        CancellationToken cancellationToken = default)
    {
        EnsureStreamIsOpen();
        return underlyingStream.ReadAsync(buffer, cancellationToken);
    }

    [MemberNotNull(nameof(underlyingStream))]
    private void EnsureStreamIsOpen() => 
        underlyingStream ??= file.OpenReadStream(maxAllowedSize);

    protected override void Dispose(bool disposing)
    {
        if (isDisposed)
        {
            return;
        }

        underlyingStream?.Dispose();
        isDisposed = true;

        base.Dispose(disposing);
    }

    public override int Read(byte[] buffer, int offset, int count)
        => throw new NotSupportedException();

    public override long Seek(long offset, SeekOrigin origin)
        => throw new NotSupportedException();

    public override void SetLength(long value)
        => throw new NotSupportedException();

    public override void Write(byte[] buffer, int offset, int count)
        => throw new NotSupportedException();
}

下列 FileUpload2 元件：

• 允許使用者從用戶端上傳檔案。
• 在 UI 中顯示用戶端所提供的未受信任/不安全檔案名稱。 未受信任/不安全檔案名稱會自動由 Razor 以 HTML 編碼，以在 UI 中安全地顯示。

警告

不要信任用戶端提供的檔案名稱，因以下原因：

• 將檔案儲存至檔案系統或服務。
• 在不會自動編碼檔案名稱或透過開發人員程式碼的 UI 中顯示。

如需將檔案上傳至伺服器時的安全性考慮詳細資訊，請參閱在 ASP.NET Core 中上傳檔案。

FileUpload2.razor：

@page "/file-upload-2"
@using System.Net.Http.Headers
@using System.Text.Json
@inject IHttpClientFactory ClientFactory
@inject ILogger<FileUpload2> Logger

<PageTitle>File Upload 2</PageTitle>

<h1>File Upload Example 2</h1>

<p>
    This example requires a backend server API to function. For more information, 
    see the <em>Upload files to a server</em> section 
    of the <em>ASP.NET Core Blazor file uploads</em> article.
</p>

<p>
    <label>
        Upload up to @maxAllowedFiles files:
        <InputFile OnChange="OnInputFileChange" multiple />
    </label>
</p>

@if (files.Any())
{
    <div class="card">
        <div class="card-body">
            <ul>
                @foreach (var file in files)
                {
                    <li>
                        File: @file.Name
                        <br>
                        @if (FileUpload(uploadResults, file.Name, Logger,
                           out var result))
                        {
                            <span>
                                Stored File Name: @result.StoredFileName
                            </span>
                        }
                        else
                        {
                            <span>
                                There was an error uploading the file
                                (Error: @result.ErrorCode).
                            </span>
                        }
                    </li>
                }
            </ul>
        </div>
    </div>
}

@code {
    private List<File> files = new();
    private List<UploadResult> uploadResults = new();
    private int maxAllowedFiles = 3;
    private bool shouldRender;

    protected override bool ShouldRender() => shouldRender;

    private async Task OnInputFileChange(InputFileChangeEventArgs e)
    {
        shouldRender = false;
        int maxFileSize = 1024 * 15;
        var upload = false;

        using var content = new MultipartFormDataContent();

        foreach (var file in e.GetMultipleFiles(maxAllowedFiles))
        {
            if (uploadResults.SingleOrDefault(
                f => f.FileName == file.Name) is null)
            {
                try
                {
                    files.Add(new() { Name = file.Name });

                    var stream = new LazyBrowserFileStream(file, maxFileSize);
                    var fileContent = new StreamContent(stream);

                    fileContent.Headers.ContentType = 
                        new MediaTypeHeaderValue(file.ContentType);

                    content.Add(
                        content: fileContent,
                        name: "\"files\"",
                        fileName: file.Name);

                    upload = true;
                }
                catch (Exception ex)
                {
                    Logger.LogInformation(
                        "{FileName} not uploaded (Err: 6): {Message}", 
                        file.Name, ex.Message);

                    uploadResults.Add(
                        new()
                        {
                            FileName = file.Name, 
                            ErrorCode = 6, 
                            Uploaded = false
                        });
                }
            }
        }

        if (upload)
        {
            var client = ClientFactory.CreateClient();

            var response = 
                await client.PostAsync("https://localhost:5001/Filesave", 
                content);

            if (response.IsSuccessStatusCode)
            {
                var options = new JsonSerializerOptions
                {
                    PropertyNameCaseInsensitive = true,
                };

                using var responseStream =
                    await response.Content.ReadAsStreamAsync();

                var newUploadResults = await JsonSerializer
                    .DeserializeAsync<IList<UploadResult>>(responseStream, options);

                if (newUploadResults is not null)
                {
                    uploadResults = uploadResults.Concat(newUploadResults).ToList();
                }
            }
        }

        shouldRender = true;
    }

    private static bool FileUpload(IList<UploadResult> uploadResults,
        string? fileName, ILogger<FileUpload2> logger, out UploadResult result)
    {
        result = uploadResults.SingleOrDefault(f => f.FileName == fileName) ?? new();

        if (!result.Uploaded)
        {
            logger.LogInformation("{FileName} not uploaded (Err: 5)", fileName);
            result.ErrorCode = 5;
        }

        return result.Uploaded;
    }

    private class File
    {
        public string? Name { get; set; }
    }
}

如果元件限制檔案一次只能上傳至單一檔案，或元件只採用互動式用戶端轉譯 (CSR， InteractiveWebAssembly)，則元件可以避免使用 LazyBrowserFileStream 並使用 Stream。 下列示範 FileUpload2 元件的變更：

- var stream = new LazyBrowserFileStream(file, maxFileSize);
- var fileContent = new StreamContent(stream);
+ var fileContent = new StreamContent(file.OpenReadStream(maxFileSize));

移除未使用的 LazyBrowserFileStream 類別 (LazyBrowserFileStream.cs)。

Web API 專案中的下列控制器會儲存從用戶端上傳的檔案。

重要

本節中的控制器是要用於與 Blazor 應用程式不同的 Web API 專案。 如果已驗證檔案上傳使用者，Web API 應降低跨網站偽造要求 (XSRF/CSRF) 攻擊的風險。

若要使用下列程式碼，請在 Development 環境中執行的應用程式的 Web API 專案根目錄建立 Development/unsafe_uploads 資料夾。

由於範例使用應用程式的環境做為檔案儲存路徑的一部分，如果測試及生產環境使用其他環境，則需要其他資料夾。 例如，建立 Staging 環境的 Staging/unsafe_uploads 資料夾。 建立 Production 環境的 Production/unsafe_uploads 資料夾。

警告

範例會儲存檔案而不掃描其內容，本文中的指導不會考慮上傳檔案的其他安全性最佳做法。 在預備和生產系統上，停用上傳資料夾上的執行權限，並在上傳後立即使用防毒/反惡意程式碼掃描器 API 掃描檔案。 如需詳細資訊，請參閱在 ASP.NET Core 中上傳檔案。

Controllers/FilesaveController.cs：

using System.Net;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("[controller]")]
public class FilesaveController(
    IHostEnvironment env, ILogger<FilesaveController> logger) 
    : ControllerBase
{
    [HttpPost]
    public async Task<ActionResult<IList<UploadResult>>> PostFile(
        [FromForm] IEnumerable<IFormFile> files)
    {
        var maxAllowedFiles = 3;
        long maxFileSize = 1024 * 15;
        var filesProcessed = 0;
        var resourcePath = new Uri($"{Request.Scheme}://{Request.Host}/");
        List<UploadResult> uploadResults = [];

        foreach (var file in files)
        {
            var uploadResult = new UploadResult();
            string trustedFileNameForFileStorage;
            var untrustedFileName = file.FileName;
            uploadResult.FileName = untrustedFileName;
            var trustedFileNameForDisplay =
                WebUtility.HtmlEncode(untrustedFileName);

            if (filesProcessed < maxAllowedFiles)
            {
                if (file.Length == 0)
                {
                    logger.LogInformation("{FileName} length is 0 (Err: 1)",
                        trustedFileNameForDisplay);
                    uploadResult.ErrorCode = 1;
                }
                else if (file.Length > maxFileSize)
                {
                    logger.LogInformation("{FileName} of {Length} bytes is " +
                        "larger than the limit of {Limit} bytes (Err: 2)",
                        trustedFileNameForDisplay, file.Length, maxFileSize);
                    uploadResult.ErrorCode = 2;
                }
                else
                {
                    try
                    {
                        trustedFileNameForFileStorage = Path.GetRandomFileName();
                        var path = Path.Combine(env.ContentRootPath,
                            env.EnvironmentName, "unsafe_uploads",
                            trustedFileNameForFileStorage);

                        await using FileStream fs = new(path, FileMode.Create);
                        await file.CopyToAsync(fs);

                        logger.LogInformation("{FileName} saved at {Path}",
                            trustedFileNameForDisplay, path);
                        uploadResult.Uploaded = true;
                        uploadResult.StoredFileName = trustedFileNameForFileStorage;
                    }
                    catch (IOException ex)
                    {
                        logger.LogError("{FileName} error on upload (Err: 3): {Message}",
                            trustedFileNameForDisplay, ex.Message);
                        uploadResult.ErrorCode = 3;
                    }
                }

                filesProcessed++;
            }
            else
            {
                logger.LogInformation("{FileName} not uploaded because the " +
                    "request exceeded the allowed {Count} of files (Err: 4)",
                    trustedFileNameForDisplay, maxAllowedFiles);
                uploadResult.ErrorCode = 4;
            }

            uploadResults.Add(uploadResult);
        }

        return new CreatedResult(resourcePath, uploadResults);
    }
}

在上述程式碼中，呼叫 GetRandomFileName 以產生安全檔案名稱。 永遠不要信任瀏覽器提供的檔案名稱，因為網路攻擊者可能會選擇會覆寫現有檔案的現有檔案名稱，或傳送嘗試在應用程式外部寫入的路徑。

伺服器應用程式必須註冊控制器服務和對應控制器端點。 如需詳細資訊，請參閱在 ASP.NET Core 中路由至控制器動作。

使用用戶端轉譯 (CSR) 將檔案上傳至伺服器

本節適用於 Blazor Web App 或 Blazor WebAssembly 應用程式中的用戶端轉譯 (CSR) 元件。

下列範例示範從採用 CSR 的 Blazor Web App 或從 Blazor WebAssembly 應用程式中的元件，將檔案上傳至個別應用程式 (可能位於不同的伺服器上) 中的後端 Web API 控制器。

下列 UploadResult 類別會維護已上傳檔案的結果。 當檔案無法在伺服器上上傳時，會在 ErrorCode 中傳回錯誤碼，以向使用者顯示。 在伺服器上針對每個檔案產生安全檔案名稱，並傳回給 StoredFileName 中的用戶端供顯示。 檔案在用戶端和伺服器之間會具有索引鍵，在 FileName 中使用不安全/不受信任的檔案名稱。

UploadResult.cs：

public class UploadResult
{
    public bool Uploaded { get; set; }
    public string? FileName { get; set; }
    public string? StoredFileName { get; set; }
    public int ErrorCode { get; set; }
}

注意

上述 UploadResult 類別可以在用戶端和伺服器型專案之間共用。 當用戶端和伺服器專案共用類別時，針對共用專案的每個專案的 _Imports.razor 檔案新增匯入。 例如：

@using BlazorSample.Shared

下列 FileUpload2 元件：

• 允許使用者從用戶端上傳檔案。
• 在 UI 中顯示用戶端所提供的未受信任/不安全檔案名稱。 未受信任/不安全檔案名稱會自動由 Razor 以 HTML 編碼，以在 UI 中安全地顯示。

生產應用程式的安全性最佳做法是避免將錯誤訊息傳送給可能會顯示應用程式、伺服器或網路相關敏感性資訊的用戶端。 提供詳細的錯誤訊息可協助惡意使用者設計對應用程式、伺服器或網路的攻擊。 本節中的範例程式碼只會在發生伺服器端錯誤時，傳回供元件用戶端顯示的錯誤碼編號 (int)。 如果使用者需要檔案上傳的協助，他們會提供錯誤碼給支援人員以進行支援票證解析，而不需要知道錯誤的確切原因。

警告

不要信任用戶端提供的檔案名稱，因以下原因：

• 將檔案儲存至檔案系統或服務。
• 在不會自動編碼檔案名稱或透過開發人員程式碼的 UI 中顯示。

如需將檔案上傳至伺服器時的安全性考慮詳細資訊，請參閱在 ASP.NET Core 中上傳檔案。

在 Blazor Web App 主要專案中，將 IHttpClientFactory 和相關服務新增在專案的 Program 中：

builder.Services.AddHttpClient();

必須將 HttpClient 服務新增至主要專案，因為伺服器上會預先呈現用戶端元件。 如果您停用下列元件的預先呈現，則不需要在主要應用程式中提供 HttpClient 服務，而且不需要將前一行新增至主要專案。

如需將 HttpClient 服務新增至 ASP.NET Core 應用程式的詳細資訊，請參閱在 ASP.NET Core 中使用 IHttpClientFactory 提出 HTTP 要求。

用戶端專案 (.Client) (在 Blazor Web App) 也必須向後端 Web API 控制器註冊 HTTP POST 要求的 HttpClient。 確認下列內容或將其新增至用戶端專案的 Program 檔案：

builder.Services.AddScoped(sp => 
    new HttpClient { BaseAddress = new Uri(builder.HostEnvironment.BaseAddress) });

上述範例會使用 builder.HostEnvironment.BaseAddress (IWebAssemblyHostEnvironment.BaseAddress) 設定基底位址 (Base Address)，其會取得應用程式的基底位址 (Base Address)，而且通常衍生自主頁面中 <base> href 標籤的值。 如果您要呼叫外部 Web API，請將 URI 設定為 Web API 的基底位址 (Base Address)。

在 Blazor Web App Web 應用程式中指定下列元件頂端的互動式 WebAssembly 轉譯模式屬性：

@rendermode InteractiveWebAssembly

FileUpload2.razor：

@page "/file-upload-2"
@using System.Linq
@using System.Net.Http.Headers
@inject HttpClient Http
@inject ILogger<FileUpload2> Logger

<PageTitle>File Upload 2</PageTitle>

<h1>File Upload Example 2</h1>

<p>
    <label>
        Upload up to @maxAllowedFiles files:
        <InputFile OnChange="OnInputFileChange" multiple />
    </label>
</p>

@if (files.Count > 0)
{
    <div class="card">
        <div class="card-body">
            <ul>
                @foreach (var file in files)
                {
                    <li>
                        File: @file.Name
                        <br>
                        @if (FileUpload(uploadResults, file.Name, Logger,
                           out var result))
                        {
                            <span>
                                Stored File Name: @result.StoredFileName
                            </span>
                        }
                        else
                        {
                            <span>
                                There was an error uploading the file
                                (Error: @result.ErrorCode).
                            </span>
                        }
                    </li>
                }
            </ul>
        </div>
    </div>
}

@code {
    private List<File> files = new();
    private List<UploadResult> uploadResults = new();
    private int maxAllowedFiles = 3;
    private bool shouldRender;

    protected override bool ShouldRender() => shouldRender;

    private async Task OnInputFileChange(InputFileChangeEventArgs e)
    {
        shouldRender = false;
        long maxFileSize = 1024 * 15;
        var upload = false;

        using var content = new MultipartFormDataContent();

        foreach (var file in e.GetMultipleFiles(maxAllowedFiles))
        {
            if (uploadResults.SingleOrDefault(
                f => f.FileName == file.Name) is null)
            {
                try
                {
                    files.Add(new() { Name = file.Name });

                    var fileContent = new StreamContent(file.OpenReadStream(maxFileSize));

                    fileContent.Headers.ContentType = 
                        new MediaTypeHeaderValue(file.ContentType);

                    content.Add(
                        content: fileContent,
                        name: "\"files\"",
                        fileName: file.Name);

                    upload = true;
                }
                catch (Exception ex)
                {
                    Logger.LogInformation(
                        "{FileName} not uploaded (Err: 6): {Message}", 
                        file.Name, ex.Message);

                    uploadResults.Add(
                        new()
                        {
                            FileName = file.Name, 
                            ErrorCode = 6, 
                            Uploaded = false
                        });
                }
            }
        }

        if (upload)
        {
            var response = await Http.PostAsync("/Filesave", content);

            var newUploadResults = await response.Content
                .ReadFromJsonAsync<IList<UploadResult>>();

            if (newUploadResults is not null)
            {
                uploadResults = uploadResults.Concat(newUploadResults).ToList();
            }
        }

        shouldRender = true;
    }

    private static bool FileUpload(IList<UploadResult> uploadResults,
        string? fileName, ILogger<FileUpload2> logger, out UploadResult result)
    {
        result = uploadResults.SingleOrDefault(f => f.FileName == fileName) ?? new();

        if (!result.Uploaded)
        {
            logger.LogInformation("{FileName} not uploaded (Err: 5)", fileName);
            result.ErrorCode = 5;
        }

        return result.Uploaded;
    }

    private class File
    {
        public string? Name { get; set; }
    }
}

伺服器端專案中的下列控制器會儲存從用戶端上傳的檔案。

若要使用下列程式碼，請在 Development 環境中執行的應用程式的伺服器端專案根目錄建立 Development/unsafe_uploads 資料夾。

由於範例使用應用程式的環境做為檔案儲存路徑的一部分，如果測試及生產環境使用其他環境，則需要其他資料夾。 例如，建立 Staging 環境的 Staging/unsafe_uploads 資料夾。 建立 Production 環境的 Production/unsafe_uploads 資料夾。

警告

範例會儲存檔案而不掃描其內容，本文中的指導不會考慮上傳檔案的其他安全性最佳做法。 在預備和生產系統上，停用上傳資料夾上的執行權限，並在上傳後立即使用防毒/反惡意程式碼掃描器 API 掃描檔案。 如需詳細資訊，請參閱在 ASP.NET Core 中上傳檔案。

在下列範例中，如果共用專案提供的是 UploadResult 類別，請更新共用專案的命名空間，以符合共用專案。

Controllers/FilesaveController.cs：

using System;
using System.Collections.Generic;
using System.IO;
using System.Net;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using BlazorSample.Shared;

[ApiController]
[Route("[controller]")]
public class FilesaveController(
    IHostEnvironment env, ILogger<FilesaveController> logger) 
    : ControllerBase
{
    [HttpPost]
    public async Task<ActionResult<IList<UploadResult>>> PostFile(
        [FromForm] IEnumerable<IFormFile> files)
    {
        var maxAllowedFiles = 3;
        long maxFileSize = 1024 * 15;
        var filesProcessed = 0;
        var resourcePath = new Uri($"{Request.Scheme}://{Request.Host}/");
        List<UploadResult> uploadResults = [];

        foreach (var file in files)
        {
            var uploadResult = new UploadResult();
            string trustedFileNameForFileStorage;
            var untrustedFileName = file.FileName;
            uploadResult.FileName = untrustedFileName;
            var trustedFileNameForDisplay =
                WebUtility.HtmlEncode(untrustedFileName);

            if (filesProcessed < maxAllowedFiles)
            {
                if (file.Length == 0)
                {
                    logger.LogInformation("{FileName} length is 0 (Err: 1)",
                        trustedFileNameForDisplay);
                    uploadResult.ErrorCode = 1;
                }
                else if (file.Length > maxFileSize)
                {
                    logger.LogInformation("{FileName} of {Length} bytes is " +
                        "larger than the limit of {Limit} bytes (Err: 2)",
                        trustedFileNameForDisplay, file.Length, maxFileSize);
                    uploadResult.ErrorCode = 2;
                }
                else
                {
                    try
                    {
                        trustedFileNameForFileStorage = Path.GetRandomFileName();
                        var path = Path.Combine(env.ContentRootPath,
                            env.EnvironmentName, "unsafe_uploads",
                            trustedFileNameForFileStorage);

                        await using FileStream fs = new(path, FileMode.Create);
                        await file.CopyToAsync(fs);

                        logger.LogInformation("{FileName} saved at {Path}",
                            trustedFileNameForDisplay, path);
                        uploadResult.Uploaded = true;
                        uploadResult.StoredFileName = trustedFileNameForFileStorage;
                    }
                    catch (IOException ex)
                    {
                        logger.LogError("{FileName} error on upload (Err: 3): {Message}",
                            trustedFileNameForDisplay, ex.Message);
                        uploadResult.ErrorCode = 3;
                    }
                }

                filesProcessed++;
            }
            else
            {
                logger.LogInformation("{FileName} not uploaded because the " +
                    "request exceeded the allowed {Count} of files (Err: 4)",
                    trustedFileNameForDisplay, maxAllowedFiles);
                uploadResult.ErrorCode = 4;
            }

            uploadResults.Add(uploadResult);
        }

        return new CreatedResult(resourcePath, uploadResults);
    }
}

在上述程式碼中，呼叫 GetRandomFileName 以產生安全檔案名稱。 永遠不要信任瀏覽器提供的檔案名稱，因為網路攻擊者可能會選擇會覆寫現有檔案的現有檔案名稱，或傳送嘗試在應用程式外部寫入的路徑。

伺服器應用程式必須註冊控制器服務和對應控制器端點。 如需詳細資訊，請參閱在 ASP.NET Core 中路由至控制器動作。

取消檔案上傳

當使用者在呼叫 IBrowserFile.OpenReadStream 或 StreamReader.ReadAsync 時，使用 CancellationToken 取消上傳，檔案上傳元件可以偵測到。

為 InputFile 元件建立 CancellationTokenSource。 在 OnInputFileChange 方法的開頭，檢查先前的上傳是否進行中。

如果檔案上傳進行中：

• 在前一個上傳中呼叫 Cancel。
• 為下一個上傳建立新的 CancellationTokenSource，並將 CancellationTokenSource.Token 傳遞至 OpenReadStream 或 ReadAsync。

上傳檔案伺服器端與進度

下列範例示範如何在伺服器端應用程式中上傳檔案，並將對使用者顯示上傳進度。

若要在測試應用程式中使用下列範例：

• 建立資料夾以針對 Development 環境儲存上傳的檔案：Development/unsafe_uploads。
• 設定檔案大小上限 (maxFileSize，在下列範例中為 15 KB)，以及允許的檔案數目上限 (maxAllowedFiles，在下列範例中為 3)。
• 如有需要，請將緩衝區設定為不同的值 (下列範例中為 10 KB)，以增加進度報告中的細微性。 由於效能和安全性考量，不建議使用大於 30 KB 的緩衝區。

警告

範例會儲存檔案而不掃描其內容，本文中的指導不會考慮上傳檔案的其他安全性最佳做法。 在預備和生產系統上，停用上傳資料夾上的執行權限，並在上傳後立即使用防毒/反惡意程式碼掃描器 API 掃描檔案。 如需詳細資訊，請參閱在 ASP.NET Core 中上傳檔案。

FileUpload3.razor：

@page "/file-upload-3"
@inject ILogger<FileUpload3> Logger
@inject IWebHostEnvironment Environment

<PageTitle>File Upload 3</PageTitle>

<h1>File Upload Example 3</h1>

<p>
    <label>
        Max file size:
        <input type="number" @bind="maxFileSize" />
    </label>
</p>

<p>
    <label>
        Max allowed files:
        <input type="number" @bind="maxAllowedFiles" />
    </label>
</p>

<p>
    <label>
        Upload up to @maxAllowedFiles of up to @maxFileSize bytes:
        <InputFile OnChange="LoadFiles" multiple />
    </label>
</p>

@if (isLoading)
{
    <p>Progress: @string.Format("{0:P0}", progressPercent)</p>
}
else
{
    <ul>
        @foreach (var file in loadedFiles)
        {
            <li>
                <ul>
                    <li>Name: @file.Name</li>
                    <li>Last modified: @file.LastModified.ToString()</li>
                    <li>Size (bytes): @file.Size</li>
                    <li>Content type: @file.ContentType</li>
                </ul>
            </li>
        }
    </ul>
}

@code {
    private List<IBrowserFile> loadedFiles = new();
    private long maxFileSize = 1024 * 15;
    private int maxAllowedFiles = 3;
    private bool isLoading;
    private decimal progressPercent;

    private async Task LoadFiles(InputFileChangeEventArgs e)
    {
        isLoading = true;
        loadedFiles.Clear();
        progressPercent = 0;

        foreach (var file in e.GetMultipleFiles(maxAllowedFiles))
        {
            try
            {
                var trustedFileName = Path.GetRandomFileName();
                var path = Path.Combine(Environment.ContentRootPath,
                    Environment.EnvironmentName, "unsafe_uploads", trustedFileName);

                await using FileStream writeStream = new(path, FileMode.Create);
                using var readStream = file.OpenReadStream(maxFileSize);
                var bytesRead = 0;
                var totalRead = 0;
                var buffer = new byte[1024 * 10];

                while ((bytesRead = await readStream.ReadAsync(buffer)) != 0)
                {
                    totalRead += bytesRead;
                    await writeStream.WriteAsync(buffer, 0, bytesRead);
                    progressPercent = Decimal.Divide(totalRead, file.Size);
                    StateHasChanged();
                }

                loadedFiles.Add(file);

                Logger.LogInformation(
                    "Unsafe Filename: {UnsafeFilename} File saved: {Filename}",
                    file.Name, trustedFileName);
            }
            catch (Exception ex)
            {
                Logger.LogError("File: {FileName} Error: {Error}", 
                    file.Name, ex.Message);
            }
        }

        isLoading = false;
    }
}

如需詳細資訊，請參閱下列 API 資源：

• FileStream：為檔案提供 Stream，同時支援同步與非同步讀取和寫入作業。
• FileStream.ReadAsync：上述 FileUpload3 元件會以 ReadAsync 非同步方式讀取串流。 Razor 元件不支援以 Read 同步方式讀取串流。

檔案串流

使用伺服器互動功能時，檔案資料會在讀取檔案時，透過 SignalR 連線串流至伺服器上的 .NET 程式碼。

對於 WebAssembly 轉譯的元件，檔案資料會直接串流至瀏覽器內的 .NET 程式碼。

上傳影像預覽

如需上傳影像的影像預覽，請從使用元件參考和 OnChange 處理常式新增 InputFile 元件開始：

<InputFile @ref="inputFile" OnChange="ShowPreview" />

新增具有元素參考的影像元素，其可做為影像預覽的預留位置：

<img @ref="previewImageElem" />

新增相關聯的參考：

@code {
    private InputFile? inputFile;
    private ElementReference previewImageElem;
}

在 JavaScript 中，新增使用 HTML input 和 img 元素呼叫的函式，其會執行下列動作：

• 擷取選取的檔案。
• 使用 createObjectURL 建立物件 URL。
• 設定事件接聽程式，以在使用 revokeObjectURL 載入影像之後撤銷物件 URL，因此記憶體不會外洩。
• 設定 img 元素的來源以顯示影像。

window.previewImage = (inputElem, imgElem) => {
  const url = URL.createObjectURL(inputElem.files[0]);
  imgElem.addEventListener('load', () => URL.revokeObjectURL(url), { once: true });
  imgElem.src = url;
}

最後，使用插入的 IJSRuntime 來新增呼叫 JavaScript 函式的 OnChange 處理常式：

@inject IJSRuntime JS

...

@code {
    ...

    private async Task ShowPreview() => await JS.InvokeVoidAsync(
        "previewImage", inputFile!.Element, previewImageElem);
}

上述範例是用於上傳單一影像。 可以擴充方法以支援 multiple 影像。

下列 FileUpload4 元件顯示完整的範例。

FileUpload4.razor：

@page "/file-upload-4"
@inject IJSRuntime JS

<h1>File Upload Example</h1>

<InputFile @ref="inputFile" OnChange="ShowPreview" />

<img style="max-width:200px;max-height:200px" @ref="previewImageElem" />

@code {
    private InputFile? inputFile;
    private ElementReference previewImageElem;

    private async Task ShowPreview() => await JS.InvokeVoidAsync(
        "previewImage", inputFile!.Element, previewImageElem);
}

將檔案上傳至外部服務

不要由應用程式處理檔案上傳位元組，且由應用程式伺服器接收上傳檔案，用戶端可以直接將檔案上傳至外部服務。 應用程式可以隨需安全地處理來自外部服務的檔案。 此方法會強化應用程式及其伺服器，以防止惡意攻擊和潛在的效能問題。

考慮使用 Azure 檔案儲存體、Azure Blob 儲存體或具有下列潛在優點的第三方服務方法：

• 使用 JavaScript 用戶端程式庫或 REST API，將檔案直接從用戶端上傳至外部服務。 例如，Azure 提供下列用戶端程式庫和 API：
  • Azure 儲存體檔案共用用戶端程式庫
  • Azure 檔案儲存體 REST API
  • 適用於 JavaScript 的 Azure 儲存體 Blob 用戶端程式庫
  • Blob 服務 REST API
• 使用應用程式 (伺服器端) 針對每個用戶端檔案上傳所產生的使用者委派共用存取簽章 (SAS) 權杖，來授權使用者上傳。 例如，Azure 提供下列 SAS 功能：
  • 適用於 JavaScript 的 Azure 儲存體檔案共用用戶端程式庫：使用 SAS 權杖
  • 適用於 JavaScript 的 Azure 儲存體 Blob 用戶端程式庫：使用 SAS 權杖
• 提供自動備援和檔案共用備份。
• 使用配額限制上傳。 請注意，Azure Blob 儲存體的配額是在帳戶層級設定，而不是容器層級。 不過，Azure 檔案儲存體配額會處於檔案共用層級，而且可能會對上傳限制提供更好的控制。 如需詳細資訊，請參閱此清單中稍早連結的 Azure 文件。
• 使用伺服器端加密保護檔案 (SSE)。

如需 Azure Blob 儲存體和 Azure 檔案儲存體的詳細資訊，請參閱 Azure 儲存體文件。

伺服器端 SignalR 訊息大小限制

當 Blazor 擷取的檔案相關資料超過訊息大小上限 SignalR 時，檔案上傳可能失敗 (甚至在開始之前)。

SignalR 會定義套用至 Blazor 接收的每個訊息的訊息大小限制，而 InputFile 元件會將檔案串流至符合所設定限制的訊息中的伺服器。 不過，指出要上傳的檔案集的第一則訊息，會以唯一的單一訊息形式傳送。 第一個訊息的大小可能超過 SignalR 訊息大小限制。 問題與檔案大小無關，而是與檔案數目相關。

記錄的錯誤類似以下：

錯誤: 連線已中斷，出現錯誤「錯誤: 伺服器關閉時傳回錯誤: 連線已關閉，出現錯誤」。 e.log @ blazor.server。js:1

上傳檔案時，在第一個訊息便達到訊息大小限制很少見。 如果達到限制，應用程式可以使用較大的值設定 HubOptions.MaximumReceiveMessageSize。

如需 SignalR 設定以及如何設定 MaximumReceiveMessageSize 的詳細資訊，請參閱 ASP.NET Core BlazorSignalR 指導。

每個用戶端中樞設定的平行叫用次數上限

Blazor 依賴 MaximumParallelInvocationsPerClient 設定為 1，這是預設值。

增加值會導致 CopyTo 作業擲回 System.InvalidOperationException: 'Reading is not allowed after reader was completed.' 的高機率。 如需詳細資訊，請參閱 MaximumParallelInvocationsPerClient > 1 在 Blazor Server 模式 (dotnet/aspnetcore #53951) 時會中斷檔案上傳。

疑難排解

呼叫 IBrowserFile.OpenReadStream 會擲回 System.TimeoutException 的程式行：

System.TimeoutException: Did not receive any data in the allotted time.

可能的原因：

• 使用 Autofac 控制反轉 (IoC) 容器，而不是內建的 ASP.NET Core 相依性插入容器。 若要解決此問題，請在伺服器端線路處理程式中樞選項中，將 DisableImplicitFromServicesParameters 設定為 true 。 如需詳細資訊，請參閱 FileUpload：未在指定的時間中收到任何資料 (dotnet/aspnetcore #38842) (英文)。

• 未讀取資料流來完成。 這不是架構問題。 請攔截例外狀況，並在本機環境/網路中進一步調查。

• 在讀取多個檔案來完成之前，先使用伺服器端轉譯並呼叫 OpenReadStream。 若要解決此問題，請使用本文使用伺服器端轉譯將檔案上傳至伺服器一節中所述的 LazyBrowserFileStream 類別和方法。

其他資源

• ASP.NET Core Blazor 檔案下載
• 在 ASP.NET Core 中上傳檔案
• ASP.NET Core Blazor 表單概觀
• Blazor 範例 GitHub 存放庫 (dotnet/blazor-samples) (如何下載)