Aplikacje oparte na plikach

Ten artykuł dotyczy: ✔️ zestawu .NET 10 SDK i nowszych wersji

Aplikacje oparte na plikach umożliwiają tworzenie, uruchamianie i publikowanie aplikacji platformy .NET z jednego pliku C# bez tworzenia tradycyjnego pliku projektu. Oferują one uproszczoną alternatywę dla tradycyjnych projektów .NET. Takie podejście upraszcza programowanie skryptów, narzędzi i małych aplikacji. Zestaw .NET SDK automatycznie generuje wymaganą konfigurację projektu na podstawie dyrektyw w pliku źródłowym.

Najważniejsze korzyści to:

Zredukowana ilość standardowego kodu dla prostych aplikacji.
Samodzielne pliki źródłowe z osadzoną konfiguracją.
Natywne publikowanie AOT jest domyślnie włączone.
Automatyczne pakowanie jako narzędzia platformy .NET.

Z tego artykułu dowiesz się, jak efektywnie tworzyć, konfigurować i pracować z aplikacjami opartymi na plikach.

Obsługiwane dyrektywy

Aplikacje oparte na plikach używają dyrektyw poprzedzonych prefiksem , #: aby skonfigurować kompilację i uruchomić aplikację. Obsługiwane dyrektywy obejmują: #:package, #:project, #:property i #:sdk. Umieść te dyrektywy w górnej części pliku C#.

`#:package`

Dodaje odwołanie do pakietu NuGet do aplikacji.

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

`#:project`

Odwołuje się do innego pliku lub katalogu projektu, który zawiera plik projektu.

#:project ../SharedLibrary/SharedLibrary.csproj

`#:property`

Ustawia wartość właściwości MSBuild.

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

`#:sdk`

Określa zestaw SDK do użycia. Wartość domyślna to Microsoft.NET.Sdk.

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

Polecenia CLI

Interfejs wiersza polecenia platformy .NET zapewnia pełną obsługę aplikacji opartych na plikach za pomocą znanych poleceń.

Uruchamianie aplikacji

Uruchom aplikację opartą na plikach dotnet run przy użyciu polecenia z opcją --file :

dotnet run --file file.cs

Możesz też użyć dotnet run polecenia , a następnie nazwy pliku:

dotnet run file.cs

Możesz też użyć składni skróconej:

dotnet file.cs

Przekazywanie argumentów

Przekaż argumenty do aplikacji, umieszczając je po: --

dotnet run file.cs -- arg1 arg2

Bez --argumentów przejdź do dotnet run polecenia :

dotnet run file.cs arg1 arg2

Kompilowanie aplikacji

Skompiluj aplikację opartą na plikach dotnet build przy użyciu polecenia :

dotnet build file.cs

Zestaw SDK generuje projekt wirtualny i kompiluje aplikację. Domyślnie dane wyjściowe kompilacji przechodzą do katalogu tymczasowego systemu w obszarze <temp>/dotnet/runfile/<appname>-<appfilesha>/bin/<configuration>/.

--output Użyj opcji z poleceniem dotnet build , aby określić inną ścieżkę. Aby zdefiniować nową domyślną ścieżkę wyjściową, ustaw OutputPath właściwość w górnej części pliku przy użyciu dyrektywy: #:property OutputPath=./output.

Czyszczenie danych wyjściowych kompilacji

Usuń artefakty kompilacji przy użyciu dotnet clean polecenia :

dotnet clean file.cs

Usuń pamięć podręczną dla aplikacji opartych na plikach w katalogu:

dotnet clean file-based-apps

--days Użyj opcji z poprzednim poleceniem, aby określić, ile dni folder artefaktu musi być nieużywany przed usunięciem. Domyślna liczba dni to 30.

Publikowanie aplikacji

Aplikacje oparte na plikach domyślnie umożliwiają natywne publikowanie AOT, tworząc zoptymalizowane, samodzielne pliki wykonywalne. Wyłącz tę funkcję, dodając #:property PublishAot=false w górnej części pliku.

Użyj polecenia , dotnet publish aby utworzyć niezależny plik wykonywalny:

dotnet publish file.cs

Domyślną lokalizacją artifacts pliku wykonywalnego jest katalog obok .cs pliku z podkatalogem o nazwie po aplikacji. --output Użyj opcji z poleceniem dotnet publish , aby określić inną ścieżkę.

Spakietuj jako narzędzie

