Dateibasierte Apps

Dieser Artikel bezieht sich auf: ✔️ .NET 10 SDK und höhere Versionen

Mit dateibasierten Apps können Sie .NET-Anwendungen aus einer einzigen C#-Datei erstellen, ausführen und veröffentlichen, ohne eine herkömmliche Projektdatei zu erstellen. Sie bieten eine einfache Alternative zu herkömmlichen .NET-Projekten. Dieser Ansatz vereinfacht die Entwicklung von Skripts, Hilfsprogrammen und kleinen Anwendungen. Das .NET SDK generiert automatisch die erforderliche Projektkonfiguration basierend auf den Direktiven in Der Quelldatei.

Zu den wichtigsten Vorteilen gehören:

Reduzierter Textbaustein für einfache Anwendungen.
Eigenständige Quelldateien mit eingebetteter Konfiguration.
Native AOT-Veröffentlichung standardmäßig aktiviert.
Automatische Paketierung als .NET-Tools.

In diesem Artikel erfahren Sie, wie Sie dateibasierte Apps effektiv erstellen, konfigurieren und damit arbeiten.

Unterstützte Direktiven

Dateibasierte Apps verwenden Direktiven, die präfixiert #: sind, um den Build zu konfigurieren und die Anwendung auszuführen. Zu den unterstützten Direktiven gehören: #:package, , #:project, #:propertyund #:sdk. Platzieren Sie diese Direktiven am Anfang der C#-Datei.

`#:package`

Fügt Ihrer Anwendung einen NuGet-Paketverweis hinzu.

#:package Newtonsoft.Json
#:package Serilog@3.1.1

`#:project`

Verweist auf eine andere Projektdatei oder ein anderes Verzeichnis, das eine Projektdatei enthält.

#:project ../SharedLibrary/SharedLibrary.csproj

`#:property`

Legt einen MSBuild-Eigenschaftswert fest.

#:property TargetFramework=net10.0
#:property PublishAot=false

`#:sdk`

Gibt das zu verwendende SDK an. Wird standardmäßig auf Microsoft.NET.Sdk festgelegt.

#:sdk Microsoft.NET.Sdk.Web
#:sdk Aspire.AppHost.Sdk@13.0.2

CLI-Befehle

Die .NET CLI bietet vollständige Unterstützung für dateibasierte Apps über vertraute Befehle.

Ausführen von Anwendungen

Führen Sie eine dateibasierte App mithilfe des dotnet run Befehls mit der --file Option aus:

dotnet run --file file.cs

Oder verwenden Sie den dotnet run Befehl gefolgt vom Namen der Datei:

dotnet run file.cs

Oder verwenden Sie die Kurzhandsyntax:

dotnet file.cs

Übergeben von Argumenten

Übergeben Sie Argumente an Ihre Anwendung, indem Sie sie hinter -- platzieren.

dotnet run file.cs -- arg1 arg2

Ohne -- werden Argumente an den dotnet run Befehl weitergegeben.

dotnet run file.cs arg1 arg2

Erstellen von Anwendungen

Kompilieren Sie Ihre dateibasierte App mithilfe des dotnet build Befehls:

dotnet build file.cs

Das SDK generiert ein virtuelles Projekt und erstellt Ihre Anwendung. Standardmäßig gelangt die Build-Ausgabe in das temporäre Verzeichnis des Systems unter <temp>/dotnet/runfile/<appname>-<appfilesha>/bin/<configuration>/.

Verwenden Sie die --output Option mit dem dotnet build Befehl, um einen anderen Pfad anzugeben. Um einen neuen Standardausgabepfad zu definieren, legen Sie die OutputPath Eigenschaft am Anfang der Datei mithilfe der Direktive fest: #:property OutputPath=./output.

Bereinigen von Buildausgaben

Entfernen Sie Build-Artefakte mit dem dotnet clean Befehl:

dotnet clean file.cs

Löschen des Caches für dateibasierte Apps in einem Verzeichnis:

dotnet clean file-based-apps

Verwenden Sie die --days Option mit dem vorherigen Befehl, um anzugeben, wie viele Tage ein Artefaktordner vor dem Entfernen nicht verwendet werden muss. Die Standardanzahl von Tagen ist 30.

Veröffentlichen von Anwendungen

Dateibasierte Apps ermöglichen standardmäßig die native AOT-Veröffentlichung, wodurch optimierte, eigenständige ausführbare Dateien erzeugt werden. Deaktivieren Sie dieses Feature, indem Sie oben in der Datei hinzufügen #:property PublishAot=false .

Verwenden Sie den dotnet publish Befehl, um eine unabhängige ausführbare Datei zu erstellen:

dotnet publish file.cs

Der Standardspeicherort der ausführbaren Datei ist ein artifacts Verzeichnis neben der .cs Datei, wobei ein Unterverzeichnis nach der Anwendung benannt ist. Verwenden Sie die --output Option mit dem dotnet publish Befehl, um einen anderen Pfad anzugeben.

