Dekiru.DtoGenerator 0.2.1

DTO Generator

A Source Generator that generates DTO classes from existing classes. Configuration is done via attributes, as described below. All generated code should be compatible with .NET Standard 2.0 or later.

The DTO generator will, by design, not include properties from any base class of the source class. If you have that need, generate a DTO from the base class and have your other DTO inherit from that one.

The DTO generator will also only include public instance properties.

Attributes

The following attributes are used to configure the DTO generator:

[DtoFor<T>]

Marks a class as a DTO for the source class T. This is the attribute that triggers the DTO generation, and the only required attribute.

The most basic example:

[DtoFor<Foo>]
public partial class FooDto;

The attribute has the following parameters:

• T: The type of the class for which the DTO is generated.
• propertyStrategy (PropertyStrategy, optional): The strategy to use when generating properties. Default is PropertyStrategy.Implicit.
  • Implicit: Generate all properties that are not explicitly removed via any [Omit]-like attribute.
  • Explicit: Generate only properties that are explicitly included via [Pick].

Note: The target (DTO) class must be public and partial.

Note: Properties must be public and have public get and set methods to be included.

Note: If a property with the same name exists in the target and source classes, it will excluded. Such a property must at present have the same type in both classes.

Configuration attributes

The following attributes are used to configure the DTO generator:

Note: Some of these attributes have parameters that represents one or more property names. While [MyAttribute("Foo")], [MyAttribute(nameof(Bar.Foo))], or a combination of the two are valid, the source generator will produce a static nested class named _ with all eligible property names as constants.

public partial class FooDto
{
  // Properties omitted for brevity
  public static class _
  {
  	public const string FooId = nameof(FooId);
  }
}

This is useful when you want to reference the property names in a strongly typed manner, like so: [Omit(_.Foo)], and is less verbose than using nameof.

[Omit]

Omits one or more properties from the generated DTO. The attribute has the following parameters:

• properties (params string[]): The names of the properties to omit.

  [OmitByNamespace]

  Omits all properties from the specified namespaces. The attribute has the following parameters:

  • namespaces (params string[]): The namespaces to omit. Regular expressions are supported, with a timeout of 0.1 seconds.

  [OmitByType]

  Omits all properties of the specified types. The attribute has the following parameters:

  • type (Type): The types to omit. The attribute supports unbounded generic types.

  [OmitByType<T>]

  Omits all properties of the specified type T. The attribute has no parameters.

  [OmitKeysByConvention]

  Omits all properties that are named Id or <Target>Id, with a case-insensitive match. The attribute has no parameters.

  [OmitReferenceProperties]

  Omits all properties that are reference types. The attribute has no parameters.

These attributes have no effect when the property strategy is PropertyStrategy.Explicit.

[Pick]

Only includes the specified properties in the generated DTO. The attribute has the following parameters:

• properties (params string[]): The names of the properties to include.

This attribute has no effect when the property strategy is PropertyStrategy.Implicit.

[Using]

Adds any number of using directives to the generated code. The attribute has the following parameters:

• namespaces (string[]): The namespaces to add.

[NoCopyMethod]

Disables the generation of the Copy method. The attribute has no parameters.

[NoCreateMethod]

Disables the generation of the Create method. The attribute has no parameters.

Member attributes

Some attributes are property specific, these are:

[ValueFor]

This attribute is only relevant for omitted properties, and is a way to ensure that their values are set. The attribute has the following parameters:

• target (string): The name of the property to set.

The attribute can be used on a method, property, or field. They may have any visibility, but if the member is a method it must be parameter-less.

As an example, let's look at a source class with a Name property:

public class Foo
{
  public string Name { get; set; }
}

However, in our DTO we wish to separate first and last name. We can then use ValueFor to handle this:

[DtoFor<Foo>]
[Omit(_.Name)]
public class FooDto
{
  public string FirstName { get; set; }
  public string LastName { get; set; }

  [ValueFor(_.Name)] private string name => $"{FirstName} {LastName}";
}