Nextended.Aspire.Hosting.AspireUI

📚 Vollständige API-Referenz — jeder öffentliche Typ und Member, erzeugt aus der kompilierten Assembly.

🇬🇧 This page in English

AspireUI — der visuelle AppHost-Builder für .NET Aspire — als Ressource im eigenen Aspire-Stack.

▶ Beispielprojekt ansehen — lauffähiger AppHost für diese Integration.

Installation

dotnet add package Nextended.Aspire.Hosting.AspireUI

Ins AppHost-Projekt.

Schnellstart

var builder = DistributedApplication.CreateBuilder(args);

builder.AddAspireUI()
    .WithAdminUser("admin", builder.AddParameter("aspireui-password", secret: true))
    .WithSeedStack("Mein Stack", "../MyApi", "../MyWorker");

builder.Build().Run();

Der Container ghcr.io/fgilde/aspireui bekommt einen HTTP-Endpunkt und erscheint im Aspire-Dashboard wie jede andere Ressource.

API

Der Container

Aufruf	Wirkung
AddAspireUI(name = "aspireui", port?, image?, tag?)	Fügt den AspireUI-Container hinzu.
.WithDataBindMount(hostPath)	Legt AspireUIs Daten in einen Host-Ordner statt in ein benanntes Volume.
.WithoutDockerSocket()	Läuft ohne den Docker-Socket des Hosts: Bauen und Deploy auf ein entferntes Ziel gehen weiter, Hosting auf diesem Rechner nicht.
.WithDockerHost(dockerHost)	Richtet AspireUIs Docker-Client woanders hin (DOCKER_HOST), impliziert WithoutDockerSocket().
.WithSourceMount(hostPath, containerPath?)	Bindet Quellcode in den Container ein, damit ein angelegter Stack dort auch laufen kann.

Benutzer und Tokens

Aufruf	Wirkung
.WithAdminUser(username, password)	Legt den Administrator beim ersten Start an (idempotent, Passwort gehasht). Nimmt auch eine Aspire-ParameterResource.
.WithUser(username, password, permissions?, viewModes?, mustChangePassword?)	Legt ein Konto an. permissions ist ein Preset aus AspireUIPermissions oder eine kommagetrennte Liste von Ids. Passwort auch als ParameterResource.
.WithUsers(params AspireUIUser[])	Legt mehrere Konten auf einmal an, Administratoren eingeschlossen.
.WithAppUser(username, password)	Ein Konto, das Apps installiert, konfiguriert und Dateien ansieht — ohne Builder.
.WithViewer(username, password)	Ein Konto, das nur schauen darf.
.WithApiToken(name, username, token)	Ein Bearer-Token für Automatisierung, mit einem Wert, den Sie schon kennen. Auch als ParameterResource.

Deploy-Ziele

Aufruf	Wirkung
.WithSshTarget(name, host, user, port, keyFile?, key?, passphrase?, publicHost?, isDefault?)	Der Docker-Daemon eines anderen Rechners über SSH. keyFile wird nur lesbar eingebunden und landet in keiner Umgebungsvariable.
.WithDockerTcpTarget(name, host, port, caFile?, certFile?, keyFile?, publicHost?, isDefault?)	Ein Docker-Daemon über TCP mit mTLS; die drei Zertifikate werden nur lesbar eingebunden.
.WithKubernetesTarget(name, context?, kubeconfigFile?, namespace?, expose?, ingressHost?, storageClass?, isDefault?)	Ein Kubernetes-Cluster, per Helm bespielt.

Apps und Stacks

Aufruf	Wirkung
.WithApps(params catalogIds)	Installiert Apps aus AspireUIs eigenem Katalog per Id (vaultwarden, gitea, …).
.WithApp(catalogId, name?, deploy?)	Installiert eine Katalog-App unter einem eigenen Namen.
.WithAppSource(name, url)	Registriert eine App-Manifest-URL als Store-Quelle.
.WithSeedStack(name, params projectPaths)	Legt einen Stack mit je einem AddProject-Knoten pro Pfad an.
.WithProjectStack(name, params projects)	Dasselbe aus den ProjectResources dieses AppHosts — deren Ordner werden eingebunden, damit der Stack auch laufen kann.
.WithSeedFromDirectory(hostPath, name?, mode?, deploy?)	Importiert einen Ordner als Stack: Manifest, Compose-Datei oder AppHost, je was drin liegt. Nur lesbar eingebunden, als Kopie importiert.
.WithSeedFromCompose(hostPath, name?, deploy?)	Importiert eine einzelne docker-compose-Datei als Stack.
.WithSeedFromGit(url, branch?, subdir?, name?, mode?, deploy?)	Klont ein Repository im Container und importiert es.
.WithSeedFile(hostPath)	Bindet ein Seed-Dokument (oder einen Ordner mit aspireui.seed.json) ein und zeigt AspireUI darauf.
.WithAutoDeploy(deploy = true)	Deployt die angelegten Stacks und Apps, sobald das Hosting läuft.

Einstellungen

