Skip to content
← Tous les articles
· Delta1 Labs DeploymentKeyright

Préinstaller une licence Keyright depuis un installeur WiX/MSI

Les logiciels de bureau d'entreprise ne sont pas activés par la personne qui les exécute. Ils sont déployés silencieusement via une stratégie de groupe, Intune ou SCCM avec msiexec /qn, vers des machines dont les utilisateurs ne voient jamais de boîte de dialogue et ne peuvent souvent pas joindre votre service de licences. Ce guide pratique construit le déploiement dont la plupart des ISV finissent par avoir besoin : un MSI qui place une licence signée à l'échelle de la machine sous ProgramData afin que l'application soit déjà sous licence au premier lancement, plus l'alternative consistant à passer une clé d'activation comme propriété du MSI et à laisser l'application la réclamer une fois en ligne. Il couvre la rédaction en WiX v5, l'emplacement où le fichier doit résider pour que tous les utilisateurs Windows de la machine partagent un siège, l'action personnalisée différée qui écrit une clé que l'application récupérera, les options du SDK qui rendent ProgramData autoritaire et les lignes de commande msiexec qu'un administrateur colle dans son outil de déploiement.

Une application grand public demande la clé de licence à la personne devant le clavier. Les logiciels d’entreprise n’y parviennent presque jamais. Ils arrivent sur un ordinateur portable via Intune, via une GPO d’installation de logiciel, via une séquence de tâches SCCM : msiexec /i Acme.msi /qn exécuté par le compte SYSTEM, sans fenêtre, sans utilisateur, souvent sans aucune route vers l’internet public. Si votre expérience de premier démarrage est « saisissez votre clé ici », ce déploiement atterrit sur quelques milliers de machines affichant une boîte de dialogue d’activation devant laquelle personne n’est assis.

La licence doit donc être en place avant le premier lancement, mise là par l’installateur. Cet article le construit pour une application de bureau .NET sous licence Keyright, en utilisant WiX v5 pour le MSI. Il existe deux formes — inclure une licence de site signée, ou passer une clé d’activation comme propriété — et la première est celle que vous voulez pour tout ce qui est isolé du réseau (air-gapped). Nous ferons les deux, et passerons l’essentiel du temps sur le détail qui fait tout réussir ou échouer : où va le fichier.

Le mauvais endroit : l’AppData par utilisateur

L’emplacement par défaut du SDK Keyright pour un bail (lease) activé et une licence hors ligne est {LocalApplicationData}\Keyright\{product}\, c’est-à-dire %LocalAppData% — un dossier par utilisateur. C’est exactement ce qu’il faut quand un utilisateur active l’application lui-même. C’est exactement ce qu’il ne faut pas pour un installateur, pour deux raisons.

Un MSI s’exécutant dans une installation silencieuse à l’échelle de la machine tourne sous NT AUTHORITY\SYSTEM. Son %LocalAppData% est C:\Windows\System32\config\systemprofile\AppData\Local — un dossier qu’aucun utilisateur interactif ne lira jamais. Et même si vous usurpiez l’identité de l’utilisateur qui installe, un déploiement de machine ne sait pas quel utilisateur exécutera l’application ; cela peut être dix personnes différentes sur un poste de travail partagé, ou un utilisateur qui ne s’est pas encore connecté quand l’installation s’exécute.

Un déploiement sous licence de machine veut une seule licence, lisible par tous les utilisateurs de la machine, écrite une fois par l’installateur. C’est à cela que sert %ProgramData% (CommonAppDataFolder, C:\ProgramData) : à l’échelle de la machine, lisible par tous, et le foyer naturel d’une licence qui appartient à l’appareil plutôt qu’à une personne.

Where the installer should put the licensemsiexec /qnruns as SYSTEMper-user AppData — wrong%LocalAppData% → System32\config\systemprofileno interactive user ever reads this folderUser A: noneUser B: noneProgramData — right%ProgramData%\Keyright\acme-studio\license.jsonmachine-wide, world-readable, written onceUser A: licensedUser B: licensedone machine fingerprint → one seatboth users present the same machineId; the service binds a single deviceA device-licensed deployment keeps the license with the device, not with whichever person logs in first.

