Building a Runtime Feature Flag Engine in .NET MAUI

🚩 Building a Runtime Feature Flag Engine in .NET MAUI

Modern mobile applications rarely behave exactly the same for every user. A feature might be available only to beta testers. A redesigned checkout experience might initially be enabled for 5% of customers. An experimental screen might need to disappear immediately if production telemetry reveals a problem. Enterprise customers may receive capabilities that aren't available in the standard edition. The traditional solution is usually some variation of:

    if (user.IsPremium)
    {
        // Show premium feature
    }

That works. Until it doesn't. As the application grows, these conditions begin appearing everywhere:

    if (configuration.EnableNewDashboard)
    {
    }
    
    if (user.Role == "Administrator")
    {
    }
    
    if (Preferences.Get("EnableExperimentalCheckout", false))
    {
    }
    
    if (DeviceInfo.Platform == DevicePlatform.Android)
    {
    }
    
    if (remoteConfig["EnableNewSearch"] == "true")
    {
    }

Soon, feature availability is scattered throughout pages, ViewModels, services, navigation code, configuration files, and platform-specific implementations.

More importantly, changing those decisions may require publishing another application version. For mobile applications, that's a significant limitation.

Users don't necessarily update immediately, store reviews take time, staged deployments can last days, and a production incident may require disabling functionality right now.

That's where a runtime feature flag engine becomes extremely useful. 🚀

In this guide, we'll build a production-oriented feature flag architecture for .NET MAUI that supports:

• 🚩 Runtime feature evaluation
• 💾 Persistent local caching
• ☁️ Remote configuration
• 📱 Offline operation
• 👤 User targeting
• 🏢 Tenant targeting
• 📱 Platform targeting
• 📊 Percentage rollouts
• 🧪 A/B experiments
• 🛡️ Kill switches
• ⏳ Time-based activation
• 🔄 Background refresh
• 🧭 Navigation integration
• 🖼️ UI integration
• ⚙️ Dependency Injection
• 🧪 Automated testing
• 📈 Diagnostics and observability
• 🔐 Security boundaries
• 🏗️ Enterprise architecture considerations

The goal isn't simply to add a few Boolean configuration values. We're going to build a small feature decision engine.

---

📚 Table of Contents

1. 🚩 What Is a Feature Flag?
2. 🤔 Why Feature Flags Matter in Mobile Applications
3. ❌ The Naive Approach
4. 🏗️ Target Architecture
5. 🧩 Feature Flag Types
6. 📦 Designing the Core Contracts
7. 🗂️ Defining Feature Keys
8. 🧠 Building the Evaluation Context
9. 📋 Modeling Feature Definitions
10. ⚙️ Building the Feature Flag Engine
11. 🔗 Implementing Evaluation Rules
12. 📱 Platform-Based Flags
13. 👤 User-Based Targeting
14. 🏢 Tenant-Based Targeting
15. 📊 Percentage Rollouts
16. 🧪 A/B Testing
17. ⏳ Time-Based Flags
18. 🛡️ Kill Switches
19. ☁️ Remote Feature Configuration
20. 💾 Building an Offline Cache
21. 🔄 Runtime Refresh
22. 📡 Connectivity-Aware Synchronization
23. ⚙️ Dependency Injection
24. 🖼️ Feature Flags in the UI
25. 🧭 Feature Flags and Navigation
26. 🧱 Feature-Gated Services
27. 🧩 Feature Flags and Modular Architectures
28. 🔐 Security Considerations
29. ⚡ Performance and Caching
30. 📈 Diagnostics and Observability
31. 🧪 Testing the Engine
32. 🏢 Multi-Tenant Applications
33. 🚀 Progressive Rollouts
34. 🔙 Rollback Strategies
35. ⚠️ Common Mistakes
36. 🧹 Feature Flag Lifecycle Management
37. 🏗️ Suggested Project Structure
38. 📊 Architecture Comparison
39. 🏢 Real-World Enterprise Scenario
40. ✅ Best Practices
41. 🎯 Final Thoughts
42. 📚 References

---

🚩 1. What Is a Feature Flag?

A feature flag, also called a feature toggle, is a runtime decision that determines whether a capability should be enabled. The simplest possible implementation is:

    bool enableNewDashboard = true;
    
    if (enableNewDashboard)
    {
        // Use new dashboard.
    }

But production feature management is considerably more powerful. Instead of asking:

Is NewDashboard enabled?

we might ask:

Is NewDashboard enabled for this particular user, tenant, platform, application version, environment, and rollout bucket at this moment?

That distinction is important. A mature feature flag system is effectively a policy evaluation engine.

---

🤔 2. Why Feature Flags Matter in Mobile Applications

Feature flags are useful everywhere, but mobile development introduces several constraints that make them especially valuable.

When deploying a web application, you can often replace the server deployment immediately. With mobile applications:

1. You publish a new version.
2. The store processes it.
3. Users receive the update.
4. Some users install it immediately.
5. Others wait days or weeks.
6. Some may never update.

This means several application versions can exist simultaneously in production.

Feature flags provide another layer of control.

                        Application Release
                               │
                               ▼
                      ┌─────────────────┐
                      │ Installed Build │
                      └────────┬────────┘
                               │
                               ▼
                     Runtime Feature Engine
                               │
                ┌──────────────┼──────────────┐
                ▼              ▼              ▼
             Enabled        Disabled       Variant
    

You can change behavior without necessarily shipping another binary.

📊 Typical scenarios

Scenario	Feature Flag Benefit
🚀 Gradual release	Enable a feature for a small percentage first
🐞 Production defect	Disable functionality remotely
🧪 Experiment	Compare two experiences
👤 Beta program	Enable features for selected users
🏢 Enterprise edition	Enable capabilities per tenant
📱 Platform issue	Disable only on Android or iOS
🌎 Regional rollout	Enable functionality gradually by market
🔄 Backend migration	Switch clients between implementations
🛡️ Emergency response	Activate a kill switch
📦 Legacy migration	Keep old and new implementations available temporarily

---

❌ 3. The Naive Approach

A common implementation begins with configuration:

    public class FeatureOptions
    {
        public bool NewDashboard { get; set; }
    
        public bool NewCheckout { get; set; }
    
        public bool ExperimentalSearch { get; set; }
    }

