Bongia.Generators 8.0.3-alpha

Bongia.Generators

Bongia.Generators is a Roslyn source generator that automatically creates projection classes and mapping expressions between a source type and one or more target types.

For example, you can easily map from an entity to a DTO, but the library itself is generic and works with any types.

How it works

By decorating your source classes with the [GenerateProjection<TTarget>] attribute, Bongia.Generators will:

1. Generate target properties automatically
   Every property from the source type is copied to the target type, unless explicitly excluded with [NotProjected] or [NotProjected<TTarget>].

2. Generate projection methods
   For each [GenerateProjection<TTarget>], a static method is added to the source type, e.g.:

   • GetUserDtoProjection()
   • GetExtendedUserDtoProjection()

   These methods return an Expression<Func<TSource, TTarget>> (wrapped in a Specification<TSource, TTarget>), ready to be used in LINQ queries or frameworks like EF Core.

3. Support custom properties
   You can extend target types with computed properties by providing generator methods.
   The generator methods must be public static and return a Specification<TSource, TValue>.
   During projection, Bongia.Generators will call these methods and populate the additional properties.

4. Provide a LINQ extension method
   Bongia.Generators adds an extension method ProjectTo<TTarget>() on IQueryable<TSource>.

   • It searches for a generated projection method from TSource to TTarget.
   • If found, it applies a .Select(...) internally and returns IQueryable<TTarget>.
   • If not found, it throws a runtime error.

Example

[GenerateProjection<UserDto>]
[GenerateProjection<ExtendedUserDto>(
    "FullName", nameof(GetFullName)
)]
internal sealed partial class User
{
    [NotProjected]
    public string? Password { get; set; }

    [NotProjected<UserDto>]
    public string FirstName { get; set; } = null!;

    [NotProjected<UserDto>]
    public string LastName { get; set; } = null!;

    public Guid Id { get; set; }
    public string Username { get; set; } = null!;

    // Custom property generator for ExtendedUserDto
    public static Specification<User, string> GetFullName() =>
        new(user => $"{user.FirstName} {user.LastName}");
}

internal sealed partial class UserDto;
internal sealed partial class ExtendedUserDto;

What gets generated

• UserDto (target type)
  Will contain all properties from User except those marked with [NotProjected<UserDto>] or [NotProjected].

• ExtendedUserDto (target type)
  Will contain all the allowed properties plus the extra FullName property, populated using the GetFullName method.

• Projection methods on User (source type)

  public static Expression<Func<User, UserDto>> GetUserDtoProjection();
  public static Expression<Func<User, ExtendedUserDto>> GetExtendedUserDtoProjection();
  

• Queryable extension method

  IQueryable<UserDto> dtos = dbContext.Users.ProjectTo<UserDto>();
  

  If the projection method exists, the query is translated. Otherwise, a runtime exception is thrown.

Excluding properties

• [NotProjected] → Excludes the property from all projections.
• [NotProjected<TTarget>] → Excludes the property only for the given target type.

Adding custom properties

To add extended properties to a target type:

1. Pass pairs of arguments to the [GenerateProjection] attribute:

   [GenerateProjection<ExtendedUserDto>(
       "FullName", nameof(GetFullName),
       "OtherProp", nameof(GetOtherProp)
   )]
   

2. Implement a static generator method for each property:

   public static Specification<User, string> GetOtherProp() =>
       new(user => user.Username.ToUpper());
   

3. The target type will get a new property:

   public string FullName { get; set; }
   public string OtherProp { get; set; }
   

Requirements

• Source and target types must be declared as partial.
• Generator methods must be public static and return a Specification<TSource, TValue>.

Visual Overview

  Source Type (User)
        |
        | [GenerateProjection<UserDto>]
        | [GenerateProjection<ExtendedUserDto> + custom generators]
        v
  Projection Methods Generated
        |
        v
  Target Types (UserDto, ExtendedUserDto)
        |
        | IQueryable<TTarget> ProjectTo<TTarget>()
        v
  LINQ Queryable results

Why use Bongia.Generators?

• Eliminate repetitive mapping code.
• Get compile-time safety for projections.
• Generate LINQ- and EF Core–friendly expressions automatically.
• Keep target types clean and partial, only defining what really matters.