[Files] Expose optional ExpiresAfter for OpenAIFileClient.UploadFileAsync()

[ShivangiReja]

Latest spec added a new property in InternalFileUploadOptions: ExpiresAfter.

Today, UploadFileAsync is GA and follows our existing OpenAI SDK pattern:

• Required properties are exposed as method parameters
• Optional properties live in an options class

That pattern explains why the current InternalFileUploadOptions properties are exposed as UploadFileAsync parameters (they were all required). Now ExpiresAfter is optional, so we need to decide how to expose it without creating inconsistency or churn.

[Megatron4537]

Hey @ShivangiReja 😄

I have created a PR #908 to address this.

Let me know if there's anything you'd like to discuss further.

[Megatron4537]

Hey @ShivangiReja, any updates on getting someone to review PR #908 ?

[ShivangiReja]

@Megatron4537 Thank you for taking the time to put together PR, and for using Copilot to help implement the change.

We’re still discussing the right shape for this API internally. In particular, we’re evaluating whether we want to move toward protocol models more broadly, which would naturally carry both required and optional fields together. Since that decision impacts more than just this one property, I’d prefer we hold off on merging a design change here until we align on the overall direction.

For that reason, we may defer this update until the internal design discussion is finalized.

Thanks again for the contribution. I’ll follow up once we have a clear decision.

[Megatron4537]

@ShivangiReja I understand the concern regarding API consistency and the desire to avoid churn, but I believe introducing FileUploadOptions is the correct path forward for a few key reasons:

Future-Proofing & Extensibility: While ExpiresAfter is the only optional property today, the API spec is likely to evolve. Adopting the standard SDK pattern of an Options class now ensures that when future optional properties are added, we won't need to introduce breaking changes or clutter the method overloads further. It provides a clean, extendable home for all future optional parameters.

Low Risk (Revertable): I’ve marked the new FileUploadOptions class and the corresponding overloads as [Experimental]. This explicitly signals to consumers that the API shape is subject to change. It allows us to ship the critical functionality immediately without "locking in" the design for GA. If we decide on a different pattern later, we can modify or remove it without breaking semantic versioning for stable users.

Immediate Necessity: This feature is critical for current use cases (managing compliance and storage). Blocking it on a perfect architectural decision that might not exist (given the mixed required/optional nature) holds back necessary functionality.

Non-Intrusive: By adding overloads rather than modifying the existing UploadFile signature, we maintain binary compatibility for all existing users while offering the new capability to those who opt-in.

Given the safeguards of the [Experimental] attribute, I believe this strikes the right balance between adhering to .NET design guidelines and delivering needed features.

[ShivangiReja]

@Megatron4537 I agree the options-class approach is reasonable under our current pattern, and marking it [Experimental] helps.

The main reason we’re holding off is that we may move this API to protocol models, where a single request model(protocol model) carries both required and optional fields. If we go that direction, we likely wouldn’t introduce a separate FileUploadOptions type at all. Since we’re still discussing the right shape for this API internally, we want to avoid merging one design now and then pivoting shortly after.

I’ll follow up once we finalize the direction.