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 version="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

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 direkt mit dem dotnet run Befehl aus:

dotnet run file.cs

Oder verwenden Sie die Kurzhandsyntax:

dotnet file.cs

Übergeben von Argumenten

Übergeben Sie Argumente auf verschiedene Arten an Ihre Anwendung:

dotnet run file.cs -- arg1 arg2

Argumente nach -- werden an Ihre Anwendung übergeben. Ohne -- werden Argumente an den dotnet run Befehl weitergegeben.

dotnet run file.cs arg1 arg2

Mit der Kurzhandsyntax gehen jedoch alle Argumente zu Ihrer Anwendung:

dotnet 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 temporäres Projekt und erstellt Ihre Anwendung.

Bereinigen von Buildausgaben

Entfernen Sie Build-Artefakte mit dem dotnet clean Befehl:

dotnet clean file.cs

Bereinigen Sie alle dateibasierten Apps in einem Verzeichnis:

dotnet clean file-based-apps

Veröffentlichen von Anwendungen

Erstellen Sie ein Bereitstellungspaket mithilfe des dotnet publish Befehls:

dotnet publish file.cs

Dateibasierte Apps ermöglichen standardmäßig die native AOT-Veröffentlichung, wodurch optimierte, eigenständige ausführbare Dateien erzeugt werden.

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.

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 .csproj Datei mit entsprechenden SDK- und Eigenschaften erstellt. Alle # Direktiven werden aus der .cs Datei entfernt und in Elemente in der entsprechenden .csproj Datei umgewandelt.

Wiederherstellen von Abhängigkeiten

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

dotnet restore file.cs

Wiederherstellen wird implizit ausgeführt, wenn Sie Ihre Anwendung erstellen oder ausführen.

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" --project file.cs

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

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 zwischen, um die Leistung bei nachfolgenden Builds zu verbessern. Dateibasierte Apps nehmen an diesem Caching-System teil.

Cacheverhalten

Das SDK speichert Buildausgaben basierend auf:

Quelldateiinhalt.
Direktivenkonfiguration.
SDK-Version.
Implizite Builddateien.

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

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.