Add JsonDateTimeFormatAttribute to eliminate SYSLIB1223 warnings with source generators

Co-authored-by: ScarletKuro <19953225+ScarletKuro@users.noreply.github.com>

Author: Copilot

AGENT.md

@@ -8,7 +8,7 @@ This document provides guidance for AI agents and developers working on the **Sc
 
 ### Key Features
 
-- Custom date/time format attributes (`JsonDateTimeConverterAttribute`)
+- Custom date/time format attributes (`JsonDateTimeConverterAttribute` for reflection, `JsonDateTimeFormatAttribute` for source generators)
 - Source generator-compatible format converters (`JsonDateTimeFormatConverter<T>`)
 - .NET 9+ contract customization resolver (`DateTimeConverterResolver`)
 - Support for `DateTime`, `DateTimeOffset`, and nullable variants
@@ -35,17 +35,20 @@ Scarlet.System.Text.Json.DateTimeConverter/
 │   │   ├── DateTimeConverterFactoryHelper.cs
 │   │   ├── DateTimeConverterResolver.cs  # .NET 9+ contract customization
 │   │   ├── IJsonDateTimeFormat.cs
-│   │   ├── JsonDateTimeConverterAttribute.cs
+│   │   ├── JsonDateTimeConverterAttribute.cs  # For reflection-based serialization
+│   │   ├── JsonDateTimeFormatAttribute.cs     # For source generators (no warnings)
 │   │   ├── JsonDateTimeFormatConverter.cs
 │   │   └── Scarlet.System.Text.Json.DateTimeConverter.csproj
 │   └── Scarlet.System.Text.Json.DateTimeConverter.Tests/
 │       ├── JsonDateTimeConverterAttributeTests.cs
 │       ├── JsonDateTimeFormatConverterTests.cs
 │       ├── Model/                # Test models
 │       │   ├── ReflectionBasedModel.cs
-│       │   ├── SourceGeneratorModel.cs
-│       │   ├── SourceGeneratorWithResolverModel.cs
-│       │   └── TestModelSourceGeneratorJsonSerializerContext.cs
+│       │   ├── SourceGeneratorWithConverterModel.cs
+│       │   ├── SourceGeneratorWithResolverAttributeModel.cs  # Uses JsonDateTimeConverter (has warnings)
+│       │   ├── SourceGeneratorWithResolverFormatModel.cs     # Uses JsonDateTimeFormat (no warnings)
+│       │   ├── ConverterModelJsonSerializerContext.cs
+│       │   └── ResolverModelJsonSerializerContext.cs
 │       └── Scarlet.System.Text.Json.DateTimeConverter.Tests.csproj
 └── .github/
     └── workflows/                # CI/CD workflows
@@ -201,7 +204,16 @@ public DateTime Date { get; set; }
 ```
 - Derives from `JsonConverterAttribute`
 - Works with reflection-based serialization
-- .NET 9+: Works with source generators via `DateTimeConverterResolver`
+- .NET 9+: Works with source generators via `DateTimeConverterResolver` but produces SYSLIB1223 warnings
+
+**`JsonDateTimeFormatAttribute` (.NET 9+)**
+```csharp
+[JsonDateTimeFormat("yyyy-MM-dd")]
+public DateTime Date { get; set; }
+```
+- Derives from `Attribute` (not `JsonConverterAttribute`)
+- Designed for use with .NET 9+ source generators and `DateTimeConverterResolver`
+- **No SYSLIB1223 warnings** (recommended over `JsonDateTimeConverterAttribute` for source generators)
 
 **`JsonDateTimeFormatConverter<T>`**
 ```csharp
