Skip to content

Latest commit

 

History

History
199 lines (130 loc) · 16 KB

README.md

File metadata and controls

199 lines (130 loc) · 16 KB
Raw

Build status NuGet Donate

BlazorFileReader

Blazor library exposing read-only file streams in Blazor using <input type="file" /> and FileReader. Drag and drop targets may also be used to initialize streams.

Here is a Live demo that contains the output of the wasm demo project. Currently, its a build based on v3.2.0.

Installation

Use Nuget: Install-Package Tewr.Blazor.FileReader

Make sure your environment is up to date with the appropriate SDK and VS2019 16.6. See this article for more details. Depending on your project type, use one of the two examples below. For a complete use-case, see the client or server-side demo projects.

Client-side / Wasm Project type / "CSB"

Setup IoC for IFileReaderServiceas in (Program.cs):

services.AddFileReaderService(options => options.UseWasmSharedBuffer = true);

Server-side / asp.net core Project type / "SSB"

Setup IoC for IFileReaderService as in the example (Startup.cs):

services.AddFileReaderService();

Documentation

The public API is documented here, generated from the XML comments.

To get started, the best is to look at the example razor files in the demo project.

Serverside/SSB: Important usage notice for versions prior to 2.1

Optional SignalR Configuration for large buffer sizes

The following notice is important for versions prior to 2.1. As of 2.1, it is no longer neccessary to modify MaximumReceiveMessageSize. While doing so may slightly increase transfer speed, "we recommend < 32K per message since they are being stored in a ring buffer (default size 5000). Storing larger messages will be awful for performance" (@DavidFowl, msft, 2012).

For server-side hosting, bufferSize + metadata (up to ~30%, depending on buffersize) should not exceed the SignalR MaximumReceiveMessageSize setting, or you will encounter a client-side exception if the file is larger than bufferSize. Make sure MaximumReceiveMessageSize exceeds your bufferSize with 30% to be on the safe side. It is also recommended to set a fixed upper file size in the input tag or validate file.Size in code before starting the uploading. The default settings is 32KB. Thus, if you leave this setting untouched, you should not use a buffer size exceeding 22KB.

You can set the MaximumReceiveMessageSize like this in Startup.cs (creds @ADefWebserver for mentioning this). Microsoft Docs

services.AddServerSideBlazor().AddHubOptions(o =>
{
    o.MaximumReceiveMessageSize = 10 * 1024 * 1024; // 10MB
});

Gotcha's

Problems with reading strings using StreamReader in while header

When publishing or compiling in Release mode, the Optimize flag is set by default. Compiling with this flag set may result in problems if you are using StreamReader. An bug is open on this subject, being investigated by the mono team. Tracked locally here. A simple workaround is available in this issue. Basically, don't call await in the while header, call it somewhere else. This has been fixed in Blazor 5rc1.

IFileReference.CreateMemoryStreamAsync()

The IFileReference.CreateMemoryStreamAsync() method (without any argument) is basically the same as calling IFileReference.CreateMemoryStreamAsync(bufferSize: file.Size). Calling IFileReference.CreateMemoryStreamAsync() may thus be unsuitable for large files (at least for client-side Blazor as the UI will be blocked during the transfer).

Usage in a Blazor View

The code for views looks the same for both client- and server-side projects. The demo projects also contains a drag and drop example. While the demo projects are the reference, examples also exist in the wiki.

@page "/MyPage"
@using Tewr.Blazor.FileReader
@using System.IO;
@inject IFileReaderService fileReaderService;

<input type="file" @ref=inputTypeFileElement /><button @onclick=ReadFile>Read file</button>

@code
{
    private ElementReference inputTypeFileElement;

    public async Task ReadFile()
    {
        foreach (var file in await fileReaderService.CreateReference(inputTypeFileElement).EnumerateFilesAsync())
        {
            // Read into buffer and act (uses less memory)
            await using (Stream stream = await file.OpenReadAsync()) {
                // Do (async) stuff with stream...
                await stream.ReadAsync(buffer, ...);
                // The following will fail. Only async read is allowed.
                stream.Read(buffer, ...)
            }

            // Read file fully into memory and act
            using (MemoryStream memoryStream = await file.CreateMemoryStreamAsync(4096)) {
                // Sync calls are ok once file is in memory
                memoryStream.Read(buffer, ...)
            }
        }
    }
}

Version notes

Version 3.3.2.23201 Fixes a a bug in 3.3.2.23185 related to drag and drop

Version 3.3.2.23185 Adds the possibility to drop multiple files and directories on elements.

Version 3.3.1.21360 Fixes a bug related to platform detection under .net6

Version 3.3.0.21348 Adds .Net6 support.

Version 3.2.0.21211 Adds Copy/Paste support.

Version 3.1.0.21158 Adds two new methods (.NET5 only): JsObjectReference for files, and CreateObjectUrl for files (built on JsObjectReference). Adds a new overload for IFileReaderRef.RegisterDropEventsAsync that provides extensibility points for custom scripts.

Version 3.0.0.20340 Add support for .NET5 and fixes a small issue with Platform detection.