Forme 1 : inclure une licence de site signée

Pour un client en volume ou de site, vous émettez un document de licence signé et vous l’expédiez à l’intérieur du MSI. Comme une licence Keyright est une charge utile signée dont la sécurité est la signature et non le secret, il est sûr de la transporter dans un installateur ; un octet modifié l’invalide. Émettez-la perpétuelle (ou verrouillée au nœud du déploiement si vous verrouillez les machines de site) afin que rien sur la machine finale n’ait à rappeler le serveur.

La rédaction WiX est un composant ordinaire qui place le fichier dans un sous-dossier de ProgramData :

<!-- Acme.Studio.wxs — WiX v5 -->
<Package Name="Acme Studio" Manufacturer="Acme Ltd"
         Version="4.2.0" UpgradeCode="7c3f9e10-7b22-4a8f-9f2e-6d4c1b0a55e1"
         Scope="perMachine">

  <StandardDirectory Id="CommonAppDataFolder">
    <Directory Id="AcmeData" Name="Keyright">
      <Directory Id="AcmeProduct" Name="acme-studio" />
    </Directory>
  </StandardDirectory>

  <!-- The signed site license, shipped in the MSI, written to ProgramData. -->
  <Component Id="SiteLicense" Directory="AcmeProduct" Guid="*">
    <File Id="LicenseJson" Source="licenses\site-license.json" Name="license.json" />
  </Component>

  <Feature Id="Main">
    <ComponentRef Id="SiteLicense" />
    <!-- app files … -->
  </Feature>
</Package>

CommonAppDataFolder se résout en C:\ProgramData, donc le fichier atterrit dans C:\ProgramData\Keyright\acme-studio\license.json. Une installation par machine donne à cette arborescence une ACL que tous les utilisateurs peuvent lire et que seuls les administrateurs peuvent écrire — ce qui est exactement ce que vous voulez pour une licence : lisible par quiconque exécute l’application, non modifiable par lui.

Maintenant, le SDK doit regarder là. Par défaut, il lit le chemin par utilisateur, donc pour un produit sous licence de machine, pointez DefaultLicensePath (l’emplacement de repli ambiant) vers la copie dans ProgramData :

using Keyright;

static KeyrightClient CreateLicenseClient()
{
    string machineWide = Path.Combine(
        Environment.GetFolderPath(Environment.SpecialFolder.CommonApplicationData),
        "Keyright", "acme-studio");

    var options = new KeyrightOptions
    {
        Product            = "acme-studio",
        PublicKeyBase64    = AcmeKeys.LicensePublicKey,   // public key only; safe to ship
        ServiceUrl         = "https://licensing.acme.example",
        DefaultLicensePath = Path.Combine(machineWide, "license.json"),
        // Lease/state stay per-user; only the seeded license is machine-wide.
    };

    return KeyrightClient.Initialize(options);
}

DefaultLicensePath est la source ambiante — elle est consultée après un LicenseFilePath explicite ou la variable d’environnement KEYRIGHT_LICENSE, mais avant que l’application ne retombe sur « pas de licence ». Cette précédence compte : un client de site qui achète plus tard une mise à niveau par siège peut déposer un fichier plus récent au chemin explicite ou définir la variable d’environnement sans que vous ayez à recréer le MSI, et il l’emporte sur celui préparé. Au premier lancement, client.Validate() trouve le document préparé, le vérifie hors ligne contre la clé publique intégrée, et l’application est sous licence sans boîte de dialogue et sans réseau.

LicenseInfo info = client.Validate(out LicenseSourceKind source);
// info.IsValid == true, source == LicenseSourceKind.LicenseFile,
// info.Licensee == "Globex Corporation", info.ExpiryUtc == null

Comme la licence préparée est perpétuelle, le SDK n’écrit aucun état local pour elle — ni bail, ni horodatage de première vue — il n’y a donc rien par utilisateur qui puisse mal tourner et rien qu’une désinstallation ait à nettoyer au-delà du fichier que le MSI possède.

Forme 2 : passer une clé d’activation comme propriété du MSI

