Eine Keyright-Lizenz aus einem WiX/MSI-Installer vorbefüllen
Desktop-Unternehmenssoftware wird nicht von der Person aktiviert, die sie ausführt. Sie wird still über Gruppenrichtlinien, Intune oder SCCM mit msiexec /qn auf Rechner ausgerollt, deren Benutzer nie einen Dialog sehen und oft Ihren Lizenzdienst nicht erreichen können. Diese Anleitung baut die Bereitstellung, die die meisten ISVs letztlich brauchen: ein MSI, das eine signierte maschinenweite Lizenz unter ProgramData ablegt, sodass die App beim ersten Start bereits lizenziert ist, plus die Alternative, einen Aktivierungsschlüssel als MSI-Eigenschaft zu übergeben und die App ihn einmal online einlösen zu lassen. Es behandelt die Erstellung in WiX v5, wo die Datei liegen muss, damit alle Windows-Benutzer des Rechners einen Platz teilen, die verzögerte benutzerdefinierte Aktion, die einen Schlüssel schreibt, den die App aufnehmen wird, die SDK-Optionen, die ProgramData maßgeblich machen, und die msiexec-Befehlszeilen, die ein Administrator in sein Bereitstellungswerkzeug einfügt.
Eine Verbraucher-App fragt die Person an der Tastatur nach dem Lizenzschlüssel. Unternehmenssoftware kommt fast nie dazu. Sie landet über Intune, über eine GPO zur Softwareinstallation, über eine SCCM-Tasksequenz auf einem Laptop: msiexec /i Acme.msi /qn, ausgeführt vom SYSTEM-Konto, ohne Fenster, ohne Benutzer, oft ganz ohne Route ins öffentliche Internet. Wenn Ihr Erststart-Erlebnis „Geben Sie hier Ihren Schlüssel ein” lautet, landet diese Bereitstellung auf ein paar tausend Rechnern und zeigt einen Aktivierungsdialog, vor dem niemand sitzt.
Die Lizenz muss also vor dem ersten Start an Ort und Stelle sein, dort vom Installer platziert. Dieser Artikel baut das für eine .NET-Desktop-App auf, die mit Keyright lizenziert ist, und verwendet WiX v5 für das MSI. Es gibt zwei Formen — eine signierte Standortlizenz beilegen oder einen Aktivierungsschlüssel als Eigenschaft übergeben — und die erste ist die, die Sie für alles Netzwerkisolierte (air-gapped) wollen. Wir machen beide und verbringen die meiste Zeit mit dem Detail, das darüber entscheidet, ob es gelingt oder scheitert: wo die Datei hinkommt.
Der falsche Ort: AppData pro Benutzer
Der Standardort des Keyright-SDK für ein aktiviertes Lease und eine Offline-Lizenz ist {LocalApplicationData}\Keyright\{product}\, also %LocalAppData% — ein Ordner pro Benutzer. Das ist genau richtig, wenn ein Benutzer die App selbst aktiviert. Es ist genau falsch für einen Installer, aus zwei Gründen.
Ein MSI, das in einer stillen maschinenweiten Installation läuft, wird als NT AUTHORITY\SYSTEM ausgeführt. Sein %LocalAppData% ist C:\Windows\System32\config\systemprofile\AppData\Local — ein Ordner, den kein interaktiver Benutzer je liest. Und selbst wenn Sie den installierenden Benutzer imitieren würden, weiß eine Maschinenbereitstellung nicht, welcher Benutzer die App ausführen wird; es können zehn verschiedene Personen an einer gemeinsam genutzten Arbeitsstation sein oder ein Benutzer, der sich noch nicht angemeldet hat, wenn die Installation läuft.
Eine maschinenlizenzierte Bereitstellung will eine Lizenz, lesbar von allen Benutzern des Rechners, einmal vom Installer geschrieben. Dafür ist %ProgramData% (CommonAppDataFolder, C:\ProgramData) da: maschinenweit, für alle lesbar und das natürliche Zuhause einer Lizenz, die zum Gerät gehört statt zu einer Person.
Form 1: eine signierte Standortlizenz beilegen
Für einen Volumen- oder Standortkunden stellen Sie ein signiertes Lizenzdokument aus und liefern es innerhalb des MSI aus. Da eine Keyright-Lizenz eine signierte Nutzlast ist, deren Sicherheit die Signatur und nicht die Geheimhaltung ist, ist es sicher, sie in einem Installer mitzuführen; ein geändertes Byte macht sie ungültig. Stellen Sie sie unbefristet aus (oder an den Knoten der Bereitstellung gebunden, wenn Sie Standortrechner knotengebunden machen), damit nichts auf dem Endrechner nach Hause telefonieren muss.
Die WiX-Erstellung ist eine gewöhnliche Komponente, die die Datei in einen Unterordner von ProgramData legt:
<!-- 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 löst sich zu C:\ProgramData auf, die Datei landet also unter C:\ProgramData\Keyright\acme-studio\license.json. Eine Pro-Maschine-Installation gibt diesem Baum eine ACL, die jeder Benutzer lesen und nur Administratoren schreiben können — was genau das ist, was Sie für eine Lizenz wollen: lesbar für jeden, der die App ausführt, nicht von ihm bearbeitbar.
Nun muss das SDK dort nachsehen. Standardmäßig liest es den Pro-Benutzer-Pfad, also richten Sie für ein maschinenlizenziertes Produkt DefaultLicensePath (den umgebenden Ausweichort) auf die Kopie in ProgramData aus:
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 ist die umgebende Quelle — sie wird nach einem expliziten LicenseFilePath oder der Umgebungsvariablen KEYRIGHT_LICENSE konsultiert, aber bevor die App auf „keine Lizenz” zurückfällt. Diese Rangfolge ist wichtig: Ein Standortkunde, der später ein Pro-Platz-Upgrade kauft, kann eine neuere Datei am expliziten Pfad ablegen oder die Umgebungsvariable setzen, ohne dass Sie das MSI neu erstellen müssen, und sie gewinnt über die vorbereitete. Beim ersten Start findet client.Validate() das vorbereitete Dokument, verifiziert es offline gegen den eingebetteten öffentlichen Schlüssel, und die App ist lizenziert — ohne Dialog und ohne Netzwerk.
LicenseInfo info = client.Validate(out LicenseSourceKind source);
// info.IsValid == true, source == LicenseSourceKind.LicenseFile,
// info.Licensee == "Globex Corporation", info.ExpiryUtc == null
Da die vorbereitete Lizenz unbefristet ist, schreibt das SDK keinen lokalen Zustand für sie — kein Lease, keinen Erstsichtungs-Zeitstempel — es gibt also nichts pro Benutzer, das schiefgehen kann, und nichts, was eine Deinstallation aufräumen müsste außer der Datei, die das MSI besitzt.
Form 2: einen Aktivierungsschlüssel als MSI-Eigenschaft übergeben
Manche Bereitstellungen sind pro Platz lizenziert, nicht pro Standort, und der Administrator hat einen Schlüssel statt einer signierten Datei. Hier wollen Sie nicht während der Installation aktivieren — eine Online-Aktivierung aus einer verzögerten benutzerdefinierten Aktion, die als SYSTEM läuft, ist der unzuverlässigste Netzwerkaufruf in Ihrem Produkt und nimmt den Fingerabdruck des falschen Sicherheitskontexts. Lassen Sie stattdessen den Installer den Schlüssel bereitstellen, und lassen Sie die App sich beim ersten Start selbst aktivieren, im Kontext des Benutzers, wo sie den Dienst erreichen und die echte Maschinenidentität präsentieren kann.
Deklarieren Sie eine öffentliche Eigenschaft, damit der Administrator den Schlüssel in der Befehlszeile liefern kann, und machen Sie sie Secure, damit sie den Wechsel in die verzögerte (SYSTEM-)Ausführungsphase übersteht:
<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>
Die benutzerdefinierte Aktion schreibt den Schlüssel in eine bekannte, maschinenweite Übergabedatei. Sie macht bewusst kein Netzwerk — sie legt nur eine Brotkrume ab, die die App verbrauchen wird:
// 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;
}
}
Beim ersten Start sucht die App diese Brotkrume, aktiviert einmal und löscht sie, damit die Aktivierung sich nie wiederholt:
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.
}
Die Aktivierung läuft als Benutzer, speichert ihr Lease pro Benutzer im Cache und bindet den Platz an die Maschine, auf der die App tatsächlich läuft. Halten Sie die Aktivierung auf Ihrer Seite idempotent (in Keyright ist sie es bereits), damit zwei Benutzer am selben gemeinsam genutzten PC, die denselben vorbereiteten Schlüssel verbrauchen, einen Platz auffrischen statt zwei zu verbrauchen — beide präsentieren denselben Maschinen-Fingerabdruck, und der zweite ActivateAsync frischt den Geräteeintrag des ersten auf.
Die Befehlszeilen, die ein Administrator tatsächlich ausführt
Was auch immer Sie bauen, das Ergebnis ist eine Zeile, die jemand in eine GPO, eine Intune-Win32-App oder ein SCCM-Programm einfügt. Dokumentieren Sie diese neben dem 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.
Zwei Warnungen, die es wert sind, dem Administrator in die Hand gegeben zu werden. Eigenschaftsnamen, die in der Befehlszeile übergeben werden, müssen öffentlich (Großbuchstaben) sein, sonst verwirft das MSI sie — LICENSEKEY, nie licenseKey. Und ein Schlüssel in einer Befehlszeile kann im ausführlichen MSI-Protokoll und kurz in der Prozessliste auftauchen; bevorzugen Sie für alles Sensible die Form der beigelegten Standortlizenz, und wenn Sie einen Schlüssel übergeben müssen, markieren Sie die Eigenschaft als Secure und sagen Sie den Administratoren, dass sie die paketweise /l*v-Protokollierung nicht in gemeinsam genutzten Transkripten aktivieren sollen.
Deinstallation, Reparatur und Upgrade
Die Komponente, die license.json besitzt, macht den Lebenszyklus der Datei zu dem des MSI. Eine Standard-Deinstallation entfernt sie, was korrekt ist — das Gerät ist nicht mehr lizenziert, das Produkt auszuführen. Eine Reparatur (msiexec /f) legt die beigelegte Standortlizenz erneut ab und heilt eine Datei, die ein Benutzer gelöscht hat. Ein Major-Upgrade ersetzt sie durch das, was das neue MSI mitführt, sodass, wenn Sie eine frische Standortlizenz in einem neuen Build ausliefern, sie die alte sauber ablöst.
Der vorbereitete Aktivierungsschlüssel ist anders: Er ist keine MSI-Komponente (der Installer schreibt ihn, er ist keine ausgelieferte Datei), also entfernt eine Deinstallation pending-activation.key nicht, es sei denn, Sie fügen einen RemoveFile-Eintrag hinzu — fügen Sie einen hinzu, damit eine Neuinstallation nicht gegen einen Schlüssel reaktiviert, den der Kunde inzwischen rotiert hat. Das Pro-Benutzer-Lease, das die App zwischengespeichert hat, ist Pro-Benutzer-AppData und per Design außerhalb der Reichweite des Installers; wenn der Kunde die Maschine außer Betrieb nimmt, lassen Sie ihn zuerst in der App deaktivieren oder geben Sie das Gerät im Devices-Panel der Lizenz im Keyright-Dashboard frei, genau wie bei jeder Platzverschiebung.
<Component Id="CleanStagedKey" Directory="AcmeProduct" Guid="*">
<RemoveFile Id="RmPendingKey" Name="pending-activation.key" On="uninstall" />
</Component>
Was mitzunehmen ist
Unternehmenssoftware wird von einem Werkzeug installiert und von einem Fremden ausgeführt, die Lizenz muss also an Ort und Stelle sein, bevor jemand die App startet. Legen Sie sie dorthin, wo das Gerät sie lesen kann — %ProgramData%, nicht Pro-Benutzer-AppData — und lassen Sie das MSI ihren Lebenszyklus besitzen. Ist die Bereitstellung netzwerkisoliert oder standortlizenziert, legen Sie eine signierte unbefristete Lizenz bei und richten Sie DefaultLicensePath darauf aus; der erste Start ist lizenziert, ohne Netzwerk und ohne Dialog. Ist sie pro Platz, bereiten Sie den Schlüssel aus einer verzögerten benutzerdefinierten Aktion vor und lassen Sie die App sich beim ersten Start im Kontext des Benutzers selbst aktivieren, wo Fingerabdruck und Netzwerk echt sind. In beiden Fällen sieht die Person, die den Laptop einschaltet, Ihr Produkt funktionieren, was der einzige akzeptable erste Start für Software ist, die sie nicht gekauft hat und nicht aktivieren kann.
Nebula.NET testen
Härten Sie Ihren .NET-Code in wenigen Minuten — starten Sie mit der kostenlosen Edition.