I don't like this API. UseOptions may change data provider on the fly and probably has a lot of other sideeffects. If you need some specific feature, we can discuss.

I don't like this API. UseOptions may change data provider on the fly and probably has a lot of other sideeffects. If you need some specific feature, we can discuss.

I get the concern, but UseOptions doesn’t allow changing everything on the fly. Things like switching the data provider or other options that fundamentally change IDataContext won’t have any effect. The main goal here is to tweak settings that affect SQL generation and execution modes within the current context. So it’s more about flexibility in query behavior rather than altering core IDataContext functionality.

Maybe we need to mention it in the documentation to avoid confusion.

I wouldn't introduce it this way. Instead, you can use the Builder pattern to restrict modifications to only the allowed options. While direct options passing may seem flexible, it often leads to maintainability issues down the road. The API should be self-descriptive.

Introducing a separate Builder pattern just to restrict modifications would add unnecessary complexity. Users will need to learn yet another part of an already feature-rich API, making it harder to adopt. Instead, we can rely on clear documentation and enforce restrictions at runtime by throwing exceptions when unsupported options are modified.

We can't ensure clear documentation when additional options are introduced. However, users might discover undocumented features that work and start relying on them. Later, if we make changes, everything undocumented could stop working. I want to prevent users from making mistakes due to a lack of documentation. Additionally, a strictly limited builder would be more precise than simply modifying the options class.

Exceptions are useful, but why not prevent mistakes entirely by designing the builder in a way that makes them impossible? If something isn’t allowed, it simply won’t compile—this is far better than letting users try unsupported options and fail at runtime.

Our API is already complex enough, and we shouldn’t make it even harder to use. The proposed UseOptions method follows the existing options-setting API, so users don’t have to learn something entirely new.

We already have a Builder-based API - Merge API, and to be honest, I can't use it without constantly referring to the documentation, examples, or even the source code. All those "prevent mistakes entirely by designing the builder" arguments don’t help in practice. Complex APIs that builders tend to become are a bad idea. Reusing the existing, familiar API is a good one.

As for user mistakes, in the latest update, I’ve added the necessary checks to ensure that invalid modifications throw an exception. I wouldn’t have even done that, but maybe this will give you more peace of mind :)

We already have a Builder-based API - Merge API, and to be honest, I can't use it without constantly referring to the documentation, examples, or even the source code. All those "prevent mistakes entirely by designing the builder" arguments don’t help in practice. Complex APIs that builders tend to become are a bad idea. Reusing the existing, familiar API is a good one.

I find that interesting, because I find the current version of the Merge API to be incredibly intuitive. The intellisense based on limited types means that the next available method(s) are immediately available and obvious to select which one should be used.

I find that interesting, because I find the current version of the Merge API to be incredibly intuitive. The intellisense based on limited types means that the next available method(s) are immediately available and obvious to select which one should be used.

Oh, that’s probably because I personally took part in refining the Merge API to make it as polished as it is! :)

But that doesn’t mean it’s simple. Like any API built using the Builder pattern, it comes with an additional learning curve, is often inconsistent with existing APIs, and isn’t always intuitive. It also adds complexity to an already feature-rich library API.

Sometimes, a Builder is necessary - Merge API is a good example. It’s complex, but I don’t see any alternative for it. However, making the entire library follow this pattern would be a huge mistake.

In the case of UseOptions, there’s simply no need for this approach. The existing options API is already familiar to users, and we don’t gain anything by introducing an extra API. It would just make things harder for no real benefit.

/azp run test-all

Test baselines changed by this PR. Don't forget to merge/close baselines PR after this pr merged/closed.