How to override default parser for a specific TimeSpan option?

[MichalMetzger]

I'm using McMaster.Extensions.CommandLineUtils (v4.1.1 on .NET 9) in C# to parse command-line arguments. I have a model class with properties decorated with the [Option] attribute.
One of my properties is a nullable TimeSpan:

class MyClass
{
    [Option("--timeout", CommandOptionType.SingleOrNoValue)]
    public TimeSpan? Timeout { get; }
    // ... 
}

The library has a built-in parser for TimeSpan, but my Timeout property needs to accept a unique string format that the default parser doesn't handle. I want to provide a custom parser only for this specific option, without affecting other TimeSpan properties in my project.
I have tried two different approaches, and both have failed.

Attempt 1: Implementing IValueParser
First, I created a custom parser that implements IValueParser<TimeSpan?>:

private sealed class MyTimeSpanParser : IValueParser<TimeSpan?>
{
    public Type TargetType => typeof(TimeSpan?);

    public TimeSpan? Parse(string? argumentName, string? value, CultureInfo culture) 
    {
        // ...
    }

    object? IValueParser.Parse(string? argumentName, string? value, CultureInfo culture)
    {
        return this.Parse(argumentName, value, culture);
    }
}

Then, I registered it in my main application setup:

var commandLineApplication = new CommandLineApplication<MyClass>();
commandLineApplication.Conventions.UseDefaultConventions();
commandLineApplication.ValueParsers.AddOrReplace(new MyTimeSpanParser()); 
commandLineApplication.Parse(args);
// ...

When I run the app with --timeout 15s, I get a FormatException: '15s' is not a valid value for TimeSpan.
When I debug the library's code, I can see that
var parser = context.Application.ValueParsers.GetParser(prop.PropertyType);
returns the default TimeSpanConverter, not my custom MyTimeSpanParser.
As a test, I created a new wrapper class class MyTimeSpan { public TimeSpan? Value { get; } ... }. When I changed my property and parser to use this new MyTimeSpan type, my custom parser was used correctly. This seems to indicate that my parser is ignored for built-in types but works for new custom types. However, creating a wrapper class just for this is not an ideal solution.

Attempt 2: Using [TypeConverter]
Following the discussion in GitHub Issue #62, I tried using a custom TypeConverter.
First, I updated my model class:

class MyClass
{
    [Option("--timeout", CommandOptionType.SingleOrNoValue)]
    [TypeConverter(typeof(MyTimeSpanConverter))]
    public TimeSpan? Timeout { get; }
    // ... 
}

And I created the custom converter:

class MyTimeSpanConverter : TimeSpanConverter
{
    public override object? ConvertFrom(ITypeDescriptorContext? context, CultureInfo? culture, object value)
    {
        if (value is string stringValue)
        {
            //...
        }
        
        return base.ConvertFrom(context, culture, value);
    }
}

My main application setup for this attempt did not register any parsers manually, relying only on the conventions:

var commandLineApplication = new CommandLineApplication<MyClass>();
commandLineApplication.Conventions.UseDefaultConventions();
commandLineApplication.Parse(args);
// ...

I get the exact same FormatException as in my first attempt. The TypeConverter attribute seems to be ignored, and the default TimeSpanConverter is used.
As another test, I tried registering my converter globally at startup with TypeDescriptor.AddAttributes(...). This did work and my converter was called. However, this is a global change that affects the entire application, and my requirement is to apply this logic only to one specific property.

What am I missing in these two approaches? How can I correctly instruct CommandLineUtils to use a custom parser for a specific option of a built-in type like TimeSpan?, without affecting other TimeSpan properties and without creating a wrapper class?

[natemcmaster]

@claude any suggestions on how to address this?

[claude]

Claude finished @natemcmaster's task in 2m 11s —— View job

---

Analysis of issue #559

• Gather context and understand the issue
• Investigate value parser lookup code
• Investigate TypeConverter handling
• Provide suggestions with code references

I investigated the root causes and have suggestions for both problems.

---

Bug: AddOrReplace with nullable types is broken

This is a real bug. When the user calls AddOrReplace(new MyTimeSpanParser()) where TargetType => typeof(TimeSpan?):

