.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

[ghost]

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.

[ghost]

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.

[ghost]

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.

[ghost]

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.

[ghost]

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.

[ghost]

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.