Vidyano.SourceGenerators 3.0.0

Disclaimer

• Use of SourceGenerators depend on available content.
• Analyzers and CodeFixes are available in any project.

Some Patterns are not supported by Analyzers at the moment:

• When Clause on Switch Expression / Statements

Generators

• Actions Generator
• BusinessRules Generator
• Context Generator
• CustomAction Generator
• Index Generator
• Model Generator
• ProjectTargetContextType Generator
• Recipients Generator

Generated Constant classes

All generated Constant classes are available under {RootNamespace}.Service.Generated namespace.

• BusinessRuleNames
• PersistentObjectTypes
• PersistentObjectAttributeNames
• ProgramUnitNames
• ProgramUnitItemsNames
• QueryNames
• QuerySources
• ActionNames
• Languages
• MessageKeys and Messages
• AppRoles
• WebsiteNames
• Obsolete.PersistentObjectTypes

Dependency Injection

By using the InitializeByCtor attribute on a field, the source generator will inject this field via the generated constructor.

The Attribute can only be applied when no constructor is provided.

public partial class CompanyActions
{
    [InitializeByCtor]
    private readonly IMyService myService;
}

Attribute is available via reference Vidyano.Abstractions.

Index Generator

Generate an index by adding the GenerateIndex attribute to an entity, a nested objects class within an entity, or any deeper nested structure.

Index Types

The generator supports two types of indexes:

1. Entity Indexes

For entities, this will generate:

• A partial {Entity} class with a QueryType attribute.
• A partial {VEntity} QueryType class.
• A partial {Entities}_Overview Index class.
• A V{Entities} property on the Context if it does not already exist.

Example:

[GenerateIndex]
public partial class Customer
{
    public string Id { get; set; }
    public string Name { get; set; }
}

2. Fan-out Indexes (Nested Collections)

For nested objects within entities, you can create fan-out indexes that flatten nested collections. These classes can optionally be marked with [ValueObject] but this is not required:

[GenerateIndex(typeof(Country), nameof(Country.Cities), nameof(City.Streets))]
[ValueObject(typeof(Country))]
public partial class Street
{
    [ValueKey]
    public string Id { get; set; }

    public string Name { get; set; }
}

This creates an index that fans out from Country → Cities → Streets, making it easy to query all streets across all cities in all countries.

Fan-out Index Requirements:

• Must specify a root entity type (e.g., typeof(Country))
• Must provide a path through collections (e.g., nameof(Country.Cities), nameof(City.Streets))
• The final segment in the path must be the collection containing the target class

Important Notes:

• Index will not be generated if QueryType or Index is already added manually, except if they are partial.
• If the index contains an Id property, the IId interface will be applied
• If the index contains any audit fields, the corresponding IAudit... interface will be applied

Additional Attributes

You can add several attributes to control the index:

On the Class

• IndexReferenceProperty: When used at the class level, includes properties from the root entity or parent entities in the fan-out path for nested collection indexes.

  When used on a class:

  [GenerateIndex(typeof(Country), nameof(Country.Cities), nameof(City.Streets))]
  [IndexReferenceProperty(typeof(Country), "Id")]
  [IndexReferenceProperty(typeof(Country), "Name", Search = true)]
  [IndexReferenceProperty(typeof(City), nameof(City.Name))]
  public partial class Street { ... }
  

  Parameters:

  • First parameter: Type of the reference entity (e.g., typeof(Country))
  • Second parameter: Property path (e.g., nameof(Country.Name) or "Address.CityName")
  • Optional Search: Creates a second {Property}_Sort property to allow full search (only needed when values can contain spaces)
  • Optional IgnoreProperty: Include this property in the index mapping but do not sync to Vidyano

• IndexCustomVariable: Define custom variables for use in the index Map function.

  [IndexCustomVariable("countryDetails", """LoadDocument<CountryDetail>(country.Id + "/details")""")]
  

• IndexCustomWhere: Add custom where clauses to filter indexed documents.

  [IndexCustomWhere("countryDetails != null")]
  

• IndexCustomProperty: Add custom computed properties to the index.

  [IndexCustomProperty("HasDetails", typeof(bool), "countryDetails != null", IgnoreProperty = true)]
  [IndexCustomProperty("InternalCode", typeof(string), "countryDetails.Code", Nullable = false)]
  

  Parameters:

  • Optional Nullable: Specifies if the property type is nullable (for reference types). For value types, use typeof(bool?) directly
  • Optional IgnoreProperty: Include this property in the index mapping but do not sync to Vidyano

  Note: For IndexCustomVariable and IndexCustomWhere, the order is important and will be reflected in the generated index.

On Properties