Aufruf	Wirkung
.WithAssistant(endpoint, model, apiKey?, label?)	Das Backend des Assistenten: eine OpenAI-kompatible URL. Nimmt auch eine ReferenceExpression für einen erst beim Start bekannten Endpunkt und eine Aspire-ParameterResource für den Key.
.WithAssistant(server, model, apiKey?, apiPath?, endpointName?, label?)	Ein Modell-Server in diesem Stack — Ollama, LocalAI, vLLM, llama.cpp. AspireUI wartet auf ihn und spricht über das Container-Netz mit ihm.
.WithOllamaAssistant(ollama, model = "llama3.2") / .WithLocalAiAssistant(localAi, model)	Dasselbe, benannt nach den zwei Servern, zu denen die meisten zuerst greifen.
.WithCliAssistant(tool, model?)	Ein Agent-CLI auf dem AspireUI-Host (claude, gemini, ollama, llm, codex). Antwortet auf Fragen, kann keine Tools aufrufen.
.WithAi(baseUrl, model, apiKey?) / .WithAi(backend, model, …)	Der ältere Name für die ersten beiden.
.WithPublicHost(host)	Der Hostname, aus dem App-URLs gebaut werden.
.WithNginxProxyManager(baseUrl, email, password, forwardHost?)	Damit eine gehostete App aus ihrem eigenen Menü eine Domain und ein Zertifikat bekommen kann. Nimmt auch eine NPM-Ressource aus demselben Stack.
.WithNotifications(webhookUrl?, telegramToken?, telegramChat?)	Wohin gemeldet wird, dass eine App hochkam, wegging oder anfing zu scheitern.
.WithBackupSchedule(intervalHours = 24, retain = 7)	Sichert die Volumes jeder gehosteten App nach Plan.
.WithHostedDashboards(browserToken?)	Hostet neben jeder deployten App ein Aspire-Dashboard.
.WithSingleSignOn(authority, clientId, clientSecret?, label?, …)	Anmeldung über einen OpenID-Connect-Provider. Nötig sind nur Authority und Client-Id — die Endpunkte kommen aus dem Discovery-Dokument des Providers. Das Secret nimmt auch eine Aspire-ParameterResource.
.WithS3Backups(bucket, accessKey, secretKey, endpoint?, region?, pathStyle?)	Kopiert jedes Backup in einen S3-kompatiblen Bucket.
.WithWebDavBackups(baseUrl, user, password)	Kopiert jedes Backup auf eine WebDAV-Freigabe.
.WithSshBackups(host, user, path, keyFile?, port?)	Kopiert jedes Backup per scp in ein Verzeichnis auf einem anderen Rechner; die Schlüsseldatei wird nur lesbar eingebunden.
.WithAuditRetention(days)	Wie lange das Aktivitätsprotokoll einen Eintrag behält (0 = alles behalten).
.WithSettings(s => { … })	Alle Einstellungen aus AspireUIs Settings, typisiert: Public-Host, mitgelieferte Dashboards, Proxy, Benachrichtigungen, Backup-Plan, Import-Grenzen, Aufbewahrung des Aktivitätsprotokolls und das Backend des Assistenten. Was null bleibt, wird nicht gesetzt.
.WithSetting(key, parameter)	Eine Einstellung, deren Wert ein Secret ist, aus einer Aspire-ParameterResource.
.WithSetting(key, value)	Jede AspireUI-Einstellung per Schlüssel.
.WithForcedSettings(force = true)	Wendet diese Einstellungen bei jedem Start an, statt nur zu füllen, was leer ist.

Alles ist idempotent über den Namen: ein Neustart mit demselben AppHost ändert nichts, ein hinzugefügter Eintrag fügt genau diesen hinzu, und was in der UI geändert wurde, bleibt geändert. WithAdminUser ist die Ausnahme — wie AspireUIs eigenes Erst-Seeding wird es übersprungen, sobald irgendein Konto existiert.

var builder = DistributedApplication.CreateBuilder(args);

var opsPassword = builder.AddParameter("ops-password", secret: true);

builder.AddAspireUI()
    .WithAdminUser("admin", "change-me-please")
    .WithUser("ops", opsPassword, AspireUIPermissions.Operator)
    .WithViewer("guest", "guest-password-1")
    .WithApiToken("pipeline", "ops", builder.AddParameter("ci-token", secret: true))
    .WithSshTarget("nas", "nas.local", "deploy", keyFile: "./keys/id_ed25519")
    .WithApps("vaultwarden", "gitea")
    .WithSeedFromDirectory("./seed/edge", "Edge")
    .WithOllamaAssistant(ollama, "llama3.2")
    .WithAutoDeploy();

builder.Build().Run();

Sicherheit

Docker-Socket

Der eingebundene Docker-Socket gibt dem Container Kontrolle über den Docker-Daemon des Hosts. Betreiben Sie das nur auf einem vertrauenswürdigen Rechner — in der Praxis heißt das: lokale Entwicklung, nicht ein geteilter oder öffentlich erreichbarer Host.

Passwörter und Tokens gehören in Aspire-Parameter, Schlüsselmaterial in die Dateien, die die Ziel-Methoden einbinden — dann landet beides nicht im Manifest.

var password = builder.AddParameter("aspireui-password", secret: true);
builder.AddAspireUI().WithAdminUser("admin", password);

Ausführbares Beispiel

git clone https://github.com/fgilde/Nextended.git
cd Nextended/Tests/TestProjects/AspireUI.AppHost
dotnet run

Unterstützte Frameworks

• net8.0
• net9.0
• net10.0

Abhängigkeiten

• Aspire.Hosting.AppHost

Links

• 📦 NuGet-Paket
• 🧑‍💻 Quellcode
• 🧪 Beispiel-AppHost
• 🔗 AspireUI-Projekt
• 🐛 Fehler melden