Exceptions

Exceptions

The library throws a small number of typed exceptions for predictable failure modes. Catch them at the call site if you want to surface diagnostic context to your users; otherwise let them propagate — they all derive from Exception.

All four live in CustomAutoAdapterMapper.Exceptions.

JsonContentException

Thrown when: the string passed to MapCollection is not valid JSON.

Typical cause: empty string, partial response body, accidentally passing the response object instead of .Content.

try
{
    json.MapCollection(products, options => { options.RootKey = "products"; });
}
catch (JsonContentException)
{
    // log + surface "the upstream payload wasn't valid JSON"
}

RootKeyOptionNullException

Thrown when: options.RootKey is not set (null or empty).

Typical cause: forgot to set RootKey in the Action<Option> callback.

RootKey is the only truly required option — the library has no way to know where the array lives in your JSON without it.

RootKeyPropertyNullException

Thrown when: options.RootKey is set, but the JSON doesn't contain anything at that path.

Typical causes:

• Typo in the root key name
• Upstream returned a different shape than expected (e.g. error response with a different envelope)
• Wrong nesting in the dot-notation path

try
{
    json.MapCollection(products, options => { options.RootKey = "data.products"; });
}
catch (RootKeyPropertyNullException)
{
    // upstream JSON didn't have a "data.products" array — log the raw payload for diagnosis
}

ItemKeyOptionNullException

Thrown when: the mapper enters Update Mode but options.ItemKey isn't set.

Typical cause: passing a non-empty, partially-populated destination list and forgetting to set ItemKey.

The fix is either:

• Set ItemKey to the property that uniquely identifies items, or
• If you wanted Create Mode (rebuild from JSON), make sure the destination starts empty or set IsItemEmpty = _ => true.

Recovery patterns

Treat upstream parse failures as soft errors

try
{
    json.MapCollection(products, options => { options.RootKey = "products"; });
}
catch (JsonContentException)        { return EmptyResult("invalid json"); }
catch (RootKeyPropertyNullException) { return EmptyResult("missing products key"); }

Validate RootKey was found before consuming the result

The library only throws if RootKey is missing entirely — it does not throw if the root key resolves to an empty array. So:

json.MapCollection(products, options => { options.RootKey = "products"; });

if (products.Count == 0)
{
    // either the array was empty, or upstream had no products to send.
    // (a missing "products" key would have thrown RootKeyPropertyNullException)
}

All four exceptions have standard constructors

Each exception type exposes the standard three .NET constructors:

new ItemKeyOptionNullException();
new ItemKeyOptionNullException("message");
new ItemKeyOptionNullException("message", innerException);

Useful if you want to wrap one in your own exception type with additional context.