Certains déploiements sont sous licence par siège, pas par site, et l’administrateur a une clé plutôt qu’un fichier signé. Ici, vous ne voulez pas activer pendant l’installation — une activation en ligne depuis une action personnalisée différée tournant sous SYSTEM est l’appel réseau le moins fiable de votre produit, et elle prend l’empreinte du mauvais contexte de sécurité. Au lieu de cela, laissez l’installateur préparer la clé, et laissez l’application s’activer elle-même au premier démarrage, dans le contexte de l’utilisateur, où elle peut joindre le service et présenter l’identité réelle de la machine.

Déclarez une propriété publique pour que l’administrateur puisse fournir la clé en ligne de commande, et rendez-la Secure afin qu’elle survive au passage à la phase d’exécution différée (SYSTEM) :

<Property Id="LICENSEKEY" Secure="yes" />

<!-- Deferred CA needs its data marshalled in via a same-named property. -->
<SetProperty Id="StageLicenseKey" Value="[LICENSEKEY]"
             Before="StageLicenseKey" Sequence="execute"
             Condition="LICENSEKEY" />

<CustomAction Id="StageLicenseKey" BinaryRef="AcmeCa"
              DllEntry="StageLicenseKey" Execute="deferred"
              Impersonate="no" Return="check" />

<InstallExecuteSequence>
  <Custom Action="StageLicenseKey" After="InstallFiles" Condition="LICENSEKEY" />
</InstallExecuteSequence>

L’action personnalisée écrit la clé dans un fichier de transfert connu, à l’échelle de la machine. Elle ne fait délibérément aucun réseau — elle dépose seulement une miette de pain que l’application consommera :

// WiX v5 custom action (WixToolset.Dtf.WindowsInstaller)
using WixToolset.Dtf.WindowsInstaller;

public class CustomActions
{
    [CustomAction]
    public static ActionResult StageLicenseKey(Session session)
    {
        // Deferred CAs cannot read properties directly; the value arrives as CustomActionData.
        string key = session["CustomActionData"]?.Trim() ?? "";
        if (key.Length == 0) return ActionResult.Success;

        string dir = Path.Combine(
            Environment.GetFolderPath(Environment.SpecialFolder.CommonApplicationData),
            "Keyright", "acme-studio");
        Directory.CreateDirectory(dir);
        File.WriteAllText(Path.Combine(dir, "pending-activation.key"), key);
        return ActionResult.Success;
    }
}

Au premier lancement, l’application cherche cette miette de pain, active une fois et la supprime pour que l’activation ne se répète jamais :

static async Task EnsureActivatedAsync(KeyrightClient client)
{
    // Already licensed from a cached lease? Nothing to do.
    if (client.Validate().IsValid) return;

    string pending = Path.Combine(
        Environment.GetFolderPath(Environment.SpecialFolder.CommonApplicationData),
        "Keyright", "acme-studio", "pending-activation.key");

    if (!File.Exists(pending)) return;   // no staged key; fall back to the UI's "Enter key" flow

    string key = (await File.ReadAllTextAsync(pending)).Trim();
    ActivationResult result = await client.ActivateAsync(key);

    if (result.Status == LicenseStatus.Ok)
        File.Delete(pending);            // consumed; do not re-activate on next launch
    else if (result.Status == LicenseStatus.SeatLimit)
        File.Delete(pending);            // a real answer, not a transient failure — stop retrying
    // On a transient/offline failure, leave the file so the next launch retries.
}

L’activation tourne en tant qu’utilisateur, met son bail en cache par utilisateur et lie le siège à la machine sur laquelle l’application s’exécute réellement. Gardez l’activation idempotente de votre côté (elle l’est déjà dans Keyright) afin que deux utilisateurs sur le même PC partagé consommant la même clé préparée rafraîchissent un siège au lieu d’en brûler deux — tous deux présentent la même empreinte de machine, et le second ActivateAsync rafraîchit l’enregistrement d’appareil du premier.