Paket als Tool

Packen Sie Ihre dateibasierte App mithilfe des dotnet pack Befehls als .NET-Tool:

dotnet pack file.cs

Die dateibasierten Apps sind standardmäßig PackAsTool=true festgelegt. Deaktivieren Sie diese Einstellung, indem Sie oben in der Datei hinzufügen #:property PackAsTool=false .

In Projekt konvertieren

Konvertieren Sie Ihre dateibasierte App mithilfe des dotnet project convert Befehls in ein herkömmliches Projekt:

dotnet project convert file.cs

Mit diesem Befehl wird eine Kopie der .cs Datei erstellt und eine .csproj Datei mit entsprechenden SDK-Elementen, Eigenschaften und Paketverweise basierend auf den Direktiven der ursprünglichen #: Datei erstellt. Beide Dateien werden in einem Verzeichnis platziert, das für die Anwendung neben der ursprünglichen .cs Datei benannt ist, was unverändert bleibt.

Wiederherstellen von Abhängigkeiten

Wiederherstellen von NuGet-Paketen, auf die in Ihrer Datei verwiesen wird, mithilfe des dotnet restore Befehls:

dotnet restore file.cs

Standardmäßig wird die Wiederherstellung implizit ausgeführt, wenn Sie Ihre Anwendung erstellen oder ausführen. Sie können jedoch --no-restore sowohl an die dotnet build- als auch an die dotnet run-Befehle übergeben, um sie auszuführen oder zu erstellen, ohne implizit wiederherzustellen.

Standardmäßig enthaltene Elemente

Dateibasierte Apps enthalten automatisch bestimmte Dateitypen für die Kompilierung und Verpackung.

Standardmäßig sind die folgenden Elemente enthalten:

Die einzelne C#-Datei selbst.
ResX-Ressourcendateien im selben Verzeichnis.

Zu den verschiedenen SDKs gehören andere Dateitypen:

Microsoft.NET.Sdk.Web enthält *.json Konfigurationsdateien.
Andere spezialisierte SDKs können andere Muster enthalten.

Native AOT-Veröffentlichung

Dateibasierte Apps aktivieren standardmäßig die native Ahead-of-Time (AOT)-Kompilierung. Dieses Feature erzeugt optimierte, eigenständige ausführbare Dateien mit schnellerem Start und einem kleineren Speicherbedarf.

Wenn Sie systemeigene AOT deaktivieren müssen, verwenden Sie die folgende Einstellung:

#:property PublishAot=false

Weitere Informationen zu systemeigenem AOT finden Sie in der nativen AOT-Bereitstellung.

Benutzergeheimnisse

Dateibasierte Apps generieren eine stabile geheime Benutzerschlüssel-ID basierend auf einem Hash des vollständigen Dateipfads. Mit dieser ID können Sie vertrauliche Konfiguration getrennt von Ihrem Quellcode speichern.

Zugriff auf geheime Benutzerschlüssel auf die gleiche Weise wie herkömmliche Projekte:

dotnet user-secrets set "ApiKey" "your-secret-value" --file file.cs

Auflisten von geheimen Benutzerschlüsseln für dateibasierte Apps:

dotnet user-secrets list --file file.cs

Der dotnet user-secrets list Befehl druckt den Wert Ihrer geheimen Schlüssel. Platzieren Sie diesen Befehl nicht in Skripts, die in öffentlichen Kontexten ausgeführt werden.

Weitere Informationen finden Sie unter "Sicherer Speicher von geheimen App-Schlüsseln in der Entwicklung".

Profile starten

Dateibasierte Apps unterstützen Startprofile zum Konfigurieren der Ausführung der Anwendung während der Entwicklung. Anstatt Startprofile in Properties/launchSettings.jsonzu platzieren, können dateibasierte Apps eine Datei mit flachen Starteinstellungen verwenden, die im selben Verzeichnis wie die Quelldatei benannt ist [ApplicationName].run.json .

Datei für einfache Starteinstellungen

Erstellen Sie eine Starteinstellungsdatei, die nach Ihrer Anwendung benannt ist. Wenn Ihre dateibasierte App beispielsweise lautet app.cs, erstellen Sie app.run.json im selben Verzeichnis:

