DE EN
Pakete & Feeds › NuGet- & npm-Pakete nutzen

NuGet- und npm-Pakete nutzen

FlawDesk Packages ist die private Paket-Registry unter packages.flawdesk.de. Sie spricht die Standard-Protokolle von NuGet (V3) und npm — du arbeitest also ganz normal mit dotnet, nuget und npm, nur mit deiner FlawDesk-Registry als Quelle.

Jeder Mandant hat einen eigenen Slug. In den Beispielen ist er als Platzhalter {slug} eingetragen — ersetze ihn durch deinen eigenen.

ℹ️ NuGet und npm teilen sich dasselbe Backend und dieselben Zugangsschlüssel. Ein Schlüsselpaar genügt für beide Protokolle.

Zugangsschlüssel

Schlüssel verwaltest du unter Projekt → Einstellungen → FlawDesk Packages. Es gibt zwei Typen:

  • Read-Key (flwpkg_r…) — zum Installieren und Restoren, also reiner Lesezugriff.
  • Push-Key (flwpkg_p…) — zum Veröffentlichen, also Schreibzugriff.
⚠️ Behandle den Push-Key wie ein Passwort. Er gehört nicht in ein Git-Repository und nicht in ausgelieferte Software.

Benutzername und Passwort

Überall, wo nach Zugangsdaten gefragt wird — der Credential-Dialog in Visual Studio, eine nuget.config, eine .npmrc — gilt dasselbe Schema:

  • Benutzername = dein Slug, also der technische Bezeichner deines Workspaces. Bei Workspace „XantoSoft" ist das xantosoft. Du findest ihn auch direkt in der Feed-URL: packages.flawdesk.de/xantosoft/v3/… — dieses Pfad-Segment ist der Slug.
  • Passwort = dein Read-Key zum Installieren/Restoren, bzw. dein Push-Key zum Veröffentlichen.
⚠️ Der Benutzername ist nicht flawdesk und auch nicht dein FlawDesk-Login. Der Feed-Server prüft Benutzername == Slug — passt der Username nicht zum Slug im Pfad, kommt ein 401, selbst mit korrektem Schlüssel.

Ein Workspace hat genau einen Slug und ein Schlüsselpaar; alle Projekte darin teilen sich denselben Feed und denselben Benutzernamen.

Von FlawDesk eingerichtete Projekte

Wenn ein Projekt über den Code-Connector angebunden ist, richtet FlawDesk den Feed automatisch ein — du musst die nuget.config (bzw. .npmrc) nicht selbst schreiben. Bei der Aktivierung von FlawDesk Packages bzw. beim Provisioning legt FlawDesk im Repository eine nuget.config an, die den Read-Key nicht im Klartext enthält, sondern über eine Umgebungsvariable bezieht:

<add key="Username" value="{slug}" />
<add key="ClearTextPassword" value="%FLAWDESK_NUGET_KEY%" />

Der Platzhalter %FLAWDESK_NUGET_KEY% wird zur Restore-Zeit aus der Umgebung aufgelöst. Damit landet kein Schlüssel im Git-Verlauf, und derselbe Feed funktioniert lokal, im CI und auf dem Server.

Wo der Schlüssel herkommt

  • GitHub Actions — FlawDesk setzt das Repository-Secret FLAWDESK_NUGET_KEY beim Provisioning automatisch. Im Windows-Build-Workflow ist es als Job-Umgebungsvariable verdrahtet; dort musst du nichts weiter tun.
  • Server-Builds über den Connector (flawdesk_code_dotnet) — der Schlüssel wird automatisch aus dem aktivierten Mandanten in die Build-Umgebung injiziert. Auch hier kein manueller Schritt.
  • Deine lokale Entwicklungsmaschine — hier, und nur hier, musst du den Schlüssel einmal selbst hinterlegen. Der empfohlene Weg dafür steht unten.

Der Platzhalter %FLAWDESK_NUGET_KEY% ist also primär für CI und Server gedacht — beide Umgebungen haben keinen interaktiven Anmelde-Speicher und beziehen den Schlüssel aus der Umgebungsvariable. Auf deinem Desktop brauchst du die Variable nicht; der Windows-Anmeldeinformations-Speicher (Credential Manager) deckt das einfacher ab.

Lokale Maschine einrichten (einmalig, empfohlen)

Beim ersten dotnet restore bzw. beim Öffnen der Solution fragt Visual Studio per Dialog nach Zugangsdaten für packages.flawdesk.de. Trag dort ein:

  • Benutzername: dein Slug (z. B. xantosoft)
  • Kennwort: dein Read-Key (flwpkg_r…, zu finden unter Projekt → Einstellungen → FlawDesk Packages → Anzeigen)
  • „Kennwort speichern" anhaken → OK