Older versions
Version 2.1.0.20274 WASM/CSB: Fixes a problem with large files and small buffer sizes. Server-side/SSB: Simplifies Setup, removes need for SignalR max size setting (`MaximumReceiveMessageSize`). It is recommended to remove the modification of this value, if present. Adds multithreaded fetch & message chunking for SignalR.
Version 2.0.0.20242 Fixes a bug when working with file larger than 2Gb in InteropStream.Seek (#153)
Version 2.0.0.20200 ⚠️ Breaking changes: Changes Root Namespace from `Blazor.FileReader` to `Tewr.Blazor.FileReader` to avoid conflicts. - `CancellationToken` can now be used in most relevant methods to cancel ongoing upload. - Native support for displaying progress. See demo project for usage.
Version 1.6.0.20166 Fixes a a memory allocation bug (before this fix - since v1.3.0.20033 - the browser would allocate the whole file in ram). Also, introduces a new collection property on File for non-standard properties (thanks to @DouglasDwyer for idea and implementation)
Version 1.5.0.20109 Fixes a a minor bug in drag and drop (before this fix, could not drop on child elements)
Version 1.5.0.20093 reverts a dependency to latest stable version of Microsoft.AspNetCore.Components (5.0.0-preview.1.20124.5 -> 3.1.3)
Version 1.5.0.20092 adds compatibility with Blazor 3.2 (CSB / Wasm) preview 3. Package now depends on latest version of Microsoft.AspNetCore.Components (3.0.0 -> 5.0.0-preview.1.20124.5)
Version 1.4.0.20072 adds compatibility with Blazor 3.2 (CSB / Wasm) preview 2. Also Adds support for the IAsyncDisposable interface.
Version 1.3.0.20049 fixes a bug that would throw an exception when attempting to use reflection on the assembly (Server-side / SSB).
Version 1.3.0.20041 fixes a faulty assembly version in the package.
Version 1.3.0.20033 adds compatibility with Blazor 3.2 (CSB / Wasm). Attention, ReadAsync is no longer a fully async implementation and may run on the UI thread. If you are using a progress bar or similar progress reporting it might be necessary to yield back to the renderer. See the demo project for an example - it is using await Task.Delay(1); to render while reading.
Version 1.2.0.19363 fixes a bug in how the offset parameter is interpreted - now represents target buffer offset, not source buffer offset. The setup option InitializeOnFirstCall now defaults to true.
Version 1.1.0.19274 adds a parameter to IFileReaderRef.RegisterDropEventsAsync for specifying additive drag n drop: When called with parameter set to true, will not reset file list of drop target (see demo for usage). Thanks @DNF-SaS for the feature suggestion.
Version 1.0.0.19267 adds support for v3.0.100
Version 0.16.0.19262 fixes a packaging issue.
Version 0.16.0.19261 adds support for v3.0.100-rc1-014190
Version 0.15.0.19242 adds support for v3.0.0-preview9-014004. Also fixes a minor packaging issue. New API: IBase64Stream, for optimizing third-party cloud uploads (data exposed as raw base64 strings). Mostly interesting for server-side deployments.
Version 0.14.19242 fixes a possible race condition for server-side initialization.
Version 0.14.19226 adds support for sdk 3.0.0-preview8-013656. Adds shared Buffer back again for WASM, this can be activated by setting the UseWasmSharedBuffer option to true (recommended).
Version 0.13.19207` Fixes a regression with the ClearValue method and adds some essential events to the drag and drop api.
Version 0.13.19206 adds support for sdk 3.0.0-preview7.19365.7. New feature: Drag and drop (contribution by @catlan)
Version 0.12.19186 fixes an issue with server-side setup which was only visible when having multiple users.
Version 0.12.19168 adds support for sdk 3.0.0-preview6.19307.2, and several issues are resolved with this release, notably meticulous setup and issues with buffer size for server-side projects. Also, the Wasm helper package has been deprecated.
Version 0.11.0 adds support for sdk 3.0.0-preview5-19227-01. It also introduces a tiny feature: The IFileReaderRef.ClearValue() method, used to clear the value of a referenced file input. Also, fixes a bug in Edge and a package issue.
Version 0.10.0 adds support for sdk v3.0.0-preview-4-19216-03
Versions 0.9.0 introduces a small helper-package for the IoC setup of Wasm, injecting an implementation of IInvokeUnmarshalled.
Versions 0.8.0 requires copy-paste implementation of IInvokeUnmarshalled.
Versions previous to 0.7.1 did not support server-side Blazor and would throw [System.PlatformNotSupportedException] Requires MonoWebAssemblyJSRuntime as the JSRuntime.
Versions previous to 0.5.1 wrapped the input element in a Blazor Component, this has been removed for better configurability and general lack of value.

Standard upload component

📰 01.10.2020 Microsoft has released a built-in file upload component called InputFile. For the most common and simple scenarios, I'd recommend using the built-in component rather than BlazorFileReader. The BlazorFileReader library gives more control over buffer size and memory usage, which may be to your advantage when working with large files. Also, not really being a blazor component, but rather a service that binds to an element, it may at times offer more flexibility.