Blazor Media Component Suite by rolandVi · Pull Request #63540 · dotnet/aspnetcore

rolandVi · 2025-09-04T10:55:33Z

Media Component Suite

Summary

This PR introduces a suite of media components for efficiently handling non-HTTP sources (byte[]s or streams) with streaming through JS interop and browser-side caching. The suite includes Image, Video, and FileDownload which built on a shared foundation.

Features

Unified source model
- MediaSource from byte[] or Stream with MimeType and CacheKey properties
- Single-use design: one MediaSource instance corresponds to exactly one media operation
- Properties: MimeType, CacheKey, Length
Automatic caching
- Caching backed by the browser Cache Storage API, keyed by CacheKey
- Shared cache across Image and Video components for efficient reuse
Stream-based transfer
- Uses DotNetStreamReference for efficient streaming from .NET to JS
- Supports progress tracking via CSS custom property --blazor-media-progress
- Robust cancellation/race handling: only the latest request for an element is finalized
Minimal markup and CSS-driven UX
- Components render native HTML elements with distinctive markers:
  - <img data-blazor-image>
  - <video data-blazor-video>
  - <a data-blazor-file-download>
- data-state="loading" or "error" enables styling via CSS
Lifecycle and memory safety
- Blob URL creation/revocation handled in JS
- Automatic URL revocation when components are removed from DOM
- Cancellation of in-progress operations when sources change

API surface

Base

Abstract MediaComponentBase class for shared functionality

Image Component

Parameters
- Source: MediaSource (required)
- AdditionalAttributes: forwarded to the underlying <img> (e.g., alt, class, style)
Render output
- <img data-blazor-image data-state="loading|error" ... />

Video Component

Parameters
- Source: MediaSource (required)
- AdditionalAttributes: forwarded to the underlying <video> (e.g., controls, autoplay, loop)
Render output
- <video data-blazor-video data-state="loading|error" ... ></video>

FileDownload Component

Parameters
- Source: MediaSource (required)
- FileName: string (required) - Name for the downloaded file
- Text: string (optional) - Link text, defaults to "Download"
- AdditionalAttributes: forwarded to the underlying <a> (e.g., class, style)
Render output
- <a data-blazor-file-download data-state="loading|error" ... >Download</a>
Doesn't use caching since users usually download a file only once

Implementation (`src\Components`)

Web\src\Media\MediaComponentBase.cs
Web\src\Media\MediaSource.cs
Web\src\Media\Image.cs
Web\src\Media\Video.cs
Web\src\Media\FileDownload.cs
Web.JS\src\Rendering\BinaryMedia.ts
Tests
- Unit tests - Web\test\Media
- E2E test components - test\testassets\BasicTestApp\MediaTest
- E2E tests
  - test\E2ETest\Tests\ImageTest.cs
  - test\E2ETest\Tests\VideoTest.cs
  - test\E2ETest\Tests\FileDownloadTest.cs

Performance considerations

Stream-based transfer avoids large memory allocations
Shared caching system prevents duplicate data storage
Blob URLs are revoked when components are removed from the DOM
Cache-first load avoids redundant streaming for repeated content
Direct-to-disk downloading when available

Examples

Image Component

@using Microsoft.AspNetCore.Components.Web.Media

<Image Source="new MediaSource(photoBytes, "image/jpeg", "photo-42")"
       alt="Product photo"
       style="max-width: 100%; height: auto;" />

Video Component

@using Microsoft.AspNetCore.Components.Web.Media

<Video Source="new MediaSource(videoBytes, "video/mp4", "product-demo")"
       controls
       style="max-width: 100%;" />

FileDownload Component

@using Microsoft.AspNetCore.Components.Web.Media

<FileDownload Source="new MediaSource(pdfData, "application/pdf", "report")"
              FileName="annual-report-2025.pdf"
              Text="Download Report" />

Related to -> #63562

into first-additions

…eaming of variable size

This reverts commit 3e674f7.

…for loading and error styling using css data-state

Copilot

Pull Request Overview

This PR introduces a comprehensive media component suite for efficiently handling non-HTTP sources (byte[]s or streams) with streaming through JS interop and browser-side caching. The suite provides Image, Video, and FileDownload components built on a shared foundation with unified source handling, automatic caching, and stream-based transfer for optimal performance.

Key changes include:

New media component architecture with MediaSource class and abstract MediaComponentBase
Browser Cache Storage API integration for efficient content reuse
TypeScript implementation for streaming and download functionality with fallback support
Comprehensive test coverage including unit tests and E2E tests

