Souborové aplikace

Tento článek se vztahuje na: ✔️ .NET 10 SDK a novější verze

Aplikace založené na souborech umožňují vytvářet, spouštět a publikovat aplikace .NET z jednoho souboru C# bez vytvoření tradičního souboru projektu. Nabízejí odlehčenou alternativu k tradičním projektům .NET. Tento přístup zjednodušuje vývoj skriptů, nástrojů a malých aplikací. Sada .NET SDK automaticky vygeneruje potřebnou konfiguraci projektu na základě direktiv ve zdrojovém souboru.

Mezi klíčové výhody patří:

Snížení šablonového kódu pro jednoduché aplikace.
Samostatné zdrojové soubory s vloženou konfigurací
Nativní publikování AOT je ve výchozím nastavení povolené.
Automatizované balíčkování jako nástroje .NET

V tomto článku se dozvíte, jak efektivně vytvářet, konfigurovat a pracovat se souborovými aplikacemi.

Podporované direktivy

Aplikace založené na souborech používají direktivy s #: předponou ke konfiguraci procesu sestavení a spouštění aplikace. Mezi podporované direktivy patří: #:package, #:project, #:propertya #:sdk. Tyto direktivy umístěte na začátek souboru C#.

`#:package`

Přidá do aplikace odkaz na balíček NuGet.

#:package Newtonsoft.Json
#:package Serilog@3.1.1
#:package Spectre.Console@*

Poznámka:

Vynechání čísla verze za názvem balíčku v současné době funguje jenom v případech, kdy používáte centrální správu balíčků se souborem Directory.Packages.props . V opačném případě zadejte explicitně číslo verze nebo přidejte @* za název balíčku, aby používal nejnovější verzi.

`#:project`

Odkazuje na jiný soubor projektu nebo adresář, který obsahuje soubor projektu.

#:project ../SharedLibrary/SharedLibrary.csproj

`#:property`

Nastaví hodnotu vlastnosti MSBuild.

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

`#:sdk`

Určuje sadu SDK, která se má použít. Výchozí hodnota je Microsoft.NET.Sdk.

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

Příkazy CLI

Rozhraní příkazového řádku .NET poskytuje úplnou podporu pro souborové aplikace prostřednictvím známých příkazů.

Spouštění aplikací

Spusťte aplikaci založenou na souborech pomocí příkazu dotnet run s volbou --file:

dotnet run --file file.cs

Nebo použijte dotnet run příkaz následovaný názvem souboru:

dotnet run file.cs

Nebo použijte zkrácenou syntaxi:

dotnet file.cs

Předání argumentů

Předejte do aplikace argumenty jejich umístěním za --:

dotnet run file.cs -- arg1 arg2

Kód potrubí ze stdinu

Kód jazyka C# směrujte přímo do dotnet run pomocí standardního vstupu s argumentem -. Argument - označuje, že dotnet run čte kód ze standardního vstupu místo souboru. S použitím argumentu -dotnet run neprohledává v aktuálním pracovním adresáři jiné soubory, jako například profily spuštění. Aktuální adresář je stále pracovním adresářem pro sestavení a spuštění programu.

PowerShell:

'Console.WriteLine("hello from stdin!");' | dotnet run -

Bash:

echo 'Console.WriteLine("hello from stdin!");' | dotnet run -

Tento přístup je užitečný pro rychlé testování, spouštění jednorázových příkazů nebo integraci se skripty prostředí, které dynamicky generují kód jazyka C#.

Sestavování aplikací

Zkompilujte aplikaci založenou na souborech dotnet build pomocí příkazu:

dotnet build file.cs

Sada SDK vygeneruje virtuální projekt a sestaví vaši aplikaci. Výstup sestavení se ve výchozím nastavení ukládá do dočasného adresáře systému v části <temp>/dotnet/runfile/<appname>-<appfilesha>/bin/<configuration>/.

--output Pomocí možnosti s příkazem dotnet build zadejte jinou cestu. Chcete-li definovat novou výchozí výstupní cestu, nastavte OutputPath vlastnost v horní části souboru pomocí direktivy: #:property OutputPath=./output.

Vyčištění výstupů sestavení

Pomocí příkazu dotnet clean odeberte artefakty sestavení.

dotnet clean file.cs