1. Storage works correctly: SafeAdd strips the nullable, so the parser is stored under typeof(TimeSpan) in the dictionary (ValueParserProvider.cs:211)

2. Lookup is broken: In GetParserImpl<TimeSpan?>() (ValueParserProvider.cs:90-119), the resolution order is:

   • Check _parsers[typeof(TimeSpan?)] → miss (stored under TimeSpan, not TimeSpan?)
   • Check if enum → no
   • Check TypeDescriptor.GetConverter(typeof(TimeSpan?)) → hit! Returns the built-in NullableConverter/TimeSpanConverter
   • Check nullable unwrap → never reached

The TypeDescriptor fallback (line 103) runs before the nullable unwrap (line 108), so the custom parser in the dictionary is never found. The fix is straightforward: move the nullable type handling before the TypeDescriptor fallback.

Suggested fix in GetParserImpl<T>():

internal IValueParser? GetParserImpl<T>()
{
    var type = typeof(T);
    if (_parsers.TryGetValue(type, out var parser))
    {
        return parser;
    }

    if (type.IsEnum)
    {
        return EnumParser.Create(type);
    }

-   if (_defaultValueParserFactory.TryGetParser<T>(out parser))
-   {
-       return parser;
-   }
-
    if (ReflectionHelper.IsNullableType(type, out var wrappedType))
    {
        if (wrappedType.IsEnum)
        {
            return new NullableValueParser(EnumParser.Create(wrappedType));
        }

        if (_parsers.TryGetValue(wrappedType, out parser))
        {
            return new NullableValueParser(parser);
        }
    }

+   if (_defaultValueParserFactory.TryGetParser<T>(out parser))
+   {
+       return parser;
+   }
+
    // ... rest of method

This ensures that user-registered parsers (stored under the unwrapped type) are found before falling back to the TypeDescriptor.

Limitation: Property-level [TypeConverter] is not supported

This one is by design of the current architecture. The parser lookup in TypeDescriptorValueParserFactory.TryGetParser<T>() calls TypeDescriptor.GetConverter(typeof(T)) which only inspects the type, not the property. Since [TypeConverter] on a property is a .NET convention for designers/serializers, but the parser resolution here only receives a Type, not a PropertyInfo, property-level attributes are invisible.

Supporting property-level [TypeConverter] would require threading PropertyInfo through the parser resolution pipeline, which is a larger change. Given the bug fix above, I think the AddOrReplace approach is the more natural API for this library anyway — once it works correctly, users can replace parsers for specific types.

For the reporter's specific use case

Once the bug is fixed, their Attempt 1 would work — registering a custom IValueParser<TimeSpan?> via AddOrReplace would correctly override the built-in parser. If they need different behavior for different TimeSpan properties, a wrapper type (MyTimeSpan) is still the cleanest approach since parsers are resolved by type.

---

Would you like me to implement this fix with tests?

[natemcmaster]

@claude yes, prepare a pull request (as well as tests to validate the before/after) fix

[claude]

Claude finished @natemcmaster's task in 2m 5s —— View job • claude/issue-559-20260405-0553 • Create PR ➔

---

Implementing fix for nullable value parser lookup

• Gather context and understand the issue
• Read relevant source files
• Implement the fix in ValueParserProvider.cs
• Write tests for before/after validation
• Commit and push changes
• Create PR

Changes

Root cause: In GetParserImpl<T>(), when looking up a parser for a nullable type like TimeSpan?, the resolution order was:

1. Check _parsers[typeof(TimeSpan?)] → miss (stored under TimeSpan)
2. Check enum → no
3. TypeDescriptor fallback → hit! Returns built-in TimeSpanConverter
4. Nullable unwrap checking _parsers[typeof(TimeSpan)] → never reached

Fix: Moved the nullable type unwrap (IsNullableType + dictionary lookup) before the TypeDescriptor fallback, so user-registered parsers stored under the unwrapped type are found first.

Tests added:

• CustomParserWorksForNullableBuiltInType — verifies a custom TimeSpan parser is used when the property is TimeSpan?
• CustomParserWorksForNonNullableBuiltInType — verifies it still works for non-nullable TimeSpan
• NullableBuiltInTypeUsesDefaultParserWhenNoCustomParser — verifies the default parser still works for TimeSpan? when no custom parser is registered

|