Reviewed Changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`src/Components/Web/src/Media/`	Core media component implementation including base classes and concrete components
`src/Components/Web.JS/src/Rendering/BinaryMedia.ts`	TypeScript implementation for streaming, caching, and download functionality
`src/Components/test/testassets/BasicTestApp/MediaTest/`	E2E test components for validating media component behavior
`src/Components/test/E2ETest/Tests/`	E2E test suites for Image, Video, and FileDownload components
`src/Components/Web/test/Media/`	Unit tests for media component functionality
`src/Components/Web/src/PublicAPI.Unshipped.txt`	Public API surface additions

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

javiercn

Looks like a great start, but I think we need to tweak things a bit to balance code-reuse and public API surface.

javiercn · 2025-09-04T11:21:25Z

+    protected override void BuildRenderTree(RenderTreeBuilder builder)
+    {
+        builder.OpenElement(0, TagName);
+
+        builder.AddAttribute(1, MarkerAttributeName, "");
+
+        if (IsLoading)
+        {
+            builder.AddAttribute(2, "data-state", "loading");
+        }
+        else if (_hasError)
+        {
+            builder.AddAttribute(2, "data-state", "error");
+        }
+
+        builder.AddAttribute(3, "href", "javascript:void(0)");
+
+        builder.AddAttribute(4, "onclick", EventCallback.Factory.Create(this, OnClickAsync));
+
+        if (AdditionalAttributes?.ContainsKey("href") == true)
+        {
+            AdditionalAttributes.Remove("href");
+        }
+        builder.AddMultipleAttributes(6, AdditionalAttributes);
+
+        builder.AddElementReferenceCapture(7, elementReference => Element = elementReference);
+
+        builder.AddContent(8, Text ?? "Download");
+
+        builder.CloseElement();
+    }


Instead of this, I think it should be something like <a href="file" download>Text</a>.

Also, if we want to avoid having the text, we can receive RenderFragment<T> as a parameter (where T might be some context we want to make available for rendering). Or just RenderFragment and let the consumer define the UI completely.

The current approach was made to support the native picker direct-to-file download. Right now when a download is triggered, if the native file picker dialog is available, we stream the data direct-to-file. If not, we default to the <a href="file" download>Text</a> download

I must have missed that

Also, if we want to avoid having the text, we can receive RenderFragment<T> as a parameter (where T might be some context we want to make available for rendering). Or just RenderFragment and let the consumer define the UI completely.

I've implemented the RenderFragment<T> approach with MediaContext as the context type, giving consumers access to loading states, error conditions and the object url.
The downside is that users have to provide the element reference to make the element propagation to JS possible, by doing something like this:

<Image Context="ctx" Source=...> ... <img @ref="ctx.Element" src="@ctx.ObjectUrl" .../> ... </Image>

javiercn · 2025-09-05T12:35:35Z

@rolandVi to throw a curve ball on this.

@pavelsavara rightly pointed out that for video we can use something like https://developer.mozilla.org/en-US/docs/Web/API/MediaSource which doesn't require us to collect all the chunks in memory, so that's something we would be interested in exploring.

rolandVi · 2025-09-08T12:14:43Z

@rolandVi to throw a curve ball on this.

@pavelsavara rightly pointed out that for video we can use something like https://developer.mozilla.org/en-US/docs/Web/API/MediaSource which doesn't require us to collect all the chunks in memory, so that's something we would be interested in exploring.

Thank you for the feedback, this is indeed very useful. I've implemented an approach using the MediaSource api for video , if the api is not available, it fallbacks to the original approach.

javiercn

Looks great!

rolandVi and others added 30 commits July 21, 2025 13:43

Adding initial component fucntionality

a94c34a

Adding demo fucntionality for Image component

08bc924

Add image chunking functionality

313291f

Fixed chunking

c3cd8e0

Added support for stream image sources

b4095f8

Edited Sample project

13db54a

Merge branch 'dotnet:main' into first-additions

ea0614a

Merge branch 'first-additions' of https://github.com/rolandVi/aspnetcore

cf1e54e

into first-additions

Fixed DisposeAsync calling JSinterop during prerendering

2ac1dad

Added default content styling

eca62e4

Added an alternative approach using a HTTP endpoint

514c600

Resolving RequiresUnreferencedCodeAttribute

1afd371

JsonSerializer working state

9a0c150

Fixed JsonSerializer

2a08f7e

Moving endpoint registration to initialization of component

7aef8e4

Improved caching strategy

f54591c

Removed OnImageLoaded and OnImageError

de01506

Removed HTTP endpoint approach

f11f52d

Made ImageSource into a class and refactored typescript to handle str…

7670c8c

…eaming of variable size

razor refactoring not working

3e674f7

Revert "razor refactoring not working"

21ddc86

This reverts commit 3e674f7.

Added transfler progress variable for loading animations

89c40d5

Adding E2E tests, not working so far

c80bfc7

Saving E2E test state

39386f6

Added Element reference approach

d86cb66