@@ -221,6 +233,7 @@ var options = new JsonSerializerOptions
 ```
 - Implements `IJsonTypeInfoResolver` and extends `JsonSerializerContext`
 - Uses `JsonPropertyInfo.AttributeProvider` (populated by source generators in .NET 9+) to read attributes
+- Supports both `JsonDateTimeFormatAttribute` (no warnings) and `JsonDateTimeConverterAttribute` (backward compatibility)
 - Enables attribute syntax with source generators
 
 #### 3. Factory Helper
@@ -248,11 +261,12 @@ public class DateTimeConverterResolver : JsonSerializerContext, IJsonTypeInfoRes
 
 ### Testing Strategy
 
-Tests verify three distinct usage patterns:
+Tests verify four distinct usage patterns:
 
 1. **Reflection-based** - Uses `JsonDateTimeConverterAttribute` with default `JsonSerializer`
 2. **Source generator with converter** - Uses `JsonDateTimeFormatConverter<T>` with `JsonSerializerContext`
-3. **Source generator with resolver** - Uses `JsonDateTimeConverterAttribute` + `DateTimeConverterResolver` (.NET 9+)
+3. **Source generator with resolver (new attribute)** - Uses `JsonDateTimeFormatAttribute` + `DateTimeConverterResolver` (.NET 9+, no warnings)
+4. **Source generator with resolver (old attribute)** - Uses `JsonDateTimeConverterAttribute` + `DateTimeConverterResolver` (.NET 9+, with SYSLIB1223 warnings for backward compatibility)
 
 Each pattern is tested with:
 - Individual types (`DateTime`, `DateTime?`, `DateTimeOffset`, `DateTimeOffset?`)

README.md

@@ -24,11 +24,12 @@ A flexible and powerful library for customizing `DateTime` and `DateTimeOffset`
 
 ## Overview
 
-This package provides three ways to specify custom date formats for `DateTime`, `DateTimeOffset`, and their nullable counterparts when serializing and deserializing JSON using `System.Text.Json`:
+This package provides four ways to specify custom date formats for `DateTime`, `DateTimeOffset`, and their nullable counterparts when serializing and deserializing JSON using `System.Text.Json`:
 
-1. **`JsonDateTimeConverterAttribute`** - Simple attribute-based approach (reflection only, or .NET 9+ with resolver)
-2. **`JsonDateTimeFormatConverter<T>`** - Type-safe converter for source generators
-3. **`DateTimeConverterResolver`** - Contract customization for .NET 9+ source generators
+1. **`JsonDateTimeConverterAttribute`** - Simple attribute-based approach (reflection only, or .NET 9+ with resolver but produces warnings)
+2. **`JsonDateTimeFormatAttribute`** - Clean attribute for source generators with .NET 9+ resolver (no warnings)
+3. **`JsonDateTimeFormatConverter<T>`** - Type-safe converter for source generators (all .NET versions)
+4. **`DateTimeConverterResolver`** - Contract customization for .NET 9+ source generators
 
 ## Installation
 
@@ -61,6 +62,26 @@ var json = JsonSerializer.Serialize(new MyModel { Date = DateTime.Now });
 // Output: {"Date":"2026-01-15"}
 ```
 
+**Best for source generators** (.NET 9+, no warnings):
+
+```csharp
+public class MyModel
+{
+    [JsonDateTimeFormat("yyyy-MM-dd")]
+    public DateTime Date { get; set; }
+}
+
+[JsonSerializable(typeof(MyModel))]
+public partial class MyJsonContext : JsonSerializerContext { }
+
+var options = new JsonSerializerOptions
+{
+    TypeInfoResolver = new DateTimeConverterResolver(MyJsonContext.Default)
+};
+var json = JsonSerializer.Serialize(new MyModel { Date = DateTime.Now }, options);
+// Output: {"Date":"2026-01-15"}
+```
+
 ## Usage Scenarios
 
 ### Reflection-Based Serialization (.NET 6+)
