Skip to content

Sample Projects

Jump to bottom
davidkallesen edited this page Mar 12, 2026 · 1 revision

📦 Sample Projects

Working code examples demonstrating each generator in realistic scenarios. All samples are located in the sample/ directory of the repository.

📁 Directory Structure

sample/
├── Atc.SourceGenerators.DependencyRegistration/     (Console app - DI registration)
│   └── Atc.SourceGenerators.DependencyRegistration.Domain/
├── Atc.SourceGenerators.OptionsBinding/             (Console app - Configuration binding)
│   └── Atc.SourceGenerators.OptionsBinding.Domain/
├── Atc.SourceGenerators.Mapping/                    (ASP.NET Core API - Object mapping)
│   ├── Atc.SourceGenerators.Mapping.Domain/
│   ├── Atc.SourceGenerators.Mapping.DataAccess/
│   └── Atc.SourceGenerators.Mapping.Contract/
├── Atc.SourceGenerators.MappingOnlyConfiguration/         (Console app - Config-based mapping)
│   ├── Atc.SourceGenerators.MappingOnlyConfiguration.Domain/
│   └── Atc.SourceGenerators.MappingOnlyConfiguration.ExternalCrm/
├── Atc.SourceGenerators.MappingCombinedConfiguration/     (Console app - Mixed mapping)
│   ├── Atc.SourceGenerators.MappingCombinedConfiguration.Domain/
│   ├── Atc.SourceGenerators.MappingCombinedConfiguration.Contract/
│   ├── Atc.SourceGenerators.MappingCombinedConfiguration.ExternalNotifications/
│   └── Atc.SourceGenerators.MappingCombinedConfiguration.ExternalAnalytics/
├── Atc.SourceGenerators.EnumMapping/                (Console app - Enum mapping)
├── Atc.SourceGenerators.AnnotationConstants/        (Console app - Annotation constants)
└── PetStore.Api/                                    (Full app - All generators together)
    ├── PetStore.Domain/
    ├── PetStore.DataAccess/
    └── PetStore.Api.Contract/

⚡ DependencyRegistration Sample

🔌 Multi-project console app showing automatic DI registration across layers with auto-detection of interfaces.

cd sample/Atc.SourceGenerators.DependencyRegistration
dotnet run

🏗️ Architecture

graph TB
    subgraph "Atc.SourceGenerators.DependencyRegistration (Console App)"
        Program[Program.cs]
        SC[ServiceCollection]
    end

    subgraph "Atc.SourceGenerators.DependencyRegistration.Domain"
        US[UserService]
        CS[CacheService]
        ES[EmailService]
        IUS[IUserService]
        ICS[ICacheService]
        IES[IEmailService]
        INS[INotificationService]

        US -->|implements| IUS
        CS -->|implements| ICS
        ES -->|implements| IES
        ES -->|implements| INS
    end

    subgraph "Generated Code"
        EXT1["AddDependencyRegistrationsFromAtcSourceGeneratorsDependencyRegistration()"]
        EXT2["AddDependencyRegistrationsFromAtcSourceGeneratorsDependencyRegistrationDomain()"]
    end

    Program --> SC
    SC --> EXT1
    SC --> EXT2
    EXT1 -->|registers| Program
    EXT2 -->|registers| US
    EXT2 -->|registers| CS
    EXT2 -->|registers| ES

    style US fill:#0969da
    style CS fill:#0969da
    style ES fill:#0969da
    style EXT1 fill:#2ea44f
    style EXT2 fill:#2ea44f
Loading

🔄 Registration Flow

sequenceDiagram
    participant App as Program.cs
    participant Gen as Source Generator
    participant DI as ServiceCollection

    Note over Gen: Build Time
    Gen->>Gen: Scan for [Registration] attributes
    Gen->>Gen: Detect implemented interfaces
    Gen->>Gen: Generate AddDependencyRegistrationsFromXXX()

    Note over App,DI: Runtime
    App->>DI: AddDependencyRegistrationsFromDomain()
    DI->>DI: services.AddScoped<IUserService, UserService>()
    DI->>DI: services.AddSingleton<ICacheService, CacheService>()
    DI->>DI: services.AddScoped<IEmailService, EmailService>()
    DI->>DI: services.AddScoped<INotificationService, EmailService>()
    DI-->>App: Configured ServiceProvider
