ASP.NET Core Blazor 文件上传

本文介绍如何使用 InputFile 组件在 Blazor 中上传文件。

文件上传

警告

允许用户上传文件时，始终遵循最佳安全做法。 有关详细信息，请参阅在 ASP.NET Core 中上传文件。

使用 InputFile 组件将浏览器文件数据读入 .NET 代码。 InputFile 组件呈现 file 类型的 HTML <input> 元素，用于单个文件上传。 可添加 multiple 属性以允许用户一次上传多个文件。

使用 InputFile 组件或其基础 HTML <input type="file"> 时，文件选择不是累积的，因此无法将文件添加到现有文件选择。 组件始终替换用户的初始文件选择，因此先前选择的文件引用不可用。

发生 OnChange (change) 事件时，以下 InputFile 组件执行 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 内容会被读入内存中的 String (reader)，因此不建议使用以下方法：

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

❌不建议：不建议对 Microsoft Azure Blob 存储使用以下方法，因为在调用 UploadBlobAsync 之前，文件的 Stream 内容会被复制到内存中的 MemoryStream (memoryStream)：

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

接收图像文件的组件可以对文件调用 BrowserFileExtensions.RequestImageFileAsync 便利方法，在图像流式传入应用之前，在浏览器的 JavaScript 运行时内调整图像数据的大小。 调用 RequestImageFileAsync 的用例最适合 Blazor WebAssembly 应用。

Autofac 控制反转 (IoC) 容器用户

如果使用的是 Autofac 控制反转 (IoC) 容器，而不是内置 ASP.NET Core 依赖关系注入容器，请在服务器端线路处理程序中心选项中将 DisableImplicitFromServicesParameters 设置为 true。 有关详细信息，请参阅文件上传：在规定时间内未收到任何数据 (dotnet/aspnetcore #38842)。

文件大小读取和上传限制

服务器端或客户端，没有文件读取或上传大小限制，尤其对于 InputFile 组件。 但是，将数据从 JavaScript 封送到 C# 时，客户端 Blazor 会将文件的字节读取到单个 JavaScript 数组缓冲区中，大小不超过 2 GB 或设备的可用内存。 使用 InputFile 组件进行客户端上传时，大型文件上传 (> 250 MB) 可能会失败。 有关详细信息，请参阅以下讨论：

• 文件上传时，Blazor InputFile Component 应处理分块 (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} 占位符是文件大小（以字节为单位，例如，2 MB 文件为 2097152）。
• {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 主项目中，在项目的 Program 文件中添加 IHttpClientFactory 和相关服务：

builder.Services.AddHttpClient();

必须将 HttpClient 服务添加到主项目中，因为客户端组件已在服务器上预呈现。 如果 禁用以下组件预呈现，则无需在主应用中提供 HttpClient 服务，并且无需将前一行添加到主项目。

有关将 HttpClient 服务添加到 ASP.NET Core 应用的详细信息，请参阅在 ASP.NET Core 中使用 IHttpClientFactory 发出 HTTP 请求。

Blazor Web App 的客户端项目 (.Client) 还必须注册一个 HttpClient，用于向后端 Web API 控制器发送 HTTP POST 请求。 确认客户端项目的 Program 文件中有以下内容或将其添加到该文件中：

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

前面的示例使用 builder.HostEnvironment.BaseAddress (IWebAssemblyHostEnvironment.BaseAddress) 设置基址，该属性会获取应用的基址，并且通常派生自主机页中 <base> 标记的 href 值。 如果要调用外部 Web API，请将 URI 设置为 Web API 的基址。

在 Blazor Web App 中指定以下组件顶部的交互式 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 CoreBlazorSignalR 指南。

每个客户端中心的最大并行调用数设置

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。 有关详细信息，请参阅文件上传：在规定时间内未收到任何数据 (dotnet/aspnetcore #38842)。

• 未读取完数据流。 这不是框架问题。 捕获异常，并在本地环境/网络中进一步调查该异常。

• 使用服务器端渲染，并在读取多个文件完成之前对其调用 OpenReadStream。 若要解决此问题，请使用本文“通过服务器端渲染将文件上传到服务器”部分中所述的 LazyBrowserFileStream 类和方法。

其他资源

• ASP.NET Core Blazor 文件下载
• 在 ASP.NET Core 中上传文件
• ASP.NET Core Blazor 窗体概述
• Blazor 示例 GitHub 存储库 (dotnet/blazor-samples)（下载方法）