Comparar derechos requeridos y concedidos al actualizar
Cuando una versión nueva necesita derechos que la licencia del cliente nunca concedió, un simple "función bloqueada" es un callejón sin salida. Así se comparan requeridos y concedidos para decirle exactamente qué comprar.
Un cliente de tu línea 3.x actualiza a 4.0. La nueva versión añade SSO, un exportador de registro de auditoría y un techo de proyectos más alto: tres cosas que su licencia actual, acuñada contra la plantilla de nivel 3.x, nunca se emitió para cubrir. Arranca, hace clic en Exportar registro de auditoría y obtiene un escueto FeatureLockedException. Hace clic en Ajustes de SSO y obtiene otro. Cada clic fallido es un ticket de soporte distinto, y ninguno responde a la única pregunta que el cliente realmente tiene: ¿qué necesito comprar para que esta versión funcione entera?
El problema no es la barrera. Condicionar cada función con cierre seguro es correcto y debes conservarlo. El problema es que las comprobaciones IsEnabled por función responden a una pregunta del tamaño equivocado. Te dicen, en el momento del uso, si una capacidad está activa. Nunca te dicen, de antemano, la forma de la brecha entre lo que esta versión de la aplicación necesita y lo que esta licencia concede. Esa forma es una diferencia de conjuntos, y calcularla una vez al arranque convierte un goteo de bloqueos misteriosos en una frase honesta.
Un derecho es una capacidad con nombre; una versión requiere un conjunto de ellos
Si has leído derechos frente a feature flags, sabes que un derecho de Keyright es una capacidad con nombre incrustada en la licencia firmada: un booleano como audit-export, o un límite numérico como max-projects: 50. La licencia lleva el conjunto que el cliente recibió. Lo que no lleva, y no debe llevar, es el conjunto que tu compilación actual requiere, porque ese conjunto cambia cada vez que publicas.
Así que decláralo en la aplicación. Un manifiesto de capacidades es una descripción pequeña y estática de cada derecho del que depende una versión dada, versionado junto al código que depende de él. Viaja dentro del ensamblado; no es un secreto ni un artefacto de licencia.
public sealed record Requirement(string Key, RequirementKind Kind, long Min = 0);
public enum RequirementKind { Flag, Limit }
public static class AppManifest
{
// Everything THIS build needs the license to grant. Grows as the product grows.
public static readonly IReadOnlyList<Requirement> Required = new[]
{
new Requirement("audit-export", RequirementKind.Flag),
new Requirement("sso", RequirementKind.Flag),
new Requirement("max-projects", RequirementKind.Limit, Min: 25),
};
}
Cuando añades en 4.0 una función que se apoya en sso, añades una línea aquí en el mismo commit. El manifiesto es el único lugar que sabe “esta versión necesita estas capacidades”, y vive junto al código, así que nunca puede desincronizarse de una versión como lo haría una configuración externa.
El conjunto concedido viene de la licencia validada
La otra mitad de la comparación es lo que la licencia concede de verdad, y eso es pura computación local. El SDK validó la licencia firmada sin conexión contra tu clave pública embebida al arranque; leer sus derechos es solo inspeccionar el resultado.
var client = KeyrightClient.Initialize(new KeyrightOptions
{
Product = "acme-suite",
PublicKeyBase64 = AcmeKeys.LicensePublicKey, // public key only; safe to ship
ServiceUrl = "https://licensing.acme.example",
});
LicenseInfo info = client.Validate(); // never throws; fails closed to Free on any problem
Validate() nunca toca la red en la ruta caliente, nunca lanza excepciones, y ante cualquier fallo devuelve un LicenseInfo en edición Free cuyo conjunto de derechos está vacío. Esa última propiedad importa para la comparación: una licencia inválida o ausente no rompe la comparación, simplemente no concede nada, así que todos los requisitos aparecen como faltantes, que es exactamente el informe que quieres en ese caso.
La comparación es aritmética de conjuntos
Ahora recorre el conjunto requerido contra la licencia concedida y recoge lo que no se satisface. Un booleano se satisface cuando la licencia lo habilita; un límite se satisface cuando el techo de la licencia alcanza o supera el mínimo que esta versión necesita.
public sealed record Gap(Requirement Need, long? Granted);
public static IReadOnlyList<Gap> Diff(LicenseInfo info, IEnumerable<Requirement> required)
{
var gaps = new List<Gap>();
foreach (var r in required)
{
switch (r.Kind)
{
case RequirementKind.Flag:
if (!info.Entitlements.IsEnabled(r.Key))
gaps.Add(new Gap(r, Granted: null));
break;
case RequirementKind.Limit:
long granted = info.Entitlements.GetLimit(r.Key); // 0 when absent
if (granted < r.Min)
gaps.Add(new Gap(r, Granted: granted));
break;
}
}
return gaps;
}
Como IsEnabled y GetLimit fallan con cierre seguro —un booleano desconocido se lee como apagado, un límite ausente se lee como 0— la comparación es correcta incluso frente a una licencia Free o malformada sin un solo caso especial. La lista de carencias es la respuesta: vacía significa que esta versión está totalmente cubierta; no vacía es una lista de la compra precisa y comprable.
Infórmalo una vez, al arranque
Ejecuta la comparación cuando la aplicación arranca y expón toda la brecha en un solo lugar —un banner, un diálogo bloqueante, una línea de log para un host sin interfaz— en vez de dejar que el usuario tropiece con cada cierre uno a uno. El mensaje nombra lo que falta y apunta a la actualización, que es la acción que lo resuelve todo de una vez.
var gaps = EntitlementDiff.Diff(info, AppManifest.Required);
if (gaps.Count > 0)
{
var lines = gaps.Select(g => g.Granted is null
? $" • {g.Need.Key} (not included in your license)"
: $" • {g.Need.Key}: need {g.Need.Min}, your license allows {g.Granted}");
_log.LogWarning(
"This version of acme-suite needs entitlements your current license ({Tier}) does " +
"not cover:\n{Gaps}\nUpgrade your license to enable them: {Url}",
info.Tier, string.Join('\n', lines), "https://acme.example/account/license");
_startup.ShowUpgradeNotice(gaps); // one notice, the full shopping list, a real next step
}
Fíjate en lo que esto no hace: no desactiva la aplicación. Una carencia significa que algunas funciones de 4.0 no están disponibles, no que el producto no tenga licencia. Todo lo que la licencia sí concede sigue funcionando; las barreras por función se quedan exactamente donde estaban y siguen cerrando en seguro en el punto de uso. La comparación es un aviso de actualización, no un interruptor de apagado: ambos viven en capas distintas y nunca se sustituyen.
Haz de la comparación también una verificación previa
El mismo manifiesto rinde antes de que un solo byte de la nueva versión llegue a un cliente. Un socio que despliega a una flota, o tu propia CI, puede acuñar una licencia de prueba en el nivel actual y afirmar que la comparación está vacía, atrapando “4.0 necesita en silencio un derecho que la plantilla del nivel Pro nunca concede” en tiempo de compilación en lugar de en una cola de soporte.
[Fact]
public void ProTier_covers_everything_v4_requires()
{
LicenseInfo pro = TestIssuer.Mint(product: "acme-suite", tier: "Pro");
var gaps = EntitlementDiff.Diff(pro, AppManifest.Required);
Assert.True(gaps.Count == 0,
"Pro tier is missing: " + string.Join(", ", gaps.Select(g => g.Need.Key)));
}
Si esa prueba se pone en rojo cuando añades una función, tienes una decisión que tomar antes de la publicación: ampliar la plantilla del nivel para que Pro conceda el nuevo derecho, o aceptar que la función es una venta adicional a un nivel superior. En cualquier caso tomaste la decisión a propósito, con la brecha delante, en vez de descubrirla por el primer cliente que actualizó y encontró un botón bloqueado.
La forma de la brecha es el producto de la comparación
Condicionar por función le dice al usuario que una puerta está cerrada. Comparar el manifiesto contra la licencia le dice cuáles puertas, por qué y qué compra única las abre todas: la diferencia entre un goteo frustrante de bloqueos y un aviso único, honesto y accionable. Conserva las barreras de cierre seguro: son tu control. Añade encima la comparación al arranque: es tu explicación. Una es cómo el software protege el negocio; la otra es cómo el negocio evita que el cliente abandone furioso una actualización que habría pagado encantado.
Prueba Nebula.NET
Endurece tu código .NET en minutos — empieza con la edición gratuita.