Loading

💻 Code Example

📂 Domain Layer Services:

using Atc.DependencyInjection;

// Auto-detected as IUserService
[Registration(Lifetime.Scoped)]
public class UserService : IUserService
{
    public void CreateUser(string name) => Console.WriteLine($"Creating user: {name}");
}

// Auto-detected as ICacheService
[Registration] // Defaults to Singleton
public class CacheService : ICacheService
{
    public void Set(string key, object value) => Console.WriteLine($"Caching {key}");
}

// Multi-interface example - registers against BOTH interfaces
[Registration(Lifetime.Scoped)]
public class EmailService : IEmailService, INotificationService
{
    public void SendEmail(string to, string subject) => Console.WriteLine($"Email to {to}: {subject}");
    public void Notify(string message) => Console.WriteLine($"Notification: {message}");
}

🚀 Application Setup:

var services = new ServiceCollection();

// Option 1: Manual registration - one line per project
services.AddDependencyRegistrationsFromAtcSourceGeneratorsDependencyRegistration();
services.AddDependencyRegistrationsFromAtcSourceGeneratorsDependencyRegistrationDomain();

// Option 2: Transitive registration (recommended) - single call
services.AddDependencyRegistrationsFromAtcSourceGeneratorsDependencyRegistration(includeReferencedAssemblies: true);

📋 All Available Overloads:

// Overload 1: Default (no transitive registration)
services.AddDependencyRegistrationsFromYourProject();

// Overload 2: Auto-detect ALL referenced assemblies recursively
services.AddDependencyRegistrationsFromYourProject(includeReferencedAssemblies: true);

// Overload 3: Register specific referenced assembly (short or full name)
services.AddDependencyRegistrationsFromYourProject("Domain");

// Overload 4: Register multiple specific assemblies
services.AddDependencyRegistrationsFromYourProject("Domain", "DataAccess", "Infrastructure");

🎯 Key Takeaways

  1. ✅ Zero Configuration: Services are automatically registered against all implemented interfaces
  2. 🛡️ Type Safety: Compile-time errors if interfaces don't match or lifetimes conflict
  3. 📦 Multi-Project: Each project gets its own AddDependencyRegistrationsFromXXX() method
  4. 🔗 Multi-Interface: One service can be registered against multiple interfaces automatically
  5. 🧹 Smart Filtering: System interfaces (IDisposable, etc.) are automatically excluded

📖 Full documentation: Working with Dependency Registration

⚙️ OptionsBinding Sample

🔧 Console app demonstrating type-safe configuration binding with validation and multiple options classes.

cd sample/Atc.SourceGenerators.OptionsBinding
dotnet run

🏗️ Architecture

graph TB
    subgraph "Configuration Sources"
        JSON[appsettings.json]
        ENV[Environment Variables]
    end

    subgraph "Options Classes"
        DO[DatabaseOptions]
        CO[CacheOptions]
        AO[ApiOptions]
        LO[LoggingOptions]
    end

    subgraph "Generated Extension Methods"
        EXT1["AddOptionsFromAtcSourceGeneratorsOptionsBinding()"]
        EXT2["AddOptionsFromAtcSourceGeneratorsOptionsBindingDomain()"]
    end

    JSON --> EXT1
    ENV --> EXT1
    JSON --> EXT2
    ENV --> EXT2

    EXT1 --> DO
    EXT2 --> CO
    EXT2 --> AO
    EXT2 --> LO

    style EXT1 fill:#2ea44f
    style EXT2 fill:#2ea44f
    style DO fill:#0969da
    style CO fill:#0969da
    style AO fill:#0969da
    style LO fill:#0969da
Loading

💻 Code Example

📂 Domain Layer Options:

using Atc.SourceGenerators.Annotations;
using System.ComponentModel.DataAnnotations;

// Explicit section name with fail-fast validation
[OptionsBinding("Database", ValidateDataAnnotations = true, ValidateOnStart = true, ErrorOnMissingKeys = true)]
public partial class DatabaseOptions
{
    [Required]
    [MinLength(10)]
    public string ConnectionString { get; set; } = string.Empty;

    [Range(1, 10)]
    public int MaxRetries { get; set; } = 3;
}