{
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Mehrere dateibasierte Apps

Wenn Sie über mehrere dateibasierte Apps im selben Verzeichnis verfügen, kann jede App über eine eigene Starteinstellungsdatei verfügen:

📁 myapps/
├── foo.cs
├── foo.run.json
├── bar.cs
└── bar.run.json

Profilauswahl

Die .NET CLI wählt Startprofile mit der folgenden Priorität aus:

Das durch die --launch-profile Option angegebene Profil.
Das durch die Umgebungsvariable DOTNET_LAUNCH_PROFILE angegebene Profil.
Das erste Profil, das in der Starteinstellungsdatei definiert ist.

Um mit einem bestimmten Profil zu arbeiten:

dotnet run app.cs --launch-profile https

Herkömmliche Starteinstellungen

Dateibasierte Apps unterstützen auch die herkömmliche Properties/launchSettings.json Datei. Wenn beide Dateien vorhanden sind, hat der herkömmliche Speicherort Vorrang. Wenn beide Dateien vorhanden sind, protokolliert die .NET CLI eine Warnung, um zu verdeutlichen, welche Datei verwendet wird.

Shellausführung

Ermöglichen Sie die direkte Ausführung von dateibasierten Apps auf Unix-ähnlichen Systemen mithilfe einer Shebang-Linie und ausführbaren Berechtigungen.

Fügen Sie oben in Ihrer Datei einen Shebang hinzu:

#!/usr/bin/env dotnet
#:package Spectre.Console

using Spectre.Console;

AnsiConsole.MarkupLine("[green]Hello, World![/]");

Datei ausführbar machen:

chmod +x file.cs

Direkt ausführen:

./file.cs

Hinweis

Verwenden Sie LF-Zeilenenden anstelle von CRLF, wenn Sie einen Shebang hinzufügen. Fügen Sie keine BOM in die Datei ein.

Implizite Builddateien

Dateibasierte Apps respektieren MSBuild- und NuGet-Konfigurationsdateien in demselben Verzeichnis oder übergeordneten Verzeichnissen. Diese Dateien wirken sich darauf aus, wie das SDK Ihre Anwendung erstellt. Beachten Sie diese Dateien beim Organisieren Ihrer dateibasierten Apps.

`Directory.Build.props`

Definiert MSBuild-Eigenschaften, die für alle Projekte in einer Verzeichnisstruktur gelten. Dateibasierte Apps erben diese Eigenschaften.

`Directory.Build.targets`

Definiert MSBuild-Ziele und benutzerdefinierte Buildlogik. Dateibasierte Apps führen diese Ziele während des Builds aus.

`Directory.Packages.props`

Aktiviert die zentrale Paketverwaltung für NuGet-Abhängigkeiten. Dateibasierte Apps können zentral verwaltete Paketversionen verwenden.

`nuget.config`

Konfiguriert NuGet-Paketquellen und -einstellungen. Dateibasierte Apps verwenden diese Konfigurationen beim Wiederherstellen von Paketen.

`global.json`

Gibt die zu verwendende .NET SDK-Version an. Dateibasierte Apps respektieren diese Versionsauswahl.

Zwischenspeichern erstellen

Das .NET SDK speichert Buildausgaben zwischenspeichern, um die Performance bei nachfolgenden Aufrufen von dotnet run zu verbessern. Dieses Zwischenspeicherungssystem ist für dateibasierte Apps einzigartig.

Cacheverhalten

Das SDK speichert Buildausgaben basierend auf:

Quelldateiinhalt.
Direktivenkonfiguration.
SDK-Version.
Implizite Existenz und Inhalt von Build-Dateien.

Die Zwischenspeicherung verbessert die Buildleistung, kann jedoch zu Verwirrung führen, wenn:

Änderungen an impliziten Builddateien lösen keine Neuerstellungen aus.
Durch das Verschieben von Dateien in verschiedene Verzeichnisse wird kein Cache ungültig.

Problemumgehungen

Löschen Sie Cacheartefakte für dateibasierte Apps mithilfe des folgenden Befehls:

dotnet clean file-based-apps

Führen Sie einen vollständigen Build mit der --no-cache Kennzeichnung aus:
```
dotnet build file.cs --no-cache
```
Erzwingen eines sauberen Builds, um den Cache zu umgehen.
```
dotnet clean file.cs
dotnet build file.cs
```

Empfehlungen für das Ordnerlayout

Organisieren Sie Ihre dateibasierten Apps sorgfältig, um Konflikte mit herkömmlichen Projekten und impliziten Builddateien zu vermeiden.

Vermeiden Sie Projektdatei-Strukturen in Kegelform

Platzieren Sie keine dateibasierten Apps in der Verzeichnisstruktur eines .csproj Projekts. Die impliziten Builddateien und Einstellungen der Projektdatei können ihre dateibasierte App beeinträchtigen.

❌ Nicht empfohlen:

📁 MyProject/
├── MyProject.csproj
├── Program.cs
└──📁 scripts/
    └── utility.cs  // File-based app - bad location

✅ Empfohlen:

📁 MyProject/
├── MyProject.csproj
└── Program.cs
📁 scripts/
└── utility.cs  // File-based app - good location

Achten Sie auf implizite Dateien

Implizite Builddateien in übergeordneten Verzeichnissen wirken sich auf alle dateibasierten Apps in Unterverzeichnissen aus. Erstellen Sie isolierte Verzeichnisse für dateibasierte Apps, wenn Sie unterschiedliche Buildkonfigurationen benötigen.