Installation¶

This guide will walk you through installing Flaggy and configuring it for your application.

Prerequisites¶

.NET 6.0, 7.0, 8.0, or 9.0
Visual Studio 2022 or later (recommended)
Visual Studio Code with C# extension (alternative)
A database (MySQL, PostgreSQL, MS SQL) or use InMemory for development

NuGet Package Installation¶

Flaggy is distributed as NuGet packages. You need the core package and at least one provider.

Install Core Package¶

dotnet add package Flaggy

Install a Provider¶

Choose one of the following providers based on your storage backend:

MySQL Provider:

dotnet add package Flaggy.Provider.MySQL

PostgreSQL Provider:

dotnet add package Flaggy.Provider.PostgreSQL

MS SQL Server Provider:

dotnet add package Flaggy.Provider.MsSql

InMemory Provider (included in core):

# No additional package needed - use InMemoryFeatureFlagProvider from Flaggy

Optional Packages¶

Redis Caching (for distributed scenarios):

dotnet add package Flaggy.Caching.Redis

UI Dashboard:

dotnet add package Flaggy.UI

Service Configuration¶

Configure Flaggy in your ASP.NET Core application during startup.

InMemory Provider (Development)¶

The InMemory provider stores flags in memory, making it perfect for development without a database.

using Flaggy.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Use InMemory provider with Memory cache
builder.Services.AddFlaggy(options =>
{
    options.UseInMemory();
    options.UseMemoryCache(TimeSpan.FromMinutes(5));
});

var app = builder.Build();
app.Run();

MySQL Provider¶

MySQL provider includes automatic database migration with version tracking.

using Flaggy.Extensions;

var builder = WebApplication.CreateBuilder(args);

var connectionString = builder.Configuration.GetConnectionString("DefaultConnection")
    ?? "Server=localhost;Database=myapp;User=root;Password=pass;";

// Add Flaggy with MySQL provider and Memory cache
builder.Services.AddFlaggy(options =>
{
    options.UseMySQL(
        connectionString: connectionString,
        tableName: "feature_flags",    // optional, default is "feature_flags"
        userTableName: "users",         // optional, default is "users"
        autoMigrate: true);             // optional, default is true

    options.UseMemoryCache(cacheExpiration: TimeSpan.FromMinutes(5));
});

var app = builder.Build();
app.Run();

Automatically created tables: - feature_flags - Stores your feature flags - users - Stores dashboard users with BCrypt hashed passwords - flaggy_migrations - Tracks schema version

PostgreSQL Provider¶

PostgreSQL provider also includes automatic migration with version tracking.

using Flaggy.Extensions;

var builder = WebApplication.CreateBuilder(args);

var connectionString = builder.Configuration.GetConnectionString("DefaultConnection")
    ?? "Host=localhost;Database=myapp;Username=postgres;Password=pass";

// Add Flaggy with PostgreSQL provider and Memory cache
builder.Services.AddFlaggy(options =>
{
    options.UsePostgreSQL(
        connectionString: connectionString,
        tableName: "feature_flags",    // optional, default is "feature_flags"
        userTableName: "users",         // optional, default is "users"
        autoMigrate: true);             // optional, default is true

    options.UseMemoryCache(cacheExpiration: TimeSpan.FromMinutes(5));
});

var app = builder.Build();
app.Run();

Automatically created tables: - feature_flags - Stores your feature flags - users - Stores dashboard users with BCrypt hashed passwords - flaggy_migrations - Tracks schema version

MS SQL Server Provider¶

MS SQL Server provider includes automatic migration with version tracking.

using Flaggy.Extensions;

var builder = WebApplication.CreateBuilder(args);

var connectionString = builder.Configuration.GetConnectionString("DefaultConnection")
    ?? "Server=localhost;Database=myapp;User Id=sa;Password=pass;TrustServerCertificate=True";

