Code Cleanup, fixed bug in File creation, and extended README with samples of use.

Author: KristofferStrube

README.md

@@ -10,11 +10,136 @@ A Blazor wrapper for the browser [File API](https://www.w3.org/TR/FileAPI/)
 
 The API provides a standard for representing file objects in the browser and ways to select them and access their data. One of the most used interfaces that is at the core of this API is the [Blob](https://www.w3.org/TR/FileAPI/#dfn-Blob) interface. This project implements a wrapper around the API for Blazor so that we can easily and safely interact with files in the browser.
 
-**The wrapper is still being developed so the API Coverage is very limited currently.**
-
 # Demo
 The sample project can be demoed at https://kristofferstrube.github.io/Blazor.FileAPI/
 
 On each page you can find the corresponding code for the example in the top right corner.
 
-On the *API Coverage Status* page you can get an overview over what parts of the API we support currently.
+On the *API Coverage Status* page you can get an overview over what parts of the API we support currently.
+
+# Getting Started
+## Prerequisites
+You need to install .NET 6.0 or newer to use the library.
+
+[Download .NET 6](https://dotnet.microsoft.com/download/dotnet/6.0)
+
+## Installation
+You can install the package via NuGet with the Package Manager in your IDE or alternatively using the command line:
+```bash
+dotnet add package KristofferStrube.Blazor.FileAPI
+```
+
+# Usage
+The package can be used in Blazor WebAssembly and Blazor Server projects.
+## Import
+You also need to reference the package in order to use it in your pages. This can be done in `_Import.razor` by adding the following.
+```razor
+@using KristofferStrube.Blazor.FileAPI
+```
+
+## Creating wrapper instances
+Most of this library is wrapper classes which can be instantiated from your code using the static `Create` and `CreateAsync` methods on the wrapper classes.
+An example could be to create an instance of a `Blob` that contains the text `"Hello World!"` and gets its `Size` and `Type`, read it as a `ReadableStream`, read as text directly, and slice it into a new `Blob` like this.
+```csharp
+Blob blob = await Blob.CreateAsync(
+    JSRuntime,
+    blobParts: new BlobPart[] {
+        new("Hello "),
+        new(new byte[] { 0X57, 0X6f, 0X72, 0X6c, 0X64, 0X21 })
+    },
+    options: new() { Type = "text/plain" }
+);
+ulong size = await blob.GetSizeAsync(); // 12
+string type = await blob.GetTypeAsync(); // "text/plain"
+ReadableStream stream = await blob.StreamAsync();
+string text = await blob.TextAsync(); // "Hello World!"
+Blob worldBlob = await blob.SliceAsync(6, 11); // Blob containing "World"
+```
+All creator methods take an `IJSRuntime` instance as the first parameter. The above sample will work in both Blazor Server and Blazor WebAssembly. If we only want to work with Blazor WebAssembly we can use the `InProcess` variant of the wrapper class. This is equivalent to the relationship between `IJSRuntime` and `IJSInProcessRuntime`. We can recreate the above sample using the `BlobInProcess` which will simplify some of the methods we can call on the `Blob` and how we access attributes.
+```csharp
+BlobInProcess blob = await BlobInProcess.CreateAsync(
+    JSRuntime,
+    blobParts: new BlobPart[] {
+        new("Hello "),
+        new(new byte[] { 0X57, 0X6f, 0X72, 0X6c, 0X64, 0X21 })
+    },
+    options: new() { Type = "text/plain" }
+);
+ulong size = blob.Size; // 12
+string type = blob.Type; // "text/plain"
+ReadableStreamInProcess stream = await blob.StreamAsync();
+string text = await blob.TextAsync(); // "Hello World!"
+BlobInProcess worldBlob = blob.Slice(6, 11); // BlobInProcess containing "World"
+```
+Some of the methods wrap a `Promise` so even in the `InProcess` variant we need to await it like we see for `TextAsync` above.
+
+If you have an `IJSObjectReference` or an `IJSInProcessObjectReference` for a type equivalent to one of the classes wrapped in this package then you can construct a wrapper for it using another set of overloads of the static `Create` and `CreateAsync` methods on the appropriate class. In the below example we create wrapper instances from existing JS references to a `File` object.
+```csharp
+// Blazor Server compatible.
+IJSObjectReference jSFile; // JS Reference from other package or your own JSInterop.
+File file = File.Create(JSRuntime, jSFile)
+
+// InProcess only supported in Blazor WebAssembly.
+IJSInProcessObjectReference jSFileInProcess; // JS Reference from other package or your own JSInterop.
+FileInProcess fileInProcess = await File.CreateAsync(JSRuntime, jSFileInProcess)
+```
+
+## Add to service collection
+We have a single service in this package that wraps the `URL` interface. An easy way to make the service available in all your pages is by registering it in the `IServiceCollection` so that it can be dependency injected in the pages that need it. This is done in `Program.cs` by adding the following before you build the host and run it.
+```csharp
+var builder = WebAssemblyHostBuilder.CreateDefault(args);
+builder.RootComponents.Add<App>("#app");
+builder.RootComponents.Add<HeadOutlet>("head::after");
+
+// Other services are added.
+
+builder.Services.AddURLService();
+
+await builder.Build().RunAsync();
+```
+## Inject in page
+Then the service can be injected in a page and be used to create Blob URLs and revoke them like so:
+```razor
+@implements IAsyncDisposable
+@inject IURLService URL;
+
+<img src="@blobURL" alt="Some blob as image" />
+
+@code {
+    private string blobURL = "";
+
+    protected override async Task OnInitializedAsync()
+    {
+        Blob blob; // We have some blob from somewhere.
+
+        blobURL = await URL.CreateObjectURLAsync(blob);
+    }
+
+    public async ValueTask DisposeAsync()
+    {
+        await URL.RevokeObjectURLAsync(blobURL);
+    }
+}
+```
+You can likewise add the `InProcess` variant of the service (`IURLServiceInProcess`) using the `AddURLServiceInProcess` extension method which is only supported in Blazor WebAssembly projects.
+
+# Issues
+Feel free to open issues on the repository if you find any errors with the package or have wishes for features.
+
+# Related repositories
+This project uses this package to return a rich `ReadableStream` from the `StreamAsync` method on a `Blob`.
+- https://github.com/KristofferStrube/Blazor.Streams
+
+This project is going to be used in this package to return a rich `File` object when getting the `File` from a `FileSystemFileHandle` and when writing a `Blob` to a `FileSystemWritableFileSystem`.
+- https://github.com/KristofferStrube/Blazor.FileSystemAccess
+
+This project uses a combination of the two styles present in the two above packages which both eventually will go more towards the style present in this project.
+
+# Related articles
+This repository was build with inspiration and help from the following series of articles:
+
+- [Wrapping JavaScript libraries in Blazor WebAssembly/WASM](https://blog.elmah.io/wrapping-javascript-libraries-in-blazor-webassembly-wasm/)
+- [Call anonymous C# functions from JS in Blazor WASM](https://blog.elmah.io/call-anonymous-c-functions-from-js-in-blazor-wasm/)
+- [Using JS Object References in Blazor WASM to wrap JS libraries](https://blog.elmah.io/using-js-object-references-in-blazor-wasm-to-wrap-js-libraries/)
+- [Blazor WASM 404 error and fix for GitHub Pages](https://blog.elmah.io/blazor-wasm-404-error-and-fix-for-github-pages/)
+- [How to fix Blazor WASM base path problems](https://blog.elmah.io/how-to-fix-blazor-wasm-base-path-problems/)

samples/KristofferStrube.Blazor.FileAPI.WasmExample/Pages/Index.razor

@@ -1,9 +1,9 @@
 @page "/"
-@implements IAsyncDisposable
+@implements IDisposable
 
 @inject IJSRuntime JSRuntime
 @inject HttpClient HttpClient
-@inject URLService URL
+@inject IURLServiceInProcess URL
 
 <PageTitle>FileAPI - Index</PageTitle>
 
@@ -35,11 +35,11 @@ content type: @file?.Type
             fileName: imageName,
             options: new() { Type = "image/png", LastModified = DateTime.Now }
         );
-        blobURL = await URL.CreateObjectURLAsync(file);
+        blobURL = URL.CreateObjectURL(file);
     }
 
-    public async ValueTask DisposeAsync()
+    public void Dispose()
     {
-        await URL.RevokeObjectURLAsync(blobURL);
+        URL.RevokeObjectURL(blobURL);
     }
 }

samples/KristofferStrube.Blazor.FileAPI.WasmExample/Program.cs

@@ -2,13 +2,12 @@
 using KristofferStrube.Blazor.FileAPI.WasmExample;
 using Microsoft.AspNetCore.Components.Web;
 using Microsoft.AspNetCore.Components.WebAssembly.Hosting;
-using Microsoft.JSInterop;
 
 var builder = WebAssemblyHostBuilder.CreateDefault(args);
 builder.RootComponents.Add<App>("#app");
 builder.RootComponents.Add<HeadOutlet>("head::after");
 
 builder.Services.AddScoped(sp => new HttpClient { BaseAddress = new Uri(builder.HostEnvironment.BaseAddress) });
-builder.Services.AddScoped<URLService>();
+builder.Services.AddURLServiceInProcess();
 
 await builder.Build().RunAsync();

src/KristofferStrube.Blazor.FileAPI/Blob.InProcess.cs

@@ -1,4 +1,5 @@
-using Microsoft.JSInterop;
+using KristofferStrube.Blazor.Streams;
+using Microsoft.JSInterop;
 
 namespace KristofferStrube.Blazor.FileAPI;
 
@@ -35,8 +36,8 @@ public static async Task<BlobInProcess> CreateAsync(IJSRuntime jSRuntime, IJSInP
         object?[]? jsBlobParts = blobParts?.Select<BlobPart, object?>(blobPart => blobPart.type switch
             {
                 BlobPartType.BufferSource => blobPart.byteArrayPart,
-                BlobPartType.Blob => blobPart.stringPart,
-                _ => blobPart.blobPart?.JSReference
+                BlobPartType.Blob => blobPart.blobPart?.JSReference,
+                _ => blobPart.stringPart
             })
             .ToArray();
         IJSInProcessObjectReference jSInstance = await inProcesshelper.InvokeAsync<IJSInProcessObjectReference>("constructBlob", jsBlobParts, options);
@@ -55,6 +56,16 @@ internal BlobInProcess(IJSRuntime jSRuntime, IJSInProcessObjectReference inProce
         JSReference = jSReference;
     }
 
+    /// <summary>
+    /// Creates a new <see cref="ReadableStreamInProcess"/> from the <see cref="Blob"/>.
+    /// </summary>
+    /// <returns>A new wrapper for a <see cref="ReadableStreamInProcess"/></returns>
+    public new async Task<ReadableStreamInProcess> StreamAsync()
+    {
+        IJSInProcessObjectReference jSInstance = JSReference.Invoke<IJSInProcessObjectReference>("stream");
+        return await ReadableStreamInProcess.CreateAsync(jSRuntime, jSInstance);
+    }
+
     /// <summary>
     /// The size of this blob.
     /// </summary>
@@ -73,12 +84,12 @@ internal BlobInProcess(IJSRuntime jSRuntime, IJSInProcessObjectReference inProce
     /// <param name="start">The start index of the range. If <see langword="null"/> or negative then <c>0</c> is assumed.</param>
     /// <param name="end">The start index of the range. If <see langword="null"/> or larger than the size of the original <see cref="Blob"/> then the size of the original <see cref="Blob"/> is assumed.</param>
     /// <param name="contentType">An optional MIME type of the new <see cref="Blob"/>. If <see langword="null"/> then the MIME type of the original <see cref="Blob"/> is used.</param>
-    /// <returns>A new <see cref="Blob"/>.</returns>
-    public Blob Slice(long? start = null, long? end = null, string? contentType = null)
+    /// <returns>A new <see cref="BlobInProcess"/>.</returns>
+    public BlobInProcess Slice(long? start = null, long? end = null, string? contentType = null)
     {
         start ??= 0;
         end ??= (long)Size;
-        IJSObjectReference jSInstance = JSReference.Invoke<IJSObjectReference>("slice", start, end, contentType);
-        return new Blob(jSRuntime, jSInstance);
+        IJSInProcessObjectReference jSInstance = JSReference.Invoke<IJSInProcessObjectReference>("slice", start, end, contentType);
+        return new BlobInProcess(jSRuntime, inProcessHelper, jSInstance);
     }
 }

src/KristofferStrube.Blazor.FileAPI/Blob.cs

@@ -32,8 +32,8 @@ public static async Task<Blob> CreateAsync(IJSRuntime jSRuntime, IList<BlobPart>
         object?[]? jsBlobParts = blobParts?.Select<BlobPart, object?>(blobPart => blobPart.type switch
             {
                 BlobPartType.BufferSource => blobPart.byteArrayPart,
-                BlobPartType.Blob => blobPart.stringPart,
-                _ => blobPart.blobPart?.JSReference
+                BlobPartType.Blob => blobPart.blobPart?.JSReference,
+                _ => blobPart.stringPart
             })
             .ToArray();
         IJSObjectReference jSInstance = await helper.InvokeAsync<IJSObjectReference>("constructBlob", jsBlobParts, options);
@@ -92,16 +92,6 @@ public async Task<ReadableStream> StreamAsync()
         return ReadableStream.Create(jSRuntime, jSInstance);
     }
 
-    /// <summary>
-    /// Creates a new <see cref="ReadableStreamInProcess"/> from the <see cref="Blob"/>.
-    /// </summary>
-    /// <returns>A new wrapper for a <see cref="ReadableStreamInProcess"/> which can access members and call non-promise methods synchronously.</returns>
-    public async Task<ReadableStreamInProcess> StreamInProcessAsync()
-    {
-        IJSInProcessObjectReference jSInstance = await JSReference.InvokeAsync<IJSInProcessObjectReference>("stream");
-        return await ReadableStreamInProcess.CreateAsync(jSRuntime, jSInstance);
-    }
-
     /// <summary>
     /// The content of the blob as a string.
     /// </summary>

src/KristofferStrube.Blazor.FileAPI/Extensions/IServiceCollectionExtensions.cs

@@ -0,0 +1,17 @@
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.JSInterop;
+
+namespace KristofferStrube.Blazor.FileAPI;
+
+public static class IServiceCollectionExtensions
+{
+    public static IServiceCollection AddURLService(this IServiceCollection serviceCollection)
+    {
+        return serviceCollection.AddScoped<IURLService, URLService>();
+    }
+
+    public static IServiceCollection AddURLServiceInProcess(this IServiceCollection serviceCollection)
+    {
+        return serviceCollection.AddScoped<IURLServiceInProcess>(sp => new URLServiceInProcess((IJSInProcessRuntime)sp.GetRequiredService<IJSRuntime>()));
+    }
+}

src/KristofferStrube.Blazor.FileAPI/File.InProcess.cs

@@ -1,4 +1,5 @@
-using Microsoft.JSInterop;
+using KristofferStrube.Blazor.Streams;
+using Microsoft.JSInterop;
 
 namespace KristofferStrube.Blazor.FileAPI;
 
@@ -56,6 +57,16 @@ internal FileInProcess(IJSRuntime jSRuntime, IJSInProcessObjectReference inProce
         JSReference = jSReference;
     }
 
+    /// <summary>
+    /// Creates a new <see cref="ReadableStreamInProcess"/> from the <see cref="Blob"/>.
+    /// </summary>
+    /// <returns>A new wrapper for a <see cref="ReadableStreamInProcess"/></returns>
+    public new async Task<ReadableStreamInProcess> StreamAsync()
+    {
+        IJSInProcessObjectReference jSInstance = JSReference.Invoke<IJSInProcessObjectReference>("stream");
+        return await ReadableStreamInProcess.CreateAsync(jSRuntime, jSInstance);
+    }
+
     /// <summary>
     /// The size of this blob.
     /// </summary>
@@ -68,6 +79,21 @@ internal FileInProcess(IJSRuntime jSRuntime, IJSInProcessObjectReference inProce
     /// <returns>The MIME type of this blob.</returns>
     public string Type => inProcessHelper.Invoke<string>("getAttribute", JSReference, "type");
 
+    /// <summary>
+    /// Gets some range of the content of a <see cref="Blob"/> as a new <see cref="Blob"/>.
+    /// </summary>
+    /// <param name="start">The start index of the range. If <see langword="null"/> or negative then <c>0</c> is assumed.</param>
+    /// <param name="end">The start index of the range. If <see langword="null"/> or larger than the size of the original <see cref="Blob"/> then the size of the original <see cref="Blob"/> is assumed.</param>
+    /// <param name="contentType">An optional MIME type of the new <see cref="Blob"/>. If <see langword="null"/> then the MIME type of the original <see cref="Blob"/> is used.</param>
+    /// <returns>A new <see cref="BlobInProcess"/>.</returns>
+    public BlobInProcess Slice(long? start = null, long? end = null, string? contentType = null)
+    {
+        start ??= 0;
+        end ??= (long)Size;
+        IJSInProcessObjectReference jSInstance = JSReference.Invoke<IJSInProcessObjectReference>("slice", start, end, contentType);
+        return new BlobInProcess(jSRuntime, inProcessHelper, jSInstance);
+    }
+
     /// <summary>
     /// The name of the file including file extension.
     /// </summary>