• Search: Creates a second {Property}_Sort property to allow full search on this property.

  Note: This is only needed when values can contain spaces.

• IgnoreForIndex: This property will not be included in the index.

• IgnoreProperty: This attribute will be copied to the QueryType.

• IndexReferenceProperty: Include properties from a reference in the index.

  When used on a property:

  [IndexReferenceProperty(nameof(Person.Name), Search = true)]
  [IndexReferenceProperty("Address.CityName")]
  [IndexReferenceProperty("InternalCode", IgnoreProperty = true)]
  [Reference(typeof(Person))]
  public string Person { get; set; }
  

  Parameters:

  • First parameter: Property path (e.g., nameof(Person.Name) or "Address.CityName")
  • Search: Creates a second {Property}_Sort property to allow full search (only needed when values can contain spaces)
  • IgnoreProperty: Include this reference property in the index mapping but do not sync to Vidyano

  Note:

  • The reference type is inferred from the [Reference] attribute
  • If no Reference attribute is found, you can specify the type as the first parameter on IndexReferenceProperty

Complete Example

[GenerateIndex(Index = typeof(Indexes.City_Overview))]
public partial class City
{
    public string Id { get; set; }

    [Search]
    public string Name { get; set; }

    [IgnoreForIndex]
    public string InternalNotes { get; set; }

    [IndexReferenceProperty(nameof(Country.Name), Search = true)]
    [IndexReferenceProperty(nameof(Country.Code), IgnoreProperty = true)]
    [Reference(typeof(Country))]
    public string Country { get; set; }

    public List<Street> Streets { get; set; }
}

[GenerateIndex(typeof(City), nameof(City.Streets))]
[IndexCustomVariable("cityDetails", """LoadDocument<CityDetail>(city.Id + "/details")""")]
[IndexCustomWhere("cityDetails != null")]
[IndexCustomProperty("HasCityDetails", typeof(bool), "cityDetails != null", Nullable = false)]
[IndexReferenceProperty(typeof(City), "Country.Name")]
[ValueObject(typeof(City))]
public partial class Street
{
    [ValueKey]
    public string Id { get; set; }

    public string Name { get; set; }

    [IndexReferenceProperty(nameof(House.Id), IgnoreProperty = true)]
    [Reference(typeof(House))]
    public string House { get; set; }
}

Projects

Main project

Additional Files & Global Usings

Add following ItemGroup to the .csproj project file.

<ItemGroup>
  
  <AdditionalFiles Include="App_Data\**\*.json" />
  
  <Using Include="$(MSBuildProjectName).Service.Generated" />
  <Using Alias="Types" Include="$(MSBuildProjectName).Service.Generated.PersistentObjectTypes.$(MSBuildProjectName)" />
  <Using Alias="AttributeNames" Include="$(MSBuildProjectName).Service.Generated.PersistentObjectAttributeNames.$(MSBuildProjectName)" />
  <Using Alias="QueryNames" Include="$(MSBuildProjectName).Service.Generated.QueryNames.$(MSBuildProjectName)" />
  <Using Alias="QuerySources" Include="$(MSBuildProjectName).Service.Generated.QuerySources.$(MSBuildProjectName)" />
</ItemGroup>   

External Context

If the context file does not exist in the main project, you can use the appsettings.json file as an alternative, as the context will be read from there.

<ItemGroup>
  
  <AdditionalFiles Include="appsettings.json" />    
</ItemGroup>

Library project

Missing App_Data json files warning

When incorporating SourceGenerators into a library project, you may encounter a VIDYANO0010 warning indicating missing App_Data JSON files. This warning is not applicable to library projects, as they do not utilize App_Data.

To bypass this warning, two methods are available.

• By disabling the Model SourceGenerator via local .editorconfig file

is_global = true

# Source Generators
disable_model_source_generator = true

• By ignore the warning via csproj file

<NoWarn>VIDYANO0010</NoWarn>

Exceptions

When using EmitCompilerGeneratedFiles in .csproj project file you can get exceptions when compiling in Windows because of use of long filenames.

<EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>

To fix this issue you need to add the following registration key (Reboot needed to take effect)

reg ADD HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem /v LongPathsEnabled /t REG_DWORD /d 1

Backwards Compatibility

For backwards compatibility we created an Obsolete PersitentObjectTypes class (old version). The only thing you need todo when upgrading to the new source generator is changing the using in de .csproj project file by adding the Generated.Obsolete namespace.

<Using Alias="Types" Include="Fleet.Service.Generated.Obsolete.PersistentObjectTypes.Fleet" />

This way the project wil run as before.

Note: If you add the new usings directly you can use de CodeFix to update to the correct code.