Then:

    if (_options.NewDashboard)
    {
        await ShowNewDashboardAsync();
    } 

For a small application, this may be enough. The problems appear when requirements become dynamic. What if NewDashboard should be:

• enabled for Android but not iOS,
• enabled for employees,
• enabled for 10% of customers,
• disabled for app versions below 5.2,
• enabled only after a specific date,
• immediately disabled during an incident?

A Boolean isn't enough anymore. You need rules.

---

🏗️ 4. Target Architecture

Let's design the system around several responsibilities.

                               ┌──────────────────────┐
                               │ Remote Configuration │
                               └───────────┬──────────┘
                                           │
                                           ▼
                                  ┌─────────────────┐
                                  │ Refresh Service │
                                  └────────┬────────┘
                                           │
                                           ▼
                                  ┌─────────────────┐
                                  │ Persistent Cache│
                                  └────────┬────────┘
                                           │
                                           ▼
                               ┌─────────────────────┐
                               │ Feature Flag Engine │
                               └──────────┬──────────┘
                                          │
                 ┌────────────────────────┼────────────────────────┐
                 │                        │                        │
                 ▼                        ▼                        ▼
          Evaluation Context          Flag Definition         Rule Pipeline
                 │                                                 │
         ┌───────┼────────┐                         ┌──────────────┼─────────────┐
         ▼       ▼        ▼                         ▼              ▼             ▼
       User    Tenant   Platform                  User          Percentage      Time
                                                                              Rules
                                          │
                                          ▼
                                  Feature Decision
                                          │
                      ┌───────────────────┼────────────────────┐
                      ▼                   ▼                    ▼
                     UI              Navigation             Services
    

This architecture separates:

• Where flags come from
• How they are stored
• How they're evaluated
• Who is requesting the decision
• What the application does with the result

That separation will become extremely important later.

---

🧩 5. Feature Flag Types

Not every feature flag serves the same purpose.

A useful classification looks like this:

Type	Purpose	Example
🚀 Release flag	Progressive feature deployment	New dashboard
🧪 Experiment flag	A/B testing	Checkout A vs B
🛡️ Operational flag	Runtime protection	Disable image processing
🏢 Entitlement flag	Customer capability	Enterprise reports
📱 Platform flag	Platform-specific control	New Android camera
🔄 Migration flag	Switch implementations	REST v1 → REST v2
🧑‍💻 Development flag	Internal/testing capability	Debug diagnostics

These flags also have different expected lifetimes.

An experiment might exist for two weeks.

An entitlement may exist for years.

A kill switch may remain permanently available.

This matters because feature flags can easily become technical debt.

We'll return to that later.

---

📦 6. Designing the Core Contracts

Let's start with the engine itself.

    public interface IFeatureFlagEngine
    {
        Task<bool> IsEnabledAsync(
            string feature,
            FeatureContext context,
            CancellationToken cancellationToken = default);
    }
    

For applications where the engine can resolve the current user context automatically, we can provide a convenience abstraction:

    public interface IFeatureManager
    {
        Task<bool> IsEnabledAsync(
            string feature,
            CancellationToken cancellationToken = default);
    }

The distinction is useful.

IFeatureFlagEngine is the low-level evaluator.

IFeatureManager is the application-facing facade.

---

🗂️ 7. Defining Feature Keys

Avoid magic strings throughout the application. Bad:

    if (await _featureManager.IsEnabledAsync("new-dashbaord"))
    {
    }

Notice the typo. Instead:

    public static class Features
    {
        public const string NewDashboard = "new-dashboard";
        public const string NewCheckout = "new-checkout";
        public const string NewSearch = "new-search";
        public const string DiagnosticPanel = "diagnostic-panel";
        public const string EmergencyPaymentsKillSwitch =
            "emergency-payments-kill-switch";
    }

Now:

    if (await _featureManager.IsEnabledAsync(Features.NewDashboard))
    {
    }

For larger applications, you can go further and introduce strongly typed identifiers:

    public readonly record struct FeatureKey(string Value);

Then:

    public static class AppFeatures
    {
        public static readonly FeatureKey NewDashboard =
            new("new-dashboard");
    
        public static readonly FeatureKey NewCheckout =
            new("new-checkout");
    }

This makes accidental interchange with arbitrary strings harder.

---

🧠 8. Building the Evaluation Context

Feature decisions need context.

    public sealed record FeatureContext
    {
        public string? UserId { get; init; }
    
        public string? TenantId { get; init; }
    
        public string? Country { get; init; }
    
        public string? AppVersion { get; init; }
    
        public string? Environment { get; init; }
    
        public string Platform { get; init; } = string.Empty;
    
        public IReadOnlyCollection<string> Roles { get; init; }
            = Array.Empty<string>();
    }

In .NET MAUI we can populate some values automatically:

    public sealed class MauiFeatureContextProvider
    {
        public FeatureContext Create(
            string? userId,
            string? tenantId,
            IEnumerable<string>? roles = null)
        {
            return new FeatureContext
            {
                UserId = userId,
                TenantId = tenantId,
                Platform = DeviceInfo.Platform.ToString(),
                AppVersion = AppInfo.Current.VersionString,
                Roles = roles?.ToArray() ?? Array.Empty<string>()
            };
        }
    }

Now the engine knows not only which feature is being evaluated, but for whom and where.

---

📋 9. Modeling Feature Definitions

A feature definition needs more than a Boolean.

    public sealed class FeatureDefinition
    {
        public required string Key { get; init; }
    
        public bool Enabled { get; init; }
    
        public bool KillSwitch { get; init; }
    
        public int? RolloutPercentage { get; init; }
    
        public DateTimeOffset? StartsAtUtc { get; init; }
    
        public DateTimeOffset? EndsAtUtc { get; init; }
    
        public IReadOnlyCollection<string> Users { get; init; }
            = Array.Empty<string>();
    
        public IReadOnlyCollection<string> Tenants { get; init; }
            = Array.Empty<string>();
    
        public IReadOnlyCollection<string> Platforms { get; init; }
            = Array.Empty<string>();
    }