Changed markup of the component, got rid of the outside div, allowed …

e00a1a3

…for loading and error styling using css data-state

Added dynamic loading when source changes

e7fcc91

Made cache key mandatory

a8aa78a

Added load version tracking

3dd55c1

Compare ImageSources on key

042c30c

rolandVi requested a review from a team as a code owner September 4, 2025 10:55

github-actions Bot added the area-blazor Includes: Blazor, Razor Components label Sep 4, 2025

dotnet-policy-service Bot added the community-contribution Indicates that the PR has been added by a community member label Sep 4, 2025

rolandVi changed the title ~~Roland/media component~~ Blazor Media Component Suite Sep 4, 2025

Copilot AI reviewed Sep 4, 2025

View reviewed changes

Comment thread src/Components/Web/src/Media/MediaComponentBase.cs Outdated

Comment thread src/Components/Web/src/Media/FileDownload.cs Outdated

Comment thread src/Components/test/E2ETest/Tests/FileDownloadTest.cs Outdated

rolandVi and others added 2 commits September 4, 2025 13:16

Update src/Components/Web/src/Media/MediaComponentBase.cs

cd7922c

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update src/Components/test/E2ETest/Tests/FileDownloadTest.cs

9becff5

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

javiercn reviewed Sep 4, 2025

View reviewed changes

dariatiurina removed the community-contribution Indicates that the PR has been added by a community member label Sep 4, 2025

Merge branch 'main' into roland/media-component

b02bea0

build-analysis Bot mentioned this pull request Sep 4, 2025

Known Build Error: error : Cannot create a file when that file already exists. #61178

Open

rolandVi added 2 commits September 4, 2025 15:18

Clean up old code

067d23c

Reduced publicapi, extend buildrendertree

dc5cee7

rolandVi added 2 commits September 8, 2025 13:46

Add MediaSource fun. for video

406e2d5

Delete broken test

d49d267

build-analysis Bot mentioned this pull request Sep 8, 2025

[Known Build Error] NavigationException_InAsyncContext_DoesNotBecomeUnobservedTaskException fails with ObjectDisposedException #62672

Open

Add custom rendering

1a9301a

This was referenced Sep 10, 2025

[Known Build Error] Failed webcil conversion: image is too small #61987

Open

The Operation will be canceled. The next steps may not contain expected logs. dotnet/dnceng#3008

Open

rolandVi added 2 commits September 11, 2025 14:01

Fix corrupt blob for small media

aa68beb

Add E2E tests for custom rendering

79b0f92

javiercn approved these changes Sep 17, 2025

View reviewed changes

javiercn merged commit 43b81a9 into dotnet:main Sep 17, 2025
30 checks passed

dotnet-policy-service Bot added this to the 11.0-preview1 milestone Sep 17, 2025

javiercn mentioned this pull request Sep 22, 2025

[Blazor] Generalize Blazor Image component to other media sources #63562

Closed

wtgodbe mentioned this pull request Nov 11, 2025

Mark API from 10.0 as shipped #64319

Merged

javiercn mentioned this pull request Apr 20, 2026

API Proposal: Media components (Image, Video, FileDownload) #66391

Open

Copilot AI mentioned this pull request Jun 10, 2026

Separate media components into Microsoft.AspNetCore.Components.Media package #67130

Merged

4 tasks

Navigation Menu

Uh oh!

Blazor Media Component Suite - #63540

Blazor Media Component Suite#63540
javiercn merged 81 commits into
dotnet:mainfrom
rolandVi:roland/media-component

rolandVi commented Sep 4, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

javiercn left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

javiercn Sep 4, 2025

Uh oh!

rolandVi Sep 4, 2025

Uh oh!

javiercn Sep 8, 2025

Uh oh!

rolandVi Sep 10, 2025

Uh oh!

javiercn commented Sep 5, 2025

Uh oh!

rolandVi commented Sep 8, 2025

Uh oh!

javiercn left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

rolandVi commented Sep 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Media Component Suite

Summary

Features

API surface

Base

Image Component

Video Component

FileDownload Component

Implementation (src\Components)

Performance considerations

Examples

Image Component

Video Component

FileDownload Component

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

javiercn left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

javiercn Sep 4, 2025

Choose a reason for hiding this comment

Uh oh!

rolandVi Sep 4, 2025

Choose a reason for hiding this comment

Uh oh!

javiercn Sep 8, 2025

Choose a reason for hiding this comment

Uh oh!

rolandVi Sep 10, 2025

Choose a reason for hiding this comment

Uh oh!

javiercn commented Sep 5, 2025

Uh oh!

rolandVi commented Sep 8, 2025

Uh oh!

javiercn left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

rolandVi commented Sep 4, 2025 •

edited

Loading

Implementation (`src\Components`)