C# template refactor

[jimschubert]

PR checklist

• Read the contribution guidelines.
• Ran the shell script under ./bin/ to update Petstore sample so that CIs can verify the change. (For instance, only need to run ./bin/{LANG}-petstore.sh and ./bin/security/{LANG}-petstore.sh if updating the {LANG} (e.g. php, ruby, python, etc) code generator or {LANG} client's mustache templates). Windows batch files can be found in .\bin\windows\.
• Filed the PR against the correct branch: master, 4.0.x. Default: master.
• Copied the technical committee to review the pull request if your PR is targeting a particular programming language.

Description of the PR

A refactoring proof of concept for the C# client.

This puts a client abstraction on top of RestSharp, such that consumers can provide a custom implementation. This is useful for SDK creators who would rather use HttpClient, or consumers who would rather construct APIs with their own solution (e.g. in-house api accessors with tracing and logging applied).

This PR includes only template changes, as generating working C# clients is currently broken on master due to a regression in enum processing (see gist).

I'm opening this for feedback.

To evaluate:

cd samples/client/petstore/csharp-refactor/OpenAPIClient
sh build.sh
csharp -r:bin/Org.OpenAPITools.dll -r:bin/Newtonsoft.Json.dll -r:bin/RestSharp.dll

csharp> using Org.OpenAPITools.Api;
csharp> var api = new PetApi("http://petstore.swagger.io/v2")
csharp> api.GetPetById(2)
class Pet {
  Id: 2
  Category: class Category {
  Id: 1
  Name: feline
}

  Name: catty
  PhotoUrls: System.Collections.Generic.List`1[System.String]
  Tags: System.Collections.Generic.List`1[Org.OpenAPITools.Model.Tag]
  Status: Available
}

[etherealjoy]

@jimschubert
Will you also deprecate .NET 2.0?

[jimschubert]

The enum issue I found was fixed by #774, so I've merged master and regenerated the C# client. Tests in the sample(s) would need to be updated to this new structure, but I'll await feedback on the approach beforehand.

Below are callouts about things done in this refactor.

Interfaces for sync/async client code

A major point of issue for consumers in the past has been our hard reliance on RestSharp, which required modifying templates to undo the coupling. To address this, I created some abstractions around a REST client.

ApiResponse (generic)

Any client implementation may return a generic ApiResponse<T> with the following structure. It implements IApiResponse as well for non-generic usage of the types when needed (typed Data is exposed as Content: Object).

IAsynchronous Client

All methods return Task<ApiResponse<T>>. All methods accept a readonly (via interface get getter-only properties) configuration object, allowing per-endpoint customization (addressing concerns about mixed auth modes or custom headers for individual calls).

ISynchronous Client

All methods return ApiResponse<T>. All methods accept a per-request readonly (via interface only) configuration object.

ApiClient

Functionality that previously tightly coupled us to RestSharp has been encapsulated into ApiClient, reducing the visibility of anything RestSharp-specific and exposing only the interfaces above.

ApiClient is still a partial class, allowing users to customize calls via partial methods for intercepting requests/responses.

Configuration

The Configuration object is made more intuitive (to me, at least).

Configuration objects implement IReadableConfiguration, allowing you to pass an instance containing only getter properties between methods. This makes the type appear immutable, but does not prevent consuming code from casting to Configuration and modifying it.

Configuration now also allows you to merge one configuration into another, creating a new instance.

This merge works similarly to various JavaScript framework utilities merge/extend functionality. For example, Lodash's _.extend({ }, first, second). This is useful to allow clients to create default settings that can be overridden on a per-request level.

GlobalConfiguration class

A partial class exposing a Singleton object… GlobalConfiguration allows users to create custom defaults without the need to mess with .openapi-generator-ignore. One could add all defaults to this file and ignore it, or could implement a partial class implementation.

Multimap

HTTP allows multiple values to be present in a single header. OpenAPI allows query string parameters to represent a collection of items for a single query string key. There was previously no clean way to represent this.

There's nothing particularly fancy about this implementation. It's essentially decorating a ConcurrentDictionary and exposing functionality for the interface it implements (IDictionary<T, IList<TValue>>).

As with all types in the generated code, users are welcome to reimplement this type and add it to .openapi-generator-ignore to prevent regeneration from overwriting. A user may want to reimplement to avoid using ConcurrentDictionary, for example.

RequestOptions

Abstracting away from RestSharp means having our own implementation of request input parameters. This is implemented as RequestOptions.

API files

All APIs generate 3 interfaces:

• asynchronous
• synchronous
• interface implementing both asynchronous and synchronous interfaces above

This allows consumers to pass the preferable implementation via interface (rather than passing the class and accidentally calling a synchronous operation where an async operation was intended).

Constructors are cleaned up to make fewer assumptions.

Properties allow users to get/set properties, with the assumption that consumers will use this functionality properly.

---

The reason for this refactor is that many consumers want to use something other than RestSharp as the underlying query framework. Users can now extend in some ways which have been requested, but would previously require local modifications to generated code and ignores:

• Implement interfaces to adapt to framework HttpClient
• Implement interfaces to adapt to internal tooling (e.g. something with in-house built tracing/metrics)
• Implement interfaces to wrap the generated ApiClient with Polly implementation (Polly provides Retry, Circuit Breaker, Timeout, Bulkhead Isolation, and Fallback)
• Provide mocked implementations of interfaces for testing the client

[jimschubert]

@etherealjoy

Will you also deprecate .NET 2.0?

I'd like to. There have been discussions about deprecation process, but there's been no target for deprecation of any generators as far as I am aware.

[jimschubert]

@wing328 I've regenerated a sample if you want to take a look at the implementation.

[jimschubert]

@mandrean I was wondering if you'd have any feedback on this refactoring approach?

[SeanFarrow]

@jimschubert, I've just looked at the template, I notice there are errors during CI, are these planned to be corrected?
I'm happy to help if you can point me to the project that is the new generated code in.

[jimschubert]

@SeanFarrow the errors in CI are because tests for all C# clients are strongly reliant on the old RestSharp specific API. I've only regenerated a single client sample, which you can evaluate manually in this branch by following the "To evaluate" steps in the PR description. As mentioned in my second comment on this PR, I'm waiting for feedback on the new design before updating tests. This will save me time if, for example, someone is opposed to any of the designs I've implemented here.

I hope that helps clarify. If not, I can provide a more detailed evaluation step.

[jimschubert]

@wing328 any concerns with planning to make this the default template in 4.0.0?

I'm hoping to have some time this weekend to resolve the test changes, and update some documentation around extending the client generated code to fit a user's needs.

[wing328]

As discussed, we will release this as "csharp-refactor" and use it to replace csharp client genreator in 4.0.0 release (original csharp generator will be renamed to csharp-deprecated)

We'll instead keep the current csharp generator and rename csharp-refactor to csharp-netcore instead to focus on .NET Core, .NET Standard.

Ref: #2348