A remote representation might look like:

    {
      "key": "new-dashboard",
      "enabled": true,
      "killSwitch": false,
      "rolloutPercentage": 25,
      "platforms": [
        "Android",
        "iOS"
      ],
      "users": [],
      "tenants": [
        "enterprise-001"
      ]
    }

This already gives us significantly more control than a Boolean configuration value.

---

⚙️ 10. Building the Feature Flag Engine

Let's introduce a definition provider.

    public interface IFeatureDefinitionProvider
    {
        Task<FeatureDefinition?> GetAsync(
            string feature,
            CancellationToken cancellationToken = default);
    }

Now the engine:

    public sealed class FeatureFlagEngine : IFeatureFlagEngine
    {
        private readonly IFeatureDefinitionProvider _definitions;
    
        public FeatureFlagEngine(
            IFeatureDefinitionProvider definitions)
        {
            _definitions = definitions;
        }
    
        public async Task<bool> IsEnabledAsync(
            string feature,
            FeatureContext context,
            CancellationToken cancellationToken = default)
        {
            var definition = await _definitions.GetAsync(
                feature,
                cancellationToken);
    
            if (definition is null)
                return false;
    
            if (!definition.Enabled)
                return false;
    
            if (definition.KillSwitch)
                return false;
    
            if (!MatchesPlatform(definition, context))
                return false;
    
            if (!MatchesTenant(definition, context))
                return false;
    
            if (!MatchesUser(definition, context))
                return false;
    
            if (!MatchesTimeWindow(definition))
                return false;
    
            if (!MatchesRollout(definition, context))
                return false;
    
            return true;
        }
    }

This is our first real decision pipeline.

But putting every rule inside one class will eventually create another monolith.

We can improve it.

---

🔗 11. Implementing Evaluation Rules

Create a rule abstraction.

    public interface IFeatureEvaluationRule
    {
        int Order { get; }
    
        ValueTask<bool> EvaluateAsync(
            FeatureDefinition definition,
            FeatureContext context,
            CancellationToken cancellationToken);
    }

Now individual policies become isolated.

    public sealed class PlatformRule : IFeatureEvaluationRule
    {
        public int Order => 100;
    
        public ValueTask<bool> EvaluateAsync(
            FeatureDefinition definition,
            FeatureContext context,
            CancellationToken cancellationToken)
        {
            if (definition.Platforms.Count == 0)
                return ValueTask.FromResult(true);
    
            var matches = definition.Platforms.Any(
                x => string.Equals(
                    x,
                    context.Platform,
                    StringComparison.OrdinalIgnoreCase));
    
            return ValueTask.FromResult(matches);
        }
    }

Then:

    public sealed class RuleBasedFeatureFlagEngine : IFeatureFlagEngine
    {
        private readonly IFeatureDefinitionProvider _definitions;
        private readonly IReadOnlyList<IFeatureEvaluationRule> _rules;
    
        public RuleBasedFeatureFlagEngine(
            IFeatureDefinitionProvider definitions,
            IEnumerable<IFeatureEvaluationRule> rules)
        {
            _definitions = definitions;
    
            _rules = rules
                .OrderBy(x => x.Order)
                .ToArray();
        }
    
        public async Task<bool> IsEnabledAsync(
            string feature,
            FeatureContext context,
            CancellationToken cancellationToken = default)
        {
            var definition = await _definitions.GetAsync(
                feature,
                cancellationToken);
    
            if (definition is null || !definition.Enabled)
                return false;
    
            foreach (var rule in _rules)
            {
                cancellationToken.ThrowIfCancellationRequested();
    
                if (!await rule.EvaluateAsync(
                        definition,
                        context,
                        cancellationToken))
                {
                    return false;
                }
            }
    
            return true;
        }
    }

Now the engine follows the Open/Closed Principle. Adding another rule doesn't require modifying the evaluator.

---

📱 12. Platform-Based Flags

Suppose a new camera implementation works well on Android but still has issues on iOS.

Instead of delaying the entire release:

    {
      "key": "new-camera",
      "enabled": true,
      "platforms": [
        "Android"
      ]
    }

The engine automatically rejects iOS:

    New Camera
         │
         ▼
    Enabled?
      Yes
         │
         ▼
    Platform Allowed?
         │
     ┌───┴────┐
     │        │
    Android   iOS
     │        │
     ▼        ▼
    YES       NO
    

This is extremely useful during platform-specific migrations.

---

👤 13. User-Based Targeting

Beta users can receive functionality first.

    public sealed class UserTargetingRule : IFeatureEvaluationRule
    {
        public int Order => 200;
    
        public ValueTask<bool> EvaluateAsync(
            FeatureDefinition definition,
            FeatureContext context,
            CancellationToken cancellationToken)
        {
            if (definition.Users.Count == 0)
                return ValueTask.FromResult(true);
    
            if (string.IsNullOrWhiteSpace(context.UserId))
                return ValueTask.FromResult(false);
    
            var enabled = definition.Users.Contains(
                context.UserId,
                StringComparer.OrdinalIgnoreCase);
    
            return ValueTask.FromResult(enabled);
        }
    }

Now your backend configuration could specify:

    {
      "key": "experimental-search",
      "enabled": true,
      "users": [
        "user-1002",
        "user-1048",
        "user-2025"
      ]
    }

---

🏢 14. Tenant-Based Targeting

For enterprise applications, tenant targeting is even more useful. Imagine three customers:

    Application
       │
       ├── Contoso
       ├── Fabrikam
       └── AdventureWorks

Only Contoso purchased Advanced Analytics.

    {
      "key": "advanced-analytics",
      "enabled": true,
      "tenants": [
        "contoso"
      ]
    }

Your UI doesn't need hardcoded customer checks. Bad:

    if (_tenant.Name == "Contoso")
    {
    }

Better:

    if (await _features.IsEnabledAsync(
            Features.AdvancedAnalytics))
    {
    }

Business policy is moved out of presentation logic.

---

📊 15. Percentage Rollouts

This is where feature flags become especially powerful. Suppose you want to release NewCheckout gradually.

Day 1

5%

Day 3

20%

Day 7

50%

Day 14

100%

A critical requirement is stable assignment. Don't do this:

    return Random.Shared.Next(0, 100) < percentage;