// Add Flaggy with MS SQL provider and Memory cache
builder.Services.AddFlaggy(options =>
{
    options.UseMsSql(
        connectionString: connectionString,
        tableName: "feature_flags",    // optional, default is "feature_flags"
        userTableName: "users",         // optional, default is "users"
        autoMigrate: true);             // optional, default is true

    options.UseMemoryCache(cacheExpiration: TimeSpan.FromMinutes(5));
});

var app = builder.Build();
app.Run();

Automatically created tables: - feature_flags - Stores your feature flags - users - Stores dashboard users with BCrypt hashed passwords - flaggy_migrations - Tracks schema version

UI Dashboard Setup¶

The Flaggy dashboard provides a web interface to manage your feature flags and users.

Install Dashboard Package¶

dotnet add package Flaggy.UI

Configure Dashboard¶

Add the dashboard middleware to your application:

using Flaggy.Extensions;
using Flaggy.UI.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Configure your provider
builder.Services.AddFlaggy(options =>
{
    options.UseMySQL(connectionString);
    options.UseMemoryCache(TimeSpan.FromMinutes(5));
});

var app = builder.Build();

// Add Flaggy UI Dashboard
app.UseFlaggyUI(options =>
{
    options.RoutePrefix = "/flaggy";           // optional, default is "/flaggy"
    options.RequireAuthorization = false;       // optional, default is false
});

app.Run();

Access the Dashboard¶

Navigate to your configured route in your browser:

https://localhost:5001/flaggy

Create Dashboard Users¶

You can create dashboard users programmatically at startup:

using Flaggy.Extensions;
using Flaggy.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddFlaggy(options =>
{
    options.UseMySQL(connectionString);
    options.UseMemoryCache(TimeSpan.FromMinutes(5));
});

var app = builder.Build();

// Seed default users
await app.SeedDashboardUsersAsync(
    new User { Username = "admin", Password = "admin123" },
    new User { Username = "operator", Password = "operator123" }
);

app.UseFlaggyUI();
app.Run();

Custom Authorization¶

Implement custom authorization logic for the dashboard:

app.UseFlaggyUI(options =>
{
    options.RoutePrefix = "/admin/flags";
    options.RequireAuthorization = true;
    options.AuthorizationFilter = context =>
    {
        // Custom authorization logic
        return context.User.IsInRole("Admin");
    };
});

Redis Caching Setup¶

For distributed scenarios across multiple servers, configure Redis caching.

Configure Redis Caching¶

using Flaggy.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Configure MySQL provider with Redis caching
builder.Services.AddFlaggy(options =>
{
    options.UseMySQL(connectionString);
    options.UseRedisCache(
        redisConnectionString: "localhost:6379",
        cacheExpiration: TimeSpan.FromMinutes(10),
        redisDatabase: 0);  // optional, default is 0
});

var app = builder.Build();
app.Run();

Redis Connection String Formats¶

Flaggy supports various Redis connection string formats:

// No authentication
redisConnectionString: "localhost:6379"

// With password
redisConnectionString: "localhost:6379,password=mypassword"

// With username and password (Redis 6+)
redisConnectionString: "localhost:6379,user=myuser,password=mypassword"

// With SSL/TLS
redisConnectionString: "localhost:6380,ssl=true,password=mypassword"

// Multiple hosts (cluster)
redisConnectionString: "server1:6379,server2:6379,server3:6379,password=pass"

Complete Example with Redis¶

using Flaggy.Extensions;
using Flaggy.UI.Extensions;

var builder = WebApplication.CreateBuilder(args);

var connectionString = builder.Configuration.GetConnectionString("DefaultConnection");
var redisConnectionString = builder.Configuration.GetConnectionString("Redis");

// Configure PostgreSQL provider with Redis caching
builder.Services.AddFlaggy(options =>
{
    options.UsePostgreSQL(connectionString);
    options.UseRedisCache(
        redisConnectionString: redisConnectionString ?? "localhost:6379,password=redis123",
        cacheExpiration: TimeSpan.FromMinutes(15));
});