Two ways to seed, one licensed first runShape 1 — site license (offline)MSI Component writesProgramData\…\license.jsonfirst launch:Validate() offline, no netlicensed, no dialogsource = LicenseFile · perpetualShape 2 — activation key (online, first run)msiexec … LICENSEKEY=…deferred CA stagespending-activation.keyfirst launch reads keyActivateAsync() onlinecache lease · delete keylicensed, no dialogseat bound to machineper-user lease cachedActivation runs in the user's context on first launch — never from the SYSTEM custom action.

Les lignes de commande qu’un administrateur exécute vraiment

Quoi que vous construisiez, la sortie est une ligne que quelqu’un colle dans une GPO, une application Win32 Intune ou un programme SCCM. Documentez-les à côté du MSI :

:: Site license baked into the MSI — nothing to pass, fully silent, works offline.
msiexec /i Acme.Studio.msi /qn /l*v %TEMP%\acme-install.log

:: Per-seat: hand the installer the activation key. Quote it; keys can contain punctuation.
msiexec /i Acme.Studio.msi /qn LICENSEKEY="ACME-7F3A-9C21-5E08-BD44"

:: Intune Win32 app "install command" is the same line; detection rule = the app's EXE/version.

Deux mises en garde qui valent la peine d’être mises entre les mains de l’administrateur. Les noms de propriété passés en ligne de commande doivent être publics (en majuscules) ou le MSI les abandonne — LICENSEKEY, jamais licenseKey. Et une clé en ligne de commande peut apparaître dans le journal MSI détaillé et, brièvement, dans la liste des processus ; préférez la forme de la licence de site incluse pour tout ce qui est sensible, et si vous devez passer une clé, marquez la propriété Secure et dites aux administrateurs de ne pas activer la journalisation /l*v par paquet dans des transcriptions partagées.

Désinstallation, réparation et mise à niveau

Le composant qui possède license.json fait du cycle de vie du fichier celui du MSI. Une désinstallation standard le supprime, ce qui est correct — l’appareil n’est plus sous licence pour exécuter le produit. Une réparation (msiexec /f) replace la licence de site incluse, réparant un fichier qu’un utilisateur a supprimé. Une mise à niveau majeure le remplace par ce que porte le nouveau MSI, donc si vous expédiez une nouvelle licence de site dans une nouvelle version, elle remplace proprement l’ancienne.

La clé d’activation préparée est différente : ce n’est pas un composant MSI (l’installateur l’écrit, ce n’est pas un fichier expédié), donc une désinstallation ne supprimera pas pending-activation.key à moins que vous n’ajoutiez une entrée RemoveFile — ajoutez-en une, pour qu’une réinstallation ne réactive pas contre une clé que le client a depuis remplacée. Le bail par utilisateur que l’application a mis en cache est de l’AppData par utilisateur et hors de portée de l’installateur par conception ; si le client met la machine hors service, faites-lui d’abord désactiver dans l’application, ou libérez l’appareil depuis le panneau Devices de la licence dans le tableau de bord Keyright, comme pour tout transfert de siège.

<Component Id="CleanStagedKey" Directory="AcmeProduct" Guid="*">
  <RemoveFile Id="RmPendingKey" Name="pending-activation.key" On="uninstall" />
</Component>

Ce qu’il faut retenir

Les logiciels d’entreprise sont installés par un outil et exécutés par un inconnu, donc la licence doit être en place avant que quiconque ne lance l’application. Mettez-la là où l’appareil peut la lire — %ProgramData%, pas l’AppData par utilisateur — et laissez le MSI posséder son cycle de vie. Si le déploiement est isolé du réseau ou sous licence de site, incluez une licence perpétuelle signée et pointez DefaultLicensePath vers elle ; le premier démarrage est sous licence sans réseau et sans boîte de dialogue. S’il est par siège, préparez la clé depuis une action personnalisée différée et laissez l’application s’activer elle-même au premier démarrage dans le contexte de l’utilisateur, où l’empreinte et le réseau sont réels. Dans les deux cas, la personne qui allume l’ordinateur portable voit votre produit fonctionner, ce qui est le seul premier démarrage acceptable pour un logiciel qu’elle n’a pas acheté et ne peut pas activer.

Essayez Nebula.NET

Renforcez votre code .NET en quelques minutes — commencez avec l'édition gratuite.