Add support for [DateTime] and [DateTimeOffset] transformations in PropertyVisitor, update proto definitions, extend unit tests, and update documentation for Timestamp handling

Author: machibuse

CLAUDE.md

@@ -4,7 +4,7 @@
 
 Porticle.Grpc.TypeMapper is a Roslyn-based post-processor shipped as a NuGet development dependency. It hooks into the build pipeline after `Protobuf_Compile` and rewrites protoc-generated C# classes to add support for Guids, decimals, nullable strings, and nullable enums — features not natively supported by Protocol Buffers.
 
-Proto field comments (`[GrpcGuid]`, `[Decimal]`, `[NullableString]`, `[NullableEnum]`) or global project properties control which transformations are applied.
+Proto field comments (`[GrpcGuid]`, `[Decimal]`, `[DateTime]`, `[DateTimeOffset]`, `[NullableString]`, `[NullableEnum]`) or global project properties control which transformations are applied.
 
 ## Solution Structure
 

README.md

@@ -1,6 +1,7 @@
 # Porticle.Grpc.TypeMapper
 
-A Roslyn-based post-processor for protoc-generated files that adds automatic mappings for `Guid`, `Guid?`, `decimal`, `decimal?`, `string?`, nullable enums and nullable reference
+A Roslyn-based post-processor for protoc-generated files that adds automatic mappings for `Guid`, `Guid?`, `decimal`, `decimal?`, `DateTime?`, `DateTimeOffset?`, `string?`,
+nullable enums and nullable reference
 types. By simply adding this
 package and adding
 comments to
@@ -22,6 +23,8 @@ This library adds automatic conversion for:
 - Protobuf google.Protobuf.StringValue to C# Guid?
 - Protobuf string to C# decimal
 - Protobuf google.Protobuf.StringValue to C# decimal?
+- Protobuf google.protobuf.Timestamp to C# DateTime?
+- Protobuf google.protobuf.Timestamp to C# DateTimeOffset?
 - Protobuf google.Protobuf.StringValue to C# string?
 - Protobuf optional enum to C# nullable enum
 - Full nullable reference type support per message via `[NullableReferenceTypes]`
@@ -34,6 +37,8 @@ Code.
 
 - Add `// [GrpcGuid]` as comment to a string or StringValue proto field to get Guid/Guid? in generated c# code
 - Add `// [Decimal]` as comment to a string or StringValue proto field to get decimal/decimal? in generated c# code
+- Add `// [DateTime]` as comment to a google.protobuf.Timestamp proto field to get DateTime? in generated c# code (UTC only - assigning a non-UTC DateTime throws)
+- Add `// [DateTimeOffset]` as comment to a google.protobuf.Timestamp proto field to get DateTimeOffset? in generated c# code
 - Add `// [NullableString]` as comment to a string or StringValue proto field to get string? in generated c# code
 - Add `// [NullableEnum]` as comment to an optional enum proto field to get MyEnum? in generated c# code
 - Add `// [NullableReferenceTypes]` as comment above a message to wrap all reference type properties with `#nullable enable/disable` and make nullable ones `string?` / `TypeName?`
@@ -74,6 +79,8 @@ There are several things you can do in your .proto files:
 - Add `// [GrpcGuid]` as comment to a StringValue field - Converts the corresponding c# string property to Guid?
 - Add `// [Decimal]` as comment to a string field - Converts the corresponding c# string property to decimal
 - Add `// [Decimal]` as comment to a StringValue field - Converts the corresponding c# string property to decimal?
+- Add `// [DateTime]` as comment to a google.protobuf.Timestamp field - Converts the corresponding c# Timestamp property to DateTime?
+- Add `// [DateTimeOffset]` as comment to a google.protobuf.Timestamp field - Converts the corresponding c# Timestamp property to DateTimeOffset?
 - Add `// [NullableString]` as comment to a StringValue field - Converts the corresponding c# string property to string?
 - Add `// [NullableEnum]` as comment to a optional enum field - Converts the corresponding optional proto enum to a C# nullable Enum
 - Add `// [NullableReferenceTypes]` as comment above a message definition - Enables full nullable reference type support for the entire message (see below)
