Add IHostedFileClient and friends by stephentoub · Pull Request #7269 · dotnet/extensions

stephentoub · 2026-02-06T05:00:56Z

Adds an abstraction for interacting with files AI services host, for things like input and output of code interpreter.

Microsoft Reviewers: Open in CodeFlow

Copilot

Pull request overview

This PR adds comprehensive support for interacting with AI service-hosted files through a new IHostedFileClient interface and related abstractions. The feature enables uploading, downloading, and managing files used by AI services, particularly for code interpreter operations.

Changes:

Introduces IHostedFileClient interface with upload, download, get, list, and delete operations
Adds supporting types: HostedFile, HostedFileDownloadStream, and various options classes
Implements OpenAI provider integration with support for both standard Files API and container-scoped files
Includes DelegatingHostedFileClient base class for middleware patterns
Adds HostedFileClientBuilder for creating file client pipelines
Implements logging and OpenTelemetry middleware for observability
Provides comprehensive extension methods for common operations

Reviewed changes

Copilot reviewed 37 out of 37 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/Shared/DiagnosticIds/DiagnosticIds.cs	Adds AIFiles experimental diagnostic ID
src/Libraries/Microsoft.Extensions.AI.Abstractions/Files/IHostedFileClient.cs	Core interface defining file operations
src/Libraries/Microsoft.Extensions.AI.Abstractions/Files/HostedFile.cs	Metadata model for hosted files
src/Libraries/Microsoft.Extensions.AI.Abstractions/Files/HostedFileDownloadStream.cs	Abstract stream base for file downloads
src/Libraries/Microsoft.Extensions.AI.Abstractions/Files/HostedFileClientOptions.cs	Base options class with Scope and AdditionalProperties
src/Libraries/Microsoft.Extensions.AI.Abstractions/Files/HostedFile*Options.cs	Specific option classes for each operation
src/Libraries/Microsoft.Extensions.AI.Abstractions/Files/HostedFileClientMetadata.cs	Provider metadata model
src/Libraries/Microsoft.Extensions.AI.Abstractions/Files/DelegatingHostedFileClient.cs	Base class for middleware implementations
src/Libraries/Microsoft.Extensions.AI.Abstractions/Files/HostedFileClientExtensions.cs	Extension methods for common file operations
src/Libraries/Microsoft.Extensions.AI/Files/HostedFileClientBuilder.cs	Builder for creating file client pipelines
src/Libraries/Microsoft.Extensions.AI/Files/HostedFileClientBuilderHostedFileClientExtensions.cs	AsBuilder extension method
src/Libraries/Microsoft.Extensions.AI/Files/LoggingHostedFileClient.cs	Logging middleware implementation
src/Libraries/Microsoft.Extensions.AI/Files/LoggingHostedFileClientBuilderExtensions.cs	UseLogging extension
src/Libraries/Microsoft.Extensions.AI/Files/OpenTelemetryHostedFileClient.cs	OpenTelemetry tracing/metrics middleware
src/Libraries/Microsoft.Extensions.AI/Files/OpenTelemetryHostedFileClientBuilderExtensions.cs	UseOpenTelemetry extension
src/Libraries/Microsoft.Extensions.AI/OpenTelemetryConsts.cs	Adds File.Name and File.Size constants
src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIHostedFileClient.cs	OpenAI implementation with Files and Container API support
src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIFileDownloadStream.cs	Download stream wrapper for OpenAI responses
src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIClientExtensions.cs	AsIHostedFileClient extension methods
src/Libraries/Microsoft.Extensions.AI/Microsoft.Extensions.AI.csproj	Enables MediaTypeMap injection
src/Libraries/Microsoft.Extensions.AI.Abstractions/Utilities/AIJsonUtilities.Defaults.cs	Adds JSON serialization support
test/Libraries/Microsoft.Extensions.AI.Abstractions.Tests/TestHostedFileClient.cs	Test helper implementation
test/Libraries/Microsoft.Extensions.AI.Abstractions.Tests/Files/*.cs	Unit tests for abstractions
test/Libraries/Microsoft.Extensions.AI.Tests/Files/*.cs	Unit tests for middleware
test/Libraries/Microsoft.Extensions.AI.OpenAI.Tests/*.cs	Unit and integration tests for OpenAI implementation
test/Libraries/Microsoft.Extensions.AI.Tests/Microsoft.Extensions.AI.Tests.csproj	Links TestHostedFileClient

Adds an abstraction for interacting with files AI services host, for things like input and output of code interpreter.

- Missing GetRequiredService methods - Disposing of caller's Stream in OpenAI upload

ericstj

Reviewed abstractions

ericstj · 2026-02-24T17:28:25Z

src/Libraries/Microsoft.Extensions.AI.Abstractions/Files/HostedFile.cs

+    /// <summary>Gets the unique identifier of the file.</summary>
+    public string Id { get; }
+
+    /// <summary>Gets or sets the name of the file.</summary>


Does this contain path information? If so, what rules are applied to those paths -- presumably they need to be platform agnostic. It may be important for folks wanting to save/upload using platform-specific assumptions.

ericstj · 2026-02-24T17:30:22Z

src/Libraries/Microsoft.Extensions.AI.Abstractions/Files/HostedFile.cs

+        Id = Throw.IfNullOrWhitespace(id);
+    }
+
+    /// <summary>Gets the unique identifier of the file.</summary>


Should we call out the scope of uniqueness so that providers implement correctly?

ericstj · 2026-02-24T17:34:42Z

src/Libraries/Microsoft.Extensions.AI.Abstractions/Files/IHostedFileClient.cs

+        string fileId,
+        HostedFileDeleteOptions? options = null,
+        CancellationToken cancellationToken = default);
+


Do any providers expose the concept of "modify" for renaming or changing properties? What about patching a file with content?

ericstj · 2026-02-24T17:42:03Z

src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIFileDownloadStream.cs

+    /// <param name="fileName">The file name.</param>
+    public OpenAIFileDownloadStream(BinaryData data, string? mediaType, string? fileName)
+    {
+        _innerStream = data.ToStream();


Since this wraps a BinaryData it should override ToDataContentAsync and implement over the BinaryData similar to

extensions/src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIImageGenerator.cs

Line 134 in e086c69

contents.Add(new DataContent(image.ImageBytes.ToMemory(), contentType));

ericstj · 2026-02-24T18:04:01Z

src/Libraries/Microsoft.Extensions.AI.Abstractions/Files/HostedFileClientExtensions.cs

+
+        // Determine the final path
+        string finalPath = destinationPath;
+        if (Directory.Exists(destinationPath))


This should be consistent with the behavior of https://github.com/stephentoub/extensions/blob/dd42b9473975f96cdce799cc955337476febbc1f/src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/DataContent.cs#L212 which will handle an empty string as a directory as well.

ericstj · 2026-02-24T18:23:16Z

src/Libraries/Microsoft.Extensions.AI.Abstractions/Files/HostedFileClientOptions.cs

+    /// <summary>
+    /// Initializes a new instance of the <see cref="HostedFileClientOptions"/> class.
+    /// </summary>
+    private protected HostedFileClientOptions()


Interesting - so rather than share a single options that's a super set we have options that are "best" for each operation and put anything shared between all in the base. I suppose that's OK, it optimizes for all-shared and op-specific.

ericstj · 2026-02-24T18:24:45Z

src/Libraries/Microsoft.Extensions.AI.Abstractions/Files/HostedFileClientOptions.cs

+    public string? Scope { get; set; }
+
+    /// <summary>Gets or sets additional properties for the request.</summary>
+    public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }


Do we need some raw representation (RawRepresentationFactory) for break glass? I can imagine some providers having advanced options.

ericstj · 2026-02-24T18:25:35Z

src/Libraries/Microsoft.Extensions.AI.Abstractions/Files/HostedFileListOptions.cs

+[Experimental(DiagnosticIds.Experiments.AIFiles, UrlFormat = DiagnosticIds.UrlFormat)]
+public sealed class HostedFileListOptions : HostedFileClientOptions
+{
+    /// <summary>Gets or sets a purpose filter.</summary>


Any other filter options supported by providers? Like a path filter or some-such?

ericstj · 2026-02-24T18:29:10Z

src/Libraries/Microsoft.Extensions.AI.Abstractions/Files/HostedFile.cs

+/// </summary>
+[DebuggerDisplay("{DebuggerDisplay,nq}")]
+[Experimental(DiagnosticIds.Experiments.AIFiles, UrlFormat = DiagnosticIds.UrlFormat)]
+public sealed class HostedFile


This doesn't actually have the file content, consider a name like HostedFileInfo or consider API that lets folks get the content from the file, presumably such API would also require the file to maintain a reference to the client that it's associated with.

ericstj · 2026-02-24T18:30:32Z

src/Libraries/Microsoft.Extensions.AI.Abstractions/Files/HostedFile.cs

+public sealed class HostedFile
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="HostedFile"/> class.


In it's current form it looks like we only ever expect providers to instantiate this. I wonder why this is different than HostedFileContent?

stephentoub requested review from ericstj, jeffhandley, jozkee and rogerbarreto February 6, 2026 05:00

stephentoub requested review from a team as code owners February 6, 2026 05:00

Copilot AI review requested due to automatic review settings February 6, 2026 05:00

github-actions bot added the area-ai Microsoft.Extensions.AI libraries label Feb 6, 2026

Copilot started reviewing on behalf of stephentoub February 6, 2026 05:01 View session

dotnet-policy-service bot assigned stephentoub Feb 6, 2026

Copilot AI reviewed Feb 6, 2026

View reviewed changes

stephentoub added 2 commits February 6, 2026 10:07

Add IHostedFileClient and friends

6a5af55

Adds an abstraction for interacting with files AI services host, for things like input and output of code interpreter.

Address offline copilot feedback

5bfc6fc

- Missing GetRequiredService methods - Disposing of caller's Stream in OpenAI upload

stephentoub force-pushed the fileclient branch from 0cf7b85 to 5bfc6fc Compare February 6, 2026 16:08

Merge branch 'main' into fileclient

dd42b94

ericstj reviewed Feb 24, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

Add IHostedFileClient and friends#7269

Add IHostedFileClient and friends#7269
stephentoub wants to merge 3 commits intodotnet:mainfrom
stephentoub:fileclient

stephentoub commented Feb 6, 2026 •

edited by dotnet-policy-service bot

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

ericstj left a comment

Uh oh!

ericstj Feb 24, 2026

Uh oh!

ericstj Feb 24, 2026

Uh oh!

ericstj Feb 24, 2026

Uh oh!

ericstj Feb 24, 2026

Uh oh!

ericstj Feb 24, 2026

Uh oh!

ericstj Feb 24, 2026

Uh oh!

ericstj Feb 24, 2026

Uh oh!

ericstj Feb 24, 2026

Uh oh!

ericstj Feb 24, 2026

Uh oh!

ericstj Feb 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

Conversation

stephentoub commented Feb 6, 2026 • edited by dotnet-policy-service bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Microsoft Reviewers: Open in CodeFlow

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

ericstj left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

stephentoub commented Feb 6, 2026 •

edited by dotnet-policy-service bot

Loading