Skip to content
Merged
27 changes: 27 additions & 0 deletions site/docs/serialization/converters.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,33 @@ public sealed class TemperatureConverter : YamlConverter<Temperature>
An exception thrown from `Read`, such as the `FormatException` of `double.Parse` above, reaches the caller of
`YamlSerializer.Deserialize` as a [`YamlException`](xref:SharpYaml.YamlException) that wraps it. See [Errors and diagnostics](error-handling.md#exceptions-thrown-by-converters).

### Rejecting a value

A converter that finds a value invalid should throw [`reader.CreateException(message)`](xref:SharpYaml.Serialization.YamlReader.CreateException(System.String))
before it consumes any of the value. The exception carries the source name and the location of the current token, and
because nothing was consumed the serializer can skip the value and report it when
[`InvalidValueHandling`](error-handling.md#invalid-values) is `FailAtEnd` or `Skip`. An exception thrown after `reader.Read()`,
or an exception of another type, always ends the call.

```csharp
public override Temperature Read(YamlReader reader)
{
if (reader.TokenType != YamlTokenType.Scalar)
{
throw YamlThrowHelper.ThrowExpectedScalar(reader);
}

var text = reader.ScalarValue!;
if (text.Length < 2 || !double.TryParse(text[..^1], NumberStyles.Float, CultureInfo.InvariantCulture, out var value))
{
throw reader.CreateException($"'{text}' is not a temperature such as '21.5C'.");
}

reader.Read();
return new Temperature { Value = value, Unit = text[^1..] };
}
```

## Converter factories

For open generic types or families of types, extend [`YamlConverterFactory`](xref:SharpYaml.Serialization.YamlConverterFactory):
Expand Down
108 changes: 108 additions & 0 deletions site/docs/serialization/error-handling.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ When possible, exceptions include:
- a span (start/end location)

These are available through [`YamlException.SourceName`](xref:SharpYaml.YamlException.SourceName), [`YamlException.Start`](xref:SharpYaml.YamlException.Start), and [`YamlException.End`](xref:SharpYaml.YamlException.End).
`Message` carries them as a prefix; [`YamlException.Reason`](xref:SharpYaml.YamlException.Reason) is the message without it, for reporting the
location in your own format.

```csharp
var options = new YamlSerializerOptions
Expand Down Expand Up @@ -45,6 +47,112 @@ Two exceptions propagate unchanged because they are not about the content: `NotS
such as a type without a converter or a context [generated without readers](../source-generation.md#keeping-the-generated-code-small),
and `IOException`, for a failure of the source `TextReader` or `Stream`.

By default the first rejected value ends the call. To collect every rejected value in one pass, or to keep the rest of the
document, see [Invalid values](#invalid-values).

## Invalid values

A converter that rejects a value, for example `abc` for an `int` member, throws a `YamlException` and the call fails at that
value. [`InvalidValueHandling`](xref:SharpYaml.YamlSerializerOptions.InvalidValueHandling) selects what happens instead:

| Mode | Behavior |
| --- | --- |
| [`FailFast`](xref:SharpYaml.YamlInvalidValueHandling.FailFast) (default) | The first invalid value throws, as before. |
| [`FailAtEnd`](xref:SharpYaml.YamlInvalidValueHandling.FailAtEnd) | Every recoverable value is skipped and the read continues. At the end the call throws one [`YamlInvalidValuesException`](xref:SharpYaml.YamlInvalidValuesException) listing all of them. |
| [`Skip`](xref:SharpYaml.YamlInvalidValueHandling.Skip) | Every recoverable value is skipped and the call succeeds. |

A skipped member keeps the value its initializer gave it, or its existing instance under
[`JsonObjectCreationHandling.Populate`](xref:System.Text.Json.Serialization.JsonObjectCreationHandling.Populate). A skipped constructor
parameter keeps its default value. The key still counts as present, so a required member whose value was skipped does not cause a
missing-member error, and a second occurrence of the key is still a duplicate.

```csharp
var options = new YamlSerializerOptions
{
SourceName = path,
InvalidValueHandling = YamlInvalidValueHandling.FailAtEnd,
};

try
{
return YamlSerializer.Deserialize<MyConfig>(yaml, options);
}
catch (YamlInvalidValuesException e)
{
foreach (var value in e.InvalidValues)
{
logger.LogError("{File}({Line},{Column}): {Path}: {Message}",
value.SourceName, value.ValueStart.Line + 1, value.ValueStart.Column + 1, value.Path, value.Message);
}

throw;
}
```

The exception is a `YamlException` located at the first skipped value, so `catch (YamlException)` and `TryDeserialize` keep working:
`TryDeserialize` returns `false` under `FailAtEnd` and `true` under `Skip`. Its message lists every value with its path.

### Observing skipped values

Under `FailAtEnd` and `Skip`, two delegates observe the skipped values, shaped like the delegates for
[unknown members](extension-data.md#handling-unknown-members-globally):

- [`InvalidValueCallback`](xref:SharpYaml.YamlSerializerOptions.InvalidValueCallback) runs once per skipped value, in document order.
- [`InvalidValuesFinalizer`](xref:SharpYaml.YamlSerializerOptions.InvalidValuesFinalizer) runs once at the end of the call with every
skipped value, only when there is at least one. Under `FailAtEnd` it runs before the exception is thrown and can throw to replace it.

Neither runs under `FailFast`. Both receive [`YamlInvalidValue`](xref:SharpYaml.Serialization.YamlInvalidValue) instances:

| Property | Description |
| --- | --- |
| `SourceName` | `YamlSerializerOptions.SourceName` (for example the file path) |
| `Path` | Document path, for example `$.servers[2].port` (`$['a.b']` for keys that are not simple identifiers) |
| `KeyStart`, `ValueStart` | Line, column and index of the key and of its value |
| `Name`, `TargetType` | The key and the CLR type of the member or constructor parameter the value was meant for |
| `DeclaringType`, `Instance` | The CLR type and the object being populated (`null` for constructor-bound types) |
| `Value` | The rejected value as a `YamlElement`; `null` unless a callback or finalizer is set |
| `Message`, `Exception` | Why the value was rejected, without a location, and the `YamlException` the converter threw, whose `Start` and `End` locate the value |

```csharp
var options = new YamlSerializerOptions
{
SourceName = path,
InvalidValueHandling = YamlInvalidValueHandling.Skip,
InvalidValueCallback = v => logger.LogWarning(
"{File}({Line},{Column}): {Path}: {Message} The default is used.",
v.SourceName, v.ValueStart.Line + 1, v.ValueStart.Column + 1, v.Path, v.Message),
};
```

### What is recoverable

A value is skipped when a `YamlException` is thrown while the reader is still on the first token of the value, that is before
any of it was consumed. This covers the built-in scalar converters, a shape mismatch such as a mapping where a scalar is
expected, and a custom converter that throws [`reader.CreateException(...)`](xref:SharpYaml.Serialization.YamlReader.CreateException(System.String))
before reading, see [Converters](converters.md#rejecting-a-value). Everything else stays fatal, in every mode:

- Other exception types. A `FormatException` from a converter is still wrapped in a `YamlException` and ends the call, so a
converter bug is never reported as invalid content.
- An exception thrown after part of the value was consumed, for example by a nested object whose own member was fine.
- Parser errors (`SyntaxErrorException`, `SemanticErrorException`).
- Values that are not member values or constructor arguments: collection elements, dictionary values, the root value and
extension data.
- Errors that no value read throws: `UnmappedMemberHandling = Disallow`, `DuplicateKeyHandling = Error`, a missing required
member and polymorphic discriminator errors.

When such an error ends a read that already skipped values, `FailAtEnd` throws `YamlInvalidValuesException` with the skipped
values and the error as its `InnerException`, while `Skip` lets the error propagate unchanged. The finalizer does not run in
either case, because the read did not complete.

### Notes

- Options stay immutable and can be shared: the state of a deserialization lives in the reader, not in the options.
- Under `FailFast` there is no extra work. The other modes track the document path only when a report is consumed.
- Source-generated contexts are supported through the same options (`context.CreateOptions(o => o with { ... })`).
- Inside polymorphic nodes the `Path` is complete, but `KeyStart`, `ValueStart` and the exception marks are relative to the buffered node.
- Member values and constructor arguments reached through a merge key (`<<`) are recovered like any other.
- Recovery applies to deserialization only. A converter that cannot write a value has a bug, not bad input.

## Required members

If a required member is missing (for example [`YamlRequiredAttribute`](xref:SharpYaml.Serialization.YamlRequiredAttribute) or [`JsonRequiredAttribute`](xref:System.Text.Json.Serialization.JsonRequiredAttribute)), deserialization throws [`YamlException`](xref:SharpYaml.YamlException).
Expand Down
3 changes: 3 additions & 0 deletions site/docs/serialization/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,9 @@ is not a lossless alternative: it currently materializes aliases as copies.
| [`SourceName`](xref:SharpYaml.YamlSerializerOptions.SourceName) | `null` | Used for error messages (file/path) when throwing [`YamlException`](xref:SharpYaml.YamlException). |
| [`UnmappedMemberCallback`](xref:SharpYaml.YamlSerializerOptions.UnmappedMemberCallback) | `null` | Invoked for every unknown key while reading. See [Handling unknown members globally](extension-data.md#handling-unknown-members-globally). |
| [`UnmappedMembersFinalizer`](xref:SharpYaml.YamlSerializerOptions.UnmappedMembersFinalizer) | `null` | Invoked once per deserialization call with all unknown keys; may throw to fail the call. |
| [`InvalidValueHandling`](xref:SharpYaml.YamlSerializerOptions.InvalidValueHandling) | [`YamlInvalidValueHandling.FailFast`](xref:SharpYaml.YamlInvalidValueHandling.FailFast) | Controls whether a value a converter rejects fails the call at once, is skipped and fails the call at the end, or is skipped. See [Invalid values](error-handling.md#invalid-values). |
| [`InvalidValueCallback`](xref:SharpYaml.YamlSerializerOptions.InvalidValueCallback) | `null` | Invoked for every skipped value while reading under `FailAtEnd` or `Skip`. |
| [`InvalidValuesFinalizer`](xref:SharpYaml.YamlSerializerOptions.InvalidValuesFinalizer) | `null` | Invoked once per deserialization call with all skipped values; may throw to replace the `FailAtEnd` exception. |

### Block sequence item style

Expand Down
28 changes: 27 additions & 1 deletion src/SharpYaml.SourceGenerator/YamlSerializerContextGenerator.cs
Original file line number Diff line number Diff line change
Expand Up @@ -2471,6 +2471,11 @@ preferredObjectCreationHandling is null ||
builder.AppendLine(" void ReadMember(string key)");
builder.AppendLine(" {");
builder.AppendLine(" var matched = false;");
builder.AppendLine(" var valueTokenType = reader.TokenType;");
builder.AppendLine(" var valueStart = reader.Start;");
builder.AppendLine(" global::System.Type? valueType = null;");
builder.AppendLine(" try");
builder.AppendLine(" {");
foreach (var member in readCandidates)
{
builder.Append(" if (!matched && global::System.String.Equals(key, ").Append(member.SerializedNameExpressionForRead)
Expand All @@ -2490,6 +2495,7 @@ preferredObjectCreationHandling is null ||
builder.Append(" __required").Append(index).Append("_").Append(member.Symbol.Name).AppendLine(" = true;");
}

builder.Append(" valueType = typeof(").Append(member.Type.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat)).AppendLine(");");
EmitReadObjectMemberValueWithObjectCreationHandling(
builder,
member,
Expand All @@ -2501,6 +2507,13 @@ preferredObjectCreationHandling is null ||
builder.AppendLine(" }");
}

builder.AppendLine(" }");
builder.AppendLine(" catch (global::SharpYaml.YamlException exception) when (valueType is not null && CanRecoverInvalidValue(reader, exception, valueTokenType, valueStart))");
builder.AppendLine(" {");
builder.Append(" RecoverInvalidValue(reader, exception, typeof(").Append(typeName).AppendLine("), instance, key, valueType);");
builder.AppendLine(" return;");
builder.AppendLine(" }");

builder.AppendLine(" if (!matched)");
builder.AppendLine(" {");
if (extensionData is not null)
Expand Down Expand Up @@ -2805,6 +2818,11 @@ private static void EmitReadObjectCoreWithConstructor(
builder.AppendLine(" void ReadMember(string key)");
builder.AppendLine(" {");
builder.AppendLine(" var matched = false;");
builder.AppendLine(" var valueTokenType = reader.TokenType;");
builder.AppendLine(" var valueStart = reader.Start;");
builder.AppendLine(" global::System.Type? valueType = null;");
builder.AppendLine(" try");
builder.AppendLine(" {");

// Read-ignored members are matched before constructor parameters so they are skipped, not captured as extension data.
for (var i = 0; i < readIgnoredMembers.Length; i++)
Expand Down Expand Up @@ -2850,6 +2868,7 @@ private static void EmitReadObjectCoreWithConstructor(
}

var tmpVar = $"__ctor{index}_tmp{i}";
builder.Append(" valueType = typeof(").Append(parameter.Type.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat)).AppendLine(");");
EmitReadKnownType(builder, sourceGenerationOptions, parameter.Type, indexByType, tmpVar, indent: " ");
builder.Append(" ").Append(parameterValueVarNames[i]).Append(" = ").Append(tmpVar).AppendLine(";");
builder.Append(" ").Append(parameterSeenVarNames[i]).AppendLine(" = true;");
Expand Down Expand Up @@ -2889,6 +2908,7 @@ private static void EmitReadObjectCoreWithConstructor(
{
builder.Append(" ").Append(requiredVar).AppendLine(" = true;");
}
builder.Append(" valueType = typeof(").Append(member.Type.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat)).AppendLine(");");
EmitReadMemberValueWithCustomConverter(builder, localModel, indexByType, sourceGenerationOptions);
builder.Append(" ").Append(localSeenVar).AppendLine(" = true;");
builder.AppendLine(" }");
Expand Down Expand Up @@ -2920,7 +2940,13 @@ private static void EmitReadObjectCoreWithConstructor(
builder.AppendLine(" }");
}

builder.AppendLine();
builder.AppendLine(" }");
builder.AppendLine(" catch (global::SharpYaml.YamlException exception) when (valueType is not null && CanRecoverInvalidValue(reader, exception, valueTokenType, valueStart))");
builder.AppendLine(" {");
builder.Append(" RecoverInvalidValue(reader, exception, typeof(").Append(typeName).AppendLine("), null, key, valueType);");
builder.AppendLine(" return;");
builder.AppendLine(" }");

builder.AppendLine(" if (!matched)");
builder.AppendLine(" {");
if (extensionData is not null)
Expand Down
Loading