That would cause users to move in and out of the feature every time it is evaluated. 😬 Instead, calculate a deterministic bucket.

    public static int GetStableBucket(
        string feature,
        string userId)
    {
        var value = $"{feature}:{userId}";
    
        var bytes = SHA256.HashData(
            Encoding.UTF8.GetBytes(value));
    
        var number = BitConverter.ToUInt32(bytes, 0);
    
        return (int)(number % 100);
    }

Then:

    var bucket = GetStableBucket(
        definition.Key,
        context.UserId!);
    
    return bucket < definition.RolloutPercentage;

A user assigned to bucket 12 remains in bucket 12.

---

📊 Rollout Example

User	Bucket	10% Rollout	25% Rollout	50% Rollout
👤 A	4	✅	✅	✅
👤 B	17	❌	✅	✅
👤 C	38	❌	❌	✅
👤 D	71	❌	❌	❌
👤 E	95	❌	❌	❌

As rollout increases, previously enabled users remain enabled.

That's exactly what we want.

---

🧪 16. A/B Testing

Feature flags can also select variants. Instead of:

    bool enabled;

you may return:

    public sealed record FeatureDecision(
        bool Enabled,
        string? Variant = null);

Possible variants:

    checkout-control
    checkout-a
    checkout-b

For example:

| Bucket | Variant | | --: | --- | | 0–49 | 🅰️ Checkout A | | 50–99 | 🅱️ Checkout B | Then:

    var decision =
        await _featureManager.EvaluateAsync(
            Features.CheckoutExperiment);
    
    switch (decision.Variant)
    {
        case "checkout-a":
            await ShowCheckoutAAsync();
            break;
    
        case "checkout-b":
            await ShowCheckoutBAsync();
            break;
    
        default:
            await ShowLegacyCheckoutAsync();
            break;
    }

⚠️ Important

A feature flag engine can assign variants, but proper experimentation also requires:

• Exposure tracking
• Conversion events
• Statistical analysis
• Experiment start/end governance
• Stable assignment
• Privacy considerations

Feature flags and experimentation overlap, but they aren't exactly the same system.

---

⏳ 17. Time-Based Flags

Some features should activate automatically.

    public sealed class TimeWindowRule : IFeatureEvaluationRule
    {
        private readonly TimeProvider _timeProvider;
    
        public TimeWindowRule(TimeProvider timeProvider)
        {
            _timeProvider = timeProvider;
        }
    
        public int Order => 300;
    
        public ValueTask<bool> EvaluateAsync(
            FeatureDefinition definition,
            FeatureContext context,
            CancellationToken cancellationToken)
        {
            var now = _timeProvider.GetUtcNow();
    
            if (definition.StartsAtUtc is { } start &&
                now < start)
            {
                return ValueTask.FromResult(false);
            }
    
            if (definition.EndsAtUtc is { } end &&
                now >= end)
            {
                return ValueTask.FromResult(false);
            }
    
            return ValueTask.FromResult(true);
        }
    }

Using TimeProvider instead of directly calling DateTime.UtcNow makes testing much easier.

---

🛡️ 18. Kill Switches

One of the highest-value applications of feature management is the kill switch.

Imagine a new image processing engine causes crashes on certain Android devices.

Without remote control:

    Bug discovered
          ↓
    Fix developed
          ↓
    New build
          ↓
    Store submission
          ↓
    Review
          ↓
    User update

With a kill switch:

    Bug discovered
          ↓
    Remote flag changed
          ↓
    Clients refresh
          ↓
    Feature disabled

🔥 Huge operational difference.

A kill switch should usually take precedence over ordinary targeting.

                     Feature Evaluation
                            │
                            ▼
                      Kill Switch?
                      /          \
                   YES            NO
                    │              │
                    ▼              ▼
                DISABLED      Continue Rules

For safety-critical operational flags, fail-safe behavior should be explicitly designed.

---

☁️ 19. Remote Feature Configuration

So far, our definitions could come from anywhere. That's intentional.

    public interface IRemoteFeatureSource
    {
        Task<IReadOnlyCollection<FeatureDefinition>> GetAsync(
            CancellationToken cancellationToken = default);
    }

Possible implementations include:

• ☁️ Azure App Configuration
• 🌐 Your REST API
• 🔥 Firebase Remote Config
• 📦 Custom configuration service
• 🏢 Internal enterprise configuration platform

Your engine should not depend directly on any one vendor.

    Azure App Configuration ─┐
                             │
    Custom REST API ─────────┼──► IRemoteFeatureSource
                             │
    Other Provider ──────────┘
                                      │
                                      ▼
                             Feature Flag Engine

That abstraction protects the application architecture from provider-specific concerns.

---

💾 20. Building an Offline Cache

Mobile applications cannot assume connectivity. If the application requires network access every time this executes:

    await _featureManager.IsEnabledAsync(...);

the architecture is already problematic. Feature evaluation should usually happen locally. Remote systems should refresh definitions, not participate in every decision.

    Remote Server
          │
          │ periodic refresh
          ▼
    Local Persistent Cache
          │
          ▼
    In-Memory Snapshot
          │
          ▼
    Feature Evaluation

Define storage:

    public interface IFeatureFlagStore
    {
        Task<IReadOnlyCollection<FeatureDefinition>> LoadAsync(
            CancellationToken cancellationToken = default);
    
        Task SaveAsync(
            IReadOnlyCollection<FeatureDefinition> definitions,
            CancellationToken cancellationToken = default);
    }

A JSON-backed implementation could serialize the current snapshot into FileSystem.AppDataDirectory.

    var path = Path.Combine(
        FileSystem.AppDataDirectory,
        "feature-flags.json");

Cache strategy

State	Behavior
🌐 Online + cache exists	Use cache immediately, refresh remotely
🌐 Online + no cache	Fetch remote definitions
📴 Offline + cache exists	Use cached definitions
📴 Offline + no cache	Use safe defaults
❌ Remote refresh fails	Keep last known good snapshot
⚠️ Remote payload invalid	Reject update and keep previous snapshot

This pattern is extremely important.

Never destroy a known-good configuration because a refresh failed.

---

🔄 21. Runtime Refresh

Flags become far more useful when they can change while the app is running.

    public interface IFeatureRefreshService
    {
        Task RefreshAsync(
            CancellationToken cancellationToken = default);
    }

