Generate DateOnly type for newer .net releases

[jods4]

For { type: "string", format: "date" } models, Kiota references a Date struct that is shipped in its Abstractions package.

In newer .net releases, it would be nice to use the built-in System.DateOnly type, so that the model integrates more naturally with the rest of the code.

[baywet]

Thanks for your interest in kiota and for reaching out.

This is something we had to think about for a while internally.

This type is only available for dotnet 6, 7 and 8

While no other versions of dotnet core are still supported today, dotnet framework is still supported (4.7 and up) and will be for years to come.

We decided to prioritize broader compatibility over new features. And we're not adding switches to kiota (or configuration) that's language specific to keep it simple.

To maintain that compatibility the dotnet libraries ship with a target of netstandard2.0 and 2.1 which matches the recommendation provided by the dotnet team (the only change here since we shipped is that net core 3.1 and 5 went OEL and the recommended target for those moved from standard 2.1 to net6.0). Removing some of those targets would be a binary breaking change. But we could always add some (not to replace the types we've introduced though)

Could you please provide code examples of what's "difficult" to move from DateOnly to Date (and from TimeOnly to Time) so we could maybe design additional methods on those types (conditionally added) to make those scenarios easier?

[jods4]

@baywet Thank you for your response!

Adopting DateOnly

I was thinking you could use #if NET6_0_OR_GREATER in the code generation, similar to what you do today for nullable reference types.
Of course the big issue is that this would be a breaking change for a project using Kiota that upgrades from .net 5 to .net 6 -- or .net 6 projects upgrading Kiota from current version to the next one.
For the sake of backward compatibility, I don't see how this could be added without an extra configuration switch --use-dateonly.

Long-term, I believe a solution needs to be found. Dotnet 6 is soon three years old, and DateOnly is the new BCL standard type for dates. As adoption grows across the ecosystem, not using it would be like shipping a custom DateTime, which sounds a bit silly?
As a case in point, other MS tools have introduced a Date type, for example MS ODataClient, and now all these tools have incompatible date representation and needs conversion functions to pass data from one to the other.

Difficulties with Date

The thing is that all our other code is using DateOnly for dates.

We like giving up on DateTime for pure dates because you easily encounter timezone or time savings issues and your date at 00:00 becomes the day before at 23:00 and your data is corrupted: (

When it comes to call an API that accepts a date, the natural thing to do is just pass the variable.

// Just an example, don't mind the fact that DateOnly.Today does not actually exist :)
DateOnly startDate = DateOnly.Today;

// Does not compile because DateOnly is not assignable to Date.
client.GetAsync(x => x.QueryParameters.Date = startDate);


// So now you need to create an extension method to perform the conversion, 
// and invoke it everywhere you pass dates to OpenApi:

public static Date ToOpenApi(this DateOnly value)
  => new Date(value.Year, value.Month, value.Day);

// With this you can do:
client.GetAsync(x => x.QueryParameters.Date = startDate.ToOpenApi());

That's a bit annoying, still doable.
You could make it a lot better if you included an Abstraction package compiled for .net 6.0+ with an implicit conversion from DateOnly to Date, so straight assignment would compile.

But the worst part is when there are Date properties inside models (either in POST payloads or in responses).
Now an implicit conversion will not be enough to bring the model back into code that uses DateOnly pervasively:

• You either need to add conversion functions everywhere you access the model property;
• Which may also includes edge cases such as serialization;
• Or you must use a mapper tool to map the response to a hand-written "duplicate" class that has DateOnly everywhere instead Date.

[baywet]

Thanks for the additional context.

To maintain compatibility, we'd still generate depending on Date, not switch to DateOnly. We might switch to DateOnly with the next major version of Kiota, as usage of dotnet framework decreases and assuming we'd drop compatibility.

With the conditional compilation we could do multiple things:

• Add a constructor to Date that accepts a DateOnly
• Add a constructor to Time that accepts TimeOnly
• Add a method to Date that returns a DateOnly
• Add a method to Time that returns a TimeOnly
• Add an extension method to DateOnly that returns a Date
• Add an extension method to TimeOnly that returns a Time.

This way you should be able to do

var result = await client.GetAsync(x => x.QueryParameters.Date = DateOnly.Today.ToDate()); // use of extension method here
var createdAtDateOnly = result.CreatedAt.ToDateOnly(); // use of the conversion method

What do you think of that experience?

[jods4]

An extension method like ToDateOnly() can be created today in user-land and sprinkled everywhere, it's not a big step up.

A more interesting improvement would be providing implicit conversions from/to DateOnly on .net 6+:

• This can only be done by you because implicit conversions must be defined directly in involved types, they can't be extensions.
• Then we could seamlessly assign DateOnly to Date parameters, and vice-versa.

With this, the scalar parameters use-case is rather well covered. There would still be friction when handling model classes but I'm afraid this can only be truly fixed by offering real support for DateOnly.

BTW quick unrelated question (I didn't want to open an issue for this): any reason the generated c# code isn't partial?
That's common with generated code, so that consumers can maybe add attribute, interfaces or additional methods to generated classes?

[baywet]

For reference to other readers we're talking about this feature of the language. Which is a great suggestion, thanks for bringing it up!

So to update my initial list we'd have:

• Add an implicit conversion operator to Date that accepts a DateOnly
• Add an implicit conversion operator to Time that accepts TimeOnly
• Add an implicit conversion operator to Date that returns a DateOnly
• Add an implicit conversion operator to Time that returns a TimeOnly

Which would give us symmetry of conversion between the types. (and those operators would be under a conditional compilation)

To answer your question about partial types: this is because it makes supporting anything much harder. Is this failing because of the code we intended to be there or some additional third party extensibility?

Transferring to the abstractions repo.

[baywet]

CC @andrueastman for review of the approach here.
@jods4 would you be interested in submitting a pull request for this now that we have clear directions?

[jods4]

Yes, I can PR conversion operators.

Question though: why do you suggest explicit conversion to Date?
This means we have to write QueryParameters.StartDate = (Date)startDate instead of QueryParameters.StartDate = startDate (assuming startDate is a DateOnly).

Is this failing because of the code we intended to be there or some additional third party extensibility?

Nothing crucial so far. I was looking to extend the main class (which I did by subclassing).
Subclassing is ok with client because I have control over instantiation. I don't have an extensibility need for model classes yet, but as they are instantiated by generated code, partial class is the only way to extend them.
Other use cases you can't solve with subclasses would be adding attributes on existing members.

[baywet]

Updated my original comment to implicit for all. I don't think we'll suffer loss of precision either way. So we shouldn't require the user to make an explicit conversion.