@@ -181,24 +202,28 @@ var deserializedOrder = (Order?)JsonSerializer.Deserialize(json, typeof(Order),
 
 ---
 
-### Source Generator with Attribute and Resolver (.NET 9+)
+### Source Generator with Resolver (.NET 9+)
 
 **.NET 9+** populates `JsonPropertyInfo.AttributeProvider` in source generators, enabling attribute-based syntax with `DateTimeConverterResolver`.
 
+#### Option A: JsonDateTimeFormatAttribute (Recommended - No Warnings)
+
+Use `JsonDateTimeFormatAttribute` for the cleanest experience without SYSLIB1223 warnings:
+
 ```csharp
 using Scarlet.System.Text.Json.DateTimeConverter;
 using System.Text.Json;
 using System.Text.Json.Serialization;
 
 public class Order
 {
-    [JsonDateTimeConverter("yyyy-MM-dd")]
+    [JsonDateTimeFormat("yyyy-MM-dd")]
     public DateTime OrderDate { get; set; }
 
-    [JsonDateTimeConverter("yyyy-MM-ddTHH:mm:ss")]
+    [JsonDateTimeFormat("yyyy-MM-ddTHH:mm:ss")]
     public DateTime? ProcessedDate { get; set; }
 
-    [JsonDateTimeConverter("yyyy-MM-ddTHH:mm:ss.fffZ")]
+    [JsonDateTimeFormat("yyyy-MM-ddTHH:mm:ss.fffZ")]
     public DateTimeOffset ShippedAt { get; set; }
 }
 
@@ -225,12 +250,35 @@ var deserializedOrder = (Order?)JsonSerializer.Deserialize(json, typeof(Order),
 **✅ Pros:**
 - Clean attribute syntax with source generators
 - AOT-friendly
+- **No SYSLIB1223 warnings**
 - Best of both worlds: readability + performance
 
 **❌ Cons:**
 - **Requires .NET 9+**
 - Slightly more setup (need to wrap context with resolver)
 
+#### Option B: JsonDateTimeConverterAttribute (Backward Compatible - Has Warnings)
+
+You can also use `JsonDateTimeConverterAttribute` (for backward compatibility), but it will produce SYSLIB1223 warnings:
+
+```csharp
+public class Order
+{
+    [JsonDateTimeConverter("yyyy-MM-dd")]  // ⚠️ Produces SYSLIB1223 warning
+    public DateTime OrderDate { get; set; }
+}
+```
+
+The resolver still works, but the source generator will emit warnings because `JsonDateTimeConverterAttribute` derives from `JsonConverterAttribute`.
+
+**✅ Pros:**
+- Works with existing code using `JsonDateTimeConverterAttribute`
+- Backward compatible
+
+**❌ Cons:**
+- Produces SYSLIB1223 warnings during build
+- May confuse users about the warnings
+
 ---
 
 ## Available Components
@@ -244,7 +292,20 @@ A `JsonConverterAttribute`-derived attribute for specifying date formats directl
 public DateTime Date { get; set; }
 ```
 
-**When to use:** Reflection-based serialization, or .NET 9+ with `DateTimeConverterResolver`.
+**When to use:** Reflection-based serialization. Can also be used with .NET 9+ `DateTimeConverterResolver` but produces SYSLIB1223 warnings.
+
+---
+
+### `JsonDateTimeFormatAttribute` (.NET 9+)
+
+A simple `Attribute`-derived attribute for specifying date formats with source generators (no warnings).
+
+```csharp
+[JsonDateTimeFormat("yyyy-MM-dd")]
+public DateTime Date { get; set; }
+```
+
+**When to use:** .NET 9+ source generators with `DateTimeConverterResolver` (recommended, no warnings).
 
 ---
 
@@ -268,14 +329,14 @@ public DateTime Date { get; set; }
 
 ### `DateTimeConverterResolver` (.NET 9+)
 
-A `JsonSerializerContext` and `IJsonTypeInfoResolver` that enables `JsonDateTimeConverterAttribute` to work with source generators by using contract customization.
+A `JsonSerializerContext` and `IJsonTypeInfoResolver` that enables attribute-based date formatting with source generators by using contract customization.
 
 ```csharp
 var resolver = new DateTimeConverterResolver(MyJsonContext.Default);
 var options = new JsonSerializerOptions { TypeInfoResolver = resolver };
 ```
 
-**When to use:** .NET 9+ source generators with attribute syntax.
+**When to use:** .NET 9+ source generators with `JsonDateTimeFormatAttribute` or `JsonDateTimeConverterAttribute`.
 
 ---
 
@@ -285,10 +346,11 @@ var options = new JsonSerializerOptions { TypeInfoResolver = resolver };
 |----------|---------------------|
 | Reflection-based, any .NET version | `JsonDateTimeConverterAttribute` |
 | Source generator, .NET 6-8 | `JsonDateTimeFormatConverter<T>` |
-| Source generator, .NET 9+ | `JsonDateTimeConverterAttribute` + `DateTimeConverterResolver` |
+| Source generator, .NET 9+ (no warnings) | `JsonDateTimeFormatAttribute` + `DateTimeConverterResolver` |
+| Source generator, .NET 9+ (backward compat) | `JsonDateTimeConverterAttribute` + `DateTimeConverterResolver` (⚠️ warnings) |
 | Need reusable formats across many properties | `JsonDateTimeFormatConverter<T>` (define format class once) |
 | Prototyping/simple projects | `JsonDateTimeConverterAttribute` (simplest) |
-| AOT compilation | `JsonDateTimeFormatConverter<T>` or .NET 9+ resolver |
+| AOT compilation | `JsonDateTimeFormatConverter<T>` or .NET 9+ resolver with attributes |
 
 ---
 
@@ -300,7 +362,29 @@ var options = new JsonSerializerOptions { TypeInfoResolver = resolver };
 
 > "Attributes deriving from JsonConverterAttribute are not supported by the source generator."
 
-**Solution:** Use `JsonDateTimeFormatConverter<T>` instead, or upgrade to .NET 9+.
+**Solution:** Use `JsonDateTimeFormatConverter<T>` instead, or upgrade to .NET 9+ and use `JsonDateTimeFormatAttribute` with `DateTimeConverterResolver` (no warnings).
+
+---
+
+### SYSLIB1223 Warning with JsonDateTimeConverterAttribute (.NET 9+ Source Generators)
+
+When using `JsonDateTimeConverterAttribute` with source generators in .NET 9+, you'll get SYSLIB1223 warnings:
+
+> "Attributes deriving from JsonConverterAttribute are not supported by the source generator."
+
+This happens because `JsonDateTimeConverterAttribute` derives from `JsonConverterAttribute`. The code still works with `DateTimeConverterResolver`, but the warnings may be confusing.
+
+**Solution:** Use `JsonDateTimeFormatAttribute` instead, which derives only from `Attribute` and produces no warnings:
+
+```csharp
+// ❌ Produces warnings (but still works)
+[JsonDateTimeConverter("yyyy-MM-dd")]
+public DateTime Date { get; set; }
+
+// ✅ No warnings
+[JsonDateTimeFormat("yyyy-MM-dd")]
+public DateTime Date { get; set; }
+```
 
 ---