// Using const SectionName (2nd priority)
[OptionsBinding(ValidateDataAnnotations = true)]
public partial class CacheOptions
{
    public const string SectionName = "ApplicationCache";

    [Range(100, 10000)]
    public int MaxSize { get; set; } = 1000;
}

// Nested section path
[OptionsBinding("App:Api")]
public partial class ApiOptions
{
    [Required] [Url]
    public string BaseUrl { get; set; } = string.Empty;
}

// Configuration change callbacks with Monitor lifetime
[OptionsBinding("Logging", Lifetime = OptionsLifetime.Monitor, OnChange = nameof(OnLoggingChanged))]
public partial class LoggingOptions
{
    public string Level { get; set; } = "Information";

    internal static void OnLoggingChanged(LoggingOptions options, string? name)
    {
        Console.WriteLine($"[OnChange] Level: {options.Level}");
    }
}

🚀 Application Setup:

var services = new ServiceCollection();

// Transitive registration (recommended)
services.AddOptionsFromAtcSourceGeneratorsOptionsBinding(configuration, includeReferencedAssemblies: true);

✨ Features Demonstrated

  • 🔍 Section name resolution priority: Explicit > SectionName const > NameTitle const > Name const > Auto-inferred
  • 🛡️ Validation: DataAnnotations with ValidateOnStart
  • 🔔 Configuration change callbacks: Auto-generated IHostedService for OnChange notifications
  • 🏷️ Named options: Multiple configurations of same type (Email: Primary/Secondary/Fallback)
  • 📂 Child sections: Simplified syntax for named options (ChildSections = new[] { "Email", "SMS", "Push" })
  • 🪆 Nested subsection binding: Complex properties auto-bound to subsections

📖 Full documentation: Working with Options Binding

🗺️ Mapping Sample

🔄 ASP.NET Core Minimal API showing 3-layer mapping (Entity → Domain → DTO) with automatic enum conversion and nested objects.

cd sample/Atc.SourceGenerators.Mapping
dotnet run

🏗️ Architecture

graph TB
    subgraph "API Layer"
        API[Minimal API Endpoints]
    end

    subgraph "Contract Layer"
        DTO[DTOs: UserDto, AddressDto, UserStatusDto]
    end

    subgraph "Domain Layer"
        DM[Domain Models: User, Address]
        DE[Domain Enums: UserStatus]
    end

    subgraph "Data Access Layer"
        ENT[Entities: UserEntity, AddressEntity]
        EE[Entity Enums: UserStatusEntity]
    end

    subgraph "Generated Bidirectional Mappings"
        M1["User ↔ UserEntity"]
        M2["User → UserDto"]
        M3["Address ↔ AddressEntity"]
        M4["Address → AddressDto"]
    end

    API --> DTO
    DTO --> DM
    DM --> M1
    DM --> M2
    M1 --> ENT
    M2 --> DTO

    style M1 fill:#2ea44f
    style M2 fill:#2ea44f
    style M3 fill:#2ea44f
    style M4 fill:#2ea44f
Loading

💻 Code Example

📂 Domain Layer:

using Atc.SourceGenerators.Annotations;

// Domain model with BIDIRECTIONAL mapping to Entity and forward mapping to DTO
[MapTo(typeof(UserDto))]
[MapTo(typeof(UserEntity), Bidirectional = true)]
public partial class User
{
    public Guid Id { get; set; }
    public string FirstName { get; set; } = string.Empty;
    public string LastName { get; set; } = string.Empty;
    public string Email { get; set; } = string.Empty;
    public UserStatus Status { get; set; }
    public Address? Address { get; set; }
}

[MapTo(typeof(AddressDto))]
[MapTo(typeof(AddressEntity), Bidirectional = true)]
public partial class Address
{
    public string Street { get; set; } = string.Empty;
    public string City { get; set; } = string.Empty;
    public string Country { get; set; } = string.Empty;
}

🔗 Usage - Multi-layer mapping chain:

var dto = entity
    .MapToUser()      // Entity → Domain
    .MapToUserDto();  // Domain → DTO

✨ Features Demonstrated

  • 🔗 Multi-layer mapping chains: Entity → Domain → DTO
  • 🔄 Bidirectional mapping: Single attribute generates both directions
  • 🎨 Automatic enum conversion: Enum types mapped automatically
  • 🪆 Nested object mapping: Address automatically chained
  • 🛡️ Null safety: Built-in null checks for nullable types
  • 🏛️ Base class property inheritance: Audit fields from base classes included automatically

