API Reference ResultJsonConverter - ulfbou/Zentient.Results GitHub Wiki
-
Namespace:
Zentient.Results
-
Type:
JsonConverterFactory
-
Summary: A custom
System.Text.Json.JsonConverterFactory
that enables seamless and robust JSON serialization and deserialization ofResult
andResult<T>
types. It ensures that these result objects are correctly represented in JSON payloads, exposing relevant properties while handling internal state.
The Result
and Result<T>
structs have internal constructor logic and private fields (_errors
, _messages
) that standard System.Text.Json
serialization might not handle optimally by default. ResultJsonConverter
was created to provide explicit control over this process. Its design ensures:
-
Consistent Output: Predictable JSON structure for
Result
types, regardless of success or failure. -
Completeness: All key public properties (
IsSuccess
,IsFailure
,Status
,Messages
,Errors
,Value
) are correctly serialized. -
Robust Deserialization: Handles various incoming JSON structures gracefully, providing fallbacks and error reporting if critical data (like
Status
) is missing. - Type Safety: Dynamically creates appropriate generic or non-generic converters based on the type being serialized/deserialized.
-
Inherits from:
System.Text.Json.Serialization.JsonConverterFactory
-
Signature:
public override bool CanConvert(Type typeToConvert)
- Summary: Determines whether this converter can convert the specified object type.
-
Parameters:
-
typeToConvert
(Type
): The type of the object to check.
-
-
Return Value: (
bool
):true
if the converter can handle thetypeToConvert
(i.e., it'sIResult
,Result
,IResult<T>
, orResult<T>
); otherwise,false
. -
Behavior: This method is used by
System.Text.Json
to identify ifResultJsonConverter
is suitable for a given type during serialization or deserialization. It supports both the interface types (IResult
,IResult<T>
) and their concrete struct implementations (Result
,Result<T>
).
-
Signature:
public override JsonConverter? CreateConverter(Type typeToConvert, JsonSerializerOptions options)
-
Summary: Creates a
JsonConverter
for the specified type. -
Parameters:
-
typeToConvert
(Type
): The type of the object to convert. -
options
(JsonSerializerOptions
): The serializer options being used.
-
-
Return Value: (
JsonConverter?
): A newJsonConverter
instance appropriate for thetypeToConvert
, ornull
if the type cannot be converted. -
Behavior: This factory method inspects
typeToConvert
. If it's a genericResult<T>
orIResult<T>
, it dynamically creates and returns an instance ofResultGenericJsonConverter<TValue>
. If it's a non-genericResult
orIResult
, it returns an instance ofResultNonGenericJsonConverter
. This ensures the correct, type-specific logic is applied.
The ResultJsonConverter
factory manages two internal, private converter implementations:
-
Role: Handles serialization and deserialization for
Result
(non-generic) andIResult
. -
Serialization (
Write
method): Explicitly writesIsSuccess
,IsFailure
,Status
,Messages
(if not empty), andErrors
(if not empty) to the JSON output. -
Deserialization (
Read
method): Reads the JSON object, attempting to parsestatus
,messages
, anderrors
. Ifstatus
cannot be determined, it defaults toResultStatuses.Error
and generates aDeserializationError
ErrorInfo
. It then constructs a newResult
instance using its internal constructor.
-
Role: Handles serialization and deserialization for
Result<TValue>
andIResult<TValue>
. -
Serialization (
Write
method): Explicitly writesIsSuccess
,IsFailure
,Status
,Messages
(if not empty),Errors
(if not empty), and crucially, theValue
property to the JSON output. -
Deserialization (
Read
method): Reads the JSON object, attempting to parsevalue
,status
,messages
, anderrors
. Similar to the non-generic converter, it handles missingstatus
by defaulting toResultStatuses.Error
and adding aDeserializationError
ErrorInfo
. It then constructs a newResult<TValue>
instance using its internal constructor.
-
Automatic Registration: To use this converter, you typically register it with your
JsonSerializerOptions
:var options = new JsonSerializerOptions { WriteIndented = true, PropertyNamingPolicy = JsonNamingPolicy.CamelCase, }; options.Converters.Add(new ResultJsonConverter()); // Then use JsonSerializer.Serialize/Deserialize with these options
-
Circular Reference Prevention: The internal converters create new
JsonSerializerOptions
instances that remove themselves from the converters list (_options.Converters.Remove(this)
). This is a standard pattern to prevent infinite recursion when a converter needs to call the default serializer for its own properties (e.g., when serializingErrorInfo
objects within theErrors
collection). -
RFC 9457 Alignment: The enhanced serialization logic, particularly for
ErrorInfo
'sDetail
andExtensions
, aids in generating JSON payloads that are more compliant with RFC 9457 (Problem Details for HTTP APIs) whenResult
types are used for API responses.
Last Updated: 2025-06-07 Version: 0.3.0