var app = builder.Build();
app.UseFlaggyUI();
app.Run();

User Management Configuration¶

Flaggy includes built-in user management for dashboard access with secure password hashing.

User Model¶

Users have the following properties:

Id - Unique identifier (auto-generated)
Username - Unique username for login
PasswordHash - BCrypt hashed password (never stored in plain text)
CreatedAt - User creation timestamp

Create Users Programmatically¶

using Flaggy.Abstractions;
using Flaggy.Extensions;
using Flaggy.Models;
using Flaggy.UI.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddFlaggy(options =>
{
    options.UseMySQL(connectionString);
    options.UseMemoryCache(TimeSpan.FromMinutes(5));
});

var app = builder.Build();

// Create users at startup
var userProvider = app.Services.GetRequiredService<IUserProvider>();

await userProvider.CreateUserAsync(new User
{
    Username = "admin",
    Password = "SecurePassword123!" // Will be hashed with BCrypt
});

await userProvider.CreateUserAsync(new User
{
    Username = "operator",
    Password = "OperatorPass456!"
});

app.UseFlaggyUI();
app.Run();

Authenticate Users¶

The dashboard uses automatic authentication:

// Users authenticate via the dashboard login form
// The system automatically:
// 1. Verifies username exists
// 2. Compares provided password with stored BCrypt hash
// 3. Creates secure session
// 4. Grants dashboard access

User Management via Dashboard¶

Once the dashboard is running, you can:

Create new users through the admin interface
Change user passwords
Delete users
Manage user permissions

Environment Configuration¶

It's recommended to use appsettings.json for configuration:

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=myapp;User=root;Password=pass;",
    "Redis": "localhost:6379,password=redis123"
  },
  "Flaggy": {
    "CacheExpiration": "00:05:00",
    "AutoMigrate": true,
    "TableName": "feature_flags",
    "UserTableName": "users"
  }
}

Then in Program.cs:

using Flaggy.Extensions;

var builder = WebApplication.CreateBuilder(args);

var connectionString = builder.Configuration.GetConnectionString("DefaultConnection");
var cacheExpiration = TimeSpan.Parse(
    builder.Configuration["Flaggy:CacheExpiration"] ?? "00:05:00"
);

builder.Services.AddFlaggy(options =>
{
    options.UseMySQL(connectionString);
    options.UseMemoryCache(cacheExpiration);
});

var app = builder.Build();
app.Run();

Verification¶

To verify Flaggy is installed and configured correctly:

using Flaggy.Abstractions;
using Flaggy.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddFlaggy(options =>
{
    options.UseMySQL(connectionString);
    options.UseMemoryCache(TimeSpan.FromMinutes(5));
});

var app = builder.Build();

// Verify service is registered
app.MapGet("/health/flaggy", async (IFeatureFlagService flagService) =>
{
    var flags = await flagService.GetAllFlagsAsync();
    return Results.Ok(new { message = "Flaggy is running", flagCount = flags.Count() });
});

app.Run();

Navigate to https://localhost:5001/health/flaggy and you should see a response with the flag count.

Troubleshooting¶

Database Connection Issues¶

If you get connection errors, verify:

Database is running - Ensure your database server is accessible
Connection string is correct - Test with a database client
Credentials are valid - Verify username and password
Database exists - Flaggy will create tables but not the database

Migration Issues¶

If auto-migration fails:

Check logs - Look for specific migration error messages
Set autoMigrate: false - For manual control of schema
Verify schema - Ensure previous migrations applied successfully

Redis Connection Issues¶

If Redis caching isn't working:

Redis is running - Verify Redis server is accessible
Connection string format - Check syntax for your authentication
Firewall rules - Ensure network access to Redis port (usually 6379)

Next Steps¶

Basic Usage - Start using feature flags
Examples - See Flaggy in action
Best Practices - Production-ready patterns