SetSharp 1.3.0

SetSharp

Tired of manually mapping appsettings.json to C# classes? SetSharp is a powerful .NET source generator that automatically creates strongly-typed C# configuration classes directly from your JSON settings, seamlessly integrating with the IOptions pattern.

Say goodbye to magic strings and runtime errors. With SetSharp, your configuration becomes a first-class citizen in your codebase, complete with compile-time safety and IntelliSense support.

Key Features

• Automatic POCO Generation: Mirrors your appsettings.json structure into clean, ready-to-use C# classes.
• Strongly-Typed Access: No more _configuration["Section:Key"]. Access settings with options.Value.Section.Key.
• Seamless DI Integration: Automatically generates extension methods to register your configuration with Dependency Injection using the IOptions pattern.
• Zero Runtime Overhead: All code generation happens at compile time, adding no performance cost to your application.
• Configurable Generation: Easily enable or disable IOptions pattern integration to fit your project's needs.

Prerequisites

Before using SetSharp, ensure your project has the following NuGet packages installed, as they are required for the IOptions pattern integration:

• Microsoft.Extensions.Options.ConfigurationExtensions
• Microsoft.Extensions.DependencyInjection

If these packages are missing and IOptions generation is enabled (which it is by default), you will encounter one of the following compile-time errors:

• SSG002: Indicates that dependencies for IOptions generation are missing.
• SSG003: Indicates that a base dependency (Microsoft.Extensions.Configuration.Abstractions) is missing.

Note: If you disable IOptions pattern generation (see the Configuration section), the Microsoft.Extensions.Options.ConfigurationExtensions package is no longer required.

Getting Started

Follow these steps to integrate SetSharp into your .NET project.

1. Install the NuGet Package

Add the SetSharp NuGet package to your project using the .NET CLI or the NuGet Package Manager.

dotnet add package SetSharp --version 1.3.0

2. Add appsettings.json to your Project File

For the source generator to work its magic, you must explicitly tell the compiler to include your appsettings.json file during the build process. Edit your .csproj file and add the following ItemGroup:

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

3. Build Your Project

That's it! Simply build your project. SetSharp will run automatically, generating your configuration classes in the background.

dotnet build

How to Use

SetSharp generates two key things for you: strongly-typed classes and Dependency Injection extension methods.

1. Generated Configuration Classes

For an appsettings.json like this:

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=.;Database=MyDb;Trusted_Connection=True;"
  },
  "FeatureManagement": {
    "EnableNewDashboard": true
  }
}

SetSharp will generate corresponding C# classes, typically within the SetSharp.Configuration namespace:

namespace SetSharp.Configuration
{
    public class RootOptions
    {
        public ConnectionStringsOptions ConnectionStrings { get; set; }
        public FeatureManagementOptions FeatureManagement { get; set; }
    }

    public class ConnectionStringsOptions
    {
        public const string SectionName = "ConnectionStrings";
        public string DefaultConnection { get; set; }
    }

    public class FeatureManagementOptions
    {
        public const string SectionName = "FeatureManagement";
        public bool EnableNewDashboard { get; set; }
    }
}

2. Dependency Injection with the Options Pattern

SetSharp makes registering these classes with your DI container incredibly simple by generating extension methods for IServiceCollection.

You have two ways to register your settings:

A) Register a specific option:

Use the generated Add[OptionName] method to register a single configuration section.

// In your Program.cs or Startup.cs
builder.Services.AddConnectionStringsOptions(builder.Configuration);

B) Register all options at once:

Use the convenient AddAllGeneratedOptions method to register all settings from your appsettings.json in a single call.

// In your Program.cs or Startup.cs
builder.Services.AddAllGeneratedOptions(builder.Configuration);

Once registered, you can inject your settings anywhere in your application using the standard IOptions<T> interface.

public class MyService
{
    private readonly ConnectionStringsOptions _connectionStrings;

    public MyService(IOptions<ConnectionStringsOptions> connectionStringsOptions)
    {
        _connectionStrings = connectionStringsOptions.Value;
    }

    public void DoWork()
    {
        var connectionString = _connectionStrings.DefaultConnection;
        // ... use the connection string
    }
}

Configuration

You can control the behavior of SetSharp with a setting in your appsettings.json.

Disabling Options Pattern Generation

If you only want the strongly-typed classes and do not need the DI extension methods for the IOptions pattern, you can disable their generation. This also removes the requirement for the Microsoft.Extensions.Options.ConfigurationExtensions package.

Add the following section to your appsettings.json:

{
  "SetSharp": {
    "OptionPatternGenerationEnabled": false
  },
  // ... your other settings
}

Contributing

Contributions are welcome! Whether it's a new feature idea, a bug report, or a pull request, your input is valued. Please feel free to open an issue to discuss your ideas or submit a pull request with your improvements.

License

This project is licensed under the MIT License. See the LICENSE file for details.