MBW.Generators.NonTryMethods 0.3.0

MBW.Generators.NonTryMethods

About

Creates non-try wrappers for methods that follow the TryX pattern. The generator scans for matching methods and emits counterparts that return the out value or throw when the original method fails. This helps turn low level APIs that expose bool Try... into friendlier ones.

Picture a repository with a TryFind method that returns a bool and an out value. Consumers often just want the value and are fine with an exception when it is missing.

Quick Start

• Install the MBW.Generators.NonTryMethods package.
• Add [GenerateNonTryMethod] (and optionally [GenerateNonTryOptions]) at the assembly or type level.
• By default, methods matching the regex ^[Tt]ry(.*) with a bool return and an out parameter are wrapped, as are async methods returning Task<(bool, T)> or ValueTask<(bool, T)>. Generated methods return the success value or throw InvalidOperationException. Generated members are emitted into partial types; set MethodsGenerationStrategy.Extensions to produce extension methods instead.

The package includes both the attributes and the source generator.

Example

using MBW.Generators.NonTryMethods.Attributes;

[GenerateNonTryMethod(typeof(InvalidOperationException))]
[GenerateNonTryOptions(returnGenerationStrategy: ReturnGenerationStrategy.TrueMeansNotNull)]
public partial class Repository
{
    public bool TryFind(int id, out string? value)
    {
        value = id == 1 ? "one" : null;
        return value is not null;
    }
}

Generates

// <auto-generated/>
#nullable enable
using System;

partial class Repository
{
    public string Find(int id)
    {
        if (TryFind(id, out var value))
            return value;

        throw new InvalidOperationException();
    }
}

Features

• Flexible targeting of try-pattern methods via attributes and regexes.
• Customize the exception thrown when a method fails.
• Supports synchronous and asynchronous wrappers.
• Uses incremental generators for performance.
• Emits diagnostics to guide correct usage, including invalid regex patterns, duplicate signatures, and collisions with existing members.
• Generated methods include XML documentation that references the source method.
• Generates partial members, extensions, and interface implementations with default bodies.
• Preserves visibility, parameter names, modifiers (ref, in, out, params) and default values from the source methods.
• Extension methods respect value-type receivers by adding ref or in where required.

Attributes

• GenerateNonTryMethodAttribute – apply to an assembly, class, interface or struct. Selects which try methods are wrapped.
  • exceptionType – exception thrown when the wrapped method returns false (default InvalidOperationException).
  • methodNamePattern – regex used to identify methods to wrap (default ^[Tt]ry(.*)).
• GenerateNonTryOptionsAttribute – apply to an assembly, class, interface or struct to control generation.
  • AsyncCandidateStrategy – include or exclude async try methods:
    • None – ignore async methods.
    • TupleBooleanAndValue – wrap methods returning Task<(bool, T)> or ValueTask<(bool, T)>.
  • ReturnGenerationStrategy – governs nullability of the generated method's return type:
    • Verbatim – copy the out parameter's nullability.
    • TrueMeansNotNull – successful calls are assumed to return non-null.
  • MethodsGenerationStrategy – where to place generated methods:
    • Auto – emit into partial types (default).
    • PartialType – emit into partial types (requires partial declaration).
    • Extensions – emit extension methods.

GenerateNonTryMethodAttribute may be used multiple times. GenerateNonTryOptionsAttribute is single-use. Neither attribute is inherited.

More information

This project is provided as-is without support. Additional examples are available in the tests.