.NET MAUI中HttpClient PUT上传文件进度更新异常问题排查

一、解决iOS平台NSUrlSessionHandler进度跳100%问题 #

iOS默认的NSUrlSessionHandler会将整个文件预读入内存，导致进度直接触发100%。需强制开启流模式并限制内存缓冲：

var handler = new NSUrlSessionHandler
{
    DisableBuffering = true, // 关键：禁用预读缓冲，强制分块发送
    MaxInputInMemory = 1024 * 1024 // 1MB缓冲，根据文件大小调整
};
var httpClient = new HttpClient(handler);

DisableBuffering是核心开关，开启后NSUrlSession会按缓冲块逐步发送文件，才能触发真实的进度回调。

二、实现精准进度跟踪的StreamContent #

自定义ProgressStreamContent，确保每发送一块数据就更新进度，同时避免回调频率过高：

public class ProgressStreamContent : StreamContent
{
    private readonly Stream _sourceStream;
    private readonly int _bufferSize;
    private readonly IProgress<long> _progressReporter;
    private long _totalBytesSent;

    public ProgressStreamContent(Stream sourceStream, int bufferSize, IProgress<long> progressReporter) 
        : base(sourceStream)
    {
        _sourceStream = sourceStream ?? throw new ArgumentNullException(nameof(sourceStream));
        _bufferSize = bufferSize > 0 ? bufferSize : 4096;
        _progressReporter = progressReporter ?? throw new ArgumentNullException(nameof(progressReporter));
    }

    protected override async Task SerializeToStreamAsync(Stream targetStream, TransportContext? context)
    {
        var buffer = new byte[_bufferSize];
        int bytesRead;

        while ((bytesRead = await _sourceStream.ReadAsync(buffer, 0, buffer.Length).ConfigureAwait(false)) > 0)
        {
            await targetStream.WriteAsync(buffer, 0, bytesRead).ConfigureAwait(false);
            _totalBytesSent += bytesRead;
            _progressReporter.Report(_totalBytesSent);
        }
    }

    protected override bool TryComputeLength(out long length)
    {
        length = _sourceStream.Length;
        return true; // 明确返回文件总长度，让HttpClient能计算准确进度比例
    }
}

使用示例 #

var fileStream = File.OpenRead("your/file/path");
var totalFileSize = fileStream.Length;
var uploadProgress = new Progress<long>(bytesSent =>
{
    var progressPercent = (double)bytesSent / totalFileSize * 100;
    // MAUI必须在主线程更新UI
    MainThread.BeginInvokeOnMainThread(() =>
    {
        UploadProgressBar.Progress = progressPercent / 100;
        ProgressLabel.Text = $"{progressPercent:F1}%";
    });
});

var content = new ProgressStreamContent(fileStream, 8192, uploadProgress);
var response = await httpClient.PutAsync("https://your-api-endpoint/upload", content);

三、优化HttpClientHandler进度更新过快问题 #

针对Android/Windows平台的HttpClientHandler，进度更新过快是因为缓冲块太小导致回调过于频繁。只需调大ProgressStreamContent的bufferSize（如8192或16384），减少回调次数，同时保证进度精准。

四、跨平台通用注意事项 #

• 每个大文件上传使用独立的HttpClient实例，避免Handler复用导致的状态干扰。
• 确保服务器支持分块传输：如果服务器要求一次性接收完整请求，客户端进度报告必然失真，需确认API的PUT接口支持Transfer-Encoding: chunked。
• 所有流操作必须使用异步方法，同步阻塞会导致进度回调不及时或异常。

五、调试验证技巧 #

• 在进度回调中打印bytesSent和totalFileSize，确认发送字节数与文件实际大小匹配。
• 用不同大小的文件测试（1MB/50MB/100MB+），验证进度曲线是否符合实际上传速度。
• 抓包查看请求是否分块发送，确认每个块的大小与设置的bufferSize一致。

内容的提问来源于stack exchange，提问作者iNCEPTiON_