Damit landet die Anmeldung im Windows Credential Manager, persistiert dort und funktioniert unabhängig von Umgebungsvariablen. Einmal eintragen, nie wieder.

ℹ️ Der Credential Manager gilt pro Windows-Benutzer für alle Projekte gegen packages.flawdesk.de — du trägst die Daten einmal pro Maschine ein, nicht pro Repository.

Falls du stattdessen die Umgebungsvariable willst

Für dotnet auf der Kommandozeile oder headless-Szenarien kannst du den Schlüssel auch als Umgebungsvariable setzen — dann greift der %FLAWDESK_NUGET_KEY%-Platzhalter aus der nuget.config auch lokal:

[Environment]::SetEnvironmentVariable('FLAWDESK_NUGET_KEY','flwpkg_r…','User')
⚠️ Unter Windows reicht es nicht, danach nur Visual Studio neu zu starten. GUI-Anwendungen erben ihren Umgebungs-Block von explorer.exe, der den alten Stand festhält. Damit die Variable bei VS ankommt, musst du dich ab- und wieder anmelden (oder explorer.exe neu starten) — erst dann sehen neu gestartete GUI-Prozesse den neuen Wert. Genau deshalb ist der Credential-Manager-Weg oben für VS der zuverlässigere.

Den manuellen Weg unten (Schlüssel direkt in die nuget.config) brauchst du nur für Projekte, die nicht über den Connector laufen, oder wenn du den Feed global im Benutzerprofil einrichten willst.

NuGet

Feed-Quelle einrichten

Der Service-Index deines Feeds:

https://packages.flawdesk.de/{slug}/v3/index.json

Trag ihn in deine nuget.config ein (neben dem Projekt oder global im Benutzerprofil). Beim Restore meldet sich NuGet per Basic-Auth an — der Benutzername muss exakt dein Slug sein, das Passwort ist dein Read-Key:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="flawdesk" value="https://packages.flawdesk.de/{slug}/v3/index.json" />
  </packageSources>
  <packageSourceCredentials>
    <flawdesk>
      <add key="Username" value="{slug}" />
      <add key="ClearTextPassword" value="DEIN_READ_KEY" />
    </flawdesk>
  </packageSourceCredentials>
</configuration>

Danach arbeitest du wie gewohnt:

dotnet restore
dotnet add package MeinPaket

Paket veröffentlichen

Veröffentlicht wird mit dem Push-Key als API-Key:

dotnet nuget push MeinPaket.1.0.0.nupkg --source https://packages.flawdesk.de/{slug}/v3/index.json --api-key DEIN_PUSH_KEY
ℹ️ Versionen sind unveränderlich. Eine bereits veröffentlichte Version lässt sich nicht überschreiben — erhöhe für jeden Push die Versionsnummer.

npm

Registry einrichten

Trag in deine .npmrc (im Projekt oder global im Benutzerprofil) das Scope-Mapping und den Token ein. Für ein Scoped Package unter @{slug}:

@{slug}:registry=https://packages.flawdesk.de/{slug}/npm/
//packages.flawdesk.de/{slug}/npm/:_authToken=DEIN_KEY
ℹ️ Die mit // beginnende Zeile ist kein Kommentar, sondern npm-Syntax — sie bindet den Auth-Token an genau diese Registry.

Als _authToken nimmst du zum Installieren den Read-Key und zum Veröffentlichen den Push-Key.

npm install @{slug}/mein-paket

Paket veröffentlichen

Mit hinterlegtem Push-Key:

npm publish

Troubleshooting

  • 401 Unauthorized — Schlüssel fehlt, ist falsch oder wurde widerrufen, oder der Benutzername passt nicht zum Slug (häufigster Tippfehler: flawdesk statt xantosoft eingetragen — der Benutzername muss der Slug sein, siehe „Benutzername und Passwort"). Bei von FlawDesk eingerichteten Projekten kann zusätzlich die Umgebungsvariable FLAWDESK_NUGET_KEY fehlen, sodass der Platzhalter in der nuget.config zu einem leeren Passwort auflöst — auf dem Desktop am einfachsten über den Credential-Dialog lösen (siehe „Lokale Maschine einrichten").
  • 403 Forbidden — Der Schlüsseltyp passt nicht zum Vorgang: ein Read-Key auf einem Schreib-Endpoint oder umgekehrt. Push braucht den Push-Key, Restore und Install den Read-Key.
  • 409 Conflict (NuGet) — Die Version existiert bereits im Feed. Versionsnummer erhöhen.