Getting Started

🚀 Getting Started

This guide covers installation, package options, and build requirements for Atc Source Generators.

📦 Installation

All generators are distributed in a single NuGet package. Install once to use all features.

✅ Required:

dotnet add package Atc.SourceGenerators

💡 Optional (recommended for better IntelliSense):

dotnet add package Atc.SourceGenerators.Annotations

Or in your .csproj:

<ItemGroup>
  <!-- Required: Source generator -->
  <PackageReference Include="Atc.SourceGenerators" Version="1.0.0" />

  <!-- Optional: Attribute definitions with XML documentation -->
  <PackageReference Include="Atc.SourceGenerators.Annotations" Version="1.0.0" />
</ItemGroup>

📝 About the Annotations Package

The generator emits fallback attributes automatically, so the Annotations package is optional. However, it provides better XML documentation and IntelliSense.

⚠️ If you include it, suppress the expected CS0436 warning:

<PropertyGroup>
  <NoWarn>$(NoWarn);CS0436</NoWarn>
</PropertyGroup>

⚙️ Build-Time Requirements

This package uses Roslyn 5.0.0 (.NET 10) for source generation. To build projects that consume this package:

✅ Required:

• 🛠️ .NET 10 SDK (or later)

📌 Important Notes:

• ✅ Projects targeting .NET 9 (or earlier) CAN successfully build using the .NET 10 SDK
• 💡 This is a build-time requirement only, not a runtime requirement
• 🎯 Your application can still target and run on .NET 9, .NET 8, or earlier framework versions
• ⚙️ The SDK version only affects the build process, not the target framework or runtime

Example:

# Install .NET 10 SDK
# Download from: https://dotnet.microsoft.com/download/dotnet/10.0

# Your project can still target .NET 9
<TargetFramework>net9.0</TargetFramework>

# But requires .NET 10 SDK to build (due to Roslyn 5.0.0 source generator dependency)
dotnet build  # Must use .NET 10 SDK

🤔 Why .NET 10 SDK?

The source generators in this package leverage Roslyn 5.0.0 APIs which ship with .NET 10. While your consuming applications can target any .NET version (including .NET 9, .NET 8, or .NET Framework), the build toolchain requires .NET 10 SDK for proper source generator execution.

🚀 Available Generators

Once installed, you have access to all five generators:

Generator	Attribute	Guide
💉 DependencyRegistration	[Registration]	Working with Dependency Registration
⚙️ OptionsBinding	[OptionsBinding]	Working with Options Binding
🗺️ ObjectMapping	[MapTo(typeof(Target))]	Working with Object Mapping
🔄 EnumMapping	[MapTo(typeof(TargetEnum))]	Working with Enum Mapping
📋 AnnotationConstants	(automatic)	Working with Annotation Constants

🔨 Building & Testing

dotnet build
dotnet test

📚 Next Steps

• 💻 Explore the Sample Projects for working code examples
• 🐾 See the PetStore API Example for a complete application using all generators together