@@ -284,6 +291,59 @@ public global::Porticle.Grpc.UnitTests.TestEnum? FooBar {
 }
 ```
 
+## `[DateTime]` / `[DateTimeOffset]` - Mapping google.protobuf.Timestamp
+
+Add `// [DateTime]` or `// [DateTimeOffset]` as comment to a `google.protobuf.Timestamp` field to get a `DateTime?` or `DateTimeOffset?` property in the generated C# code.
+Since message fields are always optional in proto3, the resulting property is always nullable.
+
+The conversion uses the original functions provided by Google.Protobuf: `Timestamp.FromDateTime`/`ToDateTime` and `Timestamp.FromDateTimeOffset`/`ToDateTimeOffset`.
+
+**Note:** `Timestamp.FromDateTime` only accepts `DateTime` values with `DateTimeKind.Utc`. Assigning a `DateTime` with kind `Local` or `Unspecified` throws an `ArgumentException`.
+`DateTimeOffset` values can have any offset - they are converted to UTC internally, so reading the property back always returns offset zero.
+
+```protobuf
+syntax = "proto3";
+
+import "google/protobuf/timestamp.proto";
+
+message Order {
+  // [DateTime] Creation time (UTC)
+  google.protobuf.Timestamp created_at = 1;
+
+  // [DateTimeOffset] Delivery time
+  google.protobuf.Timestamp delivered_at = 2;
+}
+```
+
+Will result in generated code like this:
+
+```csharp
+/// <summary>[DateTime] Creation time (UTC)</summary>
+public global::System.DateTime? CreatedAt {
+  get {
+      // return null when the underlying Timestamp is null
+      if (createdAt_ == null) return default;
+      // convert using the original Google.Protobuf function
+      return createdAt_.ToDateTime();
+  }
+  set {
+      // Timestamp.FromDateTime throws an ArgumentException when value.Kind is not Utc
+      createdAt_ = value == null ? null : global::Google.Protobuf.WellKnownTypes.Timestamp.FromDateTime(value.Value);
+  }
+}
+
+/// <summary>[DateTimeOffset] Delivery time</summary>
+public global::System.DateTimeOffset? DeliveredAt {
+  get {
+      if (deliveredAt_ == null) return default;
+      return deliveredAt_.ToDateTimeOffset();
+  }
+  set {
+      deliveredAt_ = value == null ? null : global::Google.Protobuf.WellKnownTypes.Timestamp.FromDateTimeOffset(value.Value);
+  }
+}
+```
+
 ## `[NullableReferenceTypes]` - Per-Message Nullable Reference Types
 
 Add `// [NullableReferenceTypes]` as a comment above a `message` definition to automatically apply nullable reference type annotations to **all** properties in that message:

Source/Porticle.Grpc.TypeMapper/PropertyVisitor.cs

@@ -121,6 +121,13 @@ public class PropertyVisitor(TaskLoggingHelper log, bool wrapAllNonNullableStrin
             return null;
         }
 
+        if (property.Type.ToString() == "global::Google.Protobuf.WellKnownTypes.Timestamp")
+        {
+            if (property.GetLeadingTrivia().ToFullString().Contains("[DateTimeOffset]")) return ConvertToTimestampProperty(property, true);
+
+            if (property.GetLeadingTrivia().ToFullString().Contains("[DateTime]")) return ConvertToTimestampProperty(property, false);
+        }
+
         if (property.GetLeadingTrivia().ToFullString().Contains("[NullableEnum]")) return ConvertOptionalToNullableEnum(property);
 
         if (nullableReferenceTypes) return ConvertToNullableMessageProperty(property);
@@ -484,6 +491,83 @@ public class PropertyVisitor(TaskLoggingHelper log, bool wrapAllNonNullableStrin
         return property;
     }
 