Spakuj aplikację opartą na plikach jako narzędzie .NET przy użyciu dotnet pack polecenia :

dotnet pack file.cs

Aplikacje oparte na plikach są skonfigurowane domyślnie PackAsTool=true. Wyłącz to ustawienie, dodając #:property PackAsTool=false w górnej części pliku.

Konwertowanie na projekt

Przekonwertuj aplikację opartą na plikach na tradycyjny projekt przy użyciu dotnet project convert polecenia :

dotnet project convert file.cs

To polecenie tworzy kopię .cs pliku i tworzy .csproj plik z równoważnymi elementami zestawu SDK, właściwościami i odwołaniami do pakietu na podstawie dyrektyw oryginalnego #: pliku. Oba pliki są umieszczane w katalogu o nazwie dla aplikacji obok oryginalnego .cs pliku, który pozostaje nienaruszony.

Przywracanie zależności

Przywróć pakiety NuGet, do których odwołuje się plik, używając dotnet restore polecenia :

dotnet restore file.cs

Domyślnie przywracanie jest uruchamiane niejawnie podczas kompilowanie lub uruchamianie aplikacji. Można jednak przekazać --no-restore zarówno do poleceń dotnet build, jak i dotnet run, aby kompilować lub uruchamiać bez niejawnego przywracania.

Domyślne dołączone elementy

Aplikacje oparte na plikach automatycznie zawierają określone typy plików na potrzeby kompilacji i tworzenia pakietów.

Domyślnie są uwzględniane następujące elementy:

Sam pojedynczy plik C#.
Pliki zasobów ResX w tym samym katalogu.

Różne zestawy SDK obejmują inne typy plików:

Microsoft.NET.Sdk.Web zawiera *.json pliki konfiguracji.
Inne wyspecjalizowane zestawy SDK mogą zawierać inne wzorce.

Publikowanie natywne AOT

Aplikacje oparte na plikach domyślnie umożliwiają natywną kompilację przed czasem (AOT). Ta funkcja generuje zoptymalizowane, samodzielne pliki wykonywalne z szybszym uruchamianiem i mniejszym zużyciem pamięci.

Jeśli musisz wyłączyć natywną funkcję AOT, użyj następującego ustawienia:

#:property PublishAot=false

Aby uzyskać więcej informacji na temat natywnego rozwiązania AOT, zobacz Native AOT deployment (Wdrażanie natywnego rozwiązania AOT).

Wpisy tajne użytkownika

Aplikacje oparte na plikach generują stabilny identyfikator tajnych danych użytkownika na podstawie skrótu pełnej ścieżki pliku. Ten identyfikator umożliwia przechowywanie poufnej konfiguracji niezależnie od kodu źródłowego.

Uzyskiwanie dostępu do tajemnic użytkownika w taki sam sposób jak w tradycyjnych projektach.

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

Wyświetlanie listy wpisów tajnych użytkownika dla aplikacji opartych na plikach:

dotnet user-secrets list --file file.cs

Polecenie dotnet user-secrets list drukuje wartość twoich tajnych danych. Nie umieszczaj tego polecenia w skryptach uruchamianych w kontekstach publicznych.

Więcej informacji znajdziesz w Bezpieczne przechowywanie sekretów aplikacji podczas tworzenia.

Uruchamianie profilów

Aplikacje oparte na plikach obsługują profile uruchamiania w celu skonfigurowania sposobu działania aplikacji podczas programowania. Zamiast umieszczać profile uruchamiania w Properties/launchSettings.jsonaplikacjach opartych na plikach, można użyć pliku ustawień uruchamiania prostego o nazwie [ApplicationName].run.json w tym samym katalogu co plik źródłowy.

Plik ustawień uruchamiania prostego

Utwórz plik ustawień uruchamiania o nazwie po aplikacji. Jeśli na przykład aplikacja oparta na plikach to app.cs, utwórz app.run.json w tym samym katalogu:

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

Wiele aplikacji opartych na plikach

Jeśli masz wiele aplikacji opartych na plikach w tym samym katalogu, każda aplikacja może mieć własny plik ustawień uruchamiania:

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

Wybór profilu

Interfejs wiersza polecenia platformy .NET wybiera profile uruchamiania przy użyciu następującego priorytetu:

Profil określony przez --launch-profile opcję.
Profil określony przez zmienną środowiskową DOTNET_LAUNCH_PROFILE .
Pierwszy profil zdefiniowany w pliku ustawień uruchamiania.

Aby uruchomić z określonym profilem:

