.NET to JS Streaming Interop API Proposal

[TanayParikh]

Background and Motivation

Support sending data streams from .NET to JS. This is the other end of the JS to .NET streaming functionality implemented earlier.

Proposed API

namespace Microsoft.JSInterop
{
    /// <summary>
    /// Represents the reference to a .NET stream sent to JavaScript.
    /// </summary>
    public sealed class DotNetStreamReference : IDisposable
    {
        /// <summary>
        /// Create a reference to a .NET stream sent to JavaScript.
        /// </summary>
        /// <param name="stream">The stream being sent to JavaScript.</param>
        /// <param name="leaveOpen">A flag that indicates whether the stream should be left open after transmission.</param>
        public DotNetStreamReference(Stream stream, bool leaveOpen = false);

        /// <summary>
        /// The stream being sent to JavaScript.
        /// </summary>
        public Stream Stream { get; }

        /// <summary>
        /// A flag that indicates whether the stream should be left open after transmission.
        /// </summary>
        public bool LeaveOpen { get; }
    }
}

Usage Examples

  using var data = new System.IO.MemoryStream(new byte[100 * 1024]);
  using var streamRef = new DotNetStreamReference(stream: data, leaveOpen: false);
  await JS.InvokeVoidAsync("consumeStream", streamRef);

async function consumeStream(streamRef) {
    const data = await streamRef.arrayBuffer();    // ArrayBuffer
    // or
    const stream = await streamRef.stream();       // ReadableStream
}

or as return value:

async function getFileData() {
    const streamRef = await DotNet.invokeMethodAsync('BlazorServerApp', 'GetFileData');
}

Alternative Designs

N/A

Risks

N/A

PR: #34817

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[pranavkm]

API feedback - we discussed making the properties on DotNetStreamReference non public, but they're used across assembly boundaries. Exposing an overload that accepts a Stream was also considered, but that adds more complexity particularly because we want to have a non-disposing stream.