📦 Feature Lifecycle in the OpenAI .NET Client Library

This page explains how new OpenAI features are included in the OpenAI client library for .NET, and what to expect at each stage.

🎯 Our Goals

The design and evolution of the .NET client library are guided by these goals:

• Balance delivering new features quickly with providing a high-quality, idiomatic .NET developer experience.

• Enable developers to use new service features as soon as possible, without waiting for a finalized long-term design.

• Clearly distinguish between features that:

  • Are stable, safe for long-term use, and protected from breaking changes.
  • Are experimental, still evolving, and may change as we gather feedback — sometimes introducing breaking changes.

• Provide two complementary API surfaces:

  • A friendly, high-level API that abstracts protocol details behind familiar .NET constructs.
  • A protocol API that offers low-level access to the underlying service, for scenarios where precise control is required.

• Offer a strong backward compatibility guarantee for stable features, so they're safe to use in critical applications while staying current with package updates — essential for delivering bug fixes and critical security patches.

• Ensure stable features feel natural in .NET by following the same patterns, naming conventions, and idioms as the .NET runtime, making them easy to adopt and integrate into existing applications.

🔄 Current Feature Lifecycle

Here’s how a typical feature progresses from the OpenAI service into the .NET client library:

1️⃣ Appears in the OpenAI REST API

• A new capability is added to the OpenAI service and documented in the REST API specification.

2️⃣ Introduced in the .NET client library in protocol form

• The feature becomes immediately accessible via the protocol API.
• At this stage, developers interact directly with raw request and response payloads.
• There are no high-level .NET models or abstractions yet.
• This approach enables immediate experimentation and integration, though it may require deeper familiarity with the service API.

3️⃣ Advances to experimental state

• The feature gains initial .NET models, types, and convenience methods that abstract away protocol-level details.
• These APIs follow .NET conventions but may still have rough edges.
• Breaking changes are expected as we refine the design based on real-world usage and community feedback.
• Community input is especially valuable in this phase and often shapes the final API surface.

4️⃣ Reaches stable state

• The feature has matured through feedback and testing.
• The API surface becomes polished, consistent with .NET design guidelines, and intuitive to use.
• At this point, it is protected by our strong backward compatibility promise: breaking changes are only considered in rare and critical circumstances, such as severe security issues.
• Stable features are suitable for production use and long-term maintenance.

🌱 Looking Ahead

We are continually improving our tools and processes to make it easier to deliver new features quickly and in a more developer-friendly form:

• Enhance our tooling to better recognize patterns and idioms in the OpenAI REST specification.
• Aim to move new features directly into the experimental stage — skipping the protocol-only phase wherever possible — so developers can adopt them more easily and share feedback sooner.
• Some features may still begin as protocol-only, particularly when the OpenAI service uses constructs like union types that have no direct .NET representation.
• We will continue refining our automation and design process to reduce these gaps over time.