Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/Tewr/BlazorFileReader

Library for creating read-only file streams from file input elements or drop targets in Blazor.
https://github.com/Tewr/BlazorFileReader

blazor c-sharp stream webassembly

Last synced: 12 days ago
JSON representation

Library for creating read-only file streams from file input elements or drop targets in Blazor.

Awesome Lists containing this project

README 

        
[![Build status](https://ci.appveyor.com/api/projects/status/rr7pchwk7wbc3mn1/branch/main?svg=true)](https://ci.appveyor.com/project/Tewr/blazorfilereader/branch/main)

[![NuGet](https://img.shields.io/nuget/dt/Tewr.Blazor.FileReader.svg?label=Tewr.Blazor.FileReader)](https://www.nuget.org/packages/Tewr.Blazor.FileReader)

[![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=AC77J8GFQ6LYA&item_name=Blazor+File+Reader+Project&currency_code=EUR&source=url)





  




# BlazorFileReader

Blazor library exposing read-only file streams in [Blazor](https://github.com/dotnet/aspnetcore/tree/master/src/Components#blazor) 

 using ``````

and [FileReader](https://developer.mozilla.org/en-US/docs/Web/API/FileReader). Drag and drop targets may also be used to initialize streams.



Here is a [Live demo](https://tewr.github.io/BlazorFileReader/) that contains the output of [the wasm demo project](src/Demo/Blazor.FileReader.Wasm.Demo). Currently, its a build based on ```v3.2.0```.



## Installation



Use [Nuget](https://www.nuget.org/packages/Tewr.Blazor.FileReader): ```Install-Package Tewr.Blazor.FileReader```



Make sure your environment is up to date with the appropriate SDK and VS2019 16.6. See [this article](https://devblogs.microsoft.com/aspnet/blazor-webassembly-3-2-0-preview-3-release-now-available/) for more details.

Depending on your [project type](https://docs.microsoft.com/en-us/aspnet/core/razor-components/faq?view=aspnetcore-3.0), use one of the two examples below. 

For a complete use-case, see the [client](src/Demo/Blazor.FileReader.Wasm.Demo) or [server-side](/src/Demo/Blazor.FileReader.ServerSide.Demo) demo projects.



### Client-side / Wasm Project type / "CSB"



Setup IoC for ```IFileReaderService```as in ([Program.cs](/src/Demo/Blazor.FileReader.Wasm.Demo/Program.cs#L13)):



```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](src/Demo/Blazor.FileReader.ServerSide.Demo/Startup.cs#L16)):



```cs

services.AddFileReaderService();



```

## Documentation



The public API is documented [here](src/Blazor.FileReader/Tewr.Blazor.FileReader.md), generated from the XML comments. 



To get started, the best is to look at the example razor files in the [demo project](src/Demo/Blazor.FileReader.Demo.Common).



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](https://github.com/ADefWebserver) for mentioning this). [Microsoft Docs](https://docs.microsoft.com/en-us/aspnet/core/signalr/configuration?view=aspnetcore-3.0&tabs=dotnet#configure-server-options)

```

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](https://github.com/mono/mono/issues/19936), being investigated by the mono team. Tracked locally [here](https://github.com/Tewr/BlazorFileReader/issues/132).

A simple workaround is available in [this issue](https://github.com/Tewr/BlazorFileReader/issues/97). 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](src/Demo/Blazor.FileReader.Wasm.Demo)- and [server-side](/src/Demo/Blazor.FileReader.ServerSide.Demo) projects. The demo projects also contains [a drag and drop example](src/Demo/Blazor.FileReader.Demo.Common/DragnDropCommon.razor). While the demo projects are the reference, examples also exist in the [wiki](https://github.com/Tewr/BlazorFileReader/wiki).



```cs

@page "/MyPage"

@using Tewr.Blazor.FileReader

@using System.IO;

@inject IFileReaderService fileReaderService;



Read file



@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](https://github.com/Tewr/BlazorFileReader/blob/main/src/Blazor.FileReader/Tewr.Blazor.FileReader.md#M-Tewr-Blazor-FileReader-IFileReaderRef-RegisterPasteEventAsync-Tewr-Blazor-FileReader-DropEvents-PasteEventOptions-) support.



Version 3.1.0.21158 Adds two new methods (.NET5 only): 

[JsObjectReference](src/Blazor.FileReader/Tewr.Blazor.FileReader.md#M-Tewr-Blazor-FileReader-IFileReference-GetJSObjectReferenceAsync) for files, and [CreateObjectUrl](src/Blazor.FileReader/Tewr.Blazor.FileReader.md#getobjecturlasync-method) for files (built on JsObjectReference).

Adds a new overload for [IFileReaderRef.RegisterDropEventsAsync](src/Blazor.FileReader/Tewr.Blazor.FileReader.md#M-Tewr-Blazor-FileReader-IFileReaderRef-RegisterDropEventsAsync-Tewr-Blazor-FileReader-DropEvents-DropEventsOptions-) 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](https://docs.microsoft.com/en-us/aspnet/core/blazor/file-uploads?view=aspnetcore-5.0). 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.