+    /// <summary>
+    ///     Converts a google.protobuf.Timestamp property to DateTime? or DateTimeOffset? using the
+    ///     conversion methods provided by Google.Protobuf (Timestamp.FromDateTime/ToDateTime and
+    ///     Timestamp.FromDateTimeOffset/ToDateTimeOffset). Timestamp.FromDateTime throws an
+    ///     ArgumentException when the assigned DateTime is not of kind Utc (e.g. Local).
+    /// </summary>
+    private PropertyDeclarationSyntax? ConvertToTimestampProperty(PropertyDeclarationSyntax property, bool asDateTimeOffset)
+    {
+        var targetType = asDateTimeOffset ? "global::System.DateTimeOffset" : "global::System.DateTime";
+        var fromMethod = asDateTimeOffset ? "FromDateTimeOffset" : "FromDateTime";
+        var toMethod = asDateTimeOffset ? "ToDateTimeOffset" : "ToDateTime";
+
+        var setter = property.GetSetter();
+
+        if (setter.Body == null)
+        {
+            log.LogError($"No setter found in property {property.Identifier}");
+            return null;
+        }
+
+        // Manipulate setter - message fields are always nullable, so null must be passed through
+        var assignment = GetAssignmentExpression(setter);
+
+        var newRightHandSide = SyntaxFactory.ParseExpression($"value == null ? null : global::Google.Protobuf.WellKnownTypes.Timestamp.{fromMethod}(value.Value)");
+
+        var newSetter = setter.ReplaceNode(assignment, assignment.WithRight(newRightHandSide));
+
+        property = property.ReplaceNode(setter, newSetter);
+
+        // Manipulate getter
+        var getter = property.GetGetter();
+
+        if (getter?.Body == null)
+        {
+            log.LogError($"No getter found in property {property.Identifier}");
+            return null;
+        }
+
+        var returnStatement = getter.Body?.Statements.OfType<ReturnStatementSyntax>().FirstOrDefault();
+
+        if (returnStatement?.Expression == null)
+        {
+            log.LogError($"Getter has no valid return statement in property {property.Identifier}");
+            return null;
+        }
+
+        var originalReturnExpression = returnStatement.Expression;
+
+        if (originalReturnExpression is not IdentifierNameSyntax identifierNameSyntax)
+        {
+            log.LogError($"Getter return statement should be a simple identifier in property {property.Identifier}");
+            return null;
+        }
+
+        ReplaceProps.Add(new PropertyToField(property.Identifier.ValueText, identifierNameSyntax.Identifier.ValueText));
+
+        var newReturnExpression = SyntaxFactory.InvocationExpression(SyntaxFactory.MemberAccessExpression(SyntaxKind.SimpleMemberAccessExpression, originalReturnExpression,
+            SyntaxFactory.IdentifierName(toMethod)));
+
+        var newReturnStatement = returnStatement.WithExpression(newReturnExpression).WithTrailingTrivia(SyntaxFactory.Space);
+
+        // Statement: if (field == null) return default;
+        var ifStatement = SyntaxFactory.IfStatement(
+                SyntaxFactory.BinaryExpression(SyntaxKind.EqualsExpression, originalReturnExpression, SyntaxFactory.LiteralExpression(SyntaxKind.NullLiteralExpression)),
+                SyntaxFactory.ReturnStatement(SyntaxFactory.LiteralExpression(SyntaxKind.DefaultLiteralExpression).WithLeadingTrivia(SyntaxFactory.Space)))
+            .WithTrailingTrivia(SyntaxFactory.Space);
+
+        var newGetterBody = SyntaxFactory.Block(ifStatement, newReturnStatement);
+
+        var newGetter = getter.WithBody(newGetterBody.WithTrailingTrivia(SyntaxFactory.CarriageReturnLineFeed));
+
+        property = property.ReplaceNode(getter, newGetter);
+
+        // Change the type of the property - always nullable because message fields can be null
+        return property.WithType(SyntaxFactory.ParseTypeName(targetType + "?").WithTrailingTrivia(SyntaxFactory.Space));
+    }
+
     private static AssignmentExpressionSyntax GetAssignmentExpression(AccessorDeclarationSyntax setter)
     {
         var assignment = setter.Body!.Statements.OfType<ExpressionStatementSyntax>().Select(s => s.Expression as AssignmentExpressionSyntax).FirstOrDefault();

Source/Porticle.Grpc.UnitTests/Test.proto

@@ -3,6 +3,7 @@
 option csharp_namespace = "Porticle.Grpc.UnitTests";
 
 import "google/protobuf/wrappers.proto";
+import "google/protobuf/timestamp.proto";
 
 
 message TestMessage {
@@ -13,6 +14,8 @@ message TestMessage {
   string single_decimal = 8;
   google.protobuf.StringValue single_nullable_decimal = 9;
   repeated string list_of_decimal = 10;
+  google.protobuf.Timestamp single_date_time = 11;
+  google.protobuf.Timestamp single_date_time_offset = 12;
 }
 
 message TestMessageMapped {
@@ -41,6 +44,12 @@ message TestMessageMapped {
 
   // [Decimal]
   repeated string list_of_decimal = 10;
+
+  // [DateTime]
+  google.protobuf.Timestamp single_date_time = 11;
+
+  // [DateTimeOffset]
+  google.protobuf.Timestamp single_date_time_offset = 12;
 }
 
 //////////////////////////////////////////////

Source/Porticle.Grpc.UnitTests/Tests.cs

@@ -1,6 +1,7 @@
 using System.Globalization;
 using System.Reflection;
 using Google.Protobuf;
+using Google.Protobuf.WellKnownTypes;
 
 namespace Porticle.Grpc.UnitTests;
 
@@ -16,6 +17,9 @@ public sealed class Tests
     private static readonly decimal Decimal1 = 12345.6789m;
     private static readonly decimal Decimal2 = -99999.00001m;
 
+    private static readonly DateTime UtcDateTime1 = new DateTime(2024, 5, 17, 13, 45, 30, 123, DateTimeKind.Utc).AddTicks(4567);
+    private static readonly DateTimeOffset DateTimeOffset1 = new DateTimeOffset(2024, 5, 17, 13, 45, 30, 123, TimeSpan.FromHours(2)).AddTicks(4567);
+
     [TestMethod]
     public void TestDecimalWithNull()
     {
@@ -106,6 +110,72 @@ public void TestRepeatedDecimalUnmappedToMapped()
         Assert.AreEqual(0m, deserializedMessage.ListOfDecimal[2]);
     }
 
+    [TestMethod]
+    public void TestDateTimeRoundtrip()
+    {
+        var message = new TestMessageMapped { SingleDateTime = UtcDateTime1, SingleDateTimeOffset = DateTimeOffset1 };
+
+        var byteArray = message.ToByteArray();
+
+        var deserializedMessage = TestMessageMapped.Parser.ParseFrom(byteArray);
+
+        Assert.AreEqual(UtcDateTime1, deserializedMessage.SingleDateTime);
+        Assert.AreEqual(DateTimeKind.Utc, deserializedMessage.SingleDateTime!.Value.Kind);
+
+        // DateTimeOffset equality compares the instant - the original offset is not preserved, Timestamp always returns UTC (offset zero)
+        Assert.AreEqual(DateTimeOffset1, deserializedMessage.SingleDateTimeOffset);
+        Assert.AreEqual(TimeSpan.Zero, deserializedMessage.SingleDateTimeOffset!.Value.Offset);
+    }
+
+    [TestMethod]
+    public void TestDateTimeWithNull()
+    {
+        var message = new TestMessageMapped { SingleDateTime = null, SingleDateTimeOffset = null };
+
+        var byteArray = message.ToByteArray();
+
+        var deserializedMessage = TestMessageMapped.Parser.ParseFrom(byteArray);
+
+        Assert.IsNull(deserializedMessage.SingleDateTime);
+        Assert.IsNull(deserializedMessage.SingleDateTimeOffset);
+    }
+
+    [TestMethod]
+    public void TestDateTimeLocalThrows()
+    {
+        var message = new TestMessageMapped();
+
+        // Timestamp.FromDateTime only accepts DateTimeKind.Utc
+        Assert.ThrowsException<ArgumentException>(() => message.SingleDateTime = DateTime.SpecifyKind(UtcDateTime1, DateTimeKind.Local));
+        Assert.ThrowsException<ArgumentException>(() => message.SingleDateTime = DateTime.SpecifyKind(UtcDateTime1, DateTimeKind.Unspecified));
+    }
+
+    [TestMethod]
+    public void TestDateTimeUnmappedToMapped()
+    {
+        var message = new TestMessage { SingleDateTime = Timestamp.FromDateTime(UtcDateTime1), SingleDateTimeOffset = Timestamp.FromDateTimeOffset(DateTimeOffset1) };
+
+        var byteArray = message.ToByteArray();
+
+        var deserializedMessage = TestMessageMapped.Parser.ParseFrom(byteArray);
+
+        Assert.AreEqual(UtcDateTime1, deserializedMessage.SingleDateTime);
+        Assert.AreEqual(DateTimeOffset1, deserializedMessage.SingleDateTimeOffset);
+    }
+
+    [TestMethod]
+    public void TestDateTimeMappedToUnmapped()
+    {
+        var message = new TestMessageMapped { SingleDateTime = UtcDateTime1, SingleDateTimeOffset = DateTimeOffset1 };
+
+        var byteArray = message.ToByteArray();
+
+        var deserializedMessage = TestMessage.Parser.ParseFrom(byteArray);
+
+        Assert.AreEqual(Timestamp.FromDateTime(UtcDateTime1), deserializedMessage.SingleDateTime);
+        Assert.AreEqual(Timestamp.FromDateTimeOffset(DateTimeOffset1), deserializedMessage.SingleDateTimeOffset);
+    }
+
     [TestMethod]
     public void TestWithNull()
     {