dotnet run app.cs --launch-profile https

Tradycyjne ustawienia uruchamiania

Aplikacje oparte na plikach obsługują również tradycyjny Properties/launchSettings.json plik. Jeśli oba pliki istnieją, tradycyjna lokalizacja ma priorytet. Jeśli oba pliki są obecne, interfejs wiersza polecenia platformy .NET rejestruje ostrzeżenie, aby wyjaśnić, który plik jest używany.

Wykonywanie poleceń w powłoce

Włącz bezpośrednie wykonywanie aplikacji opartych na plikach w systemach przypominających system Unix przy użyciu wiersza shebang i uprawnień do wykonywania.

Dodaj shebang w górnej części pliku:

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

using Spectre.Console;

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

Utwórz plik wykonywalny:

chmod +x file.cs

Uruchom bezpośrednio:

./file.cs

Uwaga / Notatka

Używaj zakończeń linii LF zamiast CRLF podczas dodawania znaku shebang. Nie dołączaj BOM do pliku.

Niejawne pliki kompilacji

Aplikacje oparte na plikach szanują pliki konfiguracji MSBuild i NuGet w tym samym katalogu lub katalogach nadrzędnych. Te pliki wpływają na sposób tworzenia aplikacji przez zestaw SDK. Należy pamiętać o tych plikach podczas organizowania aplikacji opartych na plikach.

`Directory.Build.props`

Definiuje właściwości programu MSBuild, które mają zastosowanie do wszystkich projektów w drzewie katalogów. Aplikacje oparte na plikach dziedziczą te właściwości.

`Directory.Build.targets`

Definiuje obiekty docelowe programu MSBuild i niestandardową logikę kompilacji. Aplikacje oparte na plikach wykonują te obiekty docelowe podczas kompilacji.

`Directory.Packages.props`

Umożliwia centralne zarządzanie pakietami dla zależności NuGet. Aplikacje oparte na plikach mogą używać centralnie zarządzanych wersji pakietów.

`nuget.config`

Konfiguruje źródła i ustawienia pakietów NuGet. Aplikacje oparte na plikach używają tych konfiguracji podczas przywracania pakietów.

`global.json`

Określa wersję zestawu .NET SDK do użycia. Aplikacje oparte na plikach szanują wybór tej wersji.

Buforowanie kompilacji

Zestaw .NET SDK buforuje dane wyjściowe kompilacji w celu zwiększenia wydajności kolejnych wywołań dotnet runprogramu . Ten system buforowania jest unikatowy dla aplikacji opartych na plikach.

Zachowanie pamięci podręcznej

Zestaw SDK buforuje dane wyjściowe kompilacji na podstawie następujących elementów:

Zawartość pliku źródłowego.
Konfiguracja dyrektywy.
Wersja zestawu SDK.
Niejawne istnienie pliku budowy i jego zawartość.

Buforowanie zwiększa wydajność kompilacji, ale może powodować zamieszanie w przypadku:

Zmiany w niejawnych plikach kompilacji nie wyzwalają ponownej kompilacji.
Przenoszenie plików do różnych katalogów nie powoduje unieważnienia pamięci podręcznej.

Rozwiązania alternatywne

Wyczyść artefakty pamięci podręcznej dla aplikacji opartych na plikach przy użyciu następującego polecenia:

dotnet clean file-based-apps

Uruchom pełną kompilację przy użyciu flagi --no-cache :
```
dotnet build file.cs --no-cache
```
Wymuś czystą kompilację w celu obejścia pamięci podręcznej:
```
dotnet clean file.cs
dotnet build file.cs
```

Zalecenia dotyczące układu folderu

Starannie organizuj aplikacje oparte na plikach, aby uniknąć konfliktów z tradycyjnymi projektami i niejawnymi plikami kompilacji.

Unikaj stożków pliku projektu

Nie umieszczaj aplikacji opartych na plikach w strukturze katalogów .csproj projektu. Niejawne pliki kompilacji i ustawienia pliku projektu mogą zakłócać działanie aplikacji opartej na plikach.

❌ Niezalecane:

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

✅ Zalecane:

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

Należy pamiętać o niejawnych plikach

Niejawne pliki kompilacji w katalogach nadrzędnych mają wpływ na wszystkie aplikacje oparte na plikach w podkatalogach. Utwórz izolowane katalogi dla aplikacji opartych na plikach, gdy potrzebujesz różnych konfiguracji kompilacji.