https://kristoffer-strube.dk/On this blog I will post about my hobby projects involving .NET, Blazor, browser specifications, and much more!enblog@kristoffer-strube.dkTue, 16 Jul 2024 23:09:46 +0200120https://kristoffer-strube.dkmultithreading-in-blazor-wasm-using-web-workershttps://kristoffer-strube.dk/post/multithreading-in-blazor-wasm-using-web-workers/Blazor has multiple rendering models, each with its pros and cons. One of the most popular is Blazor WASM, which enables a highly interactive web application running entirely in the client's browser. But its forte is also its weakness; when you offload the work of running the application to the browser, you must live under its constraints. One of these constraints is that each window in a browser is inherently single-threaded. A way to still do work on multiple threads is by using Web Workers, which are analog to Threads in .NET. In this article, we will go through how to use two of the most prominent Blazor Web Workers OSS libraries; we will show a separate Web Workers implementation that I have created myself which uses the experimental-wasm .NET workload and, in the end, do a little comparison of how each of them performs for a variety of workloads.Wed, 17 Jul 2024 00:00:00 +02002024-07-17T00:00:00+02:00<h3>Web Workers</h3> <p>Web Workers are defined as a part of <a href="https://html.spec.whatwg.org/multipage/workers.html#workers">the HTML specification</a>. They enable us to run some scripts in the background to avoid blocking the primary thread when we do heavy work. This can be a common problem in Blazor WASM, where the UI can become unresponsive when a heavy workload is executed.</p> <p>In JavaScript, we can create a worker and listen for messages posted in the worker like so:</p> <pre><code class="language-js">let worker = new Worker(&quot;my-worker-script.js&quot;, { type: &quot;classic&quot; }); worker.addEventListener(&quot;message&quot;, log) function log(e) { console.log(&quot;Some message from the worker: &quot; + e.data); } </code></pre> <p>The content of the <code>my-worker-script.js</code> file would then define the worker's work. An example could be posting a message to itself, which is what we listen for in the previous code block.</p> <h4>my-worker-script.js</h4> <pre><code class="language-js">self.postMessage(&quot;This was posted from the worker!&quot;); console.log(&quot;We can also log to the console directly from here.&quot;) </code></pre> <h3>Tewr.BlazorWorker</h3> <p><a href="https://github.com/Tewr/BlazorWorker">Tewr.BlazorWorker</a> is one of the first Web Workers abstractions made for Blazor WASM. It is made by <a href="https://github.com/Tewr">Tewr</a>, whom you might also know from the <a href="https://github.com/Tewr/BlazorFileReader">BlazorFileReader</a> library. It uses the <a href="https://github.com/esskar/Serialize.Linq">Serialize.Linq</a> library to serialize expressions that represent the work that is to be done on the background thread. First, the worker is initialized, which also starts the Blazor runtime from the worker thread. Then, the serialized expression is posted to the worker. The Blazor application, which the worker initializes, listens for messages sent to the worker, and when it sees a new message, it deserializes the expressions and invokes it.</p> <p>The following is a minimal sample of what you need to do some simple work on another thread. First, you need to install this NuGet package</p> <pre><code class="language-console">Tewr.BlazorWorker.BackgroundService </code></pre> <p>And then add its service to your service collection in <code>Program.cs</code>.</p> <pre><code class="language-csharp">builder.Services.AddWorkerFactory(); </code></pre> <p>Then, on a page, make a setup like this.</p> <pre><code class="language-razor">@using BlazorWorker.BackgroundServiceFactory @using BlazorWorker.Core @inject IWorkerFactory workerFactory &lt;button @onclick=ExecuteOnTewrBlazorWorker&gt;Execute&lt;/button&gt; &lt;br/&gt; &lt;code&gt;@result&lt;/code&gt; @code { private string result = &quot;&quot;; private async Task ExecuteOnTewrBlazorWorker() { IWorker worker = await workerFactory.CreateAsync(); var service = await worker.CreateBackgroundServiceAsync&lt;MathService&gt;(); double input = Random.Shared.NextDouble(); double output = await service.RunAsync(math =&gt; math.MutliplyByTwo(input)); result = $&quot;{input} * 2 = {output}&quot;; } public class MathService { public double MutliplyByTwo(double input) { return input * 2; } } } </code></pre> <p>The above code sample initializes a service called <code>MathService</code> in the worker and then invokes the method <code>MutliplyByTwo</code> with a random number created on the main thread. The sample is very basic, and obviously, multiplying a number by two is not very expensive. But the idea is still recognizable: Taking some input from the main thread, running some method on the worker thread, and, in the end, returning the result to the main thread.</p> <p>After going through this minimal sample, my first impression is that it indeed feels pretty minimal. The only part I'm unsure about is the use of <code>Serialize.Linq</code>, which it uses to deserialize and compile the expression every time it is called. Depending on how well the .NET WASM runtime can optimize the generated IL code, this could be expensive.</p> <h3>SpawnDev.BlazorJS.WebWorkers</h3> <p><a href="https://github.com/LostBeard/SpawnDev.BlazorJS?tab=readme-ov-file#spawndevblazorjswebworkers">SpawnDev.BlazorJS.WebWorkers</a> is a newer implementation which is a part of <a href="https://github.com/LostBeard">LostBeard</a>s project <a href="https://github.com/LostBeard/SpawnDev.BlazorJS">SpawnDev.BlazorJS</a>. It likewise uses <a href="https://github.com/esskar/Serialize.Linq">Serialize.Linq</a> to serialize the expression that should be evaluated on the worker. But it requires a bit more setup.</p> <p>Let's see an equivalent to the previous sample but with <code>SpawnDev.BlazorJS.WebWorkers</code>. We first need to add their NuGet package:</p> <pre><code class="language-console">SpawnDev.BlazorJS.WebWorkers </code></pre> <p>Then we need to do a bit of setup in <code>Program.cs</code>.</p> <pre><code class="language-csharp">builder.Services.AddBlazorJSRuntime(); builder.Services.AddWebWorkerService(); builder.Services.AddSingleton&lt;IMathService, MathService&gt;(); await builder.Build().BlazorJSRunAsync(); </code></pre> <p>We add the services needed for <code>BlazorJS</code> to work, a service needed for accessing and creating web workers, and inject <code>MathService</code> as a service. Then, we change a significant part of our <code>Program.cs</code> file. We normally call <code>RunAsync()</code> after building the <code>WebAssemblyHost</code> but here we call <code>BlazorJSRunAsync()</code> instead. This is the primary part that changes the control flow of our Blazor application. The <code>BlazorJSRunAsync</code> method checks whether we are running in the window context, in which case it starts Blazor like usual. Otherwise, it simply idles and listens for messages.</p> <p>We have updated our <code>MathService</code> a bit by making it implement an interface. This is necessary so the library can create a proxy for the service.</p> <pre><code class="language-csharp">public interface IMathService { public double MutliplyByTwo(double input); } public class MathService : IMathService { public double MutliplyByTwo(double input) { return input * 2; } } </code></pre> <p>Then, on some page, we can make our minimal sample again:</p> <pre><code class="language-razor">@using SpawnDev.BlazorJS.WebWorkers @inject WebWorkerService WebWorkerService &lt;button @onclick=ExecuteOnSpawnDevWebWorker&gt;Execute&lt;/button&gt; &lt;br/&gt; &lt;code&gt;@result&lt;/code&gt; @code { private string result = &quot;&quot;; private async Task ExecuteOnSpawnDevWebWorker() { WebWorker? worker = await WebWorkerService.GetWebWorker(); double input = Random.Shared.NextDouble(); double output = await worker!.Run&lt;IMathService, double&gt;(job =&gt; job.MutliplyByTwo(input)); result = $&quot;{input} * 2 = {output}&quot;; } } </code></pre> <p>This was a lot more setup than the <code>Tewr</code> sample, even though it seems to use the same core principles. However, that can also be helpful, as it makes certain parts of the internals more transparent to us. This can help library users troubleshoot problems with greater ease.</p> <h3>KristofferStrube.Blazor.WebWorkers</h3> <p>Before looking at how the other solutions worked, I tried to implement my own wrapper for calling .NET through Web Workers. It differs by two key points.</p> <ol> <li>It does not start a separate Blazor instance in the worker but instead starts a .NET application using the <code>wasm-experimental</code> workload.</li> <li>It does not use <code>Serialize.Linq</code> and instead enforces a standard format for a job that needs to be implemented in a separate project.</li> </ol> <p>This makes the implementation a bit more limited. The work being executed by the worker must have a single input and output. Apart from this, you can't use normal Blazor JSInterop in a <code>wasm-experimental</code> project. But if we assume you don't need to use JSInterop for your background job, then this should be fine. So, let's see what it looks like.</p> <p>You first need to install the <code>wasm-experimental</code> workload</p> <pre><code class="language-bash">dotnet workload install wasm-experimental </code></pre> <p>Then, you need to create a separate project in your solution. You can create this project using the standard .NET 8 console template</p> <pre><code class="language-bash">dotnet new console </code></pre> <p>To make this a <code>wasm-experimental</code> project, you must adjust the <code>.csproj</code> file to look like this.</p> <pre><code class="language-xml">&lt;Project Sdk=&quot;Microsoft.NET.Sdk&quot;&gt; &lt;PropertyGroup&gt; &lt;TargetFramework&gt;net8.0&lt;/TargetFramework&gt; &lt;OutputType&gt;Exe&lt;/OutputType&gt; &lt;RuntimeIdentifier&gt;browser-wasm&lt;/RuntimeIdentifier&gt; &lt;Nullable&gt;enable&lt;/Nullable&gt; &lt;ImplicitUsings&gt;enable&lt;/ImplicitUsings&gt; &lt;AllowUnsafeBlocks&gt;true&lt;/AllowUnsafeBlocks&gt; &lt;/PropertyGroup&gt; &lt;ItemGroup&gt; &lt;PackageReference Include=&quot;KristofferStrube.Blazor.WebWorkers&quot; Version=&quot;0.1.0-alpha.6&quot; /&gt; &lt;/ItemGroup&gt; &lt;/Project&gt; </code></pre> <p>Next, we need to add a class that implements the abstract <code>JsonJob</code> class to the <code>wasm-experimental</code> project. The <code>JsonJob</code> class has a single abstract method called <code>Work</code>, where you should implement the work that the job needs to do. The two type parameters of the <code>JsonJob</code> class define the input and output of the job.</p> <pre><code class="language-csharp">using KristofferStrube.Blazor.WebWorkers; public class MultiplyByTwoJob : JsonJob&lt;double, double&gt; { public override double Work(double input) { return input * 2; } } </code></pre> <p>To finish the worker part, we just need to update our <code>Program.cs</code> to start our job. Before this, we also checked that it was running in the browser, as this depends on using the interop services for JavaScript, which are only available when running in the browser.</p> <pre><code class="language-csharp">if (!OperatingSystem.IsBrowser()) throw new PlatformNotSupportedException(&quot;Can only be run in the browser!&quot;); await new MultiplyByTwoJob().StartAsync(); </code></pre> <p>We then need to take a dependency on the <code>wasm-experimental</code> project from our main Blazor project, and then we are ready to make our minimal sample</p> <pre><code class="language-razor">@using KristofferStrube.Blazor.WebWorkers @inject IJSRuntime JSRuntime &lt;button @onclick=ExecuteOnBlazorWebWorkers&gt;Execute&lt;/button&gt; &lt;br/&gt; &lt;code&gt;@result&lt;/code&gt; @code { private string result = &quot;&quot;; private async Task ExecuteOnBlazorWebWorkers() { var worker = await JobWorker&lt;double, double, MultiplyByTwoJob&gt;.CreateAsync(JSRuntime); double input = Random.Shared.NextDouble(); double output = await worker.ExecuteAsync(input); result = $&quot;{input} * 2 = {output}&quot;; } } </code></pre> <p>My solution required even more setup to get the minimal sample up and running, but it also differs a lot, so there might be other gains from this.</p> <h3>Performance comparisons</h3> <p>Now that we have seen three ways to do the same work in the background, let's make some simple benchmarks of how the different solutions perform in various settings. In all these experiments, we will repeat the experiment 1000 times and then take the average of the best 100 results to avoid including outliers. We will also compare the three wrapper implementations with the same work implemented in JavaScript.</p> <p>All of the following comparisons are also available here if you want to check the code directly or try to reproduce the results on your own machine:</p> <p>Repository: <a href="https://github.com/KristofferStrube/Blazor.WorkersBenchmarks">https://github.com/KristofferStrube/Blazor.WorkersBenchmarks</a></p> <p>Live Demo: <a href="https://kristofferstrube.github.io/Blazor.WorkersBenchmarks/">https://kristofferstrube.github.io/Blazor.WorkersBenchmarks/</a></p> <h4>Sending large inputs</h4> <p>It can be expensive to send the parameters needed to run the job. This can be one of the reasons why it might not be worth it to use a worker, as the additional workload of serializing the input would still need to be done on the main thread.</p> <p>To compare this, we have constructed a simple job that receives a string and always returns the number 42. We intentionally do not use the input to calculate something, as we would then measure the processing time of the input as well.</p> <pre><code class="language-csharp">public class LargeInputJob : JsonJob&lt;string, int&gt; { public override int Work(string input) { return 42; } } </code></pre> <p>Let's see the result of this small benchmark.</p> <p><img src="https://kristoffer-strube.dk/images/large-input.png" alt="Results from measuring the average running time for different worker wrappers" /> Surprisingly, <code>Tewr.Blazor.Worker</code> seems to be much slower than <code>SpawnDev.BlazorJS.WebWorkers</code>. It appears to have a larger overhead from starting some work, but it also grows in running time much faster than the other implementations. If we create a linear fit for the four different sets of measurements, we get the following base overheads and growth rates.</p> <br /> <table> <tr><th>Worker Implementation</th><th>Base in milliseconds</th><th>Growth in milliseconds per 10000 chars</th></tr> <tr><td>Tewr.BlazorWorker</td><td>5.776</td><td>1.033</td></tr> <tr><td>SpawnDev.BlazorJS.WebWorkers</td><td>1.576</td><td>0.196</td></tr> <tr><td>KristofferStrube.Blazor.WebWorkers</td><td>0.813</td><td>0.150</td></tr> <tr><td>JS Worker</td><td>0.317</td><td>0.087</td></tr> <table> <br /> <p>I like to present these numbers as they make clear what can be challenging to read from the plot. The primary interesting part that we can read from these numbers is that the different sets of measurements will get the same order if we sort them by their base overhead or if we sort them by their growth rate. This means that using JS for this type of work will always be most favorable, no matter how big our input is. But if we were to limit this comparison to only include .NET implementations, then our solution would be the best. That JS won is unsurprising as we need to send our string through JSInterop two times when working with the .NET implementations. First, send it from .NET to JS, then send it back to our Blazor or <code>wasm-experimental</code> application from JS in the worker.</p> <h4>CPU-intensive work</h4> <p>Our next benchmark is going to measure the speed of the work being done on the worker itself. This is an especially interesting experiment as it will compare JavaScript against Compiled Expressions and .NET pre-compiled. For this reason, we will also measure both AOT and non-AOT in this benchmark to see how big this influence has on the different .NET implementations. The work we are going to measure in this sample is going to be very simple but, nonetheless, very CPU intensive when run for a big input. We will run a for loop up to the input number and sum up all the even numbers. This is the kind of work that could freeze the UI in Blazor if we were to run it on the main thread. This time, we will return the result, not because we wish to measure how long larger numbers take to return but for reasons that will become clear soon. This job is implemented like this in .NET:</p> <pre><code class="language-csharp">public class SumEvenNumbersJob : JsonJob&lt;int, int&gt; { public override int Work(int input) { int sum = 0; for (int i = 0; i &lt; input; i++) { if (i % 2 == 0) { sum += i; } } return sum; } } </code></pre> <p>Let's see the results.</p> <p><img src="https://kristoffer-strube.dk/images/sum-even-numbers.png" alt="Results from measuring the average running time for summing even numbers up to some input with different worker wrappers" /></p> <p>We first see that we have the same order as before when sorting by speed. But this time, we don't see a clear difference in which .NET implementation grows the fastest. We still see that the JS worker is the fastest and it seems to grow much slower than the other implementations.</p> <p>But all is not lost. Let's repeat this benchmark with the project AOT compiled. This was why we ensured that the sum was returned in this sample, as AOT would else remove the for-loop entirely if the sum had not been used. This should make a considerable improvement for our .NET implementations, as we have seen in our last article on this topic: <a href="https://kristoffer-strube.dk/post/a-holistic-comparison-of-blazor-wasm-performance-from-aspnet-core-5-to-8/">A holistic comparison of Blazor WASM performance from ASP.NET Core 5 to 8</a>. We will start this experiment with some bigger inputs as the .NET implementations are now so efficient that they would seem not to change at the previous scale.</p> <p><img src="https://kristoffer-strube.dk/images/sum-even-numbers-aot.png" alt="Results from measuring the average running time for summing even numbers up to some input with different worker wrappers that are AOT compiled" /></p> <p>Notice that we now increment our input with 1 million instead of 10 thousand for each of the points at which we measure time. This is why the JS workers' change in speed seems steeper now, even though the speed has not changed significantly. But let's focus on what we are interested in. .NET is faster than JS for the same job on a worker thread! This is the first time I have seen a direct comparison of .NET against JavaScript, so I was excited to know that .NET can outperform JS for CPU-intensive work in the browser.</p> <h4>Reading, processing, and outputting</h4> <p>The next case is a more complete demonstration of a real workload. We will make a mini-version of the <a href="https://github.com/gunnarmorling/1brc">The One Billion Row Challenge</a>. The challenge at its core is to read some files with temperature measurements and then output each city's minimum, average, and maximum temperatures. To make this a bit simpler, I have chosen to create an endpoint on my personal API that can return measurements for some number of cities. Apart from this, the task is still the same. This also makes it closer to some standard browser work: getting some string, parsing it, reading through it, and reporting aggregated results. I have tried to find the simplest possible solution, as I could not make the same performance improvements I know of in .NET when making the JS implementation.</p> <p>This is the simple implementation in .NET:</p> <pre><code class="language-csharp">using KristofferStrube.Blazor.WebWorkers; public class AverageCityTemperaturesJob(HttpClient httpClient) : TaskJsonJob&lt;int, CityStatistics[]&gt; { private const string MeasurementsEndpoint = &quot;https://kristoffer-strube.dk/API/not-the-measurment-endpoint/&quot;; private string? responseAsText; public override async Task&lt;CityStatistics[]&gt; Work(int input) { if (responseAsText is null) { responseAsText = await httpClient.GetStringAsync(MeasurementsEndpoint + input); } Dictionary&lt;string, CityAggregate&gt; aggregates = new(); foreach (string line in responseAsText.Split(&quot;\n&quot;)) { string[] parts = line.Split(&quot;;&quot;); string city = parts[0]; float temperature = float.Parse(parts[1]); if (!aggregates.TryGetValue(city, out CityAggregate? aggregate)) { aggregate = new(); aggregates[city] = aggregate; } aggregate.Min = temperature &lt; aggregate.Min ? temperature : aggregate.Min; aggregate.Max = temperature &gt; aggregate.Max ? temperature : aggregate.Max; aggregate.Sum += temperature; aggregate.Count++; } var result = new List&lt;CityStatistics&gt;(); foreach ((string city, CityAggregate aggregate) in aggregates) { result.Add(new() { City = city, MinTemperature = aggregate.Min / 10.0, AverageTemperature = Math.Round(aggregate.Sum / 10.0 / aggregate.Count, 1), MaxTemperature = aggregate.Max / 10.0 }); } CityStatistics[] resultAsArray = result.ToArray(); return resultAsArray; } private class CityAggregate { public float Min { get; set; } = float.MaxValue; public float Max { get; set; } = float.MinValue; public float Sum { get; set; } public int Count { get; set; } } } </code></pre> <p>and here an implementation that uses the same structure, but in JavaScript:</p> <pre><code class="language-js">const measurementsEndpoint = &quot;https://kristoffer-strube.dk/API/not-the-measurment-endpoint/&quot; let responseAsText = undefined; async function work(input) { if (responseAsText == undefined) { let response = await fetch(measurementsEndpoint + input); responseAsText = await response.text(); } let aggregates = new Map(); for (line of responseAsText.split('\n')) { let parts = line.split(';'); let city = parts[0]; let temperature = parseFloat(parts[1]); let aggregate = aggregates.get(city); if (aggregate == undefined) { aggregate = { min: Number.MAX_VALUE, max: -Number.MAX_VALUE, sum: 0, count: 0 }; aggregates.set(city, aggregate); } aggregate.min = temperature &lt; aggregate.min ? temperature : aggregate.min; aggregate.max = temperature &gt; aggregate.max ? temperature : aggregate.max; aggregate.sum += temperature; aggregate.count++; } let result = []; aggregates.forEach((aggregate, city) =&gt; { result.push({ city: city, minTemperature: aggregate.min, averageTemperature: Math.round((aggregate.sum / aggregate.count + Number.EPSILON) * 10) / 10, maxTemperature: aggregate.max, }) }) return result; } </code></pre> <p>Common for the two implementations is that they cache the result from the API as a string. We do this for two reasons. We are not interested in comparing how fast JavaScript or .NET can download something in the browser. Secondly, download speed can vary a lot, which would add unnecessary noise to the results or the benchmark. We ran the .NET implementation with AOT compilation as I don't expect it to be comparable with the speed of JS without.</p> <p>Let's see the results.</p> <p><img src="https://kristoffer-strube.dk/images/average-city-temperature-aot.png" alt="Results from measuring the average running time for finding the average temperature of cities with different worker wrappers" /></p> <p>Not the result we were hoping for, but let's look at it anyway. None of the .NET workers were faster than the JS worker. I tried to dig deeper into the code and make some ad-hoc micro-benchmarks of the core parts, and it seems like JS is faster at most of them, even when we AOT compile. Some of the critical parts of performance are the lookups in the dictionary/map and the conversion from string to float. Both of these were faster in JS. My assumption is that the browsers have some efficient implementation that is not written in JS, which they use for these operations. It makes sense that the browser has efficient map implementations, as most browsers use the same underlying implementation for maps and objects. So, every time some attribute of an object in JS is accessed, it essentially equates to a map lookup. Furthermore, I expect that this is optimized for string keys as most attributes on objects are identified by a string key. For conversion from string to float, it also makes sense that the browsers have some efficient implementation they use for making this conversion for any input that is number typed or when parsing JSON with numbers in them.</p> <h3>Conclusion</h3> <p>Now, we have seen how we can make some work in the background using JS and Web Workers. Following that, we have seen 2 of the most popular Blazor wrappers for Web Workers that make it possible to evaluate some .NET code in a background thread. Next, we presented our own novel approach for making a .NET Web Worker, which uses the <code>wasm-experimental</code> workload. In the end, we compared three different equivalent pieces of work in JS and each of the three wrapper implementations. The first comparison looked at the performance of workloads that depend on large inputs, and for this, we saw that JS was the fastest but that our new approach for Web Workers outperformed the existing implementations. The general picture we saw from this was that there was a 2X overhead from using our Web Worker implementation compared to starting a JS worker from Blazor. Depending on your work, this might still make it worth using our implementation. You might be better equipped to maintain the .NET implementation or might not have an implementation available for JS. The next comparison was on CPU-intensive work. We first saw that JS was still faster, but after turning on AOT compilation for the .NET workers we saw that they all outperformed JS for sufficiently large workloads. Our .NET worker implementation still outperformed the others, but this time, it had the same scaling factor and only won due to a smaller startup overhead. The last benchmark was intended to represent some varied work involving reading and processing data. For this, we again saw that the JS worker was faster than the .NET workers, even with AOT on. We reasoned that JS probably uses some optimized subroutines for some of the most performance-heavy parts, which might be why it outperformed the .NET worker implementations. Even though JS outperformed .NET, it could still make sense to use .NET workers to keep your codebase coherent or if you don't have a JS implementation for the work you need to do. To conclude, using Web Workers in Blazor looks very promising, and I look forward to using this in some projects very soon. If you have any questions related to this article or our Worker implementation, feel free to reach out to me.</p> cancelling-long-running-jsinterop-callshttps://kristoffer-strube.dk/post/cancelling-long-running-jsinterop-calls/When making JSInterop calls in Blazor, the invocations can vary in duration depending on what function is invoked. If these invocations take a long time, we want to be able to cancel them if we no longer need to finish the task, i.e., if the user navigates away from the current page or actively cancels some action. It is possible to use the CancellationToken that we are all familiar with from async tasks in .NET, but this only makes it so that deserialization of the response is not handled if the invocation has already started. In this article, we will show how to cancel a JSInterop invocation in the middle of its invocation using the AbortController and AbortSignal types and present how the Blazor.DOM library makes this easy.Mon, 29 Apr 2024 00:00:00 +02002024-04-29T00:00:00+02:00<h3>Parsing a <code>CancellationToken</code> to invocations</h3> <p>As developers who are used to using async-await, we will try to see if an async method takes a <code>CancellationToken</code> when we want the ability to cancel tasks. We see that the async invocation tasks for <code>JSInterop</code> actually take a <code>CancellationToken</code> parameter. But this won't work. Let's check the source code and see what the <code>CancellationToken</code> is used for. First, we check the parameter description for <code>cancellationToken</code>.</p> <pre><code class="language-xml">&lt;param name=&quot;cancellationToken&quot;&gt; A cancellation token to signal the cancellation of the operation. Specifying this parameter will override any default cancellations such as due to timeouts (&lt;see cref=&quot;DefaultAsyncTimeout&quot;/&gt;) from being applied. &lt;/param&gt; </code></pre> <p>So, from the description, it seems like this makes it possible to cancel the invocation. But to go even deeper down the rabbit hole, let's see what it is used for. First, if the <code>CancellationToken</code> can be canceled, and this happens, it tries to set the state of the resulting task to canceled and cleans up the task and cancellation callback registration.</p> <pre><code class="language-csharp">if (cancellationToken.CanBeCanceled) { _cancellationRegistrations[taskId] = cancellationToken.Register(() =&gt; { tcs.TrySetCanceled(cancellationToken); CleanupTasksAndRegistrations(taskId); }); } </code></pre> <p>Then it does the same if the <code>CancellationToken</code> had already been cancelled so that we don't need to start the invocation if it was immediately canceled.</p> <pre><code class="language-csharp">if (cancellationToken.IsCancellationRequested) { tcs.TrySetCanceled(cancellationToken); CleanupTasksAndRegistrations(taskId); return new ValueTask&lt;TValue&gt;(tcs.Task); } </code></pre> <p>Then, it starts the invocation, which means we will have no more opportunities for the task to be stopped if a cancellation is requested before the JS function is done and calls back. If the source of the <code>CancellationToken</code> was canceled while the invocation happened, then the entire JS function will finish first. Then, when the method that receives the response is invoked, it checks whether the task callback has already been removed and exits early in that case.</p> <pre><code class="language-csharp">if (!_pendingTasks.TryRemove(taskId, out var tcs)) { // We should simply return if we can't find an id for the invocation. // This likely means that the method that initiated the call defined a timeout and stopped waiting. return false; } </code></pre> <p>This is great as we spared the work of deserializing the response, which could have been expensive, as we have seen in our previous post on <a href="https://kristoffer-strube.dk/post/a-holistic-comparison-of-blazor-wasm-performance-from-aspnet-core-5-to-8/">Blazor performance</a>. But this still doesn't enable us to cancel JS functions while they are running.</p> <h3>Cancelling using the <code>AbortController</code> and <code>AbortSignal</code></h3> <p>To support canceling a JS function, we need to parse something into it that it can use to check whether it should be stopped early. JS has a standard equivalent to the <code>CancellationToken</code> and <code>CancellationTokenSource</code> types: the <code>AbortSignal</code> and <code>AbortController</code> types. If we create an <code>AbortController</code>, we can get its <code>AbortSignal</code>. Using the <code>AbortController</code>, we can then abort the operation, and using the <code>AbortSignal</code>, we can check whether the operation has been canceled. The introduction of this has a similar history to that of the <code>CancellationToken</code> as it was not introduced when JS first got support for the async-await pattern. It was instead introduced later when we discovered that some operations would be nice to be able to abort. This also means that it is sadly not used in all APIs, as some APIs were standardized before its introduction. However, a lot of new APIs utilize it to cancel asynchronous operations.</p> <p>One API that utilizes the <code>AbortSignal</code> is the <a href="https://fetch.spec.whatwg.org/">Fetch API</a>. The fetch API standardizes ways to fetch resources in JavaScript. In Blazor WASM, the <code>HttpClient</code> is implemented so that it uses this API to make its requests, but we can also use the API directly without this abstraction. In JS, we can write the following to make a simple GET request:</p> <pre><code class="language-js">async function getCharacterInfo(characterNumber) { let response = await fetch(&quot;https://api.sampleapis.com/futurama/characters/&quot; + characterNumber); let json = response.json(); return json; } </code></pre> <p>The above sample URL returns some information about a character from Futurama and is actually pretty fast, but we could imagine that it was a slow endpoint and that we would like to abort the fetch request mid-way in some cases. To do this we simple need to specify some options for the optional <code>init</code> parameter for the fetch method.</p> <pre><code class="language-js">async function getCharacterInfo(characterNumber) { let abortController = new AbortController(); let abortSignal = abortController.signal; let requestInit = { &quot;signal&quot;: abortSignal }; let response = await fetch(&quot;https://api.sampleapis.com/futurama/characters/&quot; + characterNumber, requestInit); let json = response.json(); return json; } </code></pre> <p>In principle, the above is all we need. But currently, we cannot tell the <code>AbortController</code> that the action should be canceled as it is not exposed anywhere outside the function. There are multiple ways to achieve this. One way is to save the abort controllers in a map where the key is defined by some extra parameter like this:</p> <pre><code class="language-js">window.abortControllers = {}; async function getCharacterInfo(characterNumber, abortControllerKey) { let abortController = new AbortController(); window.abortControllers[abortControllerKey] = abortController; let abortSignal = abortController.signal; let requestInit = { &quot;signal&quot;: abortSignal }; let response = await fetch(&quot;https://api.sampleapis.com/futurama/characters/&quot; + characterNumber, requestInit); let json = response.json(); return json; } function abortFetch(abortControllerKey) { window.abortControllers[abortControllerKey].abort(); } </code></pre> <p>The above makes it possible to abort a fetch using some <code>abortControllerKey</code> to identify the operation that should be canceled. But this requires us to remember this arbitrary key and ensure that the key is unique. This also pollutes the global window with the <code>abortControllers</code> attribute that could potentially collide with attributes used by other libraries. One last problem with this solution is that the <code>AbortController</code>s would never be garbage collected as they continue to be referenced in the <code>abortControllers</code> map. To solve that problem, we would need to make a separate third call to remove the reference to the <code>AbortController</code> once the operation is finished.</p> <p>Let's instead use another approach that mitigates these problems. Instead of keeping the <code>AbortController</code> in a map, we could construct the <code>AbortController</code> outside the JS function and then parse it in as an <code>IJSObjectReference</code>. With this approach, our JS functions would look like this:</p> <pre><code class="language-js">async function getCharacterInfo(characterNumber, abortController) { let abortSignal = abortController.signal; let requestInit = { &quot;signal&quot;: abortSignal }; let response = await fetch(&quot;https://api.sampleapis.com/futurama/characters/&quot; + characterNumber, requestInit); let json = response.json(); return json; } function createAbortController() { return new AbortController(); } </code></pre> <p>This could then be used from Blazor like this:</p> <pre><code class="language-csharp">public partial class Index : IDisposable { private string age = &quot;&quot;; private int characterNumber = 1; private CancellationTokenSource? fetchCancellationTokenSource; [Inject] public required IJSRuntime JSRuntime { get; set; } public async Task UpdateCharacterAge() { age = &quot;&quot;; // Get CancellationToken. fetchCancellationTokenSource = new CancellationTokenSource(); CancellationToken token = fetchCancellationTokenSource.Token; // Create AbortController await using IJSObjectReference abortController = await JSRuntime.InvokeAsync&lt;IJSObjectReference&gt;(&quot;createAbortController&quot;); // Register that it should abort when the CancellationToken is canceled. token.Register(async () =&gt; { await abortController.InvokeVoidAsync(&quot;abort&quot;); }); // Make JS invocation. Character character = await JSRuntime.InvokeAsync&lt;Character&gt;(&quot;getCharacterInfo&quot;, token, characterNumber, abortController); // Reset the fetchCancellationTokenSource and set result. fetchCancellationTokenSource = null; age = character.Age; } public record Character(string Occupation, string Age); public void Dispose() { fetchCancellationTokenSource?.Cancel(); } } </code></pre> <p>This might seem like a lot of C# code, but I promise that it is less code than what would have been needed for the JS map-based solution that we saw the JS code for earlier. We use the <code>AbortController</code> and the <code>CancellationTokenSource</code> we discussed previously. They work nicely together. The <code>AbortController</code> ensures that we can exit the JS function early. The <code>CancellationTokenSource</code> ensures we don't use time to deserialize the <code>AbortError</code> that gets thrown when the JS function is aborted.</p> <h3>Using Blazor.DOM</h3> <p>In the above solution, we needed to write a function to construct an <code>AbortController</code>, and we needed to know that it had a function called <code>abort</code> used for aborting the <code>AbortController</code>. Another thing to point out is that we parsed the <code>AbortController</code> itself to the <code>getCharacterInfo</code> function when it really only needed the <code>AbortSignal</code>.</p> <p>I've implemented wrappers for the relevant types used in the above sample in my library <a href="https://github.com/KristofferStrube/Blazor.DOM">Blazor.DOM</a>. So let's try to rewrite the above sample to be a bit more strongly typed and minimal. Let's first make some changes to the JS part.</p> <pre><code class="language-js">async function getCharacterInfo(characterNumber, abortSignal) { let requestInit = { &quot;signal&quot;: abortSignal }; let response = await fetch(&quot;https://api.sampleapis.com/futurama/characters/&quot; + characterNumber, requestInit); let json = response.json(); return json; } </code></pre> <p>As you can see, we now need a lot less JS. We like this. The main difference is that <code>getCharacterInfo</code> takes the <code>abortSignal</code> directly instead of the <code>abortController</code>. This is nice as we really shouldn't be able to access the controller in the function as we could then potentially abort the controller from within the function, giving unwanted side effects or errors in our C# code. Apart from this, we have also removed the method that constructed an <code>AbortController</code> as we will no longer need to call this. Now, let's see the C# part.</p> <pre><code class="language-csharp">public partial class Index : IDisposable { private string age = &quot;&quot;; private int characterNumber = 1; private CancellationTokenSource? fetchCancellationTokenSource; [Inject] public required IJSRuntime JSRuntime { get; set; } public async Task UpdateCharacterAge() { age = &quot;&quot;; // Get CancellationToken. fetchCancellationTokenSource = new CancellationTokenSource(); CancellationToken token = fetchCancellationTokenSource.Token; // Create AbortController and AbortSignal await using AbortController abortController = await AbortController.CreateAsync(JSRuntime); await using AbortSignal abortSignal = await abortController.GetSignalAsync(); // Register that it should abort when the CancellationToken is canceled. token.Register(async () =&gt; { await abortController.AbortAsync(); }); // Make JS invocation. Character character = await JSRuntime.InvokeAsync&lt;Character&gt;(&quot;getCharacterInfo&quot;, token, characterNumber, abortSignal); // Reset the fetchCancellationTokenSource and set result. fetchCancellationTokenSource = null; age = character.Age; } public record Character(string Occupation, string Age); public void Dispose() { fetchCancellationTokenSource?.Cancel(); } } </code></pre> <p>It has not changed much, apart from the fact that we now use strongly-typed types from the <a href="https://www.nuget.org/packages/KristofferStrube.Blazor.DOM">KristofferStrube.Blazor.DOM</a> NuGet package.</p> <h3>Other JS functions that can be aborted</h3> <p>We have now seen one sample of a JS function that can be aborted and understand how we can parse an <code>AbortSignal</code> to it to have the option to stop the JS function before it finishes. We also understand how to create this <code>AbortSignal</code> in C# and signal it to abort. So, to better understand how we can use this, let's see some other samples of JS functions to cancel.</p> <h4>Infinite loop</h4> <pre><code class="language-js">async function infiniteLoop(abortSignal) { while(!abortSignal.aborted) { console.log(&quot;Do some actual work forever in 1 second intervals.&quot;); await new Promise(r =&gt; setTimeout(r, 1000)); } } </code></pre> <p>If we have some infinite loop that ensures that some function is called forever with some interval, we also need to be able to stop the loop. For this, we can use that the <code>AbortSignal</code> has an attribute that tells us whether the signal has been aborted.</p> <h4>Piping ReadableStream</h4> <pre><code class="language-js">function compressReadableStream(readableStream, abortSignal) { let compressionStream = new CompressionStream(&quot;gzip&quot;); let compressed = readableStream.pipeThrough(compressionStream, { &quot;signal&quot;: abortSignal }); return compressed; } </code></pre> <p>Another API that incorporates the <code>AbortSignal</code> is the <a href="https://streams.spec.whatwg.org/">Streams API</a>. When we pipe some readable stream to a writable stream or through a transformer, we can parse options to the function, enabling us to abort it. This is a good use case as a <code>ReadableStream</code> could potentially be large or even infinite.</p> <h3>Conclusion</h3> <p>In this article, we explored the source code of JSInterop to see what it does when we parse a <code>CancellationToken</code> to it. We introduced the <code>AbortController</code> and <code>AbortSignal</code> types and used them together with the Fetch API to cancel a potentially long-lived operation. Then we saw how we can use the <a href="https://github.com/KristofferStrube/Blazor.DOM">Blazor.DOM</a> library to make some of this easier and simpler. In the end, we quickly took a look at some other scenarios where we could use <code>AbortSignal</code>s. If you have any questions related to the article or use cases I did not cover, feel free to reach out to me.</p> a-holistic-comparison-of-blazor-wasm-performance-from-aspnet-core-5-to-8https://kristoffer-strube.dk/post/a-holistic-comparison-of-blazor-wasm-performance-from-aspnet-core-5-to-8/Every year, many small improvements are made to .NET and ASP.NET Core that combined make the framework perform even better. Understanding what these improvements will mean in everyday use cases can be difficult. We could dissect all the improvements individually and make statements like "Indexing in arrays has become 4000% faster when you do X!" or some other absurd comparison. But what I find just as interesting is how much faster some common tasks consisting of many operations executed in a concrete context have become. In this article, we will attempt to compare the performance of a varied set of tasks in Blazor WASM with and without AOT from ASP.NET Core 5 up to 8.Thu, 25 Jan 2024 00:00:00 +01002024-01-25T00:00:00+01:00<h3>The sample project</h3> <p>I have tried to make a sample project that represents some common work. For this, I started with my relatively new <a href="https://github.com/KristofferStrube/DocumentSearching">DocumentSearching</a> repository that implements a Suffix Trie for document searching. This is one of the simplest approaches for indexing text so that it is faster to search for all indexes of any substring in an input string. Below is a demo of what using this index can look like. You can try out this demo yourself here: <a href="https://kristofferstrube.github.io/DocumentSearching/">https://kristofferstrube.github.io/DocumentSearching/</a></p> <p><video width="800px" src="https://kristoffer-strube.dk/videos/search-periodic-table.mp4" autoplay muted controls loop></video></p> <p>The implementation is pretty naive (let's say that's intentional), so constructing the index reads through the input text many times, making it a rather intensive operation. Since the construction is expensive, it will make sense to save the constructed index somewhere in some cases so that it simply needs to be read to be ready for use. Inspired by this use case, I made a series of 7 tasks representing some common tasks.</p> <h4>Read CSV</h4> <p>We need some text to search in before constructing the search index itself. For this, I have found a CSV file containing descriptions for all the elements of the Periodic Table as a sample of something to search through. We will load this file using a <code>HttpClient</code> and then parse it using <a href="https://joshclose.github.io/CsvHelper/">CsvHelper</a>. To limit the size of this test, we will only load the descriptions of the first 10 elements. The summaries of the first 10 elements consist of 3026 characters. We place a scope around this part so that the <code>StreamReader</code> and <code>CsvReader</code> get disposed of before measuring the time.</p> <pre><code class="language-csharp">{ Stream periodicTableCsv = await HttpClient.GetStreamAsync(&quot;data/periodic-table-detailed.csv&quot;); using StreamReader streamReader = new StreamReader(periodicTableCsv); using CsvReader csv = new(streamReader, CultureInfo.InvariantCulture); elements = csv.GetRecords&lt;Element&gt;().Take(10).ToArray(); } </code></pre> <h4>Construct Index</h4> <p>Using the entries from the CSV file, we will then construct the search index using the <code>DocumentIndex</code> class from the repository. I have made a branch of the repository where the class library targets .NET 5 so that it can be used in all the versions we run tests for. The branch is here: <a href="https://github.com/KristofferStrube/DocumentSearching/tree/experiment/aspnetcore5">DocumentSearching/experiment/aspnetcore5</a>. With the <code>DocumentIndex&lt;Element&gt;.Create</code> method, we create an index over all the summary for each element. We lower the summary text so that we don't need to think about the casing as long as we also lower our search query.</p> <pre><code class="language-csharp">index = DocumentIndex&lt;Element&gt;.Create(elements, e =&gt; e.Summary.ToLower()); </code></pre> <h4>JSON Serialize</h4> <p>We will then serialize the search index. The Suffix Trie, the index's main part, consists of a large hierarchy of <code>Node</code> classes that point to each other. This is not unlike the very large models that some send between their clients and servers when the users work with complex models.</p> <p>We define the following serialization options object outside the main test loop for this and the deserialization.</p> <pre><code class="language-csharp">private readonly JsonSerializerOptions serializerOptions = new() { ReferenceHandler = ReferenceHandler.Preserve }; </code></pre> <p>And then use it like this when serializing:</p> <pre><code class="language-csharp">string serialized = JsonSerializer.Serialize(index, serializerOptions); </code></pre> <h4>Write to LocalStorage</h4> <p>Next, we need to save it somewhere. We will use JSInterop to write the serialized index to LocalStorage for this. This is also a common part of many Blazor WASM applications that rely on APIs from the browser through JSInterop to deliver a rich experience.</p> <pre><code class="language-csharp">JSRuntime.InvokeVoid(&quot;window.localStorage.setItem&quot;, &quot;index&quot;, serialized); </code></pre> <h4>Read from LocalStorage</h4> <p>In a real use case, we could imagine that we had left the site and revisited it. So, we need to read the serialized index back from LocalStorage. For this, we likewise use JSInterop to read the string back. I don't expect this to be very different from the writing to LocalStorage, but it completes the story.</p> <pre><code class="language-csharp">string readIndex = JSRuntime.Invoke&lt;string&gt;(&quot;window.localStorage.getItem&quot;, &quot;index&quot;); </code></pre> <h4>JSON Deserialize</h4> <p>Now, we reconstruct the search index from the previously serialized string. It is not uncommon to talk with some JSON-based API in a Blazor WASM application, which also involves a lot of deserialization. Depending on how data-driven your site is, this might be a hot-path in your application.</p> <pre><code class="language-csharp">DocumentIndex&lt;Element&gt; deserializedIndex = JsonSerializer.Deserialize&lt;DocumentIndex&lt;Element&gt;&gt;(readIndex, serializerOptions); </code></pre> <h4>Search</h4> <p>With the index back, we can perform some searches in the elements. I have chosen to search for 10 words that I know appear in the summaries of the first 10 elements. The search is so fast that the <code>Stopwatch</code> class I'm using for my timings wouldn't be able to measure 10 searches alone, so I'm putting these 10 searches in a loop that iterates 10 times so that we have something comparable. When searching, the index does a lot of equality checks and lookups in arrays to find the matching indexes, which could mimic the work done in applications that evaluate a lot of business logic on the client side.</p> <pre><code class="language-csharp">for (int j = 0; j &lt; 10; j++) { searchResults = deserializedIndex.ExactSearch(&quot;hydrogen&quot;); searchResults = deserializedIndex.ExactSearch(&quot;oxygen&quot;); searchResults = deserializedIndex.ExactSearch(&quot;light&quot;); searchResults = deserializedIndex.ExactSearch(&quot;heavy&quot;); searchResults = deserializedIndex.ExactSearch(&quot;chemical&quot;); searchResults = deserializedIndex.ExactSearch(&quot;element&quot;); searchResults = deserializedIndex.ExactSearch(&quot;symbol&quot;); searchResults = deserializedIndex.ExactSearch(&quot;atomic&quot;); searchResults = deserializedIndex.ExactSearch(&quot;number&quot;); searchResults = deserializedIndex.ExactSearch(&quot;weight&quot;); } </code></pre> <h3>Testing</h3> <p>I ran the steps above in their natural order inside a loop that repeated 110 times. I timed how fast each part took using the <code>Stopwatch</code> class by starting one and then measuring how many milliseconds passed. After collecting 110 measurements for each part, I removed the first and last 5 measurements and calculated the minimum, average, and maximum values. This is not a recommendation for how to make benchmarks for Blazor WASM, as many factors can influence the results when other work is done on the computer simultaneously. But it is better than simply measuring the time once.</p> <p>The following is the main loop that we will execute in our tests:</p> <pre><code class="language-csharp">private Element[] elements = default!; private DocumentIndex&lt;Element&gt; index = default!; private SearchResult&lt;Element&gt;[] searchResults = []; public async Task Start() { for (int i = 0; i &lt; 110; i++) { // Read CSV // Construct Index // JSON Serialize Index // Write to LocalStorage // Read from LocalStorage // JSON Deserialize Index // Search for words in summaries. // Cleanup elements = default!; index = default!; JSRuntime.InvokeVoid(&quot;window.localStorage.clear&quot;); searchResults = []; await Task.Delay(200); } } </code></pre> <p>At the end of every loop cycle, we also do some cleanup. Most of it is simple: returning the intermediate variables to their initial values. We also clear LocalStorage so it is empty at the start of every iteration. We also make a 200-millisecond delay. This is so that the runtime gets time to run any garbage collection it needs to perform and to ensure that the UI does not become unresponsive when using the single thread available in Blazor WASM for long periods.</p> <p>After running the loop, we get the aforementioned statistics from all the collections of measurements. We do this by parsing the collections to the following method that formats the statistics we are interested in before we output them for each part of the loop.</p> <pre><code class="language-csharp">private string GetStatistics(List&lt;double&gt; timings) { double[] middleTimings = timings.Skip(5).SkipLast(5).ToArray(); double min = Math.Round(middleTimings.Min(), 2); double average = Math.Round(middleTimings.Average(), 2); double max = Math.Round(middleTimings.Max(), 2); return $&quot;Min: {min} ms; Average: {average} ms; Max: {max} ms;&quot;; } </code></pre> <p>I will use the fastest of the 100 measurements in the plots I make later, so it wasn't necessary to throw away the first and last 5 as they could only be slower than the rest depending on how the runtime optimizes the loop. But it still makes sense to skip these to get a more meaningful insight into a long-running process's average and maximum values. Here is an example of the minimal, average, and maximal measurements made for the test project targeting ASP.NET Core 5 with .NET 5 published with the standard release configuration:</p> <pre><code class="language-bash">Read CSV: Min: 5.8 ms; Average: 9.77 ms; Max: 29.3 ms; Construct Index: Min: 5.7 ms; Average: 6 ms; Max: 7.9 ms; JSON Serialize: Min: 331 ms; Average: 336.53 ms; Max: 349.2 ms; Write LocalStorage: Min: 208.4 ms; Average: 211.46 ms; Max: 220.8 ms; Read LocalStorage: Min: 239.4 ms; Average: 242.46 ms; Max: 255.8 ms; JSON Deserialize: Min: 1041.7 ms; Average: 1052.56 ms; Max: 1093.3 ms; Search: Min: 12.5 ms; Average: 12.87 ms; Max: 17.3 ms; </code></pre> <p>I had expected that the measurements would vary a lot more. If we look at the proximity of the min values and average values, we see that they are generally pretty close. Without doing any statistical analysis, this tells me that most measurements are close to the minimum value.</p> <h3>Test scenarios</h3> <p>I started by making a sample Blazor WASM project that targeted .NET 5. In this, I created a page with the above methods defined. It is really easy to upgrade a Blazor WASM project from .NET 5 and ASP.NET Core 5 up to 8. It is just to update the versions of the Blazor-specific NuGet packages to match the selected .NET version. Apart from this, we also want to try out AOT for all the versions of Blazor WASM that support it. Actually, of the versions we want to test, only Blazor in ASP.NET Core 5 didn't have it yet. But that is fine, as it simply re-iterates how great a jump AOT was when introduced in .NET 6. To configure the application to use AOT, we only need to add the following to the csproj:</p> <pre><code class="language-xml">&lt;RunAOTCompilation&gt;true&lt;/RunAOTCompilation&gt; </code></pre> <p>Now, we are ready to run our tests. We are going to run tests on the following configurations:</p> <ul> <li>.NET 5 - ASP.NET Core 5.0.17 Release</li> <li>.NET 6 - ASP.NET Core 6.0.26 Release</li> <li>.NET 6 - ASP.NET Core 6.0.26 Release AOT</li> <li>.NET 7 - ASP.NET Core 7.0.15 Release</li> <li>.NET 7 - ASP.NET Core 7.0.15 Release AOT</li> <li>.NET 8 - ASP.NET Core 8.0.0 Release</li> <li>.NET 8 - ASP.NET Core 8.0.0 Release AOT</li> </ul> <p>You can find the ASP.NET Core 5 base project that we will upgrade to each of the above configurations here: <a href="https://github.com/KristofferStrube/DocumentSearching/tree/experiment/aspnetcore5/samples/KristofferStrube.DocumentSearching.BlazorWasm5">KristofferStrube.DocumentSearching.BlazorWasm5</a></p> <h3>Results</h3> <p>And now for the results! I have made some plots presenting the results for each part,</p> <h4>Read CSV</h4> <p>Reading the CSV had some improvement when moving to ASP.NET Core 6, but it did not seem like AOT has a large impact in this version. Surprisingly, ASP.NET Core 7 performed worse but did have another great jump in performance for AOT. In ASP.NET Core 8, we got the standard release down to the same level that we had in 6 and matched the AOT level of 7, so it seems like the greatest of both versions. Generally, there are not any huge improvements, which makes sense as there are other network-related constraints to reading a file fast with a <code>HttpClient</code>.</p> <p><img src="https://kristoffer-strube.dk/images/read-csv.png" alt="Plot showing the performance of reading CSVs in different versions of Blazor WASM" /></p> <h4>Construct Index</h4> <p>Constructing the search index also improved when moving to ASP.NET Core 6. Though, again not a huge difference with and without AOT. Then, at ASP.NET Core 7, we see a huge improvement for AOT and again see an actual regression in the standard release. As for ASP.NET Core 8, we again remain around the same level for AOT but have a nice catchup for the non-AOT that is now twice as fast as the ASP.NET Core 6 AOT version.</p> <p><img src="https://kristoffer-strube.dk/images/construct-index.png" alt="Plot showing the performance of constructing a search index in different versions of Blazor WASM" /></p> <h4>JSON Serialize</h4> <p>Serializing the search index seems to have followed an almost identical pattern of improvements. I had expected this to have a much greater percentage improvement as we have heard a lot about the improvements made to System.Text.Json throughout every release. But if we instead look at the absolute improvement of the task, this is a pretty impressive improvement, cutting a serialization task that previously took more than 300 milliseconds, which is a great enough delay for a person to perceive it, down to less than 25 milliseconds in ASP.NET Core 8 with AOT.</p> <p><img src="https://kristoffer-strube.dk/images/json-serialize.png" alt="Plot showing the performance of JSON serializing in different versions of Blazor WASM" /></p> <h4>Write LocalStorage</h4> <p>Again, it is a similar picture to what we had in the two other parts when we look at the performance of writing to LocalStorage. The one noticable thing is that writing to LocalStorage in ASP.NET Core 6 AOT is much better than its non-AOT counterpart. So, it seems that JSInterop is especially receptive to AOT's optimizations.</p> <p><img src="https://kristoffer-strube.dk/images/write-localstorage.png" alt="Plot showing the performance of writing to LocalStorage with JSInterop in different versions of Blazor WASM" /></p> <h4>Read LocalStorage</h4> <p>I had expected that returning values from JSInterop would be consistently slower than writing as we need to allocate a new string. But it seems like they are close to being equally matched. The one surprising thing to notice is that reading in ASP.NET Core 6 AOT is more than twice as fast as writing. I will definitely have this in the back of my mind when I make systems that are JSInterop intensive in the future.</p> <p><img src="https://kristoffer-strube.dk/images/read-localstorage.png" alt="Plot showing the performance of reading from LocalStorage with JSInterop in different versions of Blazor WASM" /></p> <h4>JSON Deserialize</h4> <p>The JSON deserialization is the slowest of all the parts. I assume that this is because deserialization relies heavily on reflection combined with some good old string parsing. That we start off with having the deserialization take more than a second in ASP.NET Core 5 only makes it even more impressive that we got down below 50ms in the ASP.NET Core 8 AOT release.</p> <p><img src="https://kristoffer-strube.dk/images/json-deserialize.png" alt="Plot showing the performance of JSON deserializing in different versions of Blazor WASM" /></p> <h4>Search</h4> <p>And now to the final part that all the previous steps have led to. The search itself. In ASP.NET Core 6, AOT was slower than the non-AOT counterpart, which is a contradiction to what almost seems like a rule from the previous plots. But overall, they still follow the pattern we have seen in the other plots, i.e., that non-AOT has gotten better through all versions except ASP.NET Core 7 and that the AOT version gets better over time, where the one to 7 is the greatest jump.</p> <p><img src="https://kristoffer-strube.dk/images/search.png" alt="Plot showing the performance of searching with constructed search index in different versions of Blazor WASM" /></p> <h3>Conclusion</h3> <p>Now, we have seen how fast some common tasks are performed in Blazor WASM with different versions of ASP.NET Core. A couple of tests did not have the outcome I had expected before I started the experiments. The greatest surprise is how ASP.NET Core 7 non-AOT was worse than 6 in almost all tasks. I want to explore the source of this in the future as it seems like something others should have reported on before me. Apart from this, I also found that JSON is not a valid serialization mechanism for the sample use case we created, as it was the limiting part across all the different ASP.NET Core versions we tested. But it was okay as a sample. I can't wait to see what improvements we will see in ASP.NET Core 9 when we get the first previews pretty soon. I do a lot of JSInterop, so I especially hope for more improvements to that both for AOT and non-AOT, as only Blazor WASM can employ AOT.</p> reading-notes-from-performance-improvements-in-dotnet-8https://kristoffer-strube.dk/post/reading-notes-from-performance-improvements-in-dotnet-8/For the last couple of years, Stephen Toub has posted about the performance improvements coming to the next release of .NET. People have jokingly called these posts "books" because they are very long, and this year is no exception. This year, his post on .NET 8 is 221 pages if you print the entire post with no margins and it's packed with interesting details. At my current day job, I work with practical data-intensive systems in .NET where improvements like the ones Stephen Toub presents can have a huge impact. In this post, I will share my reading notes from Stephen Toub's post on Performance Improvements in .NET 8 to give you a quick insight into what I found interesting. I especially found the improvements made to the JIT compiler interesting, so I will primarily touch on those.Tue, 26 Sep 2023 00:00:00 +02002023-09-26T00:00:00+02:00<p>I will only summarize and explain the parts that I found especially useful or interesting. That means I have not covered all parts of his post. If you want an overview of all improvements, then I very much recommend that you read his full post: <a href="https://devblogs.microsoft.com/dotnet/performance-improvements-in-net-8/">Performance Improvements in .NET 8 by Stephen Toub - MSFT</a></p> <h3>Dynamic PGO</h3> <p>I think the greatest improvement to .NET 8 is Dynamic PGO (Profile-Guided Optimization). The concept is not new to .NET 8, but .NET 8 is the first version where Dynamic PGO is turned on by default. So, what we get now in .NET 8 is actually the result of all the improvements and refinements made to Dynamic PGO since it was first introduced as a preview feature in .NET 6.</p> <p>In broad terms, Dynamic PGO enables the JIT (Just-In-Time) compiler to observe which parts of the program are run the most while the program is running in production. It can then re-compile the parts that get run the most to make them more efficient when they are run in the future. You might ask, <em>&quot;Why not compile all parts of the program to be the most efficient before it starts?&quot;</em>. The answer to this question has multiple facets.</p> <p><strong>Long startup time</strong>: If the JIT compiler should try to compile all parts of the program before the program starts, then you might experience a very long startup time. If you have ever tried to run an AOT (Ahead Of Time) compilation of a program, then you know this can take a very long time. And the worst part is that it would use valuable time on compiling methods to be effective even though you might only run it once.</p> <p><strong>Loss of insight</strong>: When the program has already started, the JIT can get a greater insight into the actual values of certain fields and make smarter decisions. Stephen Toub gives an example of a <code>static readonly bool</code> which, once initialized, gets some value that could then be handled as a <code>const</code> when that code gets re-compiled, making the access to that faster while opening up for constant-inlining in places that it is used.</p> <p>But how does it know what parts of the code get hit the most? They count how many times each method (and some other smaller parts) gets called. The JIT adds some instrumentation to all methods when it makes its first non-optimized compilation. This instrumentation is simply some code that increments by <code>1</code> every time that code is called. Then if this count hits some threshold for a method, the JIT will take the time to re-compile this to be more effective. A rather ingenious detail to this is that it also works when you work with multiple threads. Normally, when you try to increment the same number from multiple threads, we either get race conditions, meaning some of the increments will be lost, or we need to take a lock before reading and writing the number, which causes a huge performance penalty as the threads will have to wait for each other.</p> <p>They solved this using randomization. They start by using the lock method, but then once the count surpasses <code>8192</code> (<code>2^13</code>), they switch to the non-locking method but only does the increment <code>50%</code> of the time decided by a random source but then increase it with <code>2</code> instead of <code>1</code> when it happens to minimize the chance of a race condition happening. Once it increases above <code>16384</code> (<code>2^14</code>) they do this once more, changing the probability of the increment happening to <code>25%</code> with the increment step being <code>4</code>. This continues for larger and larger numbers. This maintains a rather precise estimation of the actual count with minimal delay and performance penalty.</p> <h3>GDV (Guarded Devirtualization)</h3> <p>The above counting trick is not only used to check which methods are called the most. It also checks which concrete types are used most often in places where virtual and interface types are used. The JIT then uses this information to generate a <em>fast path</em> for that concrete type. A fast path means that it adds a direct check for that type and then makes the invocation directly using that type if the type matches, and else makes the implementation lookup as normal. That's why it's called <em>Guarded</em> as we first guard for that common type. It does this for the single most used type, but it is possible to set the number of direct guards checks to another limit by setting the environment variable <code>DOTNET_JitGuardedDevirtualizationMaxTypeCheck</code>.</p> <h3>Vectorization</h3> <p>A trend over the last couple of .NET versions has been improvements to Vectorization. * drom rolls * and the trend continues!</p> <p>Vectorization is when you utilize your hardware to do the same calculation to multiple numbers at once. .NET 7 added support for doing this for <code>128</code> and <code>256</code> bits at once. <code>256</code> bits are equivalent to <code>8</code> ints, so we could execute so-called SIMD (Single Instruction/Multiple Data) instructions on <code>8</code> ints, all in the same CPU cycle if the machine supports this. In .NET 8 they added support for vectorization of <code>512</code> bits, which means that we can make certain SIMD operations on <code>16</code> ints at once if the machine supports it. This means the execution time for simple arithmetic on large data arrays can be halved if the machine supports it. In .NET 7 these improvements were also utilized in the .NET standard <code>System.Linq</code> methods <code>Sum</code>, <code>Average</code>, <code>Min</code>, and <code>Max</code>. The <code>512</code> bit vectorization has likewise been added to these implementations in .NET 8 to make them even more efficient.</p> <h3>Branching</h3> <p>We say that the program branches whenever a program has multiple paths depending on some condition. The CPU tries to predict which way the program will branch depending on what it thinks is most likely and then continues decoding the instructions on the most likely path while the branch outcome is being evaluated. This is called branch prediction. When branch prediction fails, it can be expensive. To get around this, we want to do branch-free code so that the branch prediction can never fail (as there will be none). The JIT can now emit conditional move instructions, making branch-free code much easier. Specifically, it now recognizes the pattern <code>(b ? 1 : 0)</code> where <code>b</code> is a boolean expression to be branchless. If we look at the following method:</p> <pre><code class="language-csharp">private int ModifyForRelevance(int score, bool isNew) { if (isNew) { return score * 3; } else { return score * 2; } } </code></pre> <p>This could be rewritten to the following to be branch-free in .NET 8:</p> <pre><code class="language-csharp">private int ModifyForRelevance(int score, bool isNew) { return (isNew ? 1 : 0) * score * 3 + (isNew ? 0 : 1) * score * 2; } </code></pre> <p>But that the code is branch-free doesn't mean it is more efficient. The first version of the method would generate a lot less code and would need fewer calculations, as we will always calculate both branches in the second version. So, for now, you probably shouldn't go out and use the <code>(b ? 1 : 0)</code> pattern in all parts of your code. This can be useful, though, when making methods that always take the same amount of time to execute. I don't think Stephen Toub touches on concrete use cases for this. But one such use case is to make constant-time implementations of cryptographic algorithms to prevent timing attacks.</p> <h3>Bounds Checking</h3> <p>When accessing arrays, the JIT generates checks for the bounds of the arrays that throw the well-known <code>IndexOutOfRangeException</code> if you read outside the array by accident. But sometimes we know that the index we access can't possibly be outside the bounds. In .NET 8 the JIT understands more of these cases so that unnecessary checks are omitted from the emitted IL code. Stephen Toub gives multiple realistic examples of this:</p> <pre><code class="language-csharp">private int GetBucket(int[] buckets, int hashcode) =&gt; buckets[(uint)hashcode % buckets.Length]; </code></pre> <p>The above indexes into an array using a large hash that might be larger than the actual size of the array. They use the modulus operator to get it within the bounds to get around this. This also means that it can never get outside the bounds, so the JIT doesn't need to generate the code that throws the <code>IndexOutOfRangeException</code>. Here is another example that has benefited from this:</p> <pre><code class="language-csharp">private bool IsQuoted(string s) =&gt; s.Length &gt;= 2 &amp;&amp; s[0] == '&quot;' &amp;&amp; s[^1] == '&quot;'; </code></pre> <p>The method first checks that the string is longer than <code>2</code> characters, as we can't have a quoted string shorter than <code>2</code> characters. In .NET 7 the JIT already recognized that the next sub-expression wouldn't need to make a bound check as it knew that the <code>0</code> index is safe to access when the array is <code>2</code> characters long. The new thing in .NET 8 is that it also recognizes that the last expression doesn't need bound checks as it knows that accessing the last element in the array is safe as there only needs to be at least <code>1</code> element in the array for this to be valid.</p> <h3>Constant Folding</h3> <p>Constant folding is when the JIT can take an expression that only consists of constants and precompute the expression as it will always give the same result. .NET 8 has made many improvements to constant folding that make it able to recognize more types as being constant, and then employ the folding on these. From what I gathered from the post the most important feature is the support for constant folding of the lengths of <code>ReadOnlySpan</code>, <code>string</code>, and any type of array. This plays nicely together with the bounds-checking improvements as the JIT can now inline the length of a constant string as a constant itself which again means that it can access parts of the string within its bounds before even compiling, essentially compacting the whole expression to its result before emitting the IL code for that part. The following is a somewhat simple sample:</p> <pre><code class="language-csharp">private static readonly string cat = &quot;CAT&quot;; private bool CatEndsWithT() =&gt; cat.Length == 3 &amp;&amp; (cat[^1] | 0x20) == 't'; </code></pre> <p>The <code>CatEndsWithT</code> method would previously have needed to check for the length of the string <code>cat</code> both in the first sub-expression and when accessing the last element in the string. But now in .NET 8 the entire method can return <code>true</code> without looking at the string because of constant folding.</p> <h3>Non-GC Heap</h3> <p>.NET 8 introduces a new heap, the Non-GC Heap. It is not something that most developers will use explicitly, but the JIT will use it in multiple scenarios. The Non-GC Heap is a heap parallel to the Garbage Collected heap, which the Garbage Collector will not manage. It is intended for memory that is not going to change throughout the lifetime of the application. .NET uses this to store constants and literals so that the JIT can point to them directly in the Non-GC Heap instead of first having to find out where it is in the normal heap as that can be re-arranged when the Garbage Collector cleans up memory. This means that the following things can now be referenced directly, which saves one move instruction:</p> <ul> <li>String Literals</li> <li><code>typeof(T)</code> for types that are not dynamically loaded.</li> <li><code>Array.Empty&lt;T&gt;()</code> again for types not dynamically loaded.</li> <li>Value types in static fields (which were previously boxed).</li> </ul> <h3>Closing notes</h3> <p>Now, we have seen the improvements I found most insightful from Stephen Toub's post. And I restate that you should read his full post to get all the details. There were, of course, parts that I didn't cover in this post. Many of the areas I didn't cover focus on improvements to different kinds of arrays/collections and common actions involving these. I would especially like to use spans more, as they bring many benefits. And obviously, I'm also very interested in the improvements that influence Blazor WASM. But I think I will cover that in another post.</p> blazor-svgeditor-releasedhttps://kristoffer-strube.dk/post/blazor-svgeditor-released/One of my first big Open Source projects was my Blazor SVG Editor. This project lets users edit SVG definitions in a graphical interface, all from Blazor. The users can edit and navigate existing SVGs from the editor using common user interactions like panning, zooming, translating, and scaling. They can likewise change details of the SVG elements that don't have a natural mapping and create new elements using an extensive context menu. I've seen multiple projects that have used the project or parts of it to construct some cool interactive UIs. So I figured I wanted to make it possible for more people to use it by releasing it as a component library on NuGet. In this article, we will look at what features the Blazor SVG Editor NuGet package brings out of the box and how you can extend the functions of the base library to make your own interactive graphical tool.Wed, 26 Jul 2023 00:00:00 +02002023-07-26T00:00:00+02:00<h3>Features</h3> <p>Before we look at how we can use the package, we will go through some of the central features of the editor, accompanied by some small videos that show those features.</p> <p>You can find the project on GitHub: <a href="https://github.com/KristofferStrube/Blazor.SVGEditor">https://github.com/KristofferStrube/Blazor.SVGEditor</a></p> <p>You can find the package on NuGet: <a href="https://www.nuget.org/packages/KristofferStrube.Blazor.SVGEditor">KristofferStrube.Blazor.SVGEditor</a></p> <p>And you can demo all the below features in the online demo site: <a href="https://kristofferstrube.github.io/Blazor.SVGEditor/">https://kristofferstrube.github.io/Blazor.SVGEditor/</a></p> <h4>Setting input and getting updates</h4> <p>The editor parses the XML structure that SVGs are defined in to be able to edit every detail of an SVG. To make it possible for the library consumer to populate this initial value, the <code>Input</code> is exposed as a Parameter that needs to be set when the component is used. The component has another Parameter <code>InputUpdated</code> that you can set to listen for when changes happen to the underlying SVG code. This can be used to get a live view of the underlying code while you edit it.</p> <p><video width="600px" src="https://kristoffer-strube.dk/videos/svg-editor-listen-to-changes.mp4" autoplay muted controls loop></video></p> <h4>Editing shapes</h4> <p>The editor enables us to update all shapes. Among these shapes are lines, polygons, rectangles, and paths. Paths are especially complex to parse as they contain many instructions that can be used in many combinations.</p> <p><video width="600px" src="https://kristoffer-strube.dk/videos/svg-editor-edit-shapes.mp4" autoplay muted controls loop></video></p> <h4>Creating new shapes</h4> <p>The editor supports creating new shapes through its context menu and supports unique flows for easy creation for each of these shapes.</p> <p><video width="600px" src="https://kristoffer-strube.dk/videos/svg-editor-create-shapes.mp4" autoplay muted controls loop></video></p> <h4>Panning and zooming</h4> <p>Sometimes some fine details in the SVG would be easier to edit up close either because they are very small or because you need high precision. To support this, we enable you to zoom and move around the canvas using the scroll wheel and the mouse's middle button. These interactions are only supported for desktop as they rely on you having a mouse or at least some way to scroll. If you want to contribute to the project, then I have an open issue to add support for touch devices: <a href="https://github.com/KristofferStrube/Blazor.SVGEditor/issues/11" target="_blank">Blazor.SVGEditor Issue #11</a></p> <p><video width="600px" src="https://kristoffer-strube.dk/videos/svg-editor-panning-and-zooming.mp4" autoplay muted controls loop></video></p> <h4>Multi-select and area selection</h4> <p>The editor also enables the user to select multiple elements when editing by holding the <code>CTRL</code> key down while selecting. To select multiple items in an area, the user can hold down the left mouse button and drag to mark the desired elements, similar to selecting multiple files in the Windows file explorer.</p> <p><video width="600px" src="https://kristoffer-strube.dk/videos/svg-editor-multi-select.mp4" autoplay muted controls loop></video></p> <h4>Color selection</h4> <p>Using the context menu, the users can change the fill color of all shapes by picking a color from a modal. They can likewise change the color of the strokes (the outline of shapes) and other details related to the stroke.</p> <p><video width="600px" src="https://kristoffer-strube.dk/videos/svg-editor-color-selection.mp4" autoplay muted controls loop></video></p> <h4>Grouping and Ungrouping</h4> <p>SVG elements can be grouped using the <code>&lt;g&gt;</code> tag. When elements are grouped, the editor moves them together and disables the ability to edit them individually. After selecting one or more elements, you can create a new group using the context menu. You can likewise ungroup elements that are grouped together using the context menu.</p> <p><video width="600px" src="https://kristoffer-strube.dk/videos/svg-editor-grouping.mp4" autoplay muted controls loop></video></p> <h4>Copy, paste, remove, and re-order</h4> <p>The last core part of the editor is the ability to copy, paste, remove, and re-order elements. You can mark one or more elements and press copy to paste their content into your clipboard. Then you can click paste to insert a copy. If you had any item marked when you pasted, it would make sure to add the element just above that; otherwise, it will paste it in front of all items. You can likewise select any amount of items and press remove to remove them. The last function is under the menu called move, which gives options for moving elements back or forward in the render hierarchy.</p> <p><video width="600px" src="https://kristoffer-strube.dk/videos/svg-editor-copy-paste-remove.mp4" autoplay muted controls loop></video></p> <h4>Miscellaneous features</h4> <p>Some other features are also available in the editor but need more refinement. Among these are support for editing and creating linear gradients, editing and creating animations, and optimizing paths via the context menu and anchor movement interactions.</p> <h3>Customization</h3> <p>Now that we have seen what the editor can do out of the box let's see what we can do with it if we extend it. If you want to follow these steps yourself, you should start by following the <a href="https://github.com/KristofferStrube/Blazor.SVGEditor#getting-started">Getting Started section in the repository README</a>. If you don't want to follow these steps and just want to browse the nice videos, then that is also okay.</p> <p>The example customization we will make is a network editor consisting of nodes and connectors. Commonly known as a graph. To start, we create the following page to set up a minimal editor that doesn't support any elements, has no options for adding new elements, and has a subset of all our possible context menu features.</p> <pre><code class="language-razor">&lt;div style=&quot;height:80vh&quot;&gt; &lt;SVGEditor Input=@Input InputUpdated=&quot;(string s) =&gt; { Input = s; StateHasChanged(); }&quot;¨ SnapToInteger=true SupportedElements=SupportedElements AddNewSVGElementMenuItems=AddNewSVGElementMenuItems ActionMenuItems=ActionMenuItems /&gt; &lt;/div&gt; @code { protected string Input = @&quot;&quot;; protected List&lt;SupportedElement&gt; SupportedElements { get; set; } = new() { }; protected List&lt;SupportedAddNewSVGElementMenuItem&gt; AddNewSVGElementMenuItems { get; set; } = new() { }; protected List&lt;ActionMenuItem&gt; ActionMenuItems { get; set; } = new() { new(typeof(StrokeMenuItem), (_, data) =&gt; data is Shape shape &amp;&amp; !shape.IsChildElement), new(typeof(MoveMenuItem), (_, data) =&gt; data is Shape shape &amp;&amp; !shape.IsChildElement), new(typeof(GroupMenuItem), (_, data) =&gt; data is Shape shape &amp;&amp; !shape.IsChildElement), new(typeof(UngroupMenuItem), (_, data) =&gt; data is G g &amp;&amp; !g.IsChildElement), new(typeof(RemoveMenuItem), (svgEditor, data) =&gt; data is Shape &amp;&amp; !svgEditor.DisableRemoveElement), new(typeof(CopyMenuItem), (svgEditor, data) =&gt; data is Shape &amp;&amp; !svgEditor.DisableCopyElement), new(typeof(PasteMenuItem), (svgEditor, _) =&gt; !svgEditor.DisablePasteElement), }; } </code></pre> <h4>Node.cs</h4> <p>We will first make the classes and components needed to control, render, and add new nodes. This will build on the existing code we have created for editing Circles. We first add a class called <code>Node</code> that will handle how we interact with nodes and how we create new ones. We will later add more logic to this class to enrich its interaction with connectors.</p> <pre><code class="language-csharp">public class Node : Circle { public Node(IElement element, SVGEditor svg) : base(element, svg) { string? id = element.GetAttribute(&quot;id&quot;); if (id is null || svg.Elements.Any(e =&gt; e.Id == id)) { Id = Guid.NewGuid().ToString(); } } } </code></pre> <p>The class extends <code>Circle</code> as it shares most of its logic with it. The first thing we do in the constructor is to check if the SVG definition that the <code>Node</code> is constructed from has a unique <code>Id</code>, and if it doesn't, then assign a new <code>Id</code> to it so that we have a way to reference each node individually.</p> <p>Next we override the <code>Presenter</code> property to customize how we present the <code>Node</code> with a <code>NodeEditor</code> instead of using the inherited <code>CircleEditor</code>.</p> <pre><code class="language-csharp">public override Type Presenter =&gt; typeof(NodeEditor); </code></pre> <p>We also override the <code>R</code> property that defines the radius of the <code>Circle</code> so that it is always <code>50</code> but still enables the <code>R</code> to be set to something else.</p> <pre><code class="language-csharp">public new double R { get =&gt; 50; set =&gt; base.R = value; } </code></pre> <p>Next, we override the <code>Stroke</code> property of the <code>Circle</code> so that it also updates the <code>Fill</code>. This aims to limit the user's options for editing the nodes to give a more homogeneous visual look.</p> <pre><code class="language-csharp">public override string Stroke { get =&gt; base.Stroke; set { base.Stroke = value; int[] parts = value[1..].Chunk(2).Select(part =&gt; int.Parse(part, System.Globalization.NumberStyles.HexNumber)).ToArray(); Fill = &quot;#&quot; + string.Join(&quot;&quot;, parts.Select(part =&gt; Math.Min(255, part + 50).ToString(&quot;X2&quot;))); } } </code></pre> <p>Our goal is to set the <code>Fill</code> to a color that is a bit lighter than the newly set <code>Stroke</code> color. We know the <code>Stroke</code> will always be set using a 6-character long hex value prepended by a pound sign <code>'#'</code>. To increase the color brightness, we chunk the 6 characters into chunks of 2 characters, each representing one of the color parts, i.e., red, green, and blue. We parse these chunks as hex values and use these parsed values to construct the <code>Fill</code> color. To do this, we just join the parts back together as 2-digit hex values but increase the intensity of each color by 50, capped at 255 as that is the largest possible 2-digit hex value.</p> <p>The last part we add to the <code>Node</code> class right now is a method for adding a new <code>Node</code>.</p> <pre><code class="language-csharp">public static new void AddNew(SVGEditor SVG) { IElement element = SVG.Document.CreateElement(&quot;CIRCLE&quot;); element.SetAttribute(&quot;data-elementtype&quot;, &quot;node&quot;); Node node = new(element, SVG) { Changed = SVG.UpdateInput, Stroke = &quot;#28B6F6&quot;, R = 50 }; (node.Cx, node.Cy) = SVG.LocalDetransform(SVG.LastRightClick); SVG.ClearSelectedShapes(); SVG.SelectShape(node); SVG.AddElement(node); } </code></pre> <p>We first create the underlying XML element that the <code>Node</code> will use as its data underlying data structure. We set the attribute <code>data-elementtype</code> on this to <code>&quot;node&quot;</code> so that we can distinguish it from other <code>&lt;circle&gt;</code> tags.</p> <p>Then we construct a new <code>Node</code> from this that will trigger the <code>SVGEditors</code>´s <code>UpdateInput</code> method whenever it changes and set its <code>Stroke</code> color and radius to our defaults.</p> <p>We also set the center of the new <code>Node</code> to be the last place that the user has right-clicked so that it will appear near where they last used the context menu. The <code>SVGEditor</code> automatically keeps track of this position in the screen coordinate system. We might have panned around the SVG or zoomed in, so to get the original position in the coordinate system of the SVG, we parse the screen coordinate through the <code>SVGEditor</code> method <code>LocalDetransform</code> which can transform any point from the screen coordinate system to the SVG coordinate system.</p> <p>Lastly, we deselect all selected shapes, select the new <code>Node</code>, and add it to the <code>SVGEditor</code> using the <code>AddElement</code> method.</p> <h4>NodeEditor.razor</h4> <p>We defined that the <code>Node</code> should be presented by a <code>NodeEditor</code> component. We want something very close to how we present a <code>Circle</code>, but without the capability to edit the radius. That gives us the following component:</p> <pre><code class="language-razor">@using BlazorContextMenu @using KristofferStrube.Blazor.SVGEditor.ShapeEditors @using KristofferStrube.Blazor.SVGEditor.Extensions @inherits ShapeEditor&lt;Node&gt; &lt;ContextMenuTrigger MenuId=&quot;SVGMenu&quot; WrapperTag=&quot;g&quot; Data=@SVGElement MouseButtonTrigger=&quot;SVGElement.ShouldTriggerContextMenu ? MouseButtonTrigger.Right : (MouseButtonTrigger)4&quot;&gt; &lt;g transform=&quot;translate(@SVGElement.SVG.Translate.x.AsString() @SVGElement.SVG.Translate.y.AsString()) scale(@SVGElement.SVG.Scale.AsString())&quot;&gt; &lt;circle @ref=ElementReference @onfocusin=&quot;FocusElement&quot; @onfocusout=&quot;UnfocusElement&quot; @onpointerdown=&quot;SelectAsync&quot; @onkeyup=&quot;KeyUp&quot; tabindex=&quot;@(SVGElement.IsChildElement ? -1 : 0)&quot; cx=@SVGElement.Cx.AsString() cy=@SVGElement.Cy.AsString() r=@SVGElement.R.AsString() stroke=&quot;@SVGElement.Stroke&quot; stroke-width=&quot;@SVGElement.StrokeWidth&quot; stroke-linecap=&quot;@SVGElement.StrokeLinecap.AsString()&quot; stroke-linejoin=&quot;@SVGElement.StrokeLinejoin.AsString()&quot; stroke-dasharray=&quot;@SVGElement.StrokeDasharray&quot; stroke-dashoffset=&quot;@SVGElement.StrokeDashoffset.AsString()&quot; fill=&quot;@SVGElement.Fill&quot; style=&quot;filter:brightness(@(SVGElement.Selected ? &quot;0.8&quot; : &quot;1&quot;))&quot;&gt; &lt;/circle&gt; &lt;/g&gt; &lt;/ContextMenuTrigger&gt; </code></pre> <p>Another thing we have changed is that the circle tag applies a filter to darken its fill if selected. It extends the abstract <code>ShapeEditor</code> component that implements all its necessary logic.</p> <h4>AddNewNodeMenuItem.razor</h4> <p>We also need to define a simple menu item that we can use to add new nodes.</p> <pre><code class="language-razor">@using BlazorContextMenu &lt;Item OnClick=&quot;_ =&gt; Node.AddNew(SVGEditor)&quot;&gt; &lt;div class=&quot;icon&quot;&gt;⚫&lt;/div&gt; New Node &lt;/Item&gt; @code { [CascadingParameter] public required SVGEditor SVGEditor { get; set; } [Parameter] public required object Data { get; set; } } </code></pre> <p>The component will get a reference to the <code>SVGEditor</code> that it is used in through a <code>CascadingParameter</code>. It also gets initialized with reference to the item that was last right-clicked through the <code>Data</code> <code>Parameter</code>, if there was any. We don't use the <code>Data</code> property in our sample, but one way we could have used this would be to check if the last right-clicked element was a <code>Node</code>, and if it were, then use the same <code>Stroke</code> color. Instead, we simply invoke the <code>AddNew</code> method when the menu item is clicked.</p> <p>Let's add these new components and classes to our sample razor page and see how it looks. We add the <code>Node</code> class to our list of supported elements and specify that it should handle representing any tag that is a circle with the <code>data-elementtype</code> set to <code>&quot;node&quot;</code>.</p> <pre><code class="language-csharp">protected List&lt;SupportedElement&gt; SupportedElements = new() { new(typeof(Node), element =&gt; element.TagName is &quot;CIRCLE&quot; &amp;&amp; element.GetAttribute(&quot;data-elementtype&quot;) == &quot;node&quot;), }; </code></pre> <p>And we add the menu item for adding a new <code>Node</code> to our list of menu items for the &quot;Add New&quot; sub-menu and specify that the menu item should always be presented.</p> <pre><code class="language-csharp">protected List&lt;SupportedAddNewSVGElementMenuItem&gt; AddNewSVGElementMenuItems = new() { new(typeof(AddNewNodeMenuItem), (_,_) =&gt; true), }; </code></pre> <p>Now when we run the project, we will be able to view, edit and create nodes.</p> <p><video width="600px" src="https://kristoffer-strube.dk/videos/svg-editor-just-nodes.mp4" autoplay muted controls loop></video></p> <h4>Connector.cs</h4> <p>Now we are ready to add our connectors. We start of with creating a new class that extends the existing <code>Line</code> class.</p> <pre><code class="language-csharp">public class Connector : Line { public Connector(IElement element, SVGEditor svg) : base(element, svg) { UpdateLine(); } } </code></pre> <p>When it is initialized, we call a method that will update the position of the line. We also define a custom presenter for the <code>Connector</code> that slightly changes how it is presented and how a user can interact with it.</p> <pre><code class="language-csharp">public override Type Presenter =&gt; typeof(ConnectorEditor); </code></pre> <p>We will not set the connector's position directly by moving its endpoints. Instead, this will be controlled by which nodes it is connected to. We define two properties for this that will simplify how we can access and update them later. We first define which <code>Node</code> the connecter starts in.</p> <pre><code class="language-csharp">public Node? From { get { var from = (Node?)SVG.Elements.FirstOrDefault(e =&gt; e is Node &amp;&amp; e.Id == Element.GetAttribute(&quot;data-from&quot;)); _ = from?.RelatedConnectors.Add(this); return from; } set { if (From is { } from) { _ = from.RelatedConnectors.Remove(this); } if (value is null) { _ = Element.RemoveAttribute(&quot;data-from&quot;); } else { Element.SetAttribute(&quot;data-from&quot;, value.Id); _ = value.RelatedConnectors.Add(this); } Changed?.Invoke(this); } } </code></pre> <p>When we get the <code>From</code> <code>Node</code>, it finds the <code>Node</code> among all registered elements that also match the <code>Id</code> with the content of the <code>data-from</code> attribute of the connecter. After this, it adds this connector to a <code>HashSet</code> called <code>RelatedConnectors</code> on the <code>Node</code>. If we set the <code>From</code> <code>Node</code>, we remove the previous <code>From</code> <code>Node</code> from the <code>HashSet</code> and either remove the attribute if it was set to <code>null</code> or set it to the <code>Id</code> of the new <code>Node</code> and again adds the connector to the <code>HashSet</code>. We also invoke <code>Changed</code> as we have changed some a part of the SVG definition when we set this property. We will show what we have added to the <code>Node</code> class to support the <code>RelatedConnectors</code> <code>HashSet</code> in just a bit, but let's first show the code for the <code>To</code> property as that is almost identical to the <code>From</code> node.</p> <pre><code class="language-csharp">public Node? To { get { var to = (Node?)SVG.Elements.FirstOrDefault(e =&gt; e is Node &amp;&amp; e.Id == Element.GetAttribute(&quot;data-to&quot;)); _ = to?.RelatedConnectors.Add(this); return to; } set { if (To is { } to) { _ = to.RelatedConnectors.Remove(this); } if (value is null) { _ = Element.RemoveAttribute(&quot;data-to&quot;); } else { Element.SetAttribute(&quot;data-to&quot;, value.Id); _ = value.RelatedConnectors.Add(this); } Changed?.Invoke(this); } } </code></pre> <p>Let's see what we have added to the <code>Node</code> class to support the relationship between the connectors and nodes. We first add the <code>HashSet</code> that we mentioned to the <code>Node</code> class.</p> <pre><code class="language-csharp">public HashSet&lt;Connector&gt; RelatedConnectors { get; } = new(); </code></pre> <p>We also override the <code>HandlePointerMove</code> method that every <code>Shape</code> implements to ensure that the related connectors are updated when the <code>Node</code> is moved.</p> <pre><code class="language-csharp">public override void HandlePointerMove(PointerEventArgs eventArgs) { base.HandlePointerMove(eventArgs); if (SVG.EditMode is EditMode.Move) { foreach (Connector connector in RelatedConnectors) { connector.UpdateLine(); } } } </code></pre> <p>All related connectors should also be removed if a <code>Node</code> is removed. To support this, we can override the <code>BeforeBeingRemoved</code> method, which is called before any <code>ISVGElement</code> is removed from the editor.</p> <pre><code class="language-csharp">public override void BeforeBeingRemoved() { foreach (Connector connector in RelatedConnectors) { SVG.RemoveElement(connector); } } </code></pre> <p>Next we will go back to the <code>Connector</code> class. We start of with implementing the method for adding a new <code>Connector</code>.</p> <pre><code class="language-csharp">public static void AddNew(SVGEditor SVG, Node from) { IElement element = SVG.Document.CreateElement(&quot;LINE&quot;); element.SetAttribute(&quot;data-elementtype&quot;, &quot;connector&quot;); Connector connector = new(element, SVG) { Changed = SVG.UpdateInput, Stroke = &quot;black&quot;, StrokeWidth = &quot;5&quot;, From = from }; SVG.EditMode = EditMode.Add; SVG.ClearSelectedShapes(); SVG.SelectShape(connector); SVG.AddElement(connector); } </code></pre> <p>We create a new XML element in the form of a line. We set the <code>data-elementtype</code> to <code>&quot;connector&quot;</code> on this, which we will use later to specify that it should only be the <code>Connector</code> class that handles this element. Next, we create a new <code>Connector</code> instance and set some defaults. This <code>AddNew</code> method differs from the one we specified by the <code>Node</code>. This method also takes a <code>Node</code> as a parameter. We use this to select which <code>Node</code> the <code>Connector</code> should go from so that we can finish the addition of the <code>Connector</code> with very few interactions. In the end, we do the same thing as for the <code>Node</code> <code>AddNew</code> method and clear all selected shapes, set the new <code>Connector</code> as the single selected shape, and add the new <code>Connector</code> to the <code>SVGEditor</code>.</p> <p>To give the user some feedback while selecting a second <code>Node</code> to connect to, we want to update where the <code>Connector</code> points to follow the mouse until the user has decided on a <code>Node</code>. To control this we again override the <code>HandlePointerMove</code> method.</p> <pre><code class="language-csharp">public override void HandlePointerMove(PointerEventArgs eventArgs) { if (SVG.EditMode is EditMode.Add) { (X2, Y2) = SVG.LocalDetransform((eventArgs.OffsetX, eventArgs.OffsetY)); SetStart((X2, Y2)); } } </code></pre> <p>We don't want the <code>Connector</code> to handle a pointer move in any other case than when we are adding a new one. In this case, we set the end position equal to the pointer position, which is parsed to the method. After this, we update the position of the start position so that it is oriented towards where the cursor is currently. Let's see how we do that now. This includes a tiny bit of trigonometry, so be warned.</p> <pre><code class="language-csharp">public void SetStart((double x, double y) towards) { double differenceX = towards.x - From!.Cx; double differenceY = towards.y - From!.Cy; double distance = Math.Sqrt((differenceX * differenceX) + (differenceY * differenceY)); if (distance &gt; 0) { X1 = From!.Cx + (differenceX / distance * 50); Y1 = From!.Cy + (differenceY / distance * 50); } } </code></pre> <p>We first calculate the difference between the point we are drawing toward and the center of the <code>Node</code> we draw from for the <code>x</code> and <code>y</code> axes, respectively. Then we calculate the Euclidean distance between the two same points using the Pythagorean theorem. If the cursor is any distance from the <code>From</code> <code>Node</code>, we update the start of the line. We wish to start the line at the edge of the <code>From</code> <code>Node</code> circle and find the point closest to the cursor. We already have a vector that points to the cursor <code>(differenceX, differenceY)</code>, so we start with normalizing it by dividing it by its length, which is our <code>distance</code>, and then we multiply it with <code>50</code> to make that vector point out to the edge of the <code>Node</code> as that has a radius of <code>50</code>. Then we add this re-scaled vector to the center of the <code>From</code> <code>Node</code>.</p> <p>Before continuing, let's demo this to see that it updates the line to point to the edge of the <code>From</code> <code>Node</code>. To show this, I've added a <code>@ref</code> to the <code>SVGEditor</code> in our sample page, programmatically initialized a new <code>Node</code>, and started the addition of a <code>Connector</code> like just as a temporary change.</p> <pre><code class="language-csharp">private SVGEditor SVGEditor { get; set; } = default!; protected override void OnAfterRender(bool firstRender) { if (!firstRender) return; Node.AddNew(SVGEditor); var node = (Node)SVGEditor.Elements.First(); Connector.AddNew(SVGEditor, node); } </code></pre> <p><video width="600px" src="https://kristoffer-strube.dk/videos/svg-editor-connector-going-from-node.mp4" autoplay muted controls loop></video></p> <p>Next, we need to be able to select a <code>Node</code> while adding a <code>Connector</code> to end the interaction. <code>Shape</code>s cannot be selected when other elements are being created by default, so we first need to override this inherited logic of the <code>NodeEditor</code>. We add the following to the code section of our <code>NodeEditor</code> component:</p> <pre><code class="language-csharp">public new async Task SelectAsync(MouseEventArgs eventArgs) { if (SVGElement.SVG.EditMode is EditMode.Add &amp;&amp; SVGElement.SVG.SelectedShapes.Any(s =&gt; s is Connector)) { SVGElement.SVG.SelectedShapes.Add(SVGElement); } else { await base.SelectAsync(eventArgs); } } </code></pre> <p>We wish to change the behavior of the <code>SelectAsync</code> method which is invoked when the pointer is pressed down on a <code>Node</code>, so we <code>new</code> the <code>SelectAsync</code> method in the component. In this, we have two cases. If the <code>SVGEditor</code> is in <code>Add</code> mode and any <code>Connector</code> is currently selected, then we add the <code>Node</code> to the list of selected shapes. Else we call the base implementation of the <code>SelectAsync</code> method.</p> <p>Now we can select a <code>Node</code> while a <code>Connector</code> is being added. Then we need to handle when the pointer is being raised while the <code>Connecter</code> is added. We override the <code>HandlePointerUp</code> on the <code>Connector</code> class for this.</p> <pre><code class="language-csharp">public override void HandlePointerUp(PointerEventArgs eventArgs) { if (SVG.EditMode is EditMode.Add &amp;&amp; SVG.SelectedShapes.FirstOrDefault(s =&gt; s is Node node &amp;&amp; node != From) is Node { } to) { if (to.RelatedConnectors.Any(c =&gt; c.To == From || c.From == From)) { Complete(); } else { To = to; SVG.EditMode = EditMode.None; UpdateLine(); } } } </code></pre> <p>We only care about the case where we are adding a <code>Connector</code> so we first check for this and then check if we can find any selected shape that is a <code>Node</code>. If we have matched this, we then do one of two things. If the two nodes that are going to be connected already are connected, then we call <code>Complete</code>, which we will implement to remove this unfinished <code>Connector</code> in a bit. We do this so that two nodes can't be connected more than once. If there wasn't already a <code>Connection</code> present between these two nodes then we see the <code>To</code> <code>Node</code>, reset the <code>SVGEditor</code> mode, and update its placement.</p> <p>Before going to the <code>UpdateLine</code> method, let's see the <code>Complete</code> method we used.</p> <pre><code class="language-csharp">public override void Complete() { if (To is null) { SVG.RemoveElement(this); Changed?.Invoke(this); } } </code></pre> <p>This method can also be called from the context menu to enable the user to cancel creating a new <code>Connector</code> after starting. So in these two cases, we remove the temporary <code>Connector</code> if <code>To</code> is not set.</p> <p>Now let's see the <code>UpdateLine</code> method that we have referenced a couple of times now.</p> <pre><code class="language-csharp">public void UpdateLine() { if (From is null || To is null) { (X1, Y1) = (X2, Y2); return; } double differenceX = To.Cx - From.Cx; double differenceY = To.Cy - From.Cy; double distance = Math.Sqrt((differenceX * differenceX) + (differenceY * differenceY)); if (distance &lt; 100) { (X1, Y1) = (X2, Y2); } else { SetStart((To.Cx, To.Cy)); X2 = To.Cx - (differenceX / distance * 50); Y2 = To.Cy - (differenceY / distance * 50); } } </code></pre> <p>If the <code>From</code> or <code>To</code> <code>Node</code> is not set, we set the start of the line equal to the end position so that it will not appear.</p> <p>Then we do something very close to what we have seen previously by finding the vector from the <code>To</code> <code>Node</code> to the <code>From</code> <code>Node</code>. Then we calculate the length of this vector. And if the length of the vector is less than <code>100</code>, then we know that they are so close that the <code>Connector</code> should not be rendered, so we once again set the start equal to the end. Else we set the start position to point towards the <code>To</code> <code>Node</code> and then calculate the point on the edge of the circle of the <code>To</code> <code>Node</code> closest to the <code>From</code> <code>Node</code> exactly like we did in the <code>SetStart</code> method for the <code>From</code> <code>Node</code>.</p> <h4>ConnectorEditor.razor</h4> <p>We also need to add the custom <code>ConnectorEditor</code> we previously referenced in the <code>Connector</code>. We have just copied the <code>LineEditor</code> component and made some adjustments for this.</p> <pre><code class="language-razor">@using BlazorContextMenu @using KristofferStrube.Blazor.SVGEditor.Extensions; @using KristofferStrube.Blazor.SVGEditor.ShapeEditors; @inherits ShapeEditor&lt;Connector&gt; &lt;ContextMenuTrigger MenuId=&quot;SVGMenu&quot; WrapperTag=&quot;g&quot; Data=@SVGElement MouseButtonTrigger=&quot;SVGElement.ShouldTriggerContextMenu ? MouseButtonTrigger.Right : (MouseButtonTrigger)4&quot;&gt; &lt;g style=&quot;@(SVGElement.SVG.EditMode is EditMode.Add ? &quot;pointer-events:none;&quot; : &quot;&quot;)&quot; transform=&quot;translate(@SVGElement.SVG.Translate.x.AsString() @SVGElement.SVG.Translate.y.AsString()) scale(@SVGElement.SVG.Scale.AsString())&quot;&gt; &lt;line @ref=ElementReference @onfocusin=&quot;FocusElement&quot; @onfocusout=&quot;UnfocusElement&quot; @onpointerdown=&quot;SelectAsync&quot; @onkeyup=&quot;KeyUp&quot; tabindex=&quot;@(SVGElement.IsChildElement ? -1 : 0)&quot; x1=@SVGElement.X1.AsString() y1=@SVGElement.Y1.AsString() x2=@SVGElement.X2.AsString() y2=@SVGElement.Y2.AsString() stroke=&quot;@SVGElement.Stroke&quot; stroke-width=&quot;@SVGElement.StrokeWidth&quot; stroke-linecap=&quot;@SVGElement.StrokeLinecap.AsString()&quot; stroke-linejoin=&quot;@SVGElement.StrokeLinejoin.AsString()&quot; stroke-dasharray=&quot;@SVGElement.StrokeDasharray&quot; stroke-dashoffset=&quot;@SVGElement.StrokeDashoffset.AsString()&quot; fill=&quot;@SVGElement.Fill&quot;&gt; &lt;/line&gt; &lt;/g&gt; &lt;/ContextMenuTrigger&gt; </code></pre> <p>We have changed two things for the markup part of the <code>ConnectorEditor</code>. We have added a <code>style</code> tag to the <code>&lt;g&gt;</code> that encloses the <code>&lt;line&gt;</code> itself. The style tag makes it so that it will not handle any pointer events if the editor is currently in the <code>Add</code> mode. This is to ensure that we can click through the line when we are adding a new <code>Connector</code> so that it doesn't block any <code>Node</code> we would like to click. Secondly, we have removed the two anchors that normally appear when a <code>Line</code> is selected to make the UI less noisy. We have also overridden the <code>OnAfterRenderAsync</code> method in the code section of the component.</p> <pre><code class="language-csharp">protected override async Task OnAfterRenderAsync(bool firstRender) { if (firstRender) { SVGElement.UpdateLine(); } await base.OnAfterRenderAsync(firstRender); } </code></pre> <p>This ensures that all connectors get their position updates when first rendered.</p> <h4>AddNewConnectorMenuItem.razor</h4> <p>The last component we need is the context menu item for when we want to add a new <code>Connector</code>.</p> <pre><code class="language-razor">@using BlazorContextMenu @if (Data is Node node) { &lt;Item OnClick=&quot;_ =&gt; Connector.AddNew(SVGEditor, node)&quot;&gt; &lt;div class=&quot;icon&quot;&gt;〰&lt;/div&gt; New Connector &lt;/Item&gt; } @code { [CascadingParameter] public required SVGEditor SVGEditor { get; set; } [Parameter] public required object Data { get; set; } } </code></pre> <p>This menu item is a bit more complex than the one we made for adding a <code>Node</code> as we only want it to render if we opened the context menu from a <code>Node</code>. So we check the <code>Data</code> property to get the <code>Node</code> that was right-clicked if there was any, and parse that to the <code>AddNew</code> method if the menu item is clicked.</p> <p>Lastly we need to update the configuration in our sample page to include these new handlers and components. We first add the <code>Connector</code> class to the list of <code>SupportedElements</code> and specify that it can handle any <code>&lt;line&gt;</code> tag with a <code>data-elementtype</code> attribute equal to <code>&quot;connector&quot;</code>.</p> <pre><code class="language-csharp">protected List&lt;SupportedElement&gt; SupportedElements { get; set; } = new() { new(typeof(Node), element =&gt; element.TagName is &quot;CIRCLE&quot; &amp;&amp; element.GetAttribute(&quot;data-elementtype&quot;) == &quot;node&quot;), new(typeof(Connector), element =&gt; element.TagName is &quot;LINE&quot; &amp;&amp; element.GetAttribute(&quot;data-elementtype&quot;) == &quot;connector&quot;), }; </code></pre> <p>And then, we add the menu item for adding new connectors and define that it should only count as a menu item if the context menu started from a <code>Node</code> as we defined in the component itself.</p> <pre><code class="language-csharp">protected List&lt;SupportedAddNewSVGElementMenuItem&gt; AddNewSVGElementMenuItems { get; set; } = new() { new(typeof(AddNewNodeMenuItem), (_,_) =&gt; true), new(typeof(AddNewConnectorMenuItem), (_,data) =&gt; data is Node) }; </code></pre> <p>Now let's get to the final demo with all the parts working together.</p> <p><video width="600px" src="https://kristoffer-strube.dk/videos/svg-editor-graph-editor.mp4" autoplay muted controls loop></video></p> <p>You might have noticed that the area select tool also had a new orange color in this sample video. We changed this by adding the following scoped CSS styling to our sample page.</p> <pre><code class="language-css">::deep .anchor-primary { stroke: orange; } ::deep .box { fill: orange; fill-opacity: 0.5; stroke: orange; } </code></pre> <p>You can try the demo shown in the video yourself here: <a href="https://kristofferstrube.github.io/Blazor.SVGEditor/CustomElements/">kristofferstrube.github.io/Blazor.SVGEditor/CustomElements</a> And you can see the source code for the whole sample project, including some other demo pages, here: <a href="https://github.com/KristofferStrube/Blazor.SVGEditor/tree/120101d2fce7f0f561697045f82133501836d823/samples/KristofferStrube.Blazor.SVGEditor.WasmExample">Demo project source code</a></p> <h3>Future work</h3> <p>I will continue to develop on the project whenever I find some feature or nice interaction that I would like to add. I currently have three open issues if you would to contribute yourself: <a href="https://github.com/KristofferStrube/Blazor.SVGEditor/issues/5" target="_blank">#5</a>, <a href="https://github.com/KristofferStrube/Blazor.SVGEditor/issues/11" target="_blank">#11</a>, and <a href="https://github.com/KristofferStrube/Blazor.SVGEditor/issues/12" target="_blank">#12</a>. One project that I plan to use the package in already is a demo for my <a href="https://github.com/KristofferStrube/Blazor.WebAudio">Web Audio Blazor wrapper</a>. The demo will be a network of sound sources, processors, and outputs that can be wired together to make some simple audio editing from the browser using Blazor.</p> <h3>Conclusion</h3> <p>At the start of the article, we went through all the different features of the Blazor.SVGEditor package. Features include parsing SVG definitions, adding, selecting, editing, moving, removing shapes, and navigating the canvas using the mouse. Then we went through a sample project where we added some custom handlers for SVG elements to the editor and made a network editor with these. While developing this customization, we also saw how we could still use many of the features in the package by inheriting from existing shapes. If you have any feedback or questions relating to the article, feel free to contact me on any of my social media profiles.</p> typed-exceptions-for-jsinterop-in-blazorhttps://kristoffer-strube.dk/post/typed-exceptions-for-jsinterop-in-blazor/When developing applications in Blazor we can invoke JavaScript function from C# by using JSInterop. Many types of errors can be thrown when calling these methods. Especially if something unexpected happens like missing permissions or if one of the arguments is invalid. The errors thrown from JS get bubbled up to our method invocation in C# and we can catch these JSExceptions using a try-catch statement. The exception contain the message of the original error, but we lose the context of which error type this was which has led people to do a lot of custom error handling that instead looks for key phrases or words in the error message. In this article, we look at how the existing error-handling implementation is made in Blazor. We then look at how we can map the error types defined in the standard WebIDL specification to C# exceptions, and in the end, we show some examples of how to use this in practice when making JS invocations.Fri, 26 May 2023 00:00:00 +02002023-05-26T00:00:00+02:00<h3>Classic example of handling exceptions from JSInterop</h3> <p>With the current way that Blazor propagates errors to us, we are often left with some rather simple ways of finding out what actually happened. Let's see what happens when we try to call some JS that will fail. The example we will work with is invoking a method that does not exist but which we expect might throw a JS <code>AbortError</code>.</p> <pre><code class="language-razor">@inject IJSRuntime JSRuntime @code { protected override async Task OnInitializedAsync() { await JSRuntime.InvokeVoidAsync(&quot;nonExistingMethod&quot;); } } </code></pre> <p>We will see the following error in the console of our browser.</p> <pre><code class="language-console">crit: Microsoft.AspNetCore.Components.WebAssembly.Rendering.WebAssemblyRenderer[100] Unhandled exception rendering component: Could not find 'nonExistingMethod' ('nonExistingMethod' was undefined). Error: Could not find 'nonExistingMethod' ('nonExistingMethod' was undefined). at http://localhost:5278/_framework/blazor.webassembly.js:1:328 at Array.forEach (&lt;anonymous&gt;) at a.findFunction (http://localhost:5278/_framework/blazor.webassembly.js:1:296) ... This continues with a very long stack trace that is not relevant to the exception. Not until this part which is from the .NET call stack: at Microsoft.JSInterop.JSRuntime.&lt;InvokeAsync&gt;d__16`1[[Microsoft.JSInterop.Infrastructure.IJSVoidResult, Microsoft.JSInterop, Version=7.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60]].MoveNext() at Microsoft.JSInterop.JSRuntimeExtensions.InvokeVoidAsync(IJSRuntime jsRuntime, String identifier, Object[] args) at test_project.Pages.Index.OnInitializedAsync() in F:\repos\test-project\Pages\Index.razor:line 8 at Microsoft.AspNetCore.Components.ComponentBase.RunInitAndSetParametersAsync() at Microsoft.AspNetCore.Components.RenderTree.Renderer.GetErrorHandledTask(Task taskToHandle, ComponentState owningComponentState) </code></pre> <p>And if we try to capture the exception and read its <code>Message</code> we still get the same exception except we don't get the .NET call stack.</p> <pre><code class="language-razor">@inject IJSRuntime JSRuntime &lt;pre&gt;&lt;code&gt; @exceptionMessage &lt;/code&gt;&lt;/pre&gt; @code { string? exceptionMessage; protected override async Task OnInitializedAsync() { try { await JSRuntime.InvokeVoidAsync(&quot;nonExistingMethod&quot;); } catch (JSException jsex) { exceptionMessage = jsex.Message; } } } </code></pre> <p>And this message isn't really a nice user-facing error to get. So what we have done earlier is either to forget entirely what the exception said and just write something like <strong>&quot;Something bad happened!&quot;</strong> which doesn't help anyone. Or the better case which is to check for matching parts of the exception message. That could look something like this if we expect that JS could either throw an <code>AbortError</code> or some other unexpected exception.</p> <pre><code class="language-razor">@inject IJSRuntime JSRuntime @inject ILogger Logger &lt;span style=&quot;color: red;&quot;&gt;@exceptionMessage&lt;/span&gt; @code { string? exceptionMessage; protected override async Task OnInitializedAsync() { try { await JSRuntime.InvokeVoidAsync(&quot;nonExistingMethod&quot;); } catch (JSException jsex) { if (jsex.Message.Contains(&quot;is aborted&quot;)) { exceptionMessage = &quot;The execution of the method was canceled.&quot;; } else { exceptionMessage = &quot;An unexpected error happened.&quot;; Logger.LogError(exceptionMessage, jsex); } } } } </code></pre> <p>This is a bit hand-wavy. We first need to know that the exception message contained the words <code>&quot;is aborted&quot;</code> and we then have to hope that no other exception could happen that would also contain those words which would make for a false positive.</p> <h3>How Blazor currently handles errors in JSInterop</h3> <p>It can be tough to find out why an error happens when an invocation is not successful as we saw above. The root of the problem is that we don't get all information about why an error happens when Blazor handles an error. Most noticeably we don't get information about the <code>name</code> of the specific type of error. To find out why let's look at the TypeScript code that handles Blazors dynamic invocation of functions in the <a href="https://github.com/dotnet/aspnetcore/blob/main/src/JSInterop/Microsoft.JSInterop.JS/src/src/Microsoft.JSInterop.ts#L401-L430">beginInvokeJSFromDotNet function in Microsoft.JSInterop.ts</a>:</p> <pre><code class="language-ts">beginInvokeJSFromDotNet: (asyncHandle: number, identifier: string, argsJson: string, resultType: JSCallResultType, targetInstanceId: number): void =&gt; { // Coerce synchronous functions into async ones, plus treat // synchronous exceptions the same as async ones const promise = new Promise&lt;any&gt;(resolve =&gt; { const synchronousResultOrPromise = findJSFunction(identifier, targetInstanceId).apply(null, parseJsonWithRevivers(argsJson)); resolve(synchronousResultOrPromise); }); // We only listen for a result if the caller wants to be notified about it if (asyncHandle) { // On completion, dispatch result back to .NET // Not using &quot;await&quot; because it codegens a lot of boilerplate promise .then(result =&gt; stringifyArgs([asyncHandle, true, createJSCallResult(result, resultType)])) .then( result =&gt; getRequiredDispatcher().endInvokeJSFromDotNet(asyncHandle, true, result), error =&gt; getRequiredDispatcher().endInvokeJSFromDotNet(asyncHandle, false, JSON.stringify([ asyncHandle, false, formatError(error) ])) ); } }, </code></pre> <p>They start off by making any potential synchronous method asynchronous by wrapping it in a promise. In the promise, they follow the identifier path to the function that should be invoked and then apply the arguments to that function using the <code>apply</code> method. This is all good and basically just means that they have fewer places in the code that varies. Next, they resolve the newly created promise and handle the two outcomes of the function. Either it was successful or it errored. In either case, we call back to .NET with some payload and a flag indicating if the invocation was successful. If it was successful we simply serialize the result and return that. But when it errors we instead call and return the result of the method <a href="https://github.com/dotnet/aspnetcore/blob/main/src/JSInterop/Microsoft.JSInterop.JS/src/src/Microsoft.JSInterop.ts#L540-L546">formatError function in Microsoft.JSInterop.ts</a>:</p> <pre><code class="language-ts">function formatError(error: Error | string): string { if (error instanceof Error) { return `${error.message}\n${error.stack}`; } return error ? error.toString() : &quot;null&quot;; } </code></pre> <p>This is what formats the error in the well-known format we see in the browser console or the <code>JSException</code>'s <code>Message</code> when making JSInteorp calls. Do you see what we are missing? Yes exactly, the <code>name</code> of the specific <code>Error</code>. We have lost the type of the original error. So that is exactly what we want to get back so that we can handle the original grouping of errors instead of resorting to matching on parts of the message.</p> <h3>Mapping JS errors to C# exceptions</h3> <p>We want to do something similar to what the standard JSInterop has already done but include some other information. Sadly we can't change or use the existing code for the JSInterop functionality as most of it is internal. So instead we need to wrap the existing implementations and work around some of the mechanisms. But before we go there let's look at what different kinds of errors there are in JS.</p> <h4>Overview of JS error types</h4> <p>There are 6 types of errors that we should be concerned with when working within the browser.</p> <ul> <li>EvalError</li> <li>RangeError</li> <li>ReferenceError</li> <li>SyntaxError</li> <li>TypeError</li> <li>URIError</li> </ul> <p>Each of these is used in a different scenario and can also be referred to as <em>Native Error Types</em>. Apart from these we also have some standard exceptions called the <code>DOMException</code>s. They are generally used for errors that happens as an effect of the user, the browser, or the system doing something unexpected. <code>DOMException</code>s are also errors, so we will simply refer to both JS errors and JS exceptions as errors from now on. There are many different kinds of <code>DOMExceptions</code> as well that are defined in the <a href="https://webidl.spec.whatwg.org/#idl-DOMException-error-names">WebIDL standard specifications</a>. They differ only by having different names and then of cause by being used in different scenarios. There are <code>29</code> predefined error names that are currently valid, so let's not list them all. The ones you might already know could be the <code>NotFoundError</code>, the <code>NotSupportedError</code>, and of cause the <code>AbortError</code>.</p> <h4>Capturing and rethrowing in JavaScript</h4> <p>The first step after having made clear that we are interested in the name of the exceptions is to somehow get this information into the exception that gets thrown at us. To do this we need to catch all exceptions on the JS side and rethrow them back for the Blazor implementation to handle. We could do this in all places where we need to invoke a method, but that would mean that we would need custom JS wrapper methods for <strong>ALL</strong> JS invocations we wanted to make. Instead, let's make a simple method that can execute any general method similar to how the Blazor implementation does it, but then throw another exception. We make a new JS module (a JS file with exported functions) and start with the following function which we will import and call later.</p> <pre><code class="language-js">export async function callAsyncGlobalMethod(identifier, args) { return await callAsyncInstanceMethod(window, identifier, args); } </code></pre> <p>The method has two parameters. The first is the identifiers for the method that we will invoke and the second is the arguments that we will apply to this method. It then simply calls another method that we will define now and parses the <code>window</code> object to this method. The <code>window</code> object is the topmost context for the browser and thereby exposes most methods that you can otherwise invoke. So you could call <code>alert(&quot;Hello!&quot;)</code> or you could call <code>window.alert(&quot;Hello!&quot;)</code> and get the same result.</p> <pre><code class="language-js">export async function callAsyncInstanceMethod(instance, identifier, args) { try { var [functionObject, functionInstance] = resolveFunction(instance, identifier); return await functionInstance.apply(functionObject, args); } catch (error) { throw new DOMException(formatError(error), &quot;AbortError&quot;); } } </code></pre> <p>This function starts off by creating a <code>try-catch</code> statement. In the <code>try</code> block we call a function that resolves the reference to our function. Then it actually applies the arguments to the function, awaits it, and returns that. If it throws an error while resolving or awaiting the function we hit the <code>catch</code> block. We capture the <code>error</code> in the <code>catch</code> block and throw a new error. The new error is a <code>DOMException</code> constructed with the message given from calling <code>formatError</code> with the <code>error</code> and the <code>name</code> set to <code>&quot;AbortError&quot;</code>. It actually doesn't matter what type of error we throw as we already know that the Blazor code will completely ignore the <code>name</code>, but we chose an <code>AbortError</code> as that fits what we have done. Now let's first look at the <code>resolveFunction</code> function that we used to get the function instance and the function object.</p> <pre><code class="language-js">function resolveFunction(instance, identifier) { let identifierParts = identifier.split(&quot;.&quot;); var functionObject = instance; var functionInstance = instance[identifierParts[0]]; for (let i = 1; i &lt; identifierParts.length; i++) { if (functionInstance == undefined) { throw new ReferenceError(`Cannot read properties of undefined (reading '${identifierParts[i - 1]}').`); } functionObject = functionInstance; functionInstance = functionInstance[identifierParts[i]]; } if (!(functionInstance instanceof Function)) { throw new TypeError(`'${identifierParts.slice(-1)}' is not a function.`); } return [functionObject, functionInstance]; } </code></pre> <p><code>resolveFunction</code> first splits the identifier into its parts. This is to support when calling methods on attributes like <code>window.caches.open</code> with a single invocation. We then set that the object that the function should be called on (<code>functionObject</code>) is the <code>instance</code> parsed as a start and that the function itself is the property with the name matching the first part of the identifier. Then we go through all consecutive identifier parts <em>(if there are any left)</em> and update the <code>functionObject</code> to be the <code>functionInstance</code> of the previous iteration, as it was actually an attribute, and once again set the <code>functionInstance</code> to the next part of the identifier. Finally, we return the object that the function should be called on and the function itself. We do this as functions in JS always have to be called in some context.</p> <p>If an error were to happen when invoking the returned function or while resolving it then we format that error and re-throw it. Below we see the function we use to format the error. It is a rather simple function that simply returns a stringified object containing the error <code>name</code>, <code>message</code>, and <code>stack</code>. This is similar to what Blazor does, but we use JSON as our structure instead of concatenating the details and we also include the <code>name</code>.</p> <pre><code class="language-js">function formatError(error) { var name = error.name; if (error instanceof DOMException &amp;&amp; name == &quot;SyntaxError&quot;) { name = &quot;DOMExceptionSyntaxError&quot;; } return JSON.stringify({ name: error.name, message: error.message, stack: error.stack }) } </code></pre> <p>The one special thing we do is check if it is a <code>DOMException</code> and if the <code>name</code> is <code>&quot;SyntaxError&quot;</code>. In that case we prepend the name with <code>&quot;DOMException&quot;</code> as to disambiguate it from the <code>SyntaxError</code> error type that also has this name. This is important as they have different purposes despite sharing a name. And now the JS module is done and ready to be imported from C#.</p> <h4>Capturing and rethrowing in C#</h4> <p>The C# part should be a reusable class that follows the same pattern as the existing <code>IJSRuntime</code> so that it will be easy to use instead. And how lucky can we be? <code>IJSRuntime</code> is just an interface that we can implement. We create a new class called <code>ErrorHandlingJSRuntime</code> that implements <code>IJSRuntime</code>.</p> <pre><code class="language-csharp">public class ErrorHandlingJSRuntime : IJSRuntime { public ValueTask&lt;TValue&gt; InvokeAsync&lt;[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors | DynamicallyAccessedMemberTypes.PublicFields | DynamicallyAccessedMemberTypes.PublicProperties)] TValue&gt;(string identifier, object?[]? args) { throw new NotImplementedException(); } public ValueTask&lt;TValue&gt; InvokeAsync&lt;[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors | DynamicallyAccessedMemberTypes.PublicFields | DynamicallyAccessedMemberTypes.PublicProperties)] TValue&gt;(string identifier, CancellationToken cancellationToken, object?[]? args) { throw new NotImplementedException(); } } </code></pre> <p>Before we implement the methods let's create a constructor that sets up the members we will need to make invocations.</p> <pre><code class="language-csharp"> private Lazy&lt;Task&lt;IJSObjectReference&gt;&gt; helperTask; public ErrorHandlingJSRuntime(IJSRuntime jSRuntime) { helperTask = new(async () =&gt; await jSRuntime.InvokeAsync&lt;IJSObjectReference&gt;(&quot;import&quot;, &quot;./_content/KristofferStrube.Blazor.WebIDL/KristofferStrube.Blazor.WebIDL.js&quot;) ); } </code></pre> <p>We take an <code>IJSRuntime</code> in the constructor and create a new lazily loaded <code>IJSObjectReference</code> helper task using it. The helper is created once needed by importing the module we made in the previous section. Now we are ready to implement the methods. The two methods are very similar but differ by having an extra <code>CancellationToken</code> argument that can be used to cancel an invocation. An example of a time you would cancel an invocation is if the user navigates away from the page before the invocation is done. This makes the first method easy to implement as we can simply call the other method with the default value for the <code>CancellationToken</code>.</p> <pre><code class="language-csharp">public ValueTask&lt;TValue&gt; InvokeAsync&lt;[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors | DynamicallyAccessedMemberTypes.PublicFields | DynamicallyAccessedMemberTypes.PublicProperties)] TValue&gt;(string identifier, params object?[]? args) { return InvokeAsync&lt;TValue&gt;(identifier, CancellationToken.None, args); } </code></pre> <p>You might have questioned the rather long signature for the methods by now. Especially the very long <code>DynamicallyAccessedMembers</code> attribute added to the generic type parameter. These are used to tell that there will be used reflection on the types passed to the method. This is relevant in cases where you use AOT compilation as that will normally not allow reflection, but this makes it clear to the compiler that there will be used reflection on these types. It needs reflection since <code>System.Text.Json</code> goes through all properties and constructors when deserializing.</p> <p>But now to the method that makes the invocation.</p> <pre><code class="language-csharp">public async ValueTask&lt;TValue&gt; InvokeAsync&lt;[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors | DynamicallyAccessedMemberTypes.PublicFields | DynamicallyAccessedMemberTypes.PublicProperties)] TValue&gt;(string identifier, CancellationToken cancellationToken, params object?[]? args) { var helper = await helperTask.Value; try { return await helper.InvokeAsync&lt;TValue&gt;(&quot;callAsyncGlobalMethod&quot;, cancellationToken, identifier, args); } catch (JSException exception) { if (UnpackMessageOfExeption(exception) is not Error { } error) { throw; } throw MapToWebIDLException(error, exception); } } </code></pre> <p>We first resolve our lazy-loaded helper module and then we start a <code>try-catch</code> statement. In the <code>try</code> block we invoke the <code>callAsyncGlobalMethod</code> method from our helper module and parse in the <code>CancellationToken</code> that might be the default <code>None</code> value and the original <code>identifier</code> and <code>args</code> arguments as the <code>args</code> parameter for the <code>InvokeAsync</code> method on our helper module. If it is successful then that will be it and we just return the value. But if it fails then we hit the <code>catch</code> block. We only catch <code>JSException</code> as we don't want to handle any other errors like JSON serialization errors or the like. In the block, we call the method <code>UnpackMessageOfExeption</code> that has the task of deserializing the <code>Message</code> we packed in the JS function <code>formatError</code>. If it could not unpack it then we throw the original exception as it clearly was not an exception that we had formatted. If we could unpack it then we map the <code>Error</code> and the <code>JSException</code> to some other <code>Exception</code> type and throw that instead. Let's first implement the <code>UnpackMessageOfExeption</code> method.</p> <pre><code class="language-csharp">internal Error? UnpackMessageOfExeption(JSException exception) { return JsonSerializer.Deserialize&lt;Error?&gt;(exception.Message[..^9].Trim()); } </code></pre> <p>We first trim the last <code>9</code> characters which are <code>&quot;undefined&quot;</code> as this is the <code>stack</code> that Blazor postfixes the <code>message</code> with (because we threw the exception) and then we call <code>Trim</code> to remove the line break. Then we use <code>System.Text.Json</code> to deserialize the payload as an <code>Error?</code> and return that. Pretty straightforward. Now to the <code>MapToWebIDLException</code> method that maps this <code>Error</code> to a new <code>Exception</code>.</p> <pre><code class="language-csharp">internal WebIDLException MapToWebIDLException(Error error, JSException exception) { if (ErrorMapper.TryGetValue(error.name, out Func&lt;string, string, string?, Exception, WebIDLException&gt;? creator)) { return creator(error.name, error.message, error.stack, exception); } else { return new WebIDLException($&quot;{error.name}: \&quot;{error.message}\&quot;&quot;, null, exception); } } </code></pre> <p>The method checks inside a dictionary for a key equal to the error name. The type of the dictionary is <code>Dictionary&lt;string, Func&lt;string, string, string?, Exception, WebIDLException&gt;&gt;</code> but we will get back to that later. The value returned from the dictionary is a <code>Func</code> that takes 3 strings and an <code>Exception</code> and parses back a <code>WebIDLException</code>. If we successfully find a key that matches then we invoke the <code>Func</code> that is in the value by parsing the <code>name</code>, the <code>message</code>, the <code>stack</code>, and the original <code>JSException</code> to this. If we could not find a matching key then we simply return a <code>WebIDLException</code>. This is an <code>Exception</code> type that we have implemented to give all <code>Exceptions</code> from this <code>ErrorHandlingJSRuntime</code> a common type they can be derived from.</p> <pre><code class="language-csharp">/// &lt;summary&gt; /// A common exception class for all exceptions from the &lt;c&gt;Blazor.WebIDL&lt;/c&gt; library. /// &lt;/summary&gt; public class WebIDLException : Exception { private readonly string? jSStackTrace; /// &lt;summary&gt; /// Returns the stack trace as a string. The stack is prepended with the JS stack trace if there is any. If no stack trace is available, null is returned. /// &lt;/summary&gt; public override string? StackTrace =&gt; jSStackTrace is not null ? jSStackTrace + '\n' + base.StackTrace : base.StackTrace; /// &lt;summary&gt; /// Constructs a wrapper Exception for the given error. /// &lt;/summary&gt; /// &lt;param name=&quot;message&quot;&gt;User agent-defined value that provides human readable details of the error.&lt;/param&gt; /// &lt;param name=&quot;jSStackTrace&quot;&gt;The stack trace from JavaScript if there is any.&lt;/param&gt; /// &lt;param name=&quot;innerException&quot;&gt;Inner exception which is the cause of this exception.&lt;/param&gt; public WebIDLException(string message, string? jSStackTrace, Exception innerException) : base(message, innerException) { this.jSStackTrace = jSStackTrace; } } </code></pre> <p>The <code>WebIDLException</code> has a single constructor that parses the <code>message</code> and <code>innerException</code> down to the base <code>Exception</code> and sets the field <code>jSStackTrace</code> with the potential stack trace. If the <code>jSStackTrace</code> is not null then it is prepended to the base <code>StackTrace</code>. Our goal is to map each standard error name to some <code>Exception</code> type that inherits from <code>WebIDLException</code>. For this purpose, we define the dictionary <code>ErrorMapper</code> as a public property on the <code>ErrorHandlingJSRuntime</code>.</p> <pre><code class="language-csharp">public Dictionary&lt;string, Func&lt;string, string, string?, Exception, WebIDLException&gt;&gt; ErrorMapper { get; set; } = ErrorMappers.Default; </code></pre> <p>We define a static readonly default dictionary that maps the ones defined in the specifications. This opens up for anyone to add to the error mapper if they need to support some custom JS error type. There are a lot of predefined errors in JS as we have seen previously so I will not show all the different <code>Exception</code> types I have created. But I have grouped them so that all the <em>Native Error Types</em> like <code>ReferenceErrorException</code> and <code>TypeErrorException</code> are derived from a common <code>NativeErrorException</code> and all the different <code>DOMException</code>s are derived from a common <code>DOMException</code> class.</p> <pre><code class="language-csharp">/// &lt;summary&gt; /// An exception that encapsulates a name for an exception. /// &lt;/summary&gt; /// &lt;remarks&gt;&lt;see href=&quot;https://webidl.spec.whatwg.org/#idl-DOMException&quot;&gt;See the WebIDL definition here&lt;/see&gt;&lt;/remarks&gt; public class DOMException : WebIDLException { public const string NotFoundError = &quot;NotFoundError&quot;; public const string SyntaxError = &quot;DOMExceptionSyntaxError&quot;; public const string AbortError = &quot;AbortError&quot;; // Constants for all the other predefined `DOMException` names are also included here but have been omitted for brevity. /// &lt;summary&gt; /// Error name which should be one of the ones listed in this &lt;see href=&quot;https://webidl.spec.whatwg.org/#dfn-error-names-table&quot;&gt;error names table&lt;/see&gt;. /// &lt;/summary&gt; public string Name { get; set; } /// &lt;summary&gt; /// Constructs a wrapper Exception for the given error. /// &lt;/summary&gt; /// &lt;param name=&quot;message&quot;&gt;User agent-defined value that provides human readable details of the error.&lt;/param&gt; /// &lt;param name=&quot;name&quot;&gt;Error name which should be one of the ones listed in this &lt;see href=&quot;https://webidl.spec.whatwg.org/#dfn-error-names-table&quot;&gt;error names table&lt;/see&gt;.&lt;/param&gt; /// &lt;param name=&quot;jSStackTrace&quot;&gt;The stack trace from JavaScript if there is any.&lt;/param&gt; /// &lt;param name=&quot;innerException&quot;&gt;Inner exception which is the cause of this exception.&lt;/param&gt; protected DOMException(string message, string name, string? jSStackTrace, Exception innerException) : base(message, jSStackTrace, innerException) { Name = name; } } </code></pre> <p>The <code>DOMException</code> defines a lot of constants for the different names of errors, but also adds a property <code>Name</code> that defines the error name. The constructor is protected since one should always define a derived <code>Exception</code> type for each additional custom <code>DOMException</code>. A concrete example of a <code>DOMException</code> could be the <code>NotFoundErrorException</code>.</p> <pre><code class="language-csharp">/// &lt;summary&gt; /// The object can not be found here. /// &lt;/summary&gt; /// &lt;remarks&gt;&lt;see href=&quot;https://webidl.spec.whatwg.org/#notfounderror&quot;&gt;See the WebIDL definition here&lt;/see&gt;&lt;/remarks&gt; public class NotFoundErrorException : DOMException { /// &lt;summary&gt; /// Constructs a wrapper Exception for the given error. /// &lt;/summary&gt; /// &lt;param name=&quot;message&quot;&gt;User agent-defined value that provides human readable details of the error.&lt;/param&gt; /// &lt;param name=&quot;jSStackTrace&quot;&gt;The stack trace from JavaScript if there is any.&lt;/param&gt; /// &lt;param name=&quot;innerException&quot;&gt;Inner exception which is the cause of this exception.&lt;/param&gt; public NotFoundErrorException(string message, string? jSStackTrace, Exception innerException) : base(message, NotFoundError, jSStackTrace, innerException) { } } </code></pre> <p>Now we are ready to define our <code>Default</code> <code>ErrorMapper</code>.</p> <pre><code class="language-csharp">public static class ErrorMappers { public static Dictionary&lt;string, Func&lt;string, string, string?, Exception, WebIDLException&gt;&gt; Default { get; } = new() { { DOMException.NotFoundError, (name, message, jSStackTrace, innerException) =&gt; new NotFoundErrorException(message, jSStackTrace, innerException) }, { DOMException.SyntaxError, (name, message, jSStackTrace, innerException) =&gt; new SyntaxErrorDOMException(message, jSStackTrace, innerException) }, { DOMException.AbortError, (name, message, jSStackTrace, innerException) =&gt; new AbortErrorException(message, jSStackTrace, innerException) }, // Also includes all other DOMException types, but they have been omitted from the article for brevity again. { &quot;EvalError&quot;, (name, message, jSStackTrace, innerException) =&gt; new EvalErrorException(message, jSStackTrace, innerException) }, { &quot;RangeError&quot;, (name, message, jSStackTrace, innerException) =&gt; new RangeErrorException(message, jSStackTrace, innerException) }, { &quot;ReferenceError&quot;, (name, message, jSStackTrace, innerException) =&gt; new ReferenceErrorException(message, jSStackTrace, innerException) }, { &quot;SyntaxError&quot;, (name, message, jSStackTrace, innerException) =&gt; new TypeErrorException(message, jSStackTrace, innerException) }, { &quot;TypeError&quot;, (name, message, jSStackTrace, innerException) =&gt; new TypeErrorException(message, jSStackTrace, innerException) }, { &quot;URIError&quot;, (name, message, jSStackTrace, innerException) =&gt; new URIErrorException(message, jSStackTrace, innerException) }, }; } </code></pre> <p>The <code>Default</code> mapper is pretty straight forward as we would expect so now we are done with implementing the <code>ErrorHandlingJSRuntime</code>. Let's make a small sample of using this to call a function that will fail and then catch the exception.</p> <pre><code class="language-razor">@inject IJSRuntime JSRuntime &lt;span style=&quot;color: red;&quot;&gt;@exceptionMessage&lt;/span&gt; @code { string? exceptionMessage; protected override async Task OnInitializedAsync() { try { var errorHandlingJSRuntime = new ErrorHandlingJSRuntime(JSRuntime); var url = await errorHandlingJSRuntime.InvokeAsync&lt;string&gt;(&quot;URL.createObjectURL&quot;, &quot;not a blob&quot;); } catch (TypeErrorException ex) { exceptionMessage = $&quot;Wrong type for argument. {ex.Message}&quot;; } catch (WebIDLException ex) { exceptionMessage = $&quot;An {ex.GetType().Name} happened: \&quot;{ex.Message}\&quot;&quot;; } catch (Exception) { exceptionMessage = &quot;An unexpected error happened.&quot;; } } } </code></pre> <p>In the above example, we try to call the <code>createObjectURL</code> method from the browser File API. This method takes a <code>Blob</code>, a <code>File</code>, or a <code>MediaSource</code> as its argument, but we passed a string to it. So it throws a <code>TypeErrorException</code> since there was no overload for the method taking a string. This results in the following message in our app:</p> <pre><code class="language-console">Wrong type for argument. Failed to execute 'createObjectURL' on 'URL': Overload resolution failed. </code></pre> <h3>Blazor.WebIDL</h3> <p>As the JS errors are declared in the WebIDL standard specifications I have included the work that we have done above in my <a href="https://github.com/KristofferStrube/Blazor.WebIDL">Blazor.WebIDL</a> package. You can add it to your project by running the following in the terminal while located in the folder of your Blazor project.</p> <pre><code class="language-bash">dotnet add package KristofferStrube.Blazor.WebIDL </code></pre> <p>And instead of having to construct the <code>ErrorHandlingJSRuntime</code> yourself, I've added an extension method that adds the needed services to the service collection so that you can just inject the <code>ErrorHandlingJSRuntime</code> as an <code>IErrorHandlingJSRuntime</code> in the pages that need it.</p> <pre><code class="language-csharp">builder.Services.AddErrorHandlingJSRuntime(); </code></pre> <p>I've made some more simplifications that make it easier to use. But for this to work we also need to call and await the extension method <code>SetupErrorHandlingJSInterop</code> on our <code>ServiceProvider</code> after we have <code>Build</code> the application, but before we run it.</p> <pre><code class="language-csharp">var app = builder.Build(); await app.Services.SetupErrorHandlingJSInterop(); await app.RunAsync(); </code></pre> <p>Then we can inject it into some Blazor page and use it directly to make invocations.</p> <pre><code class="language-razor">@inject IErrorHandlingJSRuntime ErrorHandlingJSRuntime &lt;button @onclick=&quot;ReadClipboard&quot;&gt;Copy from clipboard&lt;/button&gt; &lt;br /&gt; @if (result is not null) { &lt;p&gt;You have the text: '@result' in your clipboard&lt;/p&gt; } else { &lt;code&gt;@copyError&lt;/code&gt; } @code { private string? result; private string copyError = string.Empty; private async Task Copy() { try { result = await ErrorHandlingJSRuntime.InvokeAsync&lt;string&gt;(&quot;navigator.clipboard.readText&quot;); } catch (NotAllowedErrorException) { copyError = &quot;The user has not given permission to read the clipboard.&quot;; } catch (DOMException exception) { copyError = $&quot;{exception.Name} (which is a DOMException): \&quot;{exception.Message}\&quot;&quot;; } catch (Exception) { copyError = &quot;An unexpected error happened.&quot;; } } } </code></pre> <p>In the above sample, we try to read the content of the clipboard. You might not have given the site permission to do this and in this case, a <code>NotAllowedErrorException</code> will be thrown. If it wasn't this specific kind of <code>DOMException</code> that happened then it might have been some other <code>DOMException</code> type which is the next kind we try to catch and in the end, if it wasn't any of these we give back a general error message.</p> <p>I have also added error handling wrappers for the <code>IJSInProcessRuntime</code>, <code>IJSObjectReference</code>, and <code>IJSInProcessObjectReference</code> types and made sure that you get back an appropriate error handling version of an <code>IJSObjectReference</code> if this is the <code>TValue</code> type that you return from an invocation. So in total, we now have the following error-handling JSInterop interfaces that we can inject.</p> <ul> <li><code>IErrorHandlingJSRuntime</code></li> <li><code>IErrorHandlingJSInProcessRuntime</code></li> <li><code>IErrorHandlingJSObjectReference</code></li> <li><code>IErrorHandlingJSInProcessObjectReference</code></li> </ul> <p>The reason why we need to call the <code>SetupErrorHandlingJSInterop</code> was so that we could return <code>IErrorHandlingJSObjectReference</code>s without having to resolve the helper asynchronously when creating it but also so that we can use the <code>IErrorHandlingJSInProcessRuntime</code> when using Blazor WASM to make synchronous JS invocations without using some asynchronous factory to create the runtime each time it is needed.</p> <h3>Future plans</h3> <p>The plan is to also make an error-handling version of the <code>IJSUnmarshalledRuntime</code> in the future. And I intend to upgrade all my existing browser API packages <a href="https://github.com/KristofferStrube/Blazor.FileSystemAccess">Blazor.FileSystemAccess</a>, <a href="https://github.com/KristofferStrube/Blazor.FileSystem">Blazor.FileSystem</a>, <a href="https://github.com/KristofferStrube/Blazor.FileAPI">Blazor.FileAPI</a>, <a href="https://github.com/KristofferStrube/Blazor.Streams">Blazor.Streams</a>, <a href="https://github.com/KristofferStrube/Blazor.CompressionStreams">Blazor.CompressionStreams</a>, <a href="https://github.com/KristofferStrube/Blazor.WebAudio">Blazor.WebAudio</a>, <a href="https://github.com/KristofferStrube/Blazor.MediaCaptureStreams">Blazor.MediaCaptureStreams</a>, <a href="https://github.com/KristofferStrube/Blazor.DOM">Blazor.DOM</a> and all my future ones to use the error-handling versions when they make JSInterop calls.</p> <h3>Conclusion</h3> <p>At the start of this post, we saw some of the existing approaches for handling different types of exceptions when making JSInterop calls in Blazor. And we now know that this is because we don't get the name of the exception extracted when the error is returned to C#. We then found a way to catch more details of the error on the JS side of the invocation and re-throw these details back to Blazor where we could then unpack the name, message, and stack trace separately and map them to custom C# exception types. In the end, I presented the <a href="https://github.com/KristofferStrube/Blazor.WebIDL">Blazor.WebIDL</a> package that has made this <code>ErrorHandlingJSRuntime</code> easy to add to any project where you want to have typed exceptions when using JSInterop. We also went through a small example of using the package to make handle different error scenarios. I would be very happy if people want to test the package and give feedback on the GitHub repository so that I can make sure that it is both easy and safe to use. The library is still in alpha while I test it in some of my libraries, but there won't go long before I make a first full release. And as always, if you have any feedback or questions for this post then feel free to reach out to me on Mastodon or Twitter.</p> typed-signalr-clients-making-type-safe-real-time-communication-in-dotnethttps://kristoffer-strube.dk/post/typed-signalr-clients-making-type-safe-real-time-communication-in-dotnet/A small feature that was introduced during one of the previews of .NET 7 was typed SignalR clients enabling us to develop real-time tools with type safety. This means that we can make a shared contract that defines which methods can be invoked on the SignalR hub and which can be invoked on the SignalR Client. This is possible by using source generators which have been a huge focus in .NET 7 in general. In this post, we will make a sticky note bulletin board in Blazor WASM and add real-time collaboration to it using a typed SignalR client to showcase how to use typed SignalR clients.Thu, 06 Apr 2023 00:00:00 +02002023-04-06T00:00:00+02:00<h3>Project features</h3> <p>Before getting started with the actual project I want to outline the features that I would like for our real-time sticky note bulletin board.</p> <h4>Creating sticky notes</h4> <p>First of all, I would like to be able to create sticky notes and present them on a screen as yellow squares with text on them.</p> <h4>Writing text</h4> <p>I would like to be able to edit the text on the notes and for these changes to propagate to other users in real-time.</p> <h4>Moving notes</h4> <p>I would also like to be able to move each sticky note to be able to communicate association by proximity or order.</p> <h4>Deletion</h4> <p>After having written on the sticky notes I would like to be able to delete them again. I also want an option for deleting all sticky notes to clear the board.</p> <h4>Locking</h4> <p>When multiple users can move, write, and delete the same sticky notes then I would also like users to get a lock on a sticky note while they edit it i.e. so that others can intervene or move the note away while the user is writing on it. <em>A disclaimer is that the only system concurrency-related education I have is on peer-2-peer systems and blockchains so I wouldn't use the same approaches as I have employed on a large scale system as they simply are my loose ideas for a concurrency heuristic.</em></p> <p>The following image is a rough mockup of what I would like it to look like. But we might make changes as we go.</p> <p><img src="https://kristoffer-strube.dk/images/mock.png" alt="Drawn mockup of what we would like the bulletinboard to look like." /></p> <h3>Solution structure</h3> <p>The solution will consist of three different projects that we need to make our bulletin board functional. We start by making a new folder and then a new solution file.</p> <pre><code class="language-bash">mkdir DistributedStickyNotes cd DistributedStickyNotes dotnet new sln </code></pre> <h4>Shared</h4> <p>We need a small shared project in the form of a Class Library. This will hold the interfaces which define which methods the clients and the hub has and it will define our <code>Note</code> class which is what we will use to represent each sticky note. We create this project in a new sub-folder called <code>Shared/</code> and then we will get back to filling out the actual content for it later.</p> <pre><code class="language-bash">mkdir Shared cd Shared dotnet new classlib cd .. </code></pre> <h4>Client</h4> <p>Next, we need the actual Blazor WASM client. This will present the sticky notes to each user and use the generated typed SignalR client. This is a really simple project with a single purpose so for this, we use the empty variant of the Blazor WASM templates.</p> <pre><code class="language-bash">mkdir Client cd Client dotnet new blazorwasm-empty cd .. </code></pre> <h4>Server</h4> <p>The last part is the server that will host our SignalR hub enabling each client to communicate indirectly. It will also maintain the state of the bulletin board being our single source of truth both with regards to the information about each note and its locks. For this, we create an ASP.NET API using the Minimal API template.</p> <pre><code class="language-bash">mkdir Server cd Server dotnet new webapi -minimal true cd .. </code></pre> <p>Then in the end we add references to all the projects from the solution and add references to the Shared project from both the Client and Server projects.</p> <pre><code class="language-bash">dotnet sln add Shared dotnet sln add Client dotnet sln add Server cd Client dotnet add reference ../Shared cd ../Server dotnet add reference ../Shared cd .. </code></pre> <p>Then we can start coding in whatever IDE is your favourite. Be that Rider, Visual Studio, Emacs, or something else.</p> <h3>Communication interface</h3> <p>The first part we create is the interfaces that define the contract that the clients and the server will follow to communicate with each other. Before we make the interfaces we create the model that will represent a sticky note as we will use this to parse information between the client and the server. We create this in the Shared project.</p> <h5>Note.cs</h5> <pre><code class="language-csharp">public class Note { public Note() { } public Note(double x, double y) { Id = Guid.NewGuid(); LastEdited = DateTimeOffset.UtcNow; X = x; Y = y; } public Guid Id { get; set; } public string Text { get; set; } = string.Empty; public double X { get; set; } public double Y { get; set; } public string? LastLockingUser { get; set; } public DateTimeOffset LastEdited { get; set; } } </code></pre> <p>We define two constructors. One that is empty will be used for deserializing the model when receiving it. The second constructor takes a position as we always want to know where to place a new Note. This also sets the <code>Id</code> to a new random <code>Guid</code> which we will use to identify the <code>Note</code>. It also defines that the <code>Note</code> has been edited right now as it was constructed. We have some other properties that we don't set in the constructor. We have the <code>Text</code> which is what will be displayed on the <code>Note</code> and we have <code>LastLockingUser</code> which we will use to identify which user currently has the lock for editing this.</p> <p>Next, we create the interface for which methods we want available to be able to call on the hub from the client.</p> <h5>IStickyNoteHub.cs</h5> <pre><code class="language-csharp">public interface IStickyNoteHub { Task&lt;List&lt;Note&gt;&gt; LoadNotes(); Task CreateNote(double x, double y); Task UpdateNoteText(Guid id, string text); Task&lt;bool&gt; LockNote(Guid id); Task MoveNote(Guid id, double x, double y); Task ClearNotes(); Task DeleteNote(Guid id); } </code></pre> <p>The methods all return <code>Task</code> as this communication is inherently asynchronous. Each of these is represented by one of the features that we wanted for our bulletin board.</p> <p>We also have communication the other way i.e. server-to-client. For this, we create another interface representing the client and the things it will listen for.</p> <h5>IStickyNoteClient.cs</h5> <pre><code class="language-csharp">public interface IStickyNoteClient { Task NoteCreated(Note note); Task NoteUpdated(Note note); Task NoteDeleted(Guid id); } </code></pre> <p>These likewise return <code>Task</code> and enable the client to react to new notes being created, any changes being broadcasted, and when notes are being deleted.</p> <h3>Typed SignalR Hub</h3> <p>The next part is to implement the SignalR hub in the Server project. For this, we use the existing strongly typed Hub class and implement the <code>IStickyNoteHub</code> interface.</p> <h5>StickyNoteHub.cs</h5> <pre><code class="language-csharp">public class StickyNoteHub : Hub&lt;IStickyNoteClient&gt;, IStickyNoteHub { // We will add the required methods here. } </code></pre> <p>Before we actually implement the methods of the <code>IStickyNoteHub</code> interface we will need somewhere to store our sticky notes. We will make a very simple static class with a static collection in it. We could have used some service for managing this, but for the purpose of this demo, we will be okay with this.</p> <h5>StaticStorage.cs</h5> <pre><code class="language-csharp">public static class StaticStorage { public static List&lt;Note&gt; Notes { get; set; } = new(); } </code></pre> <p>Then we are ready to implement each of the methods from our hub interface. First, we implement <code>LoadNotes</code> which is really simple to implement given our <code>StaticStorage</code> collection.</p> <pre><code class="language-csharp">public Task&lt;List&lt;Note&gt;&gt; LoadNotes() { return Task.FromResult(StaticStorage.Notes); } </code></pre> <p>Then we add the method for adding a new Note <code>CreateNote</code>. This will create a new <code>Note</code> and notify all connected users that it was added by invoking the <code>IStickyNoteClient</code> method <code>NoteCreated</code>. When notifying that it was created it also sends the <code>Note</code> object itself so that the clients have a local copy of it. Together with the <code>LoadNotes</code> method, this ensures that each user has a local copy of all sticky notes that were created before the user joined and all notes that were created later.</p> <pre><code class="language-csharp">public async Task CreateNote(double x, double y) { var newNote = new Note(x, y); StaticStorage.Notes.Add(newNote); await Clients.All.NoteCreated(newNote); } </code></pre> <p>Next, we implement the method for updating the text of a sticky note.</p> <pre><code class="language-csharp">public async Task UpdateNoteText(Guid id, string text) { if (StaticStorage.Notes.FirstOrDefault(note =&gt; note.Id == id) is not { } serverNote) return; if (!serverNote.TryLock(Context.ConnectionId, Clients.Others)) { await Clients.Caller.NoteUpdated(serverNote); return; } serverNote.Text = text; await Clients.Others.NoteUpdated(serverNote); } </code></pre> <p>The method takes the <code>id</code> of an existing sticky note and the updated <code>text</code>. We first go through all the notes and find the one that has a matching <code>Id</code>. If there was none then we simply return as the client must then have been in some bad state which we should ignore. Then we call the method <code>TryLock</code> on the <code>Note</code> which tries to lock it so that only this user can change it for a short time. If it was not successful in locking the sticky note then we update the original calling client with the current state of the note so that it knows that this is locked by someone else. If it was successful then we update the text and notify all other clients of this new state. We don't need to notify the original client in this case as it will optimistically assume that it could get the lock. Let's implement the <code>TryLock</code> method on the <code>Note</code> class now while we are here. To implement this we first need two secondary methods which will become useful in other scenarios: A method for checking if a user <em>can</em> lock and a method that sets the lock. We add the following method called <code>CanLock</code> to our <code>Note</code> model.</p> <pre><code class="language-csharp">public bool CanLock(string? connectionId) =&gt; DateTimeOffset.UtcNow.Subtract(LastEdited).TotalSeconds &gt; 1 || LastLockingUser is null || LastLockingUser == connectionId; </code></pre> <p>The method takes a <code>connectionId</code> which is the id of the user that wants to lock. We state that the <code>Note</code> can be locked if it hasn't been edited within the last second, if no user has locked it before, or if the last user that locked it was the one with <code>connectionId</code>. And then we create the method that actually locks. It does so by updating the time of the last edit to the current time and by setting the locking user to the given one.</p> <pre><code class="language-csharp">public void Lock(string? connectionId) { LastLockingUser = connectionId; LastEdited = DateTimeOffset.UtcNow; } </code></pre> <p>Now, we can implement the <code>TryLock</code> method.</p> <pre><code class="language-csharp">private CancellationTokenSource? cts; public bool TryLock(string? connectionId, IStickyNoteClient others) { lock (this) { if (!CanLock(connectionId)) return false; Lock(connectionId); cts?.Cancel(); if (others is null) return true; cts = new CancellationTokenSource(); ThreadPool.QueueUserWorkItem(new WaitCallback(async parameter =&gt; { CancellationToken token = (CancellationToken)parameter!; await Task.Delay(1000); if (token.IsCancellationRequested) return; await others.NoteUpdated(this); }), cts.Token); return true; } } </code></pre> <p>It first locks the <code>Note</code> which is simply to enforce that only one user can try to lock a <code>Note</code> at any one point. Then we check if the user can lock the <code>Note</code> and if it can't then we return false. Else we lock it. The user will have a valid lock for <code>1</code> second and after this everyone should know that the sticky note is no longer locked. We do this by waiting for <code>1 second</code> on a new thread and then updating all other users with the new state. We only start this thread if the others parameter is not <code>null</code> indicating that we want to be informed once the note is free again. We parse a <code>CancellationToken</code> to the new thread which we will use to cancel notifying all other users if the lock has been reacquired within the <code>1 second</code> which would extend its lock time so that we don't spam all other users with updates of the lock state while the user is continuously editing.</p> <p>Next, we need to handle the moving of a sticky note. This will often be a long continuous set of updated coordinates over a period of time. For this reason, we want to ensure that the client has the lock for a note before they are allowed to start moving it. So now, we implement the hub method <code>LockNote</code> which returns a boolean indicating whether the <code>Note</code> was locked.</p> <pre><code class="language-csharp">public async Task&lt;bool&gt; LockNote(Guid id) { if (StaticStorage.Notes.FirstOrDefault(note =&gt; note.Id == id) is not { } serverNote) return false; if (!serverNote.TryLock(Context.ConnectionId, Clients.Others)) return false; await Clients.Others.NoteUpdated(serverNote); return true; } </code></pre> <p>Alike <code>UpdateNoteText</code> it also has the <code>id</code> of a sticky note as its parameter and tries to find that specific <code>Note</code> from our static collection. Next, if it did find it, it also tries to lock it and notify all other clients it was successful as that would change the state of the note. The client will wait for it to return before it continues and if it returns true then it knows that it can move the sticky note. The clients then update the position of the note by calling the <code>MoveNote</code> hub method.</p> <pre><code class="language-csharp">public async Task MoveNote(Guid id, double x, double y) { if (StaticStorage.Notes.FirstOrDefault(note =&gt; note.Id == id) is not { } serverNote) return; if (!serverNote.TryLock(Context.ConnectionId, Clients.Others)) { await Clients.Caller.NoteUpdated(serverNote); return; } serverNote.X = x; serverNote.Y = y; await Clients.Others.NoteUpdated(serverNote); } </code></pre> <p>It likewise finds the relevant <code>Note</code> and tries to lock it. In this case, it will likely extend its lock by calling <code>TryLock</code> unless it eventually hasn't moved for a full second which will make it possible for others to get the lock instead. If it is successful in getting or extending its lock then it updates the position of the note as expected and updates all other users of this update else it notifies the original caller of the updated state.</p> <p>Finally, we just need to implement the methods for deleting a single note and clearing all notes.</p> <pre><code class="language-csharp">public async Task DeleteNote(Guid id) { if (StaticStorage.Notes.FirstOrDefault(note =&gt; note.Id == id) is not { } serverNote) return; if (!serverNote.TryLock(Context.ConnectionId)) return; StaticStorage.Notes.Remove(serverNote); await Clients.All.NoteDeleted(id); } </code></pre> <p>What we do in this method is very similar to what we do in the other method except for the fact that we do not want to update all other users once the lock is no longer active as the <code>Note</code> will have been removed at that point.</p> <p>The <code>ClearNotes</code> hub method is the last one we need before having implemented <code>IStickyNoteHub</code> fully. It simply goes through the <code>Id</code>s of all sticky notes and tries to delete them one by one. It can likewise only delete each individual sticky note if no other user has a lock on it.</p> <pre><code class="language-csharp">public async Task ClearNotes() { var noteIds= StaticStorage.Notes.Select(note =&gt; note.Id).ToList(); foreach (var id in noteIds) { await DeleteNote(id); } } </code></pre> <p>While we are in the Server project let's configure the hub so that it is ready to be connected. We do this in <code>Program.cs</code> by calling <code>AddSignalR</code> on our service collection and by mapping our typed SignalR hub to an endpoint. I've made a very minimal setup like this:</p> <h5>Programs.cs</h5> <pre><code class="language-csharp">var builder = WebApplication.CreateBuilder(args); builder.Services.AddSignalR(); builder.Services.AddCors(); var app = builder.Build(); app.UseHttpsRedirection(); app.UseCors(builder =&gt; builder.WithOrigins(&quot;https://localhost:7171&quot;) .AllowAnyMethod() .AllowAnyHeader()); app.MapHub&lt;StickyNoteHub&gt;(&quot;/stickynotehub&quot;); app.Run(); </code></pre> <p>I added the CORS settings as well since we are going to connect to the hub from our browser which expects CORS headers.</p> <h3>Typed SignalR Client</h3> <p>Now we are ready to implement our <code>IStickyNoteClient</code> client interface. This is where all the new stuff happens which enables us to make typed calls to the hub to listen to events from the hub with relative ease. We first need to add two packages to our Blazor project.</p> <p>First, the client library for SignalR</p> <pre><code class="language-bash">dotnet add package Microsoft.AspNetCore.SignalR.Client </code></pre> <p>And then the source generator package that will make our life a piece of cake. This package is only available as a preview package as it was created during the preview development of .NET 7.</p> <pre><code class="language-bash">dotnet add package Microsoft.AspNetCore.SignalR.Client.SourceGenerator </code></pre> <h4>Source generation setup</h4> <p>To bootstrap the source generation for our typed client and hub proxy we need to define two attributes that the source generator package will use to target certain partial methods.</p> <h5>HubServerProxyAttribute.cs</h5> <pre><code class="language-csharp">[AttributeUsage(AttributeTargets.Method)] internal class HubServerProxyAttribute : Attribute { } </code></pre> <h5>HubClientProxyAttribute.cs</h5> <pre><code class="language-csharp">[AttributeUsage(AttributeTargets.Method)] internal class HubClientProxyAttribute : Attribute { } </code></pre> <p>The attributes are then used on these partial extension methods which make the source generator generate separate partial methods.</p> <h5>HubConnectionExtensions.cs</h5> <pre><code class="language-csharp">public static partial class HubConnectionExtensions { [HubClientProxy] public static partial IDisposable ClientRegistration&lt;T&gt;(this HubConnection connection, T provider); [HubServerProxy] public static partial T ServerProxy&lt;T&gt;(this HubConnection connection); } </code></pre> <h4>Implementing IStickyNoteClient</h4> <p>Then we are ready to make the code-behind for our <code>Index.razor</code> page. We start off by defining some fields and overriding the <code>OnInitializedAsync</code> method which will be called once the page is created.</p> <h5>Index.razor.cs</h5> <pre><code class="language-csharp">public partial class Index : IStickyNoteClient { private List&lt;Note&gt; notes = new(); private IStickyNoteHub hubProxy = default!; private HubConnection connection = default!; protected override async Task OnInitializedAsync() { connection = new HubConnectionBuilder() .WithUrl(&quot;https://localhost:7210/stickynotehub&quot;) .Build(); hubProxy = connection.ServerProxy&lt;IStickyNoteHub&gt;(); _ = connection.ClientRegistration&lt;IStickyNoteClient&gt;(this); await connection.StartAsync(); notes = await hubProxy.LoadNotes(); } // Methods that implement IStickyNoteClient will be inserted below here } </code></pre> <p>The first thing we did was to make the page implement <code>IStickyNoteClient</code>. We do this as we want the page itself to be what handles all notifications from the hub. Then we add a couple of fields. First a list of notes which will be our local copy of all notes and after this two fields that represent the abstraction of our hub which we can use to call the methods of the hub and the connection itself. In <code>OnInitializedAsync</code> we create the connection and make a proxy for our hub using the extension method we defined earlier. Then we register our page as the client for our connection, start the connection, and load all the initial notes if there are any.</p> <p>Then we just need to implement the methods which <code>IStickyNoteClient</code> defines to handle the events coming from the hub. We start off with <code>NoteCreated</code>.</p> <pre><code class="language-csharp">public Task NoteCreated(Note note) { notes.Add(note); StateHasChanged(); return Task.CompletedTask; } </code></pre> <p>We simply add the new note to our local collection and update and force the UI to update by invoking <code>StateHasChanged</code>. Then we implement the method for handling a sticky note that has been updated.</p> <pre><code class="language-csharp">public Task NoteUpdated(Note note) { if (notes.FirstOrDefault(n =&gt; n.Id == note.Id) is not { } localNote) return Task.CompletedTask; localNote.Text = note.Text; localNote.X = note.X; localNote.Y = note.Y; localNote.LastLockingUser = note.LastLockingUser; localNote.LastEdited = note.LastEdited; StateHasChanged(); return Task.CompletedTask; } </code></pre> <p>This should look very familiar by now. We find the relevant <code>Note</code>, update its properties, and update the UI. The last method which handles when a note is deleted is likewise pretty simple:</p> <pre><code class="language-csharp">public Task NoteDeleted(Guid id) { if (notes.FirstOrDefault(n =&gt; n.Id == id) is not { } localNote) return Task.CompletedTask; notes.Remove(localNote); StateHasChanged(); return Task.CompletedTask; } </code></pre> <h4>Handling pointer events</h4> <p>Next we need to add a couple of methods to the code-behind that will handle different kinds of user input when the user moves the sticky notes around. We first write the method that handles when a sticky note starts being moved.</p> <pre><code class="language-csharp">private (double x, double y)? anchor; private Note? editNote; public async Task Down(Note note, PointerEventArgs eventArgs) { if (!await hubProxy.LockNote(note.Id)) return; note.Lock(connection.ConnectionId); anchor = (eventArgs.ClientX, eventArgs.ClientY); editNote = note; } </code></pre> <p>It first tries to get a lock at the server through the hub proxy. If it got it then we lock our local copy and set two fields that we have added which will manage which note we are currently moving and what position the pointer was at the last time we saw it.</p> <p>Next, we need to define what happens when we move the pointer.</p> <pre><code class="language-csharp">public async Task Move(PointerEventArgs eventArgs) { if (anchor is not (double x, double y) || editNote is null || !editNote.CanLock(connection.ConnectionId)) return; editNote.X += eventArgs.ClientX - x; editNote.Y += eventArgs.ClientY - y; editNote.LastEdited = DateTimeOffset.UtcNow; anchor = (eventArgs.ClientX, eventArgs.ClientY); await hubProxy.MoveNote(editNote.Id, editNote.X, editNote.Y); } </code></pre> <p>If either the anchor is <code>null</code>, there is no current edit <code>Note</code>, or if we can't lock the current <code>Note</code> then we do nothing. But if we were successful then we update the position of the current <code>Note</code> and when it was last edited which extends our local lock. We also update the anchor with our last position and finally tell the hub that we have moved the sticky note.</p> <p>Then we just need to handle when the pointer is raised which means the user is done moving the sticky note.</p> <pre><code class="language-csharp">public async Task Up(PointerEventArgs eventArgs) { await Move(eventArgs); anchor = null; editNote = null; } </code></pre> <p>We first invoke the <code>Move</code> method to update the position for the last time before setting both the edit <code>Note</code> and the anchor to <code>null</code>. Then we are ready to write the markup that will present the actual sticky notes.</p> <h4>Presenting the sticky notes</h4> <p>We first need a little CSS for our text and our markers (delete cross and pin). We added the following to the <code>app.css</code> file of our project which was pre-generated with the template.</p> <h5>app.css</h5> <pre><code class="language-CSS">html, body, #app, main { margin: 0; width: 100%; height: 100%; overflow:hidden; } .note-textarea { min-width: 100%; min-height: 100%; max-width: 100%; max-height: 100%; background-color: transparent; border: 0; font-family: cursive; font-size: 20px; } .note-textarea:focus { outline: none; } .note-markers { font-size: 20px; user-select: none; touch-action: none; } </code></pre> <p>This will remove all margins and make use of the full width of the page all the way down to our page and the note-related classes are simple styling for our text and markers.</p> <p>Then we can begin to fill out our page.</p> <pre><code class="language-html">@page &quot;/&quot; &lt;button @onclick=&quot;() =&gt; hubProxy.CreateNote(10, 10)&quot;&gt;Create Sticky Note ➕&lt;/button&gt; &lt;button @onclick=&quot;hubProxy.ClearNotes&quot;&gt;Clear All Sticky Notes ❌&lt;/button&gt; &lt;svg width=&quot;100%&quot; height=&quot;100%&quot; @onpointerup=&quot;Up&quot; @onpointerleave=&quot;Up&quot; @onpointermove=&quot;Move&quot;&gt; &lt;defs&gt; &lt;filter id=&quot;shadow&quot; x=&quot;0&quot; y=&quot;0&quot; width=&quot;200%&quot; height=&quot;200%&quot;&gt; &lt;feOffset result=&quot;offOut&quot; in=&quot;SourceAlpha&quot; dx=&quot;5&quot; dy=&quot;5&quot; /&gt; &lt;feGaussianBlur result=&quot;blurOut&quot; in=&quot;offOut&quot; stdDeviation=&quot;2.5&quot; /&gt; &lt;feBlend in=&quot;SourceGraphic&quot; in2=&quot;blurOut&quot; mode=&quot;normal&quot; /&gt; &lt;/filter&gt; &lt;/defs&gt; @foreach (var note in notes) { &lt;!-- This is where each Note will be drawn --&gt; } &lt;/svg&gt; </code></pre> <p>We make two buttons in the top of the page for creating new sticky notes and clearing all notes. After this, we make an SVG tag that fills the rest of the page. The tag has three event handlers. Two for when the pointer is raised or the pointer leaves the SVG tag which will trigger the <code>Up</code> method and end the current drag if there is any. The third event handler is for when we move the pointer which will move the <code>Note</code> if there is an active drag. Inside the SVG tag, we define a filter that makes a blurred black-and-white shadow that we use on each <code>Note</code> and then we loop over all the notes and present them each individually.</p> <p>For each <code>Note</code> we first draw a rectangle that represents the piece of paper. There is nothing special about it except for the fact that it changes color if the user can't lock the card. We also apply the filter that we defined before.</p> <pre><code class="language-html">&lt;rect fill=&quot;@(note.CanLock(connection.ConnectionId) ? &quot;#FFFF8F&quot; : &quot;#FFDF8F&quot;)&quot; x=&quot;@note.X.AsString()&quot; y=&quot;@note.Y.AsString()&quot; stroke=&quot;#DDDD80&quot; stroke-width=&quot;1&quot; width=&quot;200px&quot; height=&quot;200px&quot; filter=&quot;url(#shadow)&quot;&gt; &lt;/rect&gt; </code></pre> <p>Then we need to draw the text that is on the <code>Note</code>. For this, we use the <code>foreignObject</code> SVG tag enables us to inline HTML in SVG which we use to inline a <code>textarea</code>.</p> <pre><code class="language-html">&lt;foreignObject x=&quot;@note.X&quot; y=&quot;@((note.Y+30).AsString())&quot; width=&quot;200px&quot; height=&quot;170px&quot;&gt; &lt;textarea @bind=note.Text @bind:event=&quot;oninput&quot; @bind:after=&quot;() =&gt; hubProxy.UpdateNoteText(note.Id, note.Text)&quot; disabled=&quot;@(!note.CanLock(connection.ConnectionId))&quot; class=&quot;note-textarea&quot;&gt; &lt;/textarea&gt; &lt;/foreignObject&gt; </code></pre> <p>We place the <code>foreignObject</code> in the same place as the rectangle, but shift it down <code>30 pixels</code> to make space for the markers at the top. We then <code>@bind</code> the value of the <code>textarea</code> to the text of <code>Note</code> and change the binding event to be <code>oninput</code> instead of the default <code>onchange</code> to make updates trigger more often. Then we use the new <code>@bind:after</code> event to call <code>UpdateNoteText</code> on our hub which will trigger every time the text of the <code>Note</code> has been updated locally. We also disable the <code>textarea</code> itself if the <code>Note</code> can't be locked by the user.</p> <p>The last part is just to make our two markers. For this, we use the SVG tag <code>text</code>. This tag has been overloaded by <code>Blazor</code> to explicitly start a markup section so we need to embed our two markers in an extra <code>text</code> tag.</p> <pre><code class="language-html">&lt;text&gt; &lt;text @onclick=&quot;() =&gt; hubProxy.DeleteNote(note.Id)&quot; x=&quot;@note.X.AsString()&quot; y=&quot;@note.Y.AsString()&quot; alignment-baseline=&quot;before-edge&quot; class=&quot;note-markers&quot; style=&quot;pointer-events:@(note.CanLock(connection.ConnectionId) ? &quot;inherit&quot; : &quot;none&quot;)&quot;&gt; ❌ &lt;/text&gt; &lt;text @onpointerdown=&quot;e =&gt; Down(note, e)&quot; x=&quot;@((note.X+180).AsString())&quot; y=&quot;@note.Y.AsString()&quot; alignment-baseline=&quot;before-edge&quot; class=&quot;note-markers&quot; style=&quot;pointer-events:@(note.CanLock(connection.ConnectionId) ? &quot;inherit&quot; : &quot;none&quot;)&quot;&gt; @(note == editNote || !note.CanLock(connection.ConnectionId) ? &quot;📌&quot; : &quot;📍&quot;) &lt;/text&gt; &lt;/text&gt; </code></pre> <p>We place the delete cross on the left side of the <code>Note</code> and the pin on the right side. Both use <code>alignment-baseline=&quot;before-edge&quot;</code> which aligns them towards the top of the <code>Note</code> vertically. For both markers, we disable pointer events if the <code>Note</code> can't be locked by the user. We also add that the pin switches icon if we ourselves are currently moving it or if someone else has the lock on it.</p> <p>Then we are done and we can enjoy the result of our work in this short video.</p> <video width="700" autoplay muted controls loop> <source src="https://kristoffer-strube.dk/videos/sticky-notes-demo.mp4" type="video/mp4"> A video showing the demo of using the real-time sticky note bulletin board. </video> <p>You can check out the full code that was created in this post here: <a href="https://github.com/KristofferStrube/DistributedStickyNotes">https://github.com/KristofferStrube/DistributedStickyNotes</a></p> <p>You can try out the above demo yourself here: <a href="https://kristofferstrube.github.io/DistributedStickyNotes/">https://kristofferstrube.github.io/DistributedStickyNotes/</a></p> <h3>Why Blazor WASM?</h3> <p>Before closing off, I promised some people to talk about why I think it makes sense to look at using Blazor WASM together with SignalR event though Blazor Server is already Blazor with SignalR. I think it makes sense to use Blazor WASM when you have rich interactive applications as having a minimal delay for these interactions is essential. Apart from this using SignalR with Blazor WASM also enables us to be much more specific about what we actually send back and forward and we could even deploy limits to this with approaches like throttling. Apart from this, I also like that the Blazor WASM application can live without the connection where it can try to reconnect for a longer time, potentially present other information while reconnecting, and save the current state of the application and re-apply it once reconnected so that no information is lost.</p> <h3>Conclusion</h3> <p>In this post, we have walked through an example application that utilizes real-time communication. We have explored some approaches to manage concurrent work and interactions. We have looked at how to use typed SignalR hubs and how to use typed SignalR clients to enable end-to-end type safe real-time communication. In the end, we presented a demo of the project and reflected on why it makes sense to use Blazor WASM together with SignalR. We might continue this project in a future blog post touching on scaling using Azure SignalR Service and how to authenticate SignalR connection. If you have any questions or comments for this post then feel free to reach out.</p> how-to-send-push-notifications-to-a-browser-in-asp-net-corehttps://kristoffer-strube.dk/post/how-to-send-push-notifications-to-a-browser-in-asp-net-core/Progressive Web Apps (PWAs) enable a website to make make a lot of interactions that are app-like. Among these are Push Notifications. This is a functionality that enables you to make native notifications for many different devices and to invoke these notifications even when the browser is not active. A lot of websites like the Twitter web app use this functionality with its original intent, but there are of cause also sites that use it maliciously. In this article, we will show how you can subscribe to Push Notifications using ASP.NET Core and how you can send Push Notifications from .NET as well.Wed, 22 Mar 2023 00:00:00 +01002023-03-22T00:00:00+01:00<p><em>This is a cross-post of this ASP.NET Core MVC-focused post by me: <a href="https://blog.elmah.io/how-to-send-push-notifications-to-a-browser-in-asp-net-core/">https://blog.elmah.io/how-to-send-push-notifications-to-a-browser-in-asp-net-core/</a></em></p> <p>You can find the full code for the project built in this post, in this GitHub Repository: <a href="https://github.com/KristofferStrube/PWAPushNotification">https://github.com/KristofferStrube/PWAPushNotification</a></p> <h3>Setting up a minimal PWA</h3> <p>Before we can get started we need to set up a minimal Service Worker and Manifest to meet the minimum requirements for a PWA (Progressive Web App) since we need a PWA for using the Notification API. We first create the manifest by making a JSON file called <code>manifest.json</code> which we will place in the <code>wwwroot</code> folder.</p> <pre><code class="language-json">{ &quot;name&quot;: &quot;PWA Push Notification&quot;, &quot;short_name&quot;: &quot;Push&quot;, &quot;icons&quot;: [ { &quot;src&quot;: &quot;/images/icon-48x48.png&quot;, &quot;sizes&quot;: &quot;48x48&quot;, &quot;type&quot;: &quot;image/png&quot; }, { &quot;src&quot;: &quot;/images/icon-512x512.png&quot;, &quot;sizes&quot;: &quot;512x512&quot;, &quot;type&quot;: &quot;image/png&quot; }, { &quot;src&quot;: &quot;/images/icon-192x192.png&quot;, &quot;sizes&quot;: &quot;192x192&quot;, &quot;type&quot;: &quot;image/png&quot; } ], &quot;start_url&quot;: &quot;/&quot;, &quot;display&quot;: &quot;standalone&quot;, &quot;background_color&quot;: &quot;#959595&quot;, &quot;theme_color&quot;: &quot;#FFFFFF&quot; } </code></pre> <p>Here we define the name for the app, the name that will be displayed in the app if installed on a device, icons for the app in a variety of sizes, the front page URL of the site if the website can be installed as a standalone app, and at the end theme colors. We add a reference to the manifest in the <code>head</code> of our layout file which is used in all our views <code>&lt;link rel=&quot;manifest&quot; href=&quot;/manifest.json&quot;&gt;</code>.</p> <p>We then need to add a Service Worker. We make the minimal Service Worker by creating a JavaScript file <code>ServiceWorker.js</code>, also in the <code>wwwroot</code> folder with the following content.</p> <pre><code class="language-javascript">self.addEventListener('fetch', function (event) { }); </code></pre> <p>We reference the service worker by inserting the following script either in a script tag element in your layout file or directly in your main js file if you have such one.</p> <pre><code class="language-javascript">if ('serviceWorker' in navigator) { window.addEventListener(&quot;load&quot;, () =&gt; { navigator.serviceWorker.register(&quot;/ServiceWorker.js&quot;); }); } </code></pre> <p>This code simply checks if your browser supports Service Workers and registers your Service Worker if it does so. Now we have a working Manifest and Service Worker.</p> <h3>Subscription and push flow</h3> <p>There are 3 primary actors in the subscription/push flow. The web page (includes Service Worker), the push service, and the server. This flow uses a pair of keys, private and public from a standard called VAPID (Voluntary Application Server Identification). There are other ways to secure the communication e.g. FCM (Firebase Cloud Messaging), but VAPID doesn't require you to use any specific platform so we use that. To start we need to make a key pair and save this in our app settings. It's an open standard that uses elliptic curve cryptography and there are a lot of implementations that generate these pairs like the python library <a href="https://pypi.org/project/py-vapid/">py-vapid</a>, the node module <a href="https://www.npmjs.com/package/web-push">web-push</a> or the online tool <a href="https://tools.reactpwa.com/vapid">tools.reactpwa.com/vapid</a>. We will generate a pair and add it to <code>appsettings.json</code>.</p> <pre><code class="language-json">{ &quot;VAPID&quot;: { &quot;subject&quot;: &quot;mailto:mail@example.com&quot;, &quot;publicKey&quot;: &quot;BPTnFPVQFAhlIFSWqAjFPtQeEz ... udykg&quot;, &quot;privateKey&quot;: &quot;4jO3OrjQY2ilE ... yuhZWho47Q&quot; } } </code></pre> <p>The <code>private key</code> is never used in other places than on the server and should be kept a secret. The <code>public key</code> is distributed to the web page and the push service to validate messages. We will send the public key in the next part and the webpage will distribute it to the push service when subscribing. The <code>public key</code> is used when subscribing so that the push messages from the server can be authenticated because they are signed using the <code>private key</code>. When the web page subscribes to the push service it gets back an <code>endpoint</code> which the server will use to send its push message to and two variables <code>p256dh</code> and <code>auth</code> that will be used to identify the subscription.</p> <h3>Subscribe to Push Notifications</h3> <p>We now want to make a view where we go through a few steps to subscribe to Push Notifications. We separate this into 3 states. First, we have a part that we will display if the user has not decided if they will allow Notifications. Then we have a part that we will display either if the browser does not support Notifications or if the user has blocked Notifications. Last, we have a form that we will use to submit an identifier for the user, the <code>endpoint</code>, and the two subscription identification variables <code>p256dh</code> and <code>auth</code>.</p> <pre><code class="language-html">&lt;h1&gt;Subscribe to Push Notifications&lt;/h1&gt; &lt;div id=&quot;GiveAccess&quot; style=&quot;display:none;&quot;&gt; Give access to making notifications: &lt;button id=&quot;PromptForAccessBtn&quot;&gt;Prompt&lt;/button&gt; &lt;/div&gt; &lt;div id=&quot;NoSupport&quot; style=&quot;display:none;&quot;&gt; Your browser does not support Push Notifications or you have blocked notifications &lt;/div&gt; &lt;form asp-action=&quot;Index&quot; id=&quot;form&quot; style=&quot;display:none;&quot;&gt; &lt;label for=&quot;client&quot;&gt;Your name: &lt;/label&gt; &lt;input id=&quot;client&quot; name=&quot;client&quot; /&gt;&lt;br /&gt; &lt;input id=&quot;endpoint&quot; name=&quot;endpoint&quot; hidden /&gt; &lt;input id=&quot;p256dh&quot; name=&quot;p256dh&quot; hidden /&gt; &lt;input id=&quot;auth&quot; name=&quot;auth&quot; hidden /&gt; &lt;button type=&quot;submit&quot;&gt;Subscribe&lt;/button&gt; &lt;/form&gt; </code></pre> <p>We will write a bit JavaScript to control when these different parts are shown and to get the hidden fields for the form.</p> <pre><code class="language-html">@section Scripts { &lt;script&gt; if ('serviceWorker' in navigator) { window.addEventListener(&quot;load&quot;, () =&gt; { navigator.serviceWorker.register(&quot;/ServiceWorker.js&quot;) .then((reg) =&gt; { if (Notification.permission === &quot;granted&quot;) { $(&quot;#form&quot;).show(); getSubscription(reg); } else if (Notification.permission === &quot;blocked&quot;) { $(&quot;#NoSupport&quot;).show(); } else { $(&quot;#GiveAccess&quot;).show(); $(&quot;#PromptForAccessBtn&quot;).click(() =&gt; requestNotificationAccess(reg)); } }); }); } else { $(&quot;#NoSupport&quot;).show(); } function requestNotificationAccess(reg) { Notification.requestPermission(function (status) { $(&quot;#GiveAccess&quot;).hide(); if (status == &quot;granted&quot;) { $(&quot;#form&quot;).show(); getSubscription(reg); } else { $(&quot;#NoSupport&quot;).show(); } }); } function getSubscription(reg) { reg.pushManager.getSubscription().then(function (sub) { if (sub === null) { reg.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey: &quot;@ViewBag.applicationServerKey&quot; }).then(function (sub) { fillSubscribeFields(sub); }).catch(function (e) { console.error(&quot;Unable to subscribe to push&quot;, e); }); } else { fillSubscribeFields(sub); } }); } function fillSubscribeFields(sub) { $(&quot;#endpoint&quot;).val(sub.endpoint); $(&quot;#p256dh&quot;).val(arrayBufferToBase64(sub.getKey(&quot;p256dh&quot;))); $(&quot;#auth&quot;).val(arrayBufferToBase64(sub.getKey(&quot;auth&quot;))); } function arrayBufferToBase64(buffer) { var binary = ''; var bytes = new Uint8Array(buffer); var len = bytes.byteLength; for (var i = 0; i &lt; len; i++) { binary += String.fromCharCode(bytes[i]); } return window.btoa(binary); } &lt;/script&gt; } </code></pre> <p>There are quite a lot of functions in this script block. Let's go through them one at a time.</p> <p>First, we register our Service worker again. We do this both to check if it can be registered. If it can't then we display the UI-appropriate UI part. We also do it to get the <code>Registration</code> object for the Service Worker. We then check if the user has given permission to make Notifications. If they granted access then we show the form and call the <code>getSubscription</code> function which also fills out the hidden fields in the form. If they have blocked notifications then we show the no-support UI part. The third scenario is that the user has not decided yet in which case we will show the UI part for requesting access to make notifications. We also subscribe to the click event for the <code>PromptForAccessBtn</code> in which case we will invoke the <code>requestNotificationAccess</code> function. The following is how it looks when the prompt is invoked in Chrome on desktop.</p> <p><img src="https://kristoffer-strube.dk/images/Prompt.png" alt="Your desktop browser asking for permission" /></p> <p>The <code>requestNotificationAccess</code> function simply requests permission for making notifications and reacts to the result of the prompt. If they granted the permission then we show the form and call the <code>getSubscription</code> function once again and if they block we show the no-support UI part.</p> <p>In the <code>getSubscription</code> function we want to get a subscription object from the Service Worker. We first try to get it by calling <code>reg.pushManager.getSubscription</code>. This method returns a subscription object if there already exists one. If it did return a subscription then we parse that to the <code>fillSubscribeFields</code> function. If there was no subscription then we try to make one by calling <code>reg.pushManager.subscribe</code>. We parse the <code>public key</code> to this function using the razor <code>ViewBag</code>. To parse this from the controller we simply add the following to our controller and action for this view. In my small example, I just use the <code>HomeController</code> since this is a small example.</p> <pre><code class="language-csharp">public class HomeController : Controller { private readonly IConfiguration configuration; public HomeController(IConfiguration configuration) { this.configuration = configuration; } public IActionResult Index() { ViewBag.applicationServerKey = configuration[&quot;VAPID:publicKey&quot;]; return View(); } } </code></pre> <p>Note that we inject <code>IConfiguration</code> into the controller, but that we have not added it in the <code>startup.cs</code> file. This can be done because <code>IConfiguration</code> is automatically dependency injected in ASP.NET. If <code>reg.pushManager.subscribe</code> returns a subscription then we simply use that to call <code>fillSubscribeFields</code> now. If something goes wrong and we do not get a subscription then we have no other option than to log an error. This error could occur if the <code>public key</code> is not generated correctly.</p> <p>The <code>fillSubscribeFields</code> function fills out the hidden inputs in the form. The <code>endpoint</code> is available as a field in the subscription object. The <code>p256dh</code> and <code>auth</code> variables are available through the <code>getKey</code> function on the object but they are returned as Array Buffers. So we use a function we have made called <code>arrayBufferToBase64</code> which converts Array Buffers to a base 64 string.</p> <h3>Saving the subscription</h3> <p>We have made a form that posts the subscription information. We need to define the action that receives this post and save it somehow. We create a new action in our controller.</p> <pre><code class="language-csharp">[HttpPost] public IActionResult Index(string client, string endpoint, string p256dh, string auth) { if (client == null) { return BadRequest(&quot;No Client Name parsed.&quot;); } if (PersistentStorage.GetClientNames().Contains(client)) { return BadRequest(&quot;Client Name already used.&quot;); } var subscription = new PushSubscription(endpoint, p256dh, auth); PersistentStorage.SaveSubscription(client, subscription); return View(&quot;Notify&quot;, PersistentStorage.GetClientNames()); } </code></pre> <p>We define that this action handles a post by setting the attribute <code>[HttpPost]</code>. The action takes the same arguments as we have parsed to it from the form. The goal of this action to save the given parameters so that they can be used later. We use a placeholder for any kind of persistent storage which we call <code>PersistentStorage</code>. This could be any kind of database or even Azure Blob Storage. In the body, we first check if the submitted client name is null in which case we return <code>BadRequest</code>. This should probably be handled with an error screen of some sort if this was a real scenario. We also check if the client's name is already used in which case we also return <code>BadRequest</code>. Then if things are looking good we make a new <code>PushSubscription</code> object which takes all the subscription details as arguments. The <code>PushSubscription</code> class is from the package <a href="https://github.com/vip30/WebPush-NetCore">WebPush-NetCore</a> which handles how to send a notification for us. We then save the <code>PushSubscription</code> object in our persistent storage. If this were to be saved in a database then there would probably be needed some serialization/deserialization process for this or as an alternative just save each field individually. In the end, we return a new view in which we can make the push notification. We will let anyone have access to this page for demonstration purposes, but this page should probably only be available for administrators in most cases. We will make this action and view after the next section.</p> <h3>Event listeners in Service Worker</h3> <p>Now, we have made it so that the server has the endpoint and the keys it needs to make a push notification. But before we push a notification we need to make the listeners that handle when a notification is pushed. These are defined in our Service Worker. First, we make the listener for a new push message by adding the following to <code>ServiceWorker.js</code>.</p> <pre><code class="language-javascript">self.addEventListener('push', function (e) { var body; if (e.data) { body = e.data.text(); } else { body = &quot;Standard Message&quot;; } var options = { body: body, icon: &quot;images/icon-512x512.png&quot;, vibrate: [100, 50, 100], data: { dateOfArrival: Date.now() }, actions: [ { action: &quot;explore&quot;, title: &quot;Go interact with this!&quot;, icon: &quot;images/checkmark.png&quot; }, { action: &quot;close&quot;, title: &quot;Ignore&quot;, icon: &quot;images/red_x.png&quot; }, ] }; e.waitUntil( self.registration.showNotification(&quot;Push Notification&quot;, options) ); }); </code></pre> <p>The event listener receives a package containing some data. The data is in our case just plain text which we retrieve by calling <code>.text()</code>. It could have been a JSON object in which case we would call <code>.json()</code> instead. If it's an empty message then we just default to some standard message. Then comes the primary part of this function, the <code>options</code> object. This defines what text will be displayed in the notification, the icon that will be shown, how the notification will vibrate (only available on phones), and extra data that some operating systems might use when showing the notification. We can also define different actions in the <code>options</code> object. We have made two actions. One indicates that something will happen and another closes the notification. We have defined an ID, the text for the action, and an icon for the action for each action. The icon is optional We use the <code>options</code> object as an argument to the <code>showNotification</code> which makes the actual notification. A title for the notification is also defined in this function and would normally be the same as the name of your web app as this will be shown with your logo at the top of the notification on most platforms. We have defined two actions, but we have not yet defined what happens when they are used. For this, we define another event listener in the Service Worker.</p> <pre><code class="language-javascript">self.addEventListener('notificationclick', function (e) { var notification = e.notification; var action = e.action; if (action === 'close') { notification.close(); } else { // Some actions clients.openWindow('http://www.example.com'); notification.close(); } }); </code></pre> <p>This listener gets a package that contains a reference to the notification and an <code>action</code> field that contains the ID for the action that was selected. We then close the notification if they press the <code>close</code> action and do what we want to do else. In this case, we direct the user to a website, but we could also run any other JavaScript code. We could have called an action in our controller and logged the action if we were interested in seeing how many users clicked/closed the notifications.</p> <h3>Pushing the notification</h3> <p>We have made it to the last part: Sending the push notification. First, we make a new view in which we will pick a client to whom we will push a message. This is the <code>Notify</code> view that we referenced earlier.</p> <pre><code class="language-razor">@model List&lt;string&gt; &lt;h1&gt;Send Push Notifications&lt;/h1&gt; @if (Model.Count() == 0) { &lt;p&gt;There are no active subscribers&lt;/p&gt; } else { &lt;form asp-action=&quot;Notify&quot;&gt; &lt;label for=&quot;message&quot;&gt;Message: &lt;/label&gt; &lt;input id=&quot;message&quot; name=&quot;message&quot; /&gt;&lt;br /&gt; @foreach (string client in Model) { &lt;input type=&quot;radio&quot; id=&quot;@(client)_identifier&quot; name=&quot;client&quot; value=&quot;@client&quot;&gt; &lt;label for=&quot;@(client)_identifier&quot;&gt;@client&lt;/label&gt;&lt;br&gt; } &lt;button type=&quot;submit&quot;&gt;Push&lt;/button&gt; &lt;/form&gt; } </code></pre> <p>The following picture shows the result of this view.</p> <p><img src="https://kristoffer-strube.dk/images/Push.png" alt="Push notification view" /></p> <p>The view uses a list of strings as its model. Each string will represent a client. We parse this list to the view from our action.</p> <pre><code class="language-csharp">public IActionResult Notify() { return View(PersistentStorage.GetClientNames()); } </code></pre> <p>We first check if there are no strings in the list and display a fitting message if so. If there are strings in the list, then we are ready to go. We make a form that will post to an action which we also call Notify. In the form, we first make an input for a message that we will send. After that, we make a radio button for each of the clients in the list with corresponding labels. Now we just need to make an Action for the post.</p> <pre><code class="language-csharp">[HttpPost] public IActionResult Notify(string message, string client) { if (client == null) { return BadRequest(&quot;No Client Name parsed.&quot;); } PushSubscription subscription = PersistentStorage.GetSubscription(client); if (subscription == null) { return BadRequest(&quot;Client was not found&quot;); } var subject = configuration[&quot;VAPID:subject&quot;]; var publicKey = configuration[&quot;VAPID:publicKey&quot;]; var privateKey = configuration[&quot;VAPID:privateKey&quot;]; var vapidDetails = new VapidDetails(subject, publicKey, privateKey); var webPushClient = new WebPushClient(); try { webPushClient.SendNotification(subscription, message, vapidDetails); } catch (Exception exception) { // Log error } return View(PersistentStorage.GetClientNames()); } </code></pre> <p>In the action, we first check if a client was selected and if the client exists. Then we extract the <code>public key</code>, <code>private key</code>, and our email from our previously injected <code>IConfiguration</code>. These are passed to the constructor of a new <code>VapidDetails</code> which is also from the <a href="https://github.com/vip30/WebPush-NetCore">WebPush-NetCore</a> package. Then a <code>WebPushClient</code> is created which can send the Push Notification. The <code>SendNotification</code> method is called in a try-catch block. This is done because there are a couple of different errors that occur e.g. if the user has unsubscribed from notification or if the service worker has been updated without re-subscribing. In the end, the <code>Notify</code> view is returned again so that a new notification can be pushed.</p> <p>The following video shows the result of this process.</p> <iframe width="700" style="aspect-ratio:16/9" src="https://www.youtube.com/embed/aFwTGdL53Mw" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe> <h3>Conclusion</h3> <p>Now we have set up a minimal Service Worker and Manifest. We have made a view that enables the user to allow notifications and subscribe to Push Notifications. We have made event listeners in the Service Worker which handles when notifications are pushed. In the end, we have pushed a notification from the server using the <a href="https://github.com/vip30/WebPush-NetCore">WebPush-NetCore</a> package. There are multiple places where this example could be improved with regards to security and aesthetics, but it still encapsulates the main functionality of Push Notifications and how it works together with ASP.NET Core. If you have feedback or questions, then feel free to reach out and share your thoughts.</p> wrapping-compression-streams-in-blazorhttps://kristoffer-strube.dk/post/wrapping-compression-streams-in-blazor/Most modern browsers implement the Compression Streams API. The API defines two interfaces CompressionStream and DecompressionStream which can be used in connection with the browser Streams API to compress and decompress data while it is streamed. This can be useful in scenarios where bandwidth is limited or where huge data blobs are streamed to and from a client. In this article, we will wrap the Compression Streams API in Blazor using definitions from the Blazor.Streams library, and in the end we will make a small Blazor WASM sample that uses it to validate its behavior.Fri, 17 Mar 2023 00:00:00 +01002023-03-17T00:00:00+01:00<p><em>Disclaimer: &quot;Most modern browsers&quot; means Chrome, Edge, Safari, and Opera. (Note that the list doesn't include Firefox)</em></p> <h3>Setup project</h3> <p>The newest version of <a href="https://github.com/KristofferStrube/Blazor.Streams">Blazor.Streams</a> uses packages that depend on .NET 7 so we need to download the newest version of .NET 7 from <a href="https://dotnet.microsoft.com/en-us/download/dotnet/7.0">dotnet.microsoft.com/en-us/download/dotnet/7.0</a>.</p> <p>Using the dotnet CLI we can create a new Razor class library in a new folder.</p> <pre><code class="language-bash">dotnet new razorclasslib </code></pre> <p>Then we add a reference to <a href="https://github.com/KristofferStrube/Blazor.Streams">Blazor.Streams</a> using the CLI as well.</p> <pre><code>dotnet add package KristofferStrube.Blazor.Streams </code></pre> <p>The <code>razorclasslib</code> template adds a couple of sample razor components that we don't need, but it also creates a sample JSInterop class which we can change every so little to be our base JS Wrapper class. The JS Wrapper base class should make a couple of fields and properties available: an <code>IJSObjectReference</code> representing the wrapped object, an <code>IJSRuntime</code> for invoking JS methods, and a lazily evaluated reference to a helper JS script file.</p> <h5>BaseJSWrapper.cs</h5> <pre><code class="language-csharp">public abstract class BaseJSWrapper : IAsyncDisposable { public IJSObjectReference JSReference { get; } public IJSRuntime JSRuntime { get; } protected readonly Lazy&lt;Task&lt;IJSObjectReference&gt;&gt; helperTask; internal BaseJSWrapper(IJSRuntime jSRuntime, IJSObjectReference jSReference) { helperTask = new(jSRuntime.GetHelperAsync); JSReference = jSReference; JSRuntime = jSRuntime; } public async ValueTask DisposeAsync() { if (helperTask.IsValueCreated) { IJSObjectReference module = await helperTask.Value; await module.DisposeAsync(); } GC.SuppressFinalize(this); } } </code></pre> <p>We have an internal constructor as we only want wrapper classes from this project to be able to extend the class. We initialize the lazy helper task using an <code>IJSRuntime</code> extension method called <code>GetHelperAsync</code>.</p> <p><code>GetHelperAsync</code> is defined like so:</p> <h5>IJSRuntimeExtensions.cs</h5> <pre><code class="language-csharp">internal static class IJSRuntimeExtensions { internal static async Task&lt;IJSObjectReference&gt; GetHelperAsync(this IJSRuntime jSRuntime) { return await jSRuntime.InvokeAsync&lt;IJSObjectReference&gt;( &quot;import&quot;, &quot;./_content/KristofferStrube.Blazor.CompressionStreams/KristofferStrube.Blazor.CompressionStreams.js&quot; ); } } </code></pre> <p>The method references our helper JS script file. The first part of the path <code>./content/</code> is where Blazor stores all resources from packages that it uses. The next part <code>/KristofferStrube.Blazor.CompressionStreams/</code> is the name of the namespace of our project and after this part of the path we find all the files from the <code>/wwwroot/</code> folder of our project which is where our helper script is placed. We call the helper script <code>KristofferStrube.Blazor.CompressionStreams.js</code> so that it is easy to find the specific script from the browser developer tool if necessary which wouldn't be as easy if everyone called their helper scripts <code>helper.js</code>. We will add some methods to the script file when we need any methods that Blazor doesn't have support for natively.</p> <h3>Looking at the WebIDL specification</h3> <p>A good start for wrapping any browser API is to look at the WebIDL specification and we are very lucky that the specification for the Compressions Streams API is very short and concise. We can <a href="https://wicg.github.io/compression/#idl-index">find the specification here</a> but I have also written it out below as it is very short.</p> <pre><code class="language-webidl">[Exposed=*] interface CompressionStream { constructor(DOMString format); }; CompressionStream includes GenericTransformStream; [Exposed=*] interface DecompressionStream { constructor(DOMString format); }; DecompressionStream includes GenericTransformStream; </code></pre> <p>We see that it defines two interfaces that are very similar. They are both exposed in <code>*</code> meaning that they can be constructed in all contexts. We see that they both have a constructor that takes a format. If we scroll up a bit in the specification we find that the API supports 3 different compression algorithms which is what we must parse as the format. It supports the following formats:</p> <ul> <li><code>deflate</code> (ZLIB Compressed Data Format)</li> <li><code>deflate-raw</code> (The DEFLATE algorithm)</li> <li><code>gzip</code> (GZIP file format)</li> </ul> <p>The next thing we note is that the interfaces both include <code>GenericTransformStream</code>. This means that it inherits the members defined in the <code>GenericTransformStream</code> mixin interface from the browser Streams API.</p> <pre><code class="language-webidl">interface mixin GenericTransformStream { readonly attribute ReadableStream readable; readonly attribute WritableStream writable; }; </code></pre> <p>We don't have extension properties nor multiple inheritances in C#. But we have defined an interface called <code>IGenericTransformStream</code> in <a href="https://github.com/KristofferStrube/Blazor.Streams">Blazor.Streams</a> that can help us ensure that we implement wrappers for these attributes.</p> <h3>Wrapping CompressionStream</h3> <p>Let's start by writing the wrapper class for the <code>CompressionStream</code>.</p> <h5>CompressionStream.cs</h5> <pre><code class="language-csharp">public class CompressionStream : BaseJSWrapper, IGenericTransformStream { public static Task&lt;CompressionStream&gt; CreateAsync(IJSRuntime jSRuntime, IJSObjectReference jSReference) { return Task.FromResult(new CompressionStream(jSRuntime, jSReference)); } protected CompressionStream(IJSRuntime jSRuntime, IJSObjectReference jSReference) : base(jSRuntime, jSReference) { } // Rest of the methods that need to be implemented. } </code></pre> <p>We make the constructor protected so that consumers of the wrapper class need to use the creator method <code>CreateAsync</code> to instantiate an instance. This method did not need to return a Task, but for uniformity, we do this as other creator methods might need to do some asynchronous work like registering event listeners or similar through JSInterop. The <code>IGenericTransformStream</code> interface defines that we need to implement two methods <code>GetReadableAsync</code> and <code>GetWritableAsync</code>. So let's do so.</p> <pre><code class="language-csharp">// Other methods in CompressionStream.cs above here public async Task&lt;ReadableStream&gt; GetReadableAsync() { IJSObjectReference helper = await helperTask.Value; IJSObjectReference jSInstance = await helper.InvokeAsync&lt;IJSObjectReference&gt;(&quot;getAttribute&quot;, JSReference, &quot;readable&quot;); return await ReadableStream.CreateAsync(JSRuntime, jSInstance); } public async Task&lt;WritableStream&gt; GetWritableAsync() { IJSObjectReference helper = await helperTask.Value; IJSObjectReference jSInstance = await helper.InvokeAsync&lt;IJSObjectReference&gt;(&quot;getAttribute&quot;, JSReference, &quot;writable&quot;); return await WritableStream.CreateAsync(JSRuntime, jSInstance); } </code></pre> <p>The two methods make it possible to access rich wrapper instances of the <code>readable</code> and <code>writable</code> counterparts in the transform stream. In each method, we first await the lazily defined helper. This uses the existing helper <code>IJSObjectReference</code> for the helper if it has been used before and else creates a new one using the <code>GetHelperAsync</code> as we defined it in the <code>BaseJSWrapper</code> constructor. Next, we use the helper to get either the <code>readable</code> or <code>writable</code> attribute from our wrapped <code>JSReference</code> using a helper method called <code>getAttribute</code>. Then we have an <code>IJSObjectReference</code> to that attribute which we can create a rich Stream wrapper from. To use the <code>getAttribute</code> method we need to add it to the helper JS script file.</p> <h5>KristofferStrube.Blazor.CompressionStreams.js</h5> <pre><code class="language-js">export function getAttribute(object, attribute) { return object[attribute]; } </code></pre> <p>It is a really simple method, but currently, Blazor doesn't have a method for accessing the attributes of a JS object so we need it. It has been planned for .NET 8 to add methods for this so that we don't need this JS method. You can check out <a href="https://github.com/dotnet/aspnetcore/issues/31151">the related issue</a> which I have linked many times before.</p> <p>The last thing we need to wrap for the <code>CompressionStream</code> is its constructor. This will be a second static <code>CreateAsync</code> method that takes an <code>IJSRuntime</code> and the <code>format</code> as it was defined in the WebIDL specification. In the specification, it was defined as being a string, but actually, only 3 different values were possible. So let's create an enum for those options.</p> <h5>CompressionAlgorithm.cs</h5> <pre><code class="language-csharp">public enum CompressionAlgorithm { Deflate, DeflateRaw, Gzip } public static class CompressionAlgorithmsExtensions { public static string AsString(this CompressionAlgorithm compressionAlgorithm) =&gt; compressionAlgorithm switch { CompressionAlgorithm.Deflate =&gt; &quot;deflate&quot;, CompressionAlgorithm.DeflateRaw =&gt; &quot;deflate-raw&quot;, CompressionAlgorithm.Gzip =&gt; &quot;gzip&quot;, _ =&gt; throw new NotSupportedException($&quot;Value {compressionAlgorithm} not supported as a Compression Algorithm format.&quot;), }; } </code></pre> <p>We also define an extension function for the enum which maps it to a string. We could have created this mapping using a custom JSON serializer, but I find this more readable and versatile. Now we are ready to make the constructor wrapping method.</p> <pre><code class="language-csharp">// Other methods in CompressionStream.cs above here public static async Task&lt;CompressionStream&gt; CreateAsync(IJSRuntime jSRuntime, CompressionAlgorithm format) { IJSObjectReference helper = await jSRuntime.GetHelperAsync(); IJSObjectReference jSInstance = await helper.InvokeAsync&lt;IJSObjectReference&gt;(&quot;createCompressionStream&quot;, format.AsString()); return new CompressionStream(jSRuntime, jSInstance); } </code></pre> <p>In this method we can't use the lazily evaluated helper as the method is static so we simply just await it directly. Using the helper we invoke a method called <code>createCompressionStream</code> which calls the constructor with our <code>format</code>. We then create and return a new <code>CompressionStream</code> using our protected constructor. So the last part is to add the <code>createCompressionStream</code> method to our helper JS script file before being done.</p> <h5>KristofferStrube.Blazor.CompressionStreams.js</h5> <pre><code class="language-js">// Other helper methods above here export function createCompressionStream(format) { return new CompressionStream(format); } </code></pre> <p>This method is also very simple but is necessary as we can't invoke constructors directly from Blazor. This feature is also planned to be added in .NET 8 as a part of the previously linked issue.</p> <p>Now we have wrapped <code>CompressionStream</code> and as we remember <code>DecompressionStream</code> is very similar so we won't go through that in this article.</p> <h3>CompressionStream InProcess</h3> <p>Blazor has an InProcess variant of <code>IJSObjectReference</code> called <code>IJSInProcessObjectReference</code> which can also make JSInterop calls synchronously. This can be very useful for accessing attributes as we can then use C# properties. <a href="https://github.com/KristofferStrube/Blazor.Streams">Blazor.Streams</a> also defines an InProcess interface for <code>IGenericTransformStreamInProcess</code>. It has the same shape as <code>IGenericTransformStream</code> but returns InProcess variants of <code>ReadableStream</code> and <code>WritableStream</code> called <code>ReadableStreamInProcess</code> and <code>WritableStreamInProcess</code>. So the primary benefit of making an InProcess variant of <code>CompressionStream</code> and <code>DecompressionStream</code> is its interoperability with the Blazor.Streams package. As we have already seen the process I will just share the result.</p> <h5>CompressionStream.InProcess.cs</h5> <pre><code class="language-csharp">public class CompressionStreamInProcess : CompressionStream, IGenericTransformStreamInProcess { public new IJSInProcessObjectReference JSReference { get; set; } public static Task&lt;CompressionStreamInProcess&gt; CreateAsync(IJSRuntime jSRuntime, IJSInProcessObjectReference jSReference) =&gt; Task.FromResult(new CompressionStreamInProcess(jSRuntime, jSReference)); public new static async Task&lt;CompressionStream&gt; CreateAsync(IJSRuntime jSRuntime, CompressionAlgorithm format) { IJSObjectReference helper = await jSRuntime.GetHelperAsync(); IJSInProcessObjectReference jSInstance = await helper.InvokeAsync&lt;IJSInProcessObjectReference&gt;(&quot;createCompressionStream&quot;, format.AsString()); return await Task.FromResult(new CompressionStreamInProcess(jSRuntime, jSInstance)); } protected CompressionStreamInProcess(IJSRuntime jSRuntime, IJSInProcessObjectReference jSReference) : base(jSRuntime, jSReference) { JSReference = jSReference; } public new async Task&lt;ReadableStreamInProcess&gt; GetReadableAsync() { IJSObjectReference helper = await helperTask.Value; IJSInProcessObjectReference jSInstance = await helper.InvokeAsync&lt;IJSInProcessObjectReference&gt;(&quot;getAttribute&quot;, JSReference, &quot;readable&quot;); return await ReadableStreamInProcess.CreateAsync(JSRuntime, jSInstance); } public new async Task&lt;WritableStreamInProcess&gt; GetWritableAsync() { IJSObjectReference helper = await helperTask.Value; IJSInProcessObjectReference jSInstance = await helper.InvokeAsync&lt;IJSInProcessObjectReference&gt;(&quot;getAttribute&quot;, JSReference, &quot;writable&quot;); return await WritableStreamInProcess.CreateAsync(JSRuntime, jSInstance); } } </code></pre> <p>The primary difference is that we hide a lot of the members of the <code>CompressionStream</code> and define InProcess variants instead.</p> <p>You can checkout the full implementation at <a href="https://github.com/KristofferStrube/Blazor.CompressionStreams/">github.com/KristofferStrube/Blazor.CompressionStreams/</a></p> <h3>Validation Sample</h3> <p>Now we just need to check that our implementation works. To validate it we will construct a stream, compress it, decompress it, and check that the content is still valid.</p> <p>We create a new Blazor WASM project in an empty folder using the CLI once again.</p> <pre><code class="language-bash">dotnet new blazorwasm </code></pre> <p>From this project, we add a reference to the class library. If you followed the previous steps and made the class library yourself then you can use the <a href="https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-add-reference">dotnet add reference</a> command to reference that project. Else you can add my published NuGet package using this command:</p> <pre><code class="language-bash">dotnet add package KristofferStrube.Blazor.CompressionStreams </code></pre> <p>Once we have added the library reference to our Blazor WASM project we can begin to make our sample page. We will simply modify the pre-generated page <code>Index.razor</code>. We define the following scaffold for our page:</p> <h5>Index.razor</h5> <pre><code class="language-razor">@page &quot;/&quot; @using KristofferStrube.Blazor.CompressionStreams @inject IJSRuntime JSRuntime @inject HttpClient HttpClient @if (compressedStreamSize is not 0) { &lt;div&gt;&lt;label style=&quot;width:200px;&quot;&gt;Compressed size was:&lt;/label&gt; @compressedStreamSize&lt;/div&gt; } @if (decompressedStreamSize is not 0) { &lt;div&gt;&lt;label style=&quot;width:200px;&quot;&gt;Decompressed size was:&lt;/label&gt; @decompressedStreamSize&lt;/div&gt; } &lt;p&gt; @content &lt;/p&gt; @code { string content = &quot;&quot;; long compressedStreamSize; long decompressedStreamSize; protected override async Task OnInitializedAsync() { // Our compression and decompression code here } } </code></pre> <p>In this scaffold, we already do a lot. We add an <code>using</code> for the <code>KristofferStrube.Blazor.CompressionStreams</code> library and inject the <code>IJSRuntime</code> and <code>HttpClient</code> services. We will use the <code>HttpClient</code> to download some data as our compression guinea pig for compression in a bit. After this, we make some markup that will present the sizes of our stream compressed and decompressed followed by the final content itself. After this, we define these fields in our code section.</p> <p>Now we just need to fill out our <code>OnInitializedAsync</code> method with the actual code for compressing and decompressing a stream. For a start we need some stream of data. For this, we use the aforementioned <code>HttpClient</code>. We can stream the result of an HTTP request using the <code>GetStreamAsync</code> method. So we need something to stream and for this purpose, we will use the world-renowned Lorem-Ipsum text which we will copy into a file called <code>lorem.txt</code> in the <code>/wwwroot/data/</code> folder of our Blazor WASM project. Then we can fetch it and construct a <code>ReadableStream</code> from the resulting stream.</p> <pre><code class="language-csharp">var data = await HttpClient.GetStreamAsync(&quot;data/lorem.txt&quot;); var streamRef = new DotNetStreamReference(stream: data, leaveOpen: false); var jSStreamReference = await JSRuntime.InvokeAsync&lt;IJSObjectReference&gt;(&quot;jSStreamReference&quot;, streamRef); var readableStream = await ReadableStream.CreateAsync(JSRuntime, jSStreamReference); </code></pre> <p>With ASP.NET Core 6, Blazor got a <code>DotNetStreamReference</code> type which can be used to construct a JS stream from any .NET <code>Stream</code> as we do in the above code. From the <code>IJSObjectReference</code> to this JS stream we construct a <code>ReadableStream</code> from the <code>Blazor.Streams</code> library.</p> <p>Then we compress the stream using a new instance of a <code>CompressionStream</code>.</p> <pre><code class="language-csharp">var compressionStream = await CompressionStream.CreateAsync(JSRuntime, CompressionAlgorithm.DeflateRaw); var compressedStream = await readableStream.PipeThroughAsync(compressionStream); </code></pre> <p>The <code>ReadableStream</code> wrapper has a method called <code>PipeThroughAsync</code> which can be used to transform a stream in any way. It takes a class that implements <code>IGenericTransformStream</code> as its only parameter which we luckily had <code>CompressionStream</code> implement.</p> <p>Now we want to measure the compressed size but reading the compressed stream will consume it. So we first <em>tee</em> the stream. By teeing the stream we create 2 new identical streams that can be consumed however we want. This also locks the original stream making it impossible to read.</p> <pre><code class="language-csharp">var (tee1, tee2) = await compressedStream.TeeAsync(); </code></pre> <p>Then we read the first tee and counts its size.</p> <pre><code class="language-csharp">var reader = await tee1.GetDefaultReaderAsync(); await foreach (var byteArrayChunk in reader.IterateByteArraysAsync()) { compressedStreamSize += byteArrayChunk.Length; } </code></pre> <p>And finally we decompress the second tee and read and measure its size.</p> <pre><code class="language-csharp">var decompressionStream = await DecompressionStream.CreateAsync(JSRuntime, CompressionAlgorithm.DeflateRaw); var decompressedStream = await tee2.PipeThroughAsync(decompressionStream); var writeStream = new System.IO.MemoryStream(); await decompressedStream.CopyToAsync(writeStream); decompressedStreamSize = writeStream.Length; content = System.Text.Encoding.UTF8.GetString(writeStream.ToArray()); </code></pre> <p>Then we are done. Let's run it and see the result.</p> <pre><code class="language-bash">dotnet run </code></pre> <p>And then we go to the index page. Normally I would have made a video for this, but this sample isn't really that interesting, so I've just copied the result here as what is actually interesting is that the text was compressed and that the resulting content was intact.</p> <pre><code class="language-bash">Compressed size was: 3696 Decompressed size was: 11481 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi et ex a dolor pulvinar euismod... (continuing) </code></pre> <p>You can check out the demo here yourself: <a href="https://kristofferstrube.github.io/Blazor.CompressionStreams/">https://kristofferstrube.github.io/Blazor.CompressionStreams/</a></p> <p>And you can check out the GitHub project here: <a href="https://github.com/KristofferStrube/Blazor.CompressionStreams">https://github.com/KristofferStrube/Blazor.CompressionStreams</a> (Throw me a star if you enjoyed the post.)</p> <h3>Conclusion</h3> <p>Now, we have seen an approach for wrapping browser APIs in Blazor WASM. We have wrapped the <code>CompressionStream</code> interface and the other related interfaces defined in the Compressions Streams API. And in the end, we have shown a small example that validates that the wrapper has the intended behavior. This post is a precursor to a series of posts that I will make on the topic of streaming files to and from Blazor WASM clients using my wrapper classes which I'm looking forward to getting started with. If you have any questions related to the article or comments then feel free to reach out.</p> the-blazor-navigationmanagerhttps://kristoffer-strube.dk/post/the-blazor-navigationmanager/The NavigationManager is a service that enables developers to programmatically navigate the user to different pages or external URIs. In ASP.NET Core 7, there were added new features that enable us to parse simple state between pages and listen to and intercept navigation. In this post, we will look at the basic capabilities of the NavigationManager, present what new features were added in ASP.NET Core 7, discuss how it fits into the Blazor/.NET ecosystem, and in the end present a scenario that is now possible with relative ease using new additions from ASP.NET Core 7.Thu, 23 Feb 2023 00:00:00 +01002023-02-23T00:00:00+01:00<h3>Members from before ASP.NET Core 7</h3> <p>First, let's see what actions were possible before ASP.NET Core 7. I will give a shallow overview of the commonly used properties and methods of the <code>NavigationManager</code>.</p> <h4>string BaseUri</h4> <p>You can use the <code>BaseUri</code> property to get or set the base path of where the application is being presented. This is equivalent to the path that the <base /> tag in the head of the HTML document points to, but the path is actually resolved. This means that you get the string <code>&quot;https://example.com/&quot;</code> if your page is hosted there even though the <code>&lt;base /&gt;</code> tag might only specify <code>&quot;/&quot;</code> as the base href.</p> <h4>string Uri</h4> <p>This is equivalent to the <code>window.location</code> property in JavaScript which we can use to get and set the absolute URI of the page.</p> <h4>void NavigateTo(...)</h4> <p>This method is also used to change the location to a specific URI, but this also has multiple useful overloads.</p> <h5>void NavigateTo(string uri, bool forceLoad)</h5> <p>The <code>forceLoad</code> parameter defines whether the navigation should simulate an HTTP reload or simply should change to the location without reloading.</p> <h5>void NavigateTo(string uri, bool forceLoad = false, bool replace = false)</h5> <p>The <code>replace</code> parameter defines whether the navigation should replace the existing part of the history. This means that you will lose your navigation history i.e. which pages you can navigate to with the back and forward buttons or gestures in the browser if you set it to true which can be desirable in certain scenarios like stateful MVVM-inspired Blazor applications.</p> <h5>void NavigateTo(string uri, NavigationOptions options)</h5> <p>The <code>options</code> parameter is simply an option that contains the two properties from the previous constructors as a contained class so that the same options can easily be used in multiple places.</p> <h4>string ToAbsoluteUri(String relativeUri)</h4> <p>Converts a relative URI to an absolute path in relation to the current path i.e. if you are at <code>&quot;https://example.com/thepage&quot;</code> and parses <code>&quot;/subpath&quot;</code> to it then you get <code>https://example.com/thepage/subpath</code>.</p> <h4>string ToBaseRelativePath(String uri)</h4> <p>Converts an absolute URI to a relative in relation path to the base path i.e. if your base path is <code>&quot;https://example.com/mysite&quot;</code> and you parse <code>&quot;https://example.com/mysite/and/my/many/subpages&quot;</code> to it then you get <code>&quot;/and/my/many/subpages&quot;</code>.</p> <h4>EventHandler<LocationChangedEventArgs> LocationChanged</h4> <p>You can listen to this event which will trigger once a location <u>has changed</u>. I emphasize that as it means you can't act on the change itself happening. From the event argument, you can see the <code>Location</code> that the navigation was to and whether this location change was <em>intercepted</em> (<code>IsNavigationIntercepted</code>). <em>Intercepted</em> means that some mechanism has changed the navigation. This is what Blazor does when you press a link on the page to navigate to a specific route instead of loading that page i.e. changing a cross-document navigation to a same-document one.</p> <h3>Members introduced in ASP.NET Core 7</h3> <p>The following member were the ones added in ASP.NET Core 7 in order to enable more stateful navigation.</p> <h4>void RegisterLocationChangingHandler(...)</h4> <p>This method is (unlike <code>LocationChanged</code>) used to handle when the location <u>is changing</u>. This means that we can actually act on it before potentially navigating/leaving a page. The method takes a <code>Func</code> from a <code>LocationChangingContext</code> to a <code>ValueTask</code>. This means that we can act on the context and do some async work. An example could be the following:</p> <pre><code class="language-csharp">NavigationManager.RegisterLocationChangingHandler(async (context) =&gt; { Console.WriteLine($&quot;We are navigating to: {context.TargetLocation}&quot;); await AnimatedTransitionAsync(); }); </code></pre> <p>A nice thing we can do with the context is to stop the navigation using the <code>context.PreventNavigation()</code> method. This has been a very requested feature. It enables us to support canceling navigation to another page if the user has an unsubmitted form or some state that needs to be saved before leaving the page.</p> <h4>string HistoryEntryState</h4> <p>Another nice addition from ASP.NET Core 7 is the <code>HistoryEntryState</code> property. This has been added to many of the types that we have touched on above and enables us to send some state with our navigation without appending a query string (<code>?somekey=somevalue</code>) or a URI fragment (<code>#someValue</code>). The property has been added to the <code>NavigationManager</code> itself, but also to the <code>NavigationOptions</code>, <code>LocationChangingContext</code>, and <code>LocationChangedEventArgs</code> types. Setting the <code>HistoryEntryState</code> on the <code>NavigationOptions</code> enables us to append some information that can be acted on by reading the event argument or context in one of the two handlers. The state corresponds to the state that can also be parsed to the <code>navigate</code> method from the browser Navigation API where the state can be any serializable value. So that we can only parse a string through the <code>HistoryEntryState</code> is a simplification. But it can be justified as we can just serialize what state we need to parse as JSON or similar and then deserialize it again once read, essentially mimicking what the Navigation API does internally.</p> <h3>The <code>NavigationManager</code> fitting into the Blazor ecosystem</h3> <p>When I inspect a <em>new</em> feature or actually <em>any</em> feature in Blazor I look at three key parameters for how well I think it fits with the values of Blazor: <strong>Simplicity</strong>, <strong>Parity</strong>, and <strong>Familiarity</strong>.</p> <ul> <li><strong>Simplicity</strong> is when we make a simple abstraction over something complex to make the life of the developers easier.</li> <li><strong>Parity</strong> is when we have the same functionality as other web frameworks (or more).</li> <li><strong>Familiarity</strong> is when we have taken known concepts from the .NET ecosystem and made our solution match those.</li> </ul> <p>If you have all three then you are lucky; If you have two then you have made a deliberate design decision; and if you have one then it is either too simple or you are religious.</p> <p><em>This is of cause only a very opinionated analysis.</em></p> <h4>Simplicity</h4> <p>Simplicity is one of the key reasons why someone new to Blazor would actually use a feature as it hides away overly complex functionality. This is done in some parts of the <code>NavigationManager</code>. One obvious one is the one we have mentioned above related to the <code>HistoryEntryState</code> that it is simply a <code>string</code> instead of being some complex object that is annotated as serializable. Another one that is very common in Blazor is the <code>LocationChangedEventArgs</code> which is simply a Data Transfer Object without any interop functionality. This is what is done for all event arguments across Blazor like <code>MouseEventArgs</code> or <code>ClipboardEventArgs</code>. This makes it very simple to work with, but advanced users might be missing more extensibility options.</p> <h4>Parity</h4> <p>The NavigationManager is obviously meant to be analogous to the browser Navigation API so it makes sense to compare it to the features in that. Below here we see the WebIDL definition of the Navigation interaface from the browser Navigation API.</p> <pre><code class="language-webidl">interface Navigation : EventTarget { sequence&lt;NavigationHistoryEntry&gt; entries(); readonly attribute NavigationHistoryEntry? currentEntry; undefined updateCurrentEntry(NavigationUpdateCurrentEntryOptions options); readonly attribute NavigationTransition? transition; readonly attribute boolean canGoBack; readonly attribute boolean canGoForward; NavigationResult navigate(USVString url, optional NavigationNavigateOptions options = {}); NavigationResult reload(optional NavigationReloadOptions options = {}); NavigationResult traverseTo(DOMString key, optional NavigationOptions options = {}); NavigationResult back(optional NavigationOptions options = {}); NavigationResult forward(optional NavigationOptions options = {}); attribute EventHandler onnavigate; attribute EventHandler onnavigatesuccess; attribute EventHandler onnavigateerror; attribute EventHandler oncurrententrychange; }; </code></pre> <p>We obviously see some parallels to the <code>NavigationManager</code> like the <code>currentEntry</code>, <code>navigate</code>, <code>onnavigatesuccess</code>, and <code>oncurrententrychange</code> members. We also see that there are multiple methods that Blazor has encapsulated by parameterizing the <code>NavigateTo</code> method i.e. <code>updateCurrentEntry</code>, <code>navigate</code>, and <code>reload</code>.</p> <p>But we also see parts that are missing. We have two attributes <code>canGoBack</code> and <code>canGoForward</code> which would be easy to add like we have access to <code>currentEntry</code>, but they really only make sense to have if we were also able to call <code>back(...)</code> and <code>forward(...)</code>. Apart from this, we are also missing the <code>entries()</code> and <code>traverseTo(...)</code> methods that give access to the whole history of navigation in this session and enable us to navigate easily to a specific entry. This is only <strong>one</strong> part of the whole Navigation API so there are obviously more parts of the API that could have been accessible somehow, be that with direct wrappers or indirect abstractions like <code>NavigateTo</code> does.</p> <h4>Familiarity</h4> <p>For many, the key selling point of Blazor is that .NET backend developers can now also develop interactive websites using their knowledge of the .NET ecosystem. For this reason, it makes sense to use concepts from other .NET frameworks when appropriate. If we should relate the <code>NavigationManager</code> to some mechanism from another .NET framework then I would probably relate it to the <code>WebView2</code> control which is available in WPF and WinForms applications. This has a lot more methods for navigation and properties giving insight into the current state of the page like <code>GoBack()</code>, <code>GoForward()</code>, <code>NavigateToString(...)</code>, <code>CanGoBack</code>, <code>ZoomFactor</code>, and many more! As you can see WebView2 is a lot more featureful, but it is also a wrapper of an actual whole browsing experience so the comparison might not be all that fair as it also has access to things the <code>NavigationManager</code> couldn't possibly access in its context.</p> <p>The naming of the methods or the properties isn't really consistent between the <code>NavigationManager</code> and the <code>WebView2</code> control. But a part that is consistent is the usage of <code>EventHandler</code>s for <code>LocationChanged</code>/<code>NavigationCompleted</code>. What doesn't really fit into the style is that <code>WebView2</code> also uses an <code>EventHander</code> for when a page is going to change called <code>NavigationStarting</code> whereas Blazor uses a <code>Func</code> that is evaluated before navigation by parsing it to the <code>RegisterLocationChangingHandler</code> as we have seen previously. I'm not quite sure why this distinguishment was made, but my guess would be that this is friendlier to async work whereas <code>event</code>s inherently has problems when used with async work.</p> <h4>Then, how did it do?</h4> <p>It did pretty well on the <strong>simplicity</strong> keeping things easily accessible and encapsulating multiple methods functionality in the <code>NavigateTo</code> method. It did okay in <strong>parity</strong> having methods and properties that are clearly mappable to the <code>Navigation</code> interface from the Navigation API. But there is still missing some functionality. But don't be discouraged we might get these in a future release of ASP.NET if people request this. The <strong>familiarity</strong> part could need some love and I would especially have liked for all events to use <code>EventHandler</code>'s and maybe even supply attribute-specific methods as well parallel to <code>addEventListener</code> and <code>removeEventListener</code> from the <code>EventTarget</code> interface which the <code>Navigation</code> interface extends in the browser specifications.</p> <p>So if we were to put it somewhere on the scale that I presented earlier then I would say that the <code>NavigationManager</code> fulfills somewhere between 1 and 2 of my key parameters for fitting into Blazors values. This puts it somewhere between being too simple and having made deliberate design considerations (which is really good!). And if we would just have had a few more of the obvious missing functionality like <code>Back()</code> and <code>Forward()</code> navigation then I would definitely have leaned more towards it fulfilling parity as well. The additions from ASP.NET Core 7 have already pushed us towards this, so we are getting there.</p> <h3>Scenario enabled using ASP.NET Core 7</h3> <p>I will now show a scenario that is enabled by the additions that came with ASP.NET Core 7. The scenario is &quot;Canceling navigation to prevent loss of data.&quot; In this scenario, we will make a simple form that can be submitted to an API. We want to display a pop-up if you try to navigate away from the form while there is text in it giving you the option to cancel the navigation. After all the code I have made a small video that shows the scenario in practice.</p> <h4>Modal Component</h4> <p>Let's first make a simple modal component that can work as a pop-up that forces the user to make a decision.</p> <h5>Shared/Modal.razor</h5> <pre><code class="language-razor">@if (!_isShown) return; &lt;div class=&quot;modal-container&quot; @onclick=&quot;Close&quot;&gt; &lt;div class=&quot;modal-content&quot; @onclick:stopPropagation=true&gt; &lt;h3&gt; @Title &lt;span @onclick=&quot;Close&quot; class=&quot;close&quot;&gt;X&lt;/span&gt; &lt;/h3&gt; &lt;p&gt;@ChildContent&lt;/p&gt; &lt;button @onclick=Accept&gt;Accept&lt;/button&gt; &lt;/div&gt; &lt;/div&gt; </code></pre> <p>And then the associated code-behind which defines some simple logic for changing whether the modal is visible.</p> <h5>Shared/Modal.razor.cs</h5> <pre><code class="language-csharp">public partial class Modal { private bool _isShown { get; set; } private Action _accept { get; set; } = default!; [Parameter] public string Title { get; set; } = &quot;&quot;; [Parameter] public RenderFragment? ChildContent { get; set; } public void Show(Action accept) { _accept = accept; _isShown = true; StateHasChanged(); } private void Close() { _isShown = false; } private void Accept() { _accept(); _isShown = false; } } </code></pre> <p>And let's use a little styling to make the modal <em>&quot;pretty&quot;</em>.</p> <h5>Shared/Modal.razor.css</h5> <pre><code class="language-css">.modal-container { position: fixed; z-index: 1; left: 0; top: 0; width: 100vw; height: 100vh; background-color: rgba(0, 0, 0, 0.2); display: flex; justify-content: center; align-items: center; } .modal-content { width: 600px; max-width: 80vw; padding: 30px; background-color: white; border-radius: 10px; } .close { float: right; } .close:hover { font-weight: bold; cursor: pointer; } </code></pre> <h4>Index page</h4> <p>Next, we will make the markdown for our actual page which will be pretty simple because we encapsulated the modal behavior in its own component.</p> <h5>index.razor</h5> <pre><code class="language-razor">@page &quot;/&quot; &lt;Modal @ref=PreventModal Title=&quot;You are about to leave&quot;&gt; You have unsaved data, which you will lose if you navigate away from this page. Decline to save your data before leaving. &lt;/Modal&gt; &lt;label for=&quot;name&quot;&gt;Fill in your name&lt;/label&gt; &lt;input id=&quot;name&quot; @bind-value=@name&gt;&lt;/input&gt; &lt;button @onclick=Save&gt;Save!&lt;/button&gt; </code></pre> <p>And then the code-behind for the index page. The interesting part is in the <code>OnInitialized</code> method. It observes all navigation.</p> <ol> <li>We start off by ignoring cases where the <code>name</code> field is empty or the parsed <code>HistoryEntryState</code> had been set to <code>&quot;leave&quot;</code>.</li> <li>Then we show the <code>Modal</code> and if they accept that they will leave then we clear the name and navigate to the original <code>TargetLocation</code> and <code>HistoryEntryState</code> set to <code>&quot;leave&quot;</code>.</li> <li>Finally, we prevent the navigation as we want to stay on the site until the user decides.</li> </ol> <h5>index.razor.cs</h5> <pre><code class="language-csharp">public partial class Index { private string name = &quot;&quot;; private Modal? PreventModal; [Inject] public NavigationManager NavigationManager { get; set; } = default!; protected override void OnInitialized() { NavigationManager.RegisterLocationChangingHandler((context) =&gt; { if (string.IsNullOrWhiteSpace(name) || context.HistoryEntryState is &quot;leave&quot;) { return ValueTask.CompletedTask; } PreventModal!.Show(accept: () =&gt; { name = &quot;&quot;; NavigationManager.NavigateTo( context.TargetLocation, new NavigationOptions() { HistoryEntryState = &quot;leave&quot; } ); }); context.PreventNavigation(); return ValueTask.CompletedTask; }); } private void Save() { Console.WriteLine(&quot;We have saved!&quot;); name = &quot;&quot;; } } </code></pre> <p>Then we are done with the code part and can enjoy our result below.</p> <h4>Demo Video</h4> <div class="center"> <video width="700" autoplay muted controls loop> <source src="https://kristoffer-strube.dk/videos/navigation-manager.mp4" type="video/mp4"> A video showing a demo of the code written above. </video> </div> <h3>Conclusion</h3> <p>In this article, we have looked at what features the <code>NavigationManager</code> had before ASP.NET Core 7. We have looked at what was introduced in that version. We have discussed the qualities of the <code>NavigationManager</code> both the good and bad. And in the end, we have presented a small demo scenario with code that showcases some of the new features.</p> <p>Feel free to reach out if you have any questions or comments to the post. And remember that parts of this is my subjective opinion.</p> welcome-to-the-bloghttps://kristoffer-strube.dk/post/welcome-to-the-blog/I used to blog for the 4 years that I worked at elmah.io writing a lot about Blazor and .NET; Often in the format of some kind of tutorial or walk-along style article. I stopped my work there towards the end of 2021 as I began focusing on my other work as an instructor at that time. I have been thinking about blogging for others previously, but I feel like there is a lot of loops to get through for those as they of cause need to have a high level of quality. So, in this post I will introduce myself, show some of the projects that I have worked a lot with, and in the end talk about what I will blog about in the future.Fri, 17 Feb 2023 00:00:00 +01002023-02-18T00:00:00+01:00<h3>What do I do?</h3> <p>I'm a .NET Developer that posts semi-frequently on <a href="https://twitter.com/KStrubeG">Twitter</a> and <a href="https://hachyderm.io/@KristofferStrube">Mastodon</a> about the open source projects that I work on, on <a href="https://github.com/KristofferStrube">GitHub</a>. I have previously worked professionally with developing/testing Blazor applications as my primary job, but I recently transitioned into a new job that is more heavily architecture-focused. Therefore I work a lot with Blazor in my spare time to get my curiosity satisfied. I graduated in the summer of 2022 with a Master's degree in Computer Science from Aarhus University. So it should be no surprise that I enjoy technically complex problems especially if they have a focus on modeling systems or if they need to work with large amounts of data.</p> <h3>Projects</h3> <p>The ones of you who know me from Twitter/Mastodon probably do so in the context of two of my projects that I have shared a lot about.</p> <p>The first one is my <a href="https://github.com/KristofferStrube/Blazor.FileSystemAccess">Blazor Wrapper for the File System Access API</a>. This is a wrapper for a somewhat simple API, but also a very useful API as it enables the consumers of the API to interact with their local file system from the browser. This helps us move towards something a lot of Blazor developers want: Application-like websites. This is not the first wrapper that I have made for Blazor <em>(that is <a href="https://github.com/KristofferStrube/Blazor.Popper">Blazor.Popper</a>)</em>, but it is the project that I have learned the most from. It has also sprouted a handful of other API wrappers that I have worked on to facilitate rich interactions with the API like <a href="https://github.com/KristofferStrube/Blazor.FileSystem">Blazor.FileSystem</a>, <a href="https://github.com/KristofferStrube/Blazor.FileAPI">Blazor.FileAPI</a>, and <a href="https://github.com/KristofferStrube/Blazor.Streams">Blazor.Streams</a>. Through my work with these I have built myself a good standard for how to wrap browser API's in Blazor and have begun to wrap some of the lower level APIs like the DOM API.</p> <video width="500" autoplay muted controls loop> <source src="https://kristoffer-strube.dk/videos/Zip_and_IndexedDB.mp4" type="video/mp4"> A video showing some of the functionality of the File System Access API wrapper </video> <p><em>This video is an example of some of the functionality that the File System Access API wrapper supports. This was also one of the first times I had a sample submitted by someone in a PR.</em></p> <p>The second project some might know me from is my <a href="https://github.com/KristofferStrube/Blazor.SVGEditor">Blazor SVG Editor</a>. This is a much more creative and mathematically challenging project that I have worked on for 2 years. With it, I can edit SVGs simply by dragging anchors around the screen and seeing the resulting SVG code in real-time. I often get back to this project when I feel like making something visual or if I really need to be able to make that specific kind of SVG be that a gradient or an animated stroke offset. This also crosses over into my wrapper libraries every so often like when I made a partial wrapper for the SVG Animation API.</p> <p><img src="https://github.com/KristofferStrube/Blazor.SVGEditor/raw/main/docs/showcase.gif?raw=true" alt="The Simpson character Bart being drawn in the SVG Editor." /></p> <p><em>This is an example of an SVG I created 1½ years ago, which actually landed me my first paid gig outside the borders of Denmark.</em></p> <h3>This platform</h3> <p>When I started writing this I figured this would be the nerdy part, but I see that I have already geeked out a lot, so let's keep it simple. This blog is a static site, generated from markdown files and some configuration in JSON. It is a generator that I have made myself called <a href="http://StaticBlog.NET">StaticBlog.NET</a>, but that is not the important part. The important part is that all the content I will write here is in markdown which can be utilized in a huge variety of ways or be consumed by other blogging platforms. This reminds me of a <a href="https://twitter.com/terrajobst/status/1622031997454671872">comment to a post on Twitter</a> by <a href="https://twitter.com/terrajobst">Immo Landwerth</a>:</p> <blockquote> <p>&quot;This is one of the reasons why folks like me decided that we don’t blog straight via WordPress — we use markdown in GitHub and merging there stages it in Wordpress. If they kill that again, we have a bunch of static markdown files we can easily serve.&quot;</p> </blockquote> <p>This idea of having a structure that I can easily move is important to me and will be a key focus for me when continuing the development of the generator and editor for this blog.</p> <h3>Future posts</h3> <p>I intend to make some posts here every so often. At least one post every month. I know that setting goals for creative work can be bad a idea, but I thrive under these kinds of hard measurable goals. Some of my first posts will be about my existing open-source projects, the work I have recently done on them, and the work that follows in the near future. I have also made a list of some topics that I would like to make some posts about in the near future so that I don't forget:</p> <ul> <li>.EditorConfig files for .NET and C#</li> <li>Performance optimizations in .NET 8</li> <li>ActivityPub: The open social network standard</li> <li>Concurrency with SignalR and Blazor WASM</li> <li>The forgotten Typed SignalR Clients introduced in .NET 7</li> <li>StaticBlog.NET: A minimal Static Site Generator written in .NET edited with Blazor WASM.</li> </ul> <p>Feel free to reach out if any of the topics above sounds especially interesting to you. Then I might do them first.</p>