📖 Full documentation: Working with Object Mapping

🗺️ MappingOnlyConfiguration Sample

🔧 Console app demonstrating pure configuration-based mapping for third-party types. Use this approach when you cannot place [MapTo] attributes on source types (e.g., third-party SDK types, NuGet package models, or legacy code you don't control).

dotnet run --project sample/Atc.SourceGenerators.MappingOnlyConfiguration

📁 Project Structure

sample/
  Atc.SourceGenerators.MappingOnlyConfiguration/              # Console app (entry point)
    Program.cs
  Atc.SourceGenerators.MappingOnlyConfiguration.Domain/       # Domain models + mapping config
    Customer.cs
    Address.cs
    CustomerCategory.cs
    CrmMappings.cs                                            # Configuration-based mappings
  Atc.SourceGenerators.MappingOnlyConfiguration.ExternalCrm/  # Simulated 3rd-party SDK
    Contact.cs
    ContactAddress.cs
    ContactType.cs

🔧 CrmMappings Configuration Class

The [MappingConfiguration] class defines how external types map to domain types. Each method signature declares the mapping direction, and attributes control property renaming and exclusion:

using Atc.SourceGenerators.Annotations;
using Atc.SourceGenerators.MappingOnlyConfiguration.ExternalCrm;

namespace Atc.SourceGenerators.MappingOnlyConfiguration.Domain;

[MappingConfiguration]
public static partial class CrmMappings
{
    // Maps CRM Contact to domain Customer with property renaming
    [MapConfigProperty("FullName", "Name")]
    [MapConfigProperty("EmailAddress", "Email")]
    [MapConfigProperty("PhoneNumber", "Phone")]
    [MapConfigProperty("PrimaryAddress", "Address")]
    [MapConfigProperty("CreatedDate", "CreatedAt")]
    [MapConfigProperty("ModifiedDate", "UpdatedAt")]
    [MapConfigProperty("Type", "Category")]
    [MapConfigIgnore("ContactId")]
    [MapConfigIgnore("InternalTrackingCode")]
    public static partial Customer MapToCustomer(this Contact source);

    // Maps CRM ContactAddress to domain Address with ZipCode -> PostalCode rename
    [MapConfigProperty("ZipCode", "PostalCode")]
    public static partial Address MapToAddress(this ContactAddress source);
}

🎯 Key points:

  • 🏷️ [MapConfigProperty("SourceProp", "TargetProp")] renames properties during mapping
  • 🚫 [MapConfigIgnore("SourceProp")] excludes properties from mapping (e.g., internal tracking fields)
  • ✅ Same-name properties (like Street, City) are mapped automatically without any attribute
  • 🪆 Nested mapping is automatic -- PrimaryAddress calls MapToAddress() for the ContactAddress type
  • 🎨 Enum values are auto-detected using the special case engine (None maps to Unknown, etc.)

🎯 Key Takeaways

  1. 🚫 No attributes on source types: All mapping configuration lives in your domain project
  2. 🏷️ Property renaming: [MapConfigProperty] handles different naming conventions between external and domain types
  3. 🙈 Property exclusion: [MapConfigIgnore] removes internal/irrelevant fields from external types
  4. ✅ Automatic same-name mapping: Properties with matching names require no configuration
  5. 🔗 Nested mapping chains: ContactAddress to Address is automatically chained when mapping Contact to Customer
  6. 🎨 Enum auto-detection: ContactType.None maps to CustomerCategory.Unknown automatically

📖 Full documentation: Configuration-Based Mapping

🗺️ MappingCombinedConfiguration Sample

🔀 Console app demonstrating mixed attribute-based and configuration-based mapping working together. This sample shows how [MapTo] attributes for types you own can coexist with [MappingConfiguration] for external types, including multi-hop mapping chains that span both styles.

dotnet run --project sample/Atc.SourceGenerators.MappingCombinedConfiguration

📁 Project Structure

sample/
  Atc.SourceGenerators.MappingCombinedConfiguration/                    # Console app (entry point)
    Program.cs
  Atc.SourceGenerators.MappingCombinedConfiguration.Domain/             # Domain models (mixed mapping)
    Notification.cs              # Attribute-based [MapTo] for owned types
    Urgency.cs                   # Attribute-based [MapTo] for enum
    ActivityEvent.cs             # Plain domain model (target of config mapping)
    ActivitySeverity.cs          # Domain enum
    BrowsingSession.cs           # Plain domain model (target of config mapping)
    ExternalMappings.cs          # Configuration-based mappings for external types
  Atc.SourceGenerators.MappingCombinedConfiguration.Contract/           # API contracts
    NotificationDto.cs
    UrgencyLevel.cs
  Atc.SourceGenerators.MappingCombinedConfiguration.ExternalNotifications/  # Simulated SDK
    PushNotification.cs
    NotificationPriority.cs
  Atc.SourceGenerators.MappingCombinedConfiguration.ExternalAnalytics/     # Simulated SDK
    AnalyticsEvent.cs
    UserSession.cs
    EventSeverity.cs

🔀 Mixed Mapping Approach

✏️ Attribute-based for types you own (forward mapping to DTOs):

[MapTo(typeof(NotificationDto))]
public partial class Notification
{
    public int Id { get; set; }
    public string Recipient { get; set; } = string.Empty;
    public string Title { get; set; } = string.Empty;
    public string Message { get; set; } = string.Empty;
    public Urgency Urgency { get; set; }
    public DateTime SentAt { get; set; }
    public bool Delivered { get; set; }
}

[MapTo(typeof(UrgencyLevel))]
public enum Urgency { Unknown, Low, Medium, High, Urgent }

🔧 Configuration-based for external types (inbound mapping from SDKs):

[MappingConfiguration]
public static partial class ExternalMappings
{
    // PushNotification -> Notification (property renaming)
    [MapConfigProperty("NotificationId", "Id")]
    [MapConfigProperty("RecipientToken", "Recipient")]
    [MapConfigProperty("Body", "Message")]
    [MapConfigProperty("IsDelivered", "Delivered")]
    [MapConfigProperty("Priority", "Urgency")]
    public static partial Notification MapToNotification(this PushNotification source);

    // AnalyticsEvent -> ActivityEvent (property renaming)
    [MapConfigProperty("EventId", "Id")]
    [MapConfigProperty("EventName", "Name")]
    public static partial ActivityEvent MapToActivityEvent(this AnalyticsEvent source);

    // UserSession -> BrowsingSession (record support)
    [MapConfigProperty("SessionId", "Id")]
    public static partial BrowsingSession MapToBrowsingSession(this UserSession source);
}

🔗 Multi-Hop Mapping Chain

The combined approach enables multi-hop chains that span both mapping styles:

PushNotification (External SDK)
    ↓ .MapToNotification()       ← configuration-based mapping
Notification (Domain)
    ↓ .MapToNotificationDto()    ← attribute-based mapping
NotificationDto (Contract)

// Chain: External SDK -> Domain -> DTO
var domainNotification = pushNotification.MapToNotification();   // config-based
var dto = domainNotification.MapToNotificationDto();             // attribute-based

🎯 Key Takeaways

  1. 🤝 Both approaches coexist: Attribute-based [MapTo] for owned types and [MappingConfiguration] for external types work together seamlessly
  2. 🔗 Multi-hop chains: External SDK types flow through domain models to DTOs, crossing mapping style boundaries
  3. 🎨 Enum auto-detection in both modes: NotificationPriority to Urgency (config-based) and Urgency to UrgencyLevel (attribute-based) both use the special case engine
  4. 📝 Record type support: UserSession record maps to BrowsingSession class including constructor parameter matching
  5. 📦 Multiple external SDKs: Configuration-based mappings can target types from different external assemblies in a single [MappingConfiguration] class

📖 Full documentation: Configuration-Based Mapping

🔄 EnumMapping Sample

🎨 Console app demonstrating intelligent enum-to-enum mapping with special case handling, bidirectional mappings, and case-insensitive matching.

cd sample/Atc.SourceGenerators.EnumMapping
dotnet run

💻 Code Example

using Atc.SourceGenerators.Annotations;
using Atc.Mapping;

// Special case: None → Unknown (auto-detected)
[MapTo(typeof(PetStatusDto), Bidirectional = true)]
public enum PetStatusEntity
{
    None,       // Maps to PetStatusDto.Unknown
    Pending,
    Available,
    Adopted,
}

public enum PetStatusDto
{
    Unknown,    // Maps from PetStatusEntity.None
    Available,
    Pending,
    Adopted,
}

// Usage
var entity = PetStatusEntity.None;
var dto = entity.MapToPetStatusDto();         // PetStatusDto.Unknown
var back = dto.MapToPetStatusEntity();        // PetStatusEntity.None (bidirectional!)

✨ Features Demonstrated

  • 🪄 Special case detection: None ↔ Unknown ↔ Default auto-mapped
  • 🔄 Bidirectional mapping: Both forward and reverse from one attribute
  • 🔤 Case-insensitive matching: ACTIVE matches Active
  • ⚠️ Compile-time warnings: ATCENUM002 for unmapped values
  • 🛡️ Runtime safety: ArgumentOutOfRangeException for unmapped values

📖 Full documentation: Working with Enum Mapping

📋 AnnotationConstants Sample

🏷️ Console app demonstrating compile-time access to DataAnnotation metadata without reflection.

cd sample/Atc.SourceGenerators.AnnotationConstants
dotnet run

💻 Code Example

📝 Model with DataAnnotations:

using System.ComponentModel.DataAnnotations;

public class Product
{
    [Display(Name = "Product Name", Description = "The display name of the product")]
    [Required(ErrorMessage = "Product name is required")]
    [StringLength(100, MinimumLength = 3)]
    public string Name { get; set; } = string.Empty;

    [Display(Name = "Price")]
    [Required]
    [Range(typeof(decimal), "0.01", "999999.99")]
    public decimal Price { get; set; }

    [Display(Name = "SKU")]
    [StringLength(20)]
    [RegularExpression(@"^[A-Z]{3}-\d{4}$")]
    public string? Sku { get; set; }
}

⚡ Access generated constants:

// Zero reflection - compile-time constants!
string label = AnnotationConstants.Product.Name.DisplayName;       // "Product Name"
int maxLen = AnnotationConstants.Product.Name.MaximumLength;       // 100
bool required = AnnotationConstants.Product.Name.IsRequired;       // true

string minPrice = AnnotationConstants.Product.Price.Minimum;       // "0.01"
string pattern = AnnotationConstants.Product.Sku.Pattern;          // "^[A-Z]{3}-\d{4}$"

💡 Use Cases

  • 🖥️ Blazor/MAUI Forms: Generate form labels and validation rules without reflection
  • 📄 API Documentation: Extract constraint metadata for OpenAPI/Swagger
  • 🌐 Client-Side Validation: Send validation rules to JavaScript/TypeScript
  • ⚡ Native AOT Applications: Access metadata without breaking trimming

📖 Full documentation: Working with Annotation Constants

🐾 PetStore API - Complete Example

🌟 Full-featured ASP.NET Core application using all generators together with OpenAPI/Scalar documentation. This is the flagship example demonstrating production-ready patterns.

cd sample/PetStore.Api
dotnet run
# Open https://localhost:42616/scalar/v1 for API documentation

📖 See PetStore API Example for the complete walkthrough with architecture diagrams, code, and request flow sequences.

Viewing Generated Code

To inspect the source code that generators produce for any sample project, use the EmitCompilerGeneratedFiles MSBuild property:

dotnet build sample/PetStore.Domain -p:EmitCompilerGeneratedFiles=true

Generated files appear under:

sample/PetStore.Domain/obj/Debug/net10.0/generated/
  Atc.SourceGenerators/
    Atc.SourceGenerators.Generators.DependencyRegistrationGenerator/
    Atc.SourceGenerators.Generators.OptionsBindingGenerator/
    Atc.SourceGenerators.Generators.ObjectMappingGenerator/
    Atc.SourceGenerators.Generators.EnumMappingGenerator/

Each file contains the complete generated extension methods and registration code. This is useful for debugging mapping logic or understanding what the generator produces.

Tip: In Visual Studio, expand the project node in Solution Explorer under Dependencies > Analyzers > Atc.SourceGenerators to browse generated files directly.

🏠 Home

📖 Getting Started

⚡ Generators

🎯 Examples

🔗 Integrations

🔍 Reference

📋 Feature Roadmaps

🔗 Resources

Clone this wiki locally