.NET quickstart
Entitlements and plan-based feature gating for .NET.
Subscrio.Core is an open source MIT-licensed entitlement library for .NET 8, 9, and 10.
ASP.NET example
Register Subscrio through dependency injection.
Set DATABASE_URL and, when needed, DATABASE_TYPE to PostgreSQL or SqlServer. ConfigLoader.LoadConfig() reads those environment variables. You can also build SubscrioConfig from your existing application configuration. This example uses scoped ASP.NET registration; other .NET applications can create and manage a Subscrio instance directly.
dotnet add package Subscrio.Core
using Microsoft.Extensions.DependencyInjection;
using Subscrio.Core.Config;
using Subscrio.Core.DependencyInjection;
var builder = WebApplication.CreateBuilder(args);
var config = ConfigLoader.LoadConfig();
builder.Services.AddSubscrio(config, ServiceLifetime.Scoped);Schema
Install once, then migrate with releases.
The database must already exist. InstallSchemaAsync creates the required tables and stores the hashed admin passphrase. After package upgrades, MigrateAsync applies pending schema changes.
Run schema work in a deployment step or guarded startup path. Do not call installation blindly each time the application starts.
using Subscrio.Core;
using Subscrio.Core.Config;
var config = ConfigLoader.LoadConfig();
using var subscrio = new Subscrio(config);
var version = await subscrio.VerifySchemaAsync();
if (version is null)
{
await subscrio.InstallSchemaAsync(
Environment.GetEnvironmentVariable("ADMIN_PASSPHRASE")
);
}
else
{
await subscrio.MigrateAsync();
}Catalog configuration
Define the catalog in JSON or build it in C#.
Products, features, plans, billing cycles, and plan values can live in one version-controlled JSON file. Sync it during deployment or a guarded startup path so each environment receives the same catalog.
If the catalog depends on application settings or other runtime data, build a ConfigSyncDto in C# and pass it to the same sync service. Both paths return a report of what was created, updated, archived, or ignored.
using Subscrio.Core.Application.DTOs;
// Sync a version-controlled JSON file.
var fileReport = await subscrio.ConfigSync.SyncFromFileAsync(
"./subscrio.config.json"
);
// Or build the same catalog in C#.
ConfigSyncDto catalog = BuildEntitlementCatalog();
var codeReport = await subscrio.ConfigSync.SyncFromJsonAsync(catalog);ASP.NET example
Resolve access through an injected Subscrio instance.
The customer, product, and feature use stable keys. Request int with a fallback of 0 to receive the seat limit without a parsing branch. The same feature checker can be called from any .NET application.
using Subscrio.Core;
app.MapPost("/accounts/{customerKey}/reports",
async (string customerKey, Subscrio subscrio) =>
{
var allowed = await subscrio.FeatureChecker.IsEnabledForCustomerAsync(
customerKey, "analytics", "advanced-reporting"
);
if (!allowed) return Results.Forbid();
var seatLimit = await subscrio.FeatureChecker.GetValueForCustomerAsync<int>(
customerKey, "analytics", "seat-limit", 0
);
return Results.Ok(new { seatLimit });
});Customer override
Put the exception on the subscription.
When Acme's contract includes 40 seats instead of the Growth plan's 25, add an override to Acme's subscription. The endpoint continues to ask for seat-limit.
using Subscrio.Core.Domain.ValueObjects;
await subscrio.Subscriptions.AddFeatureOverrideAsync(
"acme-growth",
"seat-limit",
"40",
OverrideType.Permanent
);Before shipping
What to verify before this runs in production.
A working access check is the starting point. Test overrides, plan values, defaults, and missing subscriptions. Then check instance lifetimes, migrations, secrets, and billing events.
Test these cases
- Toggle enabled and disabled by plan.
- Numeric value returned from the plan.
- Subscription override takes precedence.
- Feature default is used when the plan has no value.
- Inactive or missing subscription follows your deny policy.
Production checks
- Choose an instance lifetime that fits the host application. Use scoped registration for ASP.NET requests.
- Run migrations in a controlled release step.
- Keep connection strings and admin passphrases in secret storage.
- Verify Stripe signatures when your application receives the events, or use the Web Admin as the webhook endpoint.
- Dispose manually created Subscrio instances.
Next: follow the plan-based feature gating guide, review the entitlement data model, or see what the optional Web Admin adds.
Common questions
Questions about .NET entitlement integration
How do I add plan-based feature gating to a .NET application?
Install Subscrio.Core, connect a supported database, define or sync the entitlement catalog, and resolve stable feature keys for the current customer. The same model supports toggle access, limits, and subscription overrides.
Which .NET versions does Subscrio.Core support?
The package includes builds for .NET 8, .NET 9, and .NET 10. The correct target is selected by the consuming project.
Which databases can the .NET library use?
Subscrio.Core supports PostgreSQL and SQL Server. You create the database first, then the library installs and migrates its schema inside it.
How should Subscrio be registered in ASP.NET?
Register it with AddSubscrio and a scoped service lifetime. This gives each request a fresh Subscrio instance and DbContext.
Can a customer have a custom feature limit?
Yes. Add a feature override to the customer's subscription. Resolution checks the override before the plan value and feature default.
Can I configure Subscrio.Core with JSON or C#?
Yes. Define products, features, plans, billing cycles, and plan values in a version-controlled JSON file and sync it with SyncFromFileAsync. You can also build a ConfigSyncDto in C# and pass it to SyncFromJsonAsync.
Next step
Add the package, connect a database, and resolve one feature.
Use the complete .NET documentation for schema installation, migrations, DTOs, service methods, hooks, and Stripe integration.