Implementation:

    public sealed class FeatureRefreshService
        : IFeatureRefreshService
    {
        private readonly IRemoteFeatureSource _remote;
        private readonly IFeatureFlagStore _store;
        private readonly FeatureSnapshotProvider _snapshot;
    
        public FeatureRefreshService(
            IRemoteFeatureSource remote,
            IFeatureFlagStore store,
            FeatureSnapshotProvider snapshot)
        {
            _remote = remote;
            _store = store;
            _snapshot = snapshot;
        }
    
        public async Task RefreshAsync(
            CancellationToken cancellationToken = default)
        {
            var definitions =
                await _remote.GetAsync(cancellationToken);
    
            await _store.SaveAsync(
                definitions,
                cancellationToken);
    
            _snapshot.Replace(definitions);
        }
    }

The refresh pipeline becomes:

    Refresh Requested
          │
          ▼
    Download Configuration
          │
          ▼
    Validate Configuration
          │
          ▼
    Persist Snapshot
          │
          ▼
    Swap In-Memory Snapshot
          │
          ▼
    Notify Interested UI

Notice that the active snapshot changes only after the new configuration has been validated.

---

📡 22. Connectivity-Aware Synchronization

.NET MAUI exposes connectivity information through Connectivity. You can use it as a hint:

    if (Connectivity.Current.NetworkAccess ==
        NetworkAccess.Internet)
    {
        await _refreshService.RefreshAsync();
    }

You can also react to connectivity changes:

    Connectivity.Current.ConnectivityChanged +=
        OnConnectivityChanged;

But connectivity APIs don't guarantee that your backend is reachable.

The device might technically have internet access while:

• DNS fails,
• your API is unavailable,
• authentication expired,
• a captive portal intercepts requests.

Therefore:

Connectivity should optimize refresh behavior, not determine correctness.

Remote refresh must still handle network failures normally.

---

⚙️ 23. Dependency Injection

Register the architecture in MauiProgram.cs.

    builder.Services.AddSingleton<FeatureSnapshotProvider>();
    
    builder.Services.AddSingleton<IFeatureFlagStore, JsonFeatureFlagStore>();
    
    builder.Services.AddSingleton<IRemoteFeatureSource, ApiFeatureSource>();
    
    builder.Services.AddSingleton<IFeatureDefinitionProvider, CachedFeatureDefinitionProvider>();
    
    builder.Services.AddSingleton<IFeatureEvaluationRule, KillSwitchRule>();
    builder.Services.AddSingleton<IFeatureEvaluationRule, PlatformRule>();
    builder.Services.AddSingleton<IFeatureEvaluationRule, UserTargetingRule>();
    builder.Services.AddSingleton<IFeatureEvaluationRule, TenantTargetingRule>();
    builder.Services.AddSingleton<IFeatureEvaluationRule, TimeWindowRule>();
    builder.Services.AddSingleton<IFeatureEvaluationRule, PercentageRolloutRule>();
    
    builder.Services.AddSingleton<IFeatureFlagEngine, RuleBasedFeatureFlagEngine>();
    
    builder.Services.AddSingleton<IFeatureManager, FeatureManager>();
    
    builder.Services.AddSingleton<IFeatureRefreshService, FeatureRefreshService>();
    
    builder.Services.AddSingleton(TimeProvider.System);

The application layer only needs:

    IFeatureManager

Most pages shouldn't know anything about remote configuration, caching, hashing, targeting rules, or synchronization.

---

🖼️ 24. Feature Flags in the UI

A ViewModel can evaluate a feature.

    public partial class HomeViewModel : ObservableObject
    {
        private readonly IFeatureManager _features;
    
        [ObservableProperty]
        private bool isNewDashboardEnabled;
    
        public HomeViewModel(IFeatureManager features)
        {
            _features = features;
        }
    
        public async Task InitializeAsync()
        {
            IsNewDashboardEnabled =
                await _features.IsEnabledAsync(
                    Features.NewDashboard);
        }
    }

XAML:

    <Button
        Text="Open New Dashboard"
        IsVisible="{Binding IsNewDashboardEnabled}" />

This is much cleaner than embedding feature evaluation logic throughout XAML converters or code-behind.

---

🧭 25. Feature Flags and Navigation

Flags can protect navigation too.

Hiding a button is not enough.

A route might still be reached through:

• Deep links
• Programmatic navigation
• Restored navigation state
• Notifications
• Custom URI handlers

Create a navigation guard:

    public sealed class FeatureNavigationGuard
    {
        private readonly IFeatureManager _features;
    
        public FeatureNavigationGuard(
            IFeatureManager features)
        {
            _features = features;
        }
    
        public async Task<bool> CanNavigateAsync(
            string requiredFeature)
        {
            return await _features.IsEnabledAsync(
                requiredFeature);
        }
    }

Usage:

    if (!await _guard.CanNavigateAsync(
            Features.AdvancedReports))
    {
        return;
    }
    
    await Shell.Current.GoToAsync(
        nameof(AdvancedReportsPage));

🛡️ Defense in depth

    Feature Flag
        │
        ├── UI Visibility
        │
        ├── Navigation Guard
        │
        └── Service / API Authorization

The feature flag improves UX.

The backend still enforces authorization.

---

🧱 26. Feature-Gated Services

Sometimes the feature controls an implementation rather than a screen.

Suppose you're migrating from a legacy API.

    public interface ICheckoutService
    {
        Task CheckoutAsync();
    }

Two implementations:

    public sealed class LegacyCheckoutService
        : ICheckoutService
    {
        public Task CheckoutAsync()
        {
            // Existing implementation.
            return Task.CompletedTask;
        }
    }
    

    public sealed class NewCheckoutService
        : ICheckoutService
    {
        public Task CheckoutAsync()
        {
            // New implementation.
            return Task.CompletedTask;
        }
    }

Feature-aware facade:

    public sealed class FeatureAwareCheckoutService
        : ICheckoutService
    {
        private readonly IFeatureManager _features;
        private readonly LegacyCheckoutService _legacy;
        private readonly NewCheckoutService _modern;
    
        public FeatureAwareCheckoutService(
            IFeatureManager features,
            LegacyCheckoutService legacy,
            NewCheckoutService modern)
        {
            _features = features;
            _legacy = legacy;
            _modern = modern;
        }
    
        public async Task CheckoutAsync()
        {
            if (await _features.IsEnabledAsync(
                    Features.NewCheckout))
            {
                await _modern.CheckoutAsync();
                return;
            }
    
            await _legacy.CheckoutAsync();
        }
    }

The consumer remains unaware of the migration.

🔥 This is an excellent pattern for safely replacing production implementations.

---

🧩 27. Feature Flags and Modular Architectures

Feature flags pair extremely well with modular/plugin architectures. Imagine:

    Host Application
          │
          ├── Orders Module
          ├── Reports Module
          ├── Analytics Module
          └── Support Module

Feature flags can determine which modules appear in the user experience.

    if (await features.IsEnabledAsync(
            Features.Analytics))
    {
        menu.Add(analyticsMenuItem);
    }

But there's an important architectural distinction:

A runtime feature flag does not necessarily mean the assembly itself should be dynamically loaded or unloaded.

In many MAUI applications, the code remains packaged with the application while runtime flags control whether it is reachable or active.

This avoids unnecessary complexity with:

• AOT
• Trimming
• Assembly loading
• Native platform packaging
• App Store constraints

---

🔐 28. Security Considerations

This deserves special attention.

🚨 Feature flags are not authorization. Never assume this:

    if (!await features.IsEnabledAsync("admin-panel"))
    {
        return;
    }

protects sensitive backend operations. A modified client could bypass the check. The server must independently authorize the operation.

Correct model

                 MAUI Client
                     │
              Feature Flag Check
                     │
                     ▼
                Show Feature
                     │
                     ▼
                 API Request
                     │
                     ▼
            Server Authorization
                     │
                ┌────┴────┐
                ▼         ▼
             Allowed    Denied

🔒 Sensitive flag data

Avoid putting secrets into flag definitions. Bad:

    {
      "apiKey": "super-secret-key"
    }

Feature configuration should be treated as client-readable configuration. Even if stored securely, assume a determined user can inspect the application.

---

⚡ 29. Performance and Caching

Feature evaluation can occur frequently. Consider a page with:

12 buttons
8 menu entries
5 cards
4 navigation actions

If every decision performs an HTTP request, performance will be terrible. The evaluation path should ideally be:

    Feature Request
          │
          ▼
    In-Memory Snapshot
          │
          ▼
    Local Rule Evaluation
          │
          ▼
    Decision

No network. No disk. No JSON parsing.

📊 Comparison

Strategy	Latency	Offline	Recommended
🌐 Remote request per evaluation	High	❌	❌
💾 Disk read per evaluation	Medium	✅	❌
🧠 In-memory snapshot	Very low	✅	✅
🧠 Memory + periodic refresh	Very low	✅	⭐ Best

Use immutable or effectively immutable snapshots whenever possible.

---

📈 30. Diagnostics and Observability

When feature flags influence production behavior, you eventually need to answer:

Why did this user receive this experience?

A simple Boolean doesn't tell you. Consider a richer decision:

    public sealed record FeatureDecision(
        string Feature,
        bool Enabled,
        string Reason,
        string? Variant = null,
        DateTimeOffset? EvaluatedAt = null);

Possible reasons:

• GloballyDisabled
• KillSwitchActive
• PlatformMismatch
• TenantMismatch
• UserTargeted
• RolloutIncluded
• RolloutExcluded
• TimeWindowExpired
• Enabled

Example:

    new FeatureDecision(
        Feature: "new-checkout",
        Enabled: false,
        Reason: "RolloutExcluded",
        EvaluatedAt: DateTimeOffset.UtcNow);

This is extremely useful for diagnostics.

📊 Useful telemetry

Track aggregate information such as:

• Feature evaluated
• Feature enabled
• Variant selected
• Configuration refreshed
• Configuration refresh failed
• Snapshot age
• Invalid configuration rejected

Be careful with user identifiers and privacy-sensitive telemetry.

---

🧪 31. Testing the Engine

One major benefit of separating evaluation rules is testability.

Platform test

    [Fact]
    public async Task AndroidOnlyFeature_ShouldBeDisabledOnIos()
    {
        var definition = new FeatureDefinition
        {
            Key = "camera-v2",
            Enabled = true,
            Platforms = new[] { "Android" }
        };
    
        var context = new FeatureContext
        {
            Platform = "iOS"
        };
    
        var rule = new PlatformRule();
    
        var result = await rule.EvaluateAsync(
            definition,
            context,
            CancellationToken.None);
    
        Assert.False(result);
    }

Tenant test

    [Fact]
    public async Task Feature_ShouldBeEnabledForConfiguredTenant()
    {
        var definition = new FeatureDefinition
        {
            Key = "enterprise-reports",
            Enabled = true,
            Tenants = new[] { "contoso" }
        };
    
        var context = new FeatureContext
        {
            TenantId = "contoso"
        };
    
        var rule = new TenantTargetingRule();
    
        Assert.True(await rule.EvaluateAsync(
            definition,
            context,
            CancellationToken.None));
    }

Rollout stability test

    [Fact]
    public void Bucket_ShouldBeStable()
    {
        var first = StableBucket.Get(
            "new-dashboard",
            "user-123");
    
        var second = StableBucket.Get(
            "new-dashboard",
            "user-123");
    
        Assert.Equal(first, second);
    }

Offline fallback test

    [Fact]
    public async Task FailedRefresh_ShouldKeepPreviousSnapshot()
    {
        // Arrange known-good cached configuration.
    
        // Simulate remote failure.
    
        // Verify active configuration remains unchanged.
    }

These tests become essential once flags influence critical workflows.

---

🏢 32. Multi-Tenant Applications

Enterprise MAUI applications frequently support multiple organizations from one application binary. Feature flags can act as a runtime capability layer.

                        MAUI Application
                               │
                 ┌─────────────┼─────────────┐
                 ▼             ▼             ▼
              Tenant A      Tenant B      Tenant C
                 │             │             │
              Standard      Premium       Custom

Configuration:

    {
      "features": {
        "advanced-reports": {
          "enabled": true,
          "tenants": [
            "tenant-b",
            "tenant-c"
          ]
        }
      }
    }

This is useful for:

• 🏢 Enterprise licensing
• 🎨 White-label experiences
• 🧩 Optional modules
• 🌎 Regional functionality
• 🧪 Customer-specific pilots

However, commercial entitlements should normally also be enforced server-side.

---

🚀 33. Progressive Rollouts

A safe rollout might look like:

    Internal Users
          │
          ▼
         1%
          │
          ▼
         5%
          │
          ▼
        10%
          │
          ▼
        25%
          │
          ▼
        50%
          │
          ▼
       100%

At every stage you monitor:

• 💥 Crash rate
• ⏱️ Response times
• 📉 Failure rates
• 👤 User feedback
• 📊 Conversion
• 🔋 Resource consumption

If something degrades:

    50%
     │
     ▼
    Problem detected
     │
     ▼
    Kill switch / rollback
     │
     ▼
    0%

No new mobile binary required for the flag change itself.

---

🔙 34. Rollback Strategies

Feature flags enable several rollback patterns.

🛡️ Immediate Disable

New implementation → OFF
Legacy implementation → ON

📉 Rollout Reduction

50% → 10%

📱 Platform Rollback

Android → OFF
iOS → ON

🏢 Tenant Rollback

Tenant A → OFF
Other tenants → ON

This level of precision is difficult to achieve with application releases alone.

---

⚠️ 35. Common Mistakes

❌ Calling the Server for Every Evaluation

Feature decisions should generally be local.

---

❌ Using Random Percentage Assignment

    Random.Shared.Next(...)

will create inconsistent experiences. Use deterministic bucketing.

---

❌ Treating Flags as Authorization

The client cannot be trusted as the final security boundary.

---

❌ Keeping Flags Forever

Old flags accumulate quickly.

• NewDashboard
• NewDashboardV2
• UseNewDashboard
• DashboardExperiment
• DashboardMigration
• DashboardFinal

😵 Remove obsolete flags.

---

❌ Feature Logic Everywhere

Avoid:

    if (flag)

in dozens of unrelated classes. Prefer feature-aware abstractions when behavior becomes complex.

---

❌ No Offline Strategy

Mobile connectivity is unreliable by definition. Always define fallback behavior.

---

❌ Replacing Good Configuration with Bad Data

Remote refresh should be transactional:

    Download
       ↓
    Validate
       ↓
    Persist
       ↓
    Activate

Never:

    Download
       ↓
    Immediately Activate
       ↓
    Discover Invalid Configuration 💥

---

🧹 36. Feature Flag Lifecycle Management

Feature flags should have owners. A useful metadata model might include:

    public sealed record FeatureMetadata(
        string Owner,
        string Purpose,
        DateTimeOffset CreatedAt,
        DateTimeOffset? ExpectedRemovalDate);

Example:

    Feature: new-checkout
    Owner: Payments Team
    Type: Release
    Created: 2026-04-01
    Expected Removal: 2026-06-15

Once rollout reaches 100% and the old implementation is removed, the flag should usually disappear too.

📊 Suggested policy

Flag Type	Typical Lifetime
🚀 Release	Days / weeks
🧪 Experiment	Weeks
🔄 Migration	Weeks / months
🛡️ Operational	Long-lived
🏢 Entitlement	Long-lived
🧑‍💻 Development	Short-lived

Without lifecycle management, feature flags become architecture debt.

---

🏗️ 37. Suggested Project Structure

A clean implementation could look like:

    Features/
    │
    ├── Abstractions/
    │   ├── IFeatureManager.cs
    │   ├── IFeatureFlagEngine.cs
    │   ├── IFeatureDefinitionProvider.cs
    │   ├── IFeatureFlagStore.cs
    │   └── IRemoteFeatureSource.cs
    │
    ├── Models/
    │   ├── FeatureDefinition.cs
    │   ├── FeatureContext.cs
    │   └── FeatureDecision.cs
    │
    ├── Evaluation/
    │   ├── FeatureFlagEngine.cs
    │   ├── KillSwitchRule.cs
    │   ├── PlatformRule.cs
    │   ├── UserTargetingRule.cs
    │   ├── TenantTargetingRule.cs
    │   ├── TimeWindowRule.cs
    │   └── PercentageRolloutRule.cs
    │
    ├── Storage/
    │   ├── JsonFeatureFlagStore.cs
    │   └── FeatureSnapshotProvider.cs
    │
    ├── Remote/
    │   └── ApiFeatureSource.cs
    │
    ├── Synchronization/
    │   └── FeatureRefreshService.cs
    │
    └── Diagnostics/
        └── FeatureDiagnostics.cs

This is significantly easier to evolve than a single FeatureService containing everything.

---

📊 38. Architecture Comparison

Capability	Hardcoded Boolean	Remote Boolean	Runtime Feature Engine
🚩 Enable/disable	✅	✅	✅
☁️ Remote changes	❌	✅	✅
📴 Offline support	✅	⚠️	✅
👤 User targeting	❌	⚠️	✅
🏢 Tenant targeting	❌	⚠️	✅
📱 Platform targeting	❌	⚠️	✅
📊 Percentage rollout	❌	❌	✅
🧪 Experiments	❌	❌	✅
🛡️ Kill switches	❌	✅	✅
⏳ Scheduling	❌	⚠️	✅
📈 Decision diagnostics	❌	❌	✅
🧪 Rule-level testing	❌	❌	✅
🔄 Last-known-good fallback	❌	⚠️	✅

---

🏢 39. Real-World Enterprise Scenario

Imagine a retail application used by thousands of employees.

A new inventory scanner is ready.

The company doesn't want to release it to everyone immediately.

Stage 1 — Development

    Employees in development group only

Stage 2 — Pilot Stores

    Tenant / Store IDs:
    101
    204
    309

Stage 3 — Android Rollout

Platform: Android
Rollout: 10%

Stage 4 — Expanded Rollout

Platform: Android
Rollout: 50%

Stage 5 — All Android Users

Android: 100%
iOS: 0%

Stage 6 — Full Deployment

Android: 100%
iOS: 100%

Then a crash appears on a specific platform version. Instead of rolling back the entire application:

    Inventory Scanner
           │
           ├── Android affected version → OFF
           │
           ├── Android other versions → ON
           │
           └── iOS → ON

That is the operational power of feature flags.

---

✅ 40. Best Practices

🚩 Flag Design

• ✅ Give every feature a stable identifier.
• ✅ Define safe defaults.
• ✅ Classify flags by purpose.
• ✅ Assign ownership.
• ✅ Define expected removal dates for temporary flags.

🧠 Evaluation

• ✅ Evaluate locally.
• ✅ Use deterministic rollout buckets.
• ✅ Make rules independently testable.
• ✅ Return diagnostic reasons when useful.
• ✅ Use immutable snapshots.

☁️ Remote Configuration

• ✅ Treat remote configuration as synchronization.
• ✅ Validate before activation.
• ✅ Preserve last-known-good configuration.
• ✅ Handle remote failures gracefully.
• ✅ Never put secrets in feature definitions.

📴 Offline

• ✅ Persist a snapshot.
• ✅ Define first-launch defaults.
• ✅ Never require connectivity for normal evaluation.
• ✅ Treat connectivity APIs as hints.

🔒 Security

• ✅ Never replace server authorization with feature flags.
• ✅ Assume client-side configuration can be inspected.
• ✅ Protect commercial entitlements server-side.
• ✅ Minimize sensitive targeting data.

⚡ Performance

• ✅ Keep decisions in memory.
• ✅ Avoid HTTP calls during evaluation.
• ✅ Avoid disk access during evaluation.
• ✅ Cache deterministic context where appropriate.

🧪 Testing

• ✅ Test every rule independently.
• ✅ Test percentage stability.
• ✅ Test offline startup.
• ✅ Test corrupted configuration.
• ✅ Test failed refresh.
• ✅ Test kill-switch precedence.
• ✅ Test navigation protection.

🧹 Maintenance

• ✅ Remove completed rollout flags.
• ✅ Remove obsolete code paths.
• ✅ Track flag ownership.
• ✅ Audit long-lived flags regularly.

---

🎯 41. Final Thoughts

Feature flags are often introduced as a simple mechanism:

    if (enabled)
    {
    }

But at scale, they become much more than Boolean configuration.

A well-designed runtime feature flag engine can become an operational control plane for your .NET MAUI application.

It allows teams to: 🚀 release features progressively, 🧪 run controlled experiments, 🛡️ disable problematic functionality, 📱 isolate platform-specific issues, 🏢 customize enterprise experiences, 👤 target specific users, 📊 control percentage rollouts, 🔄 migrate between implementations, and 📴 continue making decisions even when the device is offline.

The most important architectural principle is to separate feature evaluation from feature synchronization.

Your application shouldn't contact a remote service every time it needs a decision.

Instead:

    Remote Configuration
            │
            ▼
         Refresh
            │
            ▼
    Persistent Last-Known-Good Snapshot
            │
            ▼
    In-Memory Configuration
            │
            ▼
    Local Decision Engine
            │
            ▼
    Application Behavior

That design is fast, resilient, testable, provider-independent, and appropriate for the realities of mobile applications.

And perhaps the biggest benefit is operational.

A traditional release answers:

What code did we ship?

A runtime feature engine lets you answer another question:

What functionality should this particular user receive right now?

For large .NET MAUI applications, that can be an extremely powerful capability. 🚀

---

📚 42. References

Resource	Description
📘 .NET MAUI Documentation	Official .NET MAUI documentation
🚩 Feature management in .NET	Microsoft's .NET feature-management reference
☁️ Azure App Configuration	Centralized configuration and feature management
🚩 Azure App Configuration Feature Management	Feature flag concepts and management
📱 .NET MAUI Connectivity	Network connectivity APIs in MAUI
💾 .NET MAUI File System Helpers	Application data and cache directories
🔐 .NET MAUI Secure Storage	Securely storing small key/value data
⚙️ .NET MAUI Dependency Injection	DI architecture in .NET MAUI
🧭 .NET MAUI Shell Navigation	Shell navigation and route architecture
📱 .NET MAUI Device Information	Platform/device context
📦 .NET MAUI App Information	Application version and package information
⏰ TimeProvider	Testable abstraction for time-based rules
🔐 SHA256	Deterministic hashing foundation for rollout buckets
🧪 xUnit	Unit testing framework for .NET
🧰 .NET Community Toolkit	.NET helper libraries
📱 .NET Community Toolkit MVVM	MVVM helpers useful for feature-aware ViewModels

---

🚀 Where to Go From Here

Once this architecture is working, several interesting extensions become possible:

• 📊 Build an A/B Experiment Engine
• 🧩 Integrate flags with a Plugin Architecture
• 📈 Build a Feature Telemetry Dashboard
• 📴 Add a Self-Healing Offline Configuration Layer
• 🔄 Implement server-driven UI capabilities
• 🏢 Build tenant-specific capability policies
• 🧬 Generate strongly typed feature keys with a Roslyn Source Generator
• 🛡️ Add automated kill-switch health policies
• 🚀 Create a complete progressive delivery platform for .NET MAUI

At that point, feature flags stop being a collection of if statements and become a genuine part of your application's runtime architecture. 🚩🚀

Was this useful?

👍 Like 0❤️ Love 0💡 Insightful 0🔥 Awesome 0

Sign in to react. Guest comments are still welcome.

Comments (0)

No approved comments yet.

Leave a comment

Name Email

Your email is used only for moderation and is never displayed.

Comment Submit for moderation

Related Posts

Building a Full-Text Search Engine Inside .NET MAUI with SQLite's FTS5 Extension

February 5, 2026

Build a fast, offline full-text search engine in .NET MAUI using SQLite FTS5 and Shaunebu.Data.SQLite, with async, fluent, and production-ready data access.

Building a Cross-Platform Speech Recognition Engine in .NET MAUI

June 29, 2026

Build a cross-platform speech recognition engine in .NET MAUI to enable voice commands, real-time speech-to-text, and hands-free user interactions across Android, iOS, Windows, and MacCatalyst.

Building a Runtime Application Self-Protection (RASP) Layer in .NET MAUI

June 25, 2026

Learn how to build a Runtime Application Self-Protection (RASP) layer in .NET MAUI to detect runtime threats such as root, jailbreak, debuggers, code tampering, and instrumentation, helping secure enterprise mobile applications against sophisticated attacks.