Odstraňte mezipaměť pro souborové aplikace v adresáři:

dotnet clean file-based-apps

--days Pomocí možnosti s předchozím příkazem určete, kolik dní musí být složka artefaktů před odebráním nepoužitá. Výchozí počet dní je 30.

Publikování aplikací

Aplikace pracující se soubory umožňují výchozí nativní AOT publikování, které vytváří optimalizované, samostatné spustitelné soubory. Tuto funkci zakažte přidáním #:property PublishAot=false do horní části souboru.

dotnet publish Pomocí příkazu vytvořte nezávislý spustitelný soubor:

dotnet publish file.cs

Výchozí umístění spustitelného souboru je artifacts adresář vedle .cs souboru s podadresářem pojmenovaným po aplikaci. --output Pomocí možnosti s příkazem dotnet publish zadejte jinou cestu.

Balíček jako nástroj

Zabalte svou souborovou aplikaci jako nástroj .NET pomocí příkazu dotnet pack:

dotnet pack file.cs

Aplikace založené na souborech jsou standardně nastavené PackAsTool=true . Toto nastavení zakažte přidáním #:property PackAsTool=false v horní části souboru.

Převést na projekt

Pomocí příkazu převeďte aplikaci založenou dotnet project convert na souborech na tradiční projekt:

dotnet project convert file.cs

Tento příkaz vytvoří kopii .cs souboru a vytvoří .csproj soubor s ekvivalentními položkami sady SDK, vlastnostmi a odkazy na balíčky na základě direktiv původního #: souboru. Oba soubory se umístí do adresáře pojmenovaného pro aplikaci vedle původního .cs souboru, který zůstane nedotčený.

Obnovení závislostí

Obnovte balíčky NuGet odkazované v souboru pomocí dotnet restore příkazu:

dotnet restore file.cs

Ve výchozím nastavení se obnovení spouští implicitně při sestavování nebo spouštění aplikace. Můžete ale předat --no-restore jak příkazům dotnet build a dotnet run k sestavení nebo spuštění bez implicitního obnovení.

Výchozí zahrnuté položky

Aplikace založené na souborech automaticky obsahují konkrétní typy souborů pro kompilaci a balení.

Ve výchozím nastavení je zahrnut samostatný soubor C#.

Mezi různé sady SDK patří i jiné typy souborů:

Microsoft.NET.Sdk.Web obsahuje *.json konfigurační soubory.
Jiné než výchozí sady SDK obsahují soubory prostředků ResX.

Nativní publikování AOT

Aplikace založené na souborech ve výchozím nastavení umožňují nativní Ahead-of-Time (AOT) kompilaci. Tato funkce vytváří optimalizované samostatné spustitelné soubory s rychlejším spuštěním a menšími nároky na paměť.

Pokud potřebujete zakázat nativní AOT, použijte následující nastavení:

#:property PublishAot=false

Další informace o nativním nasazení AOT najdete v tématu Nativní nasazení AOT.

Tajné kódy uživatelů

Aplikace založené na souborech generují stabilní ID tajných kódů uživatelů na základě hodnoty hash celé cesty k souboru. Toto ID umožňuje ukládat citlivou konfiguraci odděleně od zdrojového kódu.

Přístup k tajným kódům uživatelů stejným způsobem jako u tradičních projektů:

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

Výpis tajných kódů uživatelů pro aplikace založené na souborech:

dotnet user-secrets list --file file.cs

Příkaz dotnet user-secrets list vytiskne hodnotu tajných kódů. Tento příkaz neukládejte do skriptů, které běží ve veřejných kontextech.

Další informace najdete v tématu Bezpečné ukládání tajných kódů aplikací při vývoji.

Spouštěcí profily

Aplikace založené na souborech podporují startovací profily pro konfiguraci chodu aplikace během vývoje. Místo umístění profilů spuštění do Properties/launchSettings.jsonaplikací založených na souborech můžou používat soubor nastavení plochého spuštění pojmenovaný [ApplicationName].run.json ve stejném adresáři jako zdrojový soubor.

Soubor nastavení plochého spuštění

Vytvořte soubor nastavení spuštění pojmenovaný po aplikaci. Pokud je app.csnapříklad vaše aplikace založená na souborech, vytvořte app.run.json ve stejném adresáři:

{
  "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"
      }
    }
  }
}

Více souborových aplikací

Pokud máte ve stejném adresáři více aplikací založených na souborech, můžou mít každá aplikace vlastní soubor nastavení spuštění:

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

Výběr profilu

.NET CLI volí profily spuštění s následující prioritou:

Profil specifikovaný volbou --launch-profile.
Profil určený proměnnou DOTNET_LAUNCH_PROFILE prostředí.
První profil definovaný v souboru nastavení spuštění.

Spuštění s konkrétním profilem:

dotnet run app.cs --launch-profile https

Tradiční nastavení spuštění

Aplikace založené na souborech podporují také tradiční Properties/launchSettings.json soubor. Pokud existují oba soubory, má tradiční umístění prioritu. Pokud existují oba soubory, rozhraní příkazového řádku .NET zaznamená upozornění, které objasní, který soubor se použije.

Spouštění prostředí

Povolte přímé spouštění programů založených na souborech v systémech typu Unix pomocí řádky začínající shebang a spustitelných oprávnění.

Na začátek souboru přidejte "shebang":

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

using Spectre.Console;

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

Nastavte soubor jako spustitelný:

chmod +x file.cs

Spustit přímo:

./file.cs

Poznámka:

Používejte ukončení řádku LF místo CRLF při přidání shebangu. Nezahrnujte do souboru BOM.

Implicitní soubory sestavení

Aplikace založené na souborech respektují konfigurační soubory MSBuild a NuGet ve stejném adresáři nebo nadřazených adresářích. Tyto soubory ovlivňují, jak sada SDK sestaví vaši aplikaci. Při uspořádání aplikací založených na souborech mějte na paměti tyto soubory.

`Directory.Build.props`

Definuje vlastnosti nástroje MSBuild, které se vztahují na všechny projekty v adresářové struktuře. Aplikace založené na souborech dědí tyto vlastnosti.

`Directory.Build.targets`

Definuje cíle MSBuild a vlastní logiku sestavení. Aplikace založené na souborech spouštějí tyto cíle během sestavování.

`Directory.Packages.props`

Umožňuje centrální správu balíčků pro závislosti NuGet. Aplikace založené na souborech můžou používat centrálně spravované verze balíčků.

`nuget.config`

Konfiguruje zdroje a nastavení balíčků NuGet. Při obnovování balíčků tyto konfigurace používají souborové aplikace.

`global.json`

Určuje verzi sady .NET SDK, která se má použít. Aplikace založené na souborech respektují výběr této verze.

Ukládání do mezipaměti sestavení

Sada .NET SDK ukládá výstupy sestavení do mezipaměti za účelem zvýšení výkonu při následných vyvoláních dotnet run. Tento systém ukládání do mezipaměti je jedinečný pro souborové aplikace.

Chování mezipaměti

Sada SDK ukládá výstupy sestavení do mezipaměti na základě:

Obsah zdrojového souboru
Konfigurace směrnic.
Verze sady SDK.
Implicitní existence a obsah souboru build.

Ukládání do mezipaměti zlepšuje výkon sestavení, ale může způsobit nejasnosti, když:

Změny implicitních souborů sestavení neaktivují opětovné sestavení.
Při přesouvání souborů do různých adresářů nedojde k zneplatnění mezipaměti.

Alternativní řešení

Pomocí následujícího příkazu vymažte artefakty mezipaměti pro souborové aplikace:

dotnet clean file-based-apps

Vynucení čistého sestavení pro obejití mezipaměti:
```
dotnet clean file.cs
dotnet build file.cs
```

Doporučení rozložení složky

Uspořádejte si aplikace založené na souborech pečlivě, abyste se vyhnuli konfliktům s tradičními projekty a implicitními soubory sestavení.

Vyhněte se kuželům souborů projektu

Neumisťujte aplikace založené na souborech do adresářové struktury .csproj projektu. Implicitní soubory a nastavení souboru projektu můžou kolidovat s vaší souborovou aplikací.

❌ Nedoporučuje se:

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

✅ Doporučené:

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

Mějte na paměti implicitní soubory

Implicitní soubory sestavení v nadřazených adresářích ovlivňují všechny aplikace založené na souborech v podadresářích. Pokud potřebujete jiné konfigurace sestavení, vytvořte izolované adresáře pro souborové aplikace.