Aplikasi berbasis file

Artikel ini berlaku untuk: ✔️ .NET 10 SDK dan versi yang lebih baru

Aplikasi berbasis file memungkinkan Anda membangun, menjalankan, dan menerbitkan aplikasi .NET dari satu file C# tanpa membuat file proyek tradisional. Mereka menawarkan alternatif ringan untuk proyek .NET tradisional. Pendekatan ini menyederhanakan pengembangan untuk skrip, utilitas, dan aplikasi kecil. .NET SDK secara otomatis menghasilkan konfigurasi proyek yang diperlukan berdasarkan arahan dalam file sumber Anda.

Keuntungan utamanya meliputi:

Mengurangi boilerplate untuk aplikasi sederhana.
File sumber berbasis mandiri dengan konfigurasi yang disematkan.
Penerbitan Native AOT diaktifkan secara default.
Pengemasan otomatis sebagai alat bantu .NET.

Dalam artikel ini, pelajari cara membuat, mengonfigurasi, dan bekerja dengan aplikasi berbasis file secara efektif.

Direktif yang didukung

Aplikasi berbasis file menggunakan direktif yang diawali dengan #: untuk mengonfigurasi build dan menjalankan aplikasi. Arahan yang didukung meliputi: #:package, , #:project#:property, dan #:sdk. Tempatkan arahan ini di bagian atas file C#.

`#:package`

Menambahkan referensi paket NuGet ke aplikasi Anda.

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

Nota

Menghilangkan nomor versi setelah nama paket saat ini hanya berfungsi saat Anda menggunakan manajemen paket pusat dengan Directory.Packages.props file. Jika tidak, tentukan nomor versi secara eksplisit, atau tambahkan @* setelah nama paket untuk menggunakan versi terbaru.

`#:project`

Mereferensikan file atau direktori proyek lain yang berisi file proyek.

#:project ../SharedLibrary/SharedLibrary.csproj

`#:property`

Mengatur nilai properti MSBuild.

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

`#:sdk`

Menentukan SDK yang akan digunakan. Secara default menjadi Microsoft.NET.Sdk.

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

Perintah CLI

.NET CLI menyediakan dukungan penuh untuk aplikasi berbasis file melalui perintah yang sudah dikenal.

Menjalankan aplikasi

Jalankan aplikasi berbasis file dengan menggunakan dotnet run perintah dengan --file opsi :

dotnet run --file file.cs

Atau gunakan dotnet run perintah diikuti dengan nama file:

dotnet run file.cs

Atau gunakan sintaks singkat:

dotnet file.cs

Menyalurkan argumen

Teruskan argumen ke aplikasi Anda dengan menempatkannya setelah --:

dotnet run file.cs -- arg1 arg2

Kode pipa dari stdin

Salurkan kode C# langsung ke dotnet run dengan menggunakan input standar dan argumen -. Argumen - menunjukkan bahwa dotnet run membaca kode dari input standar alih-alih file. Tanpa argumen -, dotnet run tidak mencari direktori kerja saat ini untuk file lain, seperti profil startup. Direktori saat ini masih menjadi direktori kerja untuk membangun dan menjalankan program.

PowerShell:

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

Bash:

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

Pendekatan ini berguna untuk pengujian cepat, menjalankan perintah satu kali, atau mengintegrasikan dengan skrip shell yang menghasilkan kode C# secara dinamis.

Membuat aplikasi

Kompilasi aplikasi berbasis file Anda dengan menggunakan dotnet build perintah :

dotnet build file.cs

SDK menghasilkan proyek virtual dan membangun aplikasi Anda. Secara default, output build masuk ke direktori sementara sistem di bawah <temp>/dotnet/runfile/<appname>-<appfilesha>/bin/<configuration>/.

Gunakan opsi --output dengan perintah dotnet build untuk menentukan jalur yang berbeda. Untuk menentukan jalur output default baru, atur OutputPath properti di bagian atas file Anda dengan menggunakan direktif: #:property OutputPath=./output.

Bersihkan hasil kompilasi

Hapus artefak build dengan menggunakan perintah dotnet clean:

dotnet clean file.cs

Hapus cache untuk aplikasi berbasis file di direktori:

dotnet clean file-based-apps

--days Gunakan opsi dengan perintah sebelumnya untuk menentukan berapa hari folder artefak perlu tidak digunakan sebelum penghapusan. Jumlah hari default adalah 30.

Menerbitkan aplikasi

Aplikasi berbasis file memungkinkan publikasi AOT native secara default, menghasilkan file executable mandiri yang dioptimalkan. Nonaktifkan fitur ini dengan menambahkan #:property PublishAot=false di bagian atas file Anda.

Gunakan perintah dotnet publish untuk membuat executable independen.

dotnet publish file.cs

Lokasi default file yang bisa dieksekusi adalah di direktori artifacts di samping file .cs, dengan subdirektori yang diberi nama menurut aplikasi. Gunakan opsi --output dengan perintah dotnet publish untuk menentukan jalur yang berbeda.

Paket sebagai alat

Kemas aplikasi berbasis file Anda sebagai alat .NET dengan menggunakan dotnet pack perintah :

dotnet pack file.cs

Aplikasi berbasis file diatur PackAsTool=true sebagai pengaturan awal. Nonaktifkan pengaturan ini dengan menambahkan #:property PackAsTool=false di bagian atas file Anda.

Konversi ke proyek

Konversikan aplikasi berbasis file Anda ke proyek tradisional dengan menggunakan dotnet project convert perintah :

dotnet project convert file.cs

Perintah ini membuat salinan .cs file dan membuat .csproj file dengan item SDK, properti, dan referensi paket yang setara berdasarkan arahan file #: asli. Kedua file ditempatkan dalam direktori bernama untuk aplikasi di samping file asli .cs , yang dibiarkan tidak tersentuh.

Memulihkan dependensi

Pulihkan paket NuGet yang dirujuk dalam file Anda dengan menggunakan dotnet restore perintah :

dotnet restore file.cs

Secara default, pemulihan berjalan secara implisit saat Anda membuat atau menjalankan aplikasi Anda. Namun, Anda dapat meneruskan --no-restore ke perintah dotnet build dan dotnet run untuk membangun atau menjalankan tanpa memulihkan secara implisit.

Item yang disertakan secara bawaan

Aplikasi berbasis file secara otomatis menyertakan jenis file tertentu untuk kompilasi dan pengemasan.

Secara default, file C# tunggal disertakan.

SDK yang berbeda mencakup jenis file lainnya:

Microsoft.NET.Sdk.Web termasuk *.json file konfigurasi.
SDK yang tidak default menyertakan file sumber daya ResX.

Penerbitan AOT asli

Aplikasi berbasis file mengaktifkan kompilasi native ahead-of-time (AOT) secara default. Fitur ini menghasilkan executable mandiri yang dioptimalkan dengan startup yang lebih cepat dan jejak memori yang lebih kecil.

Jika Anda perlu menonaktifkan AOT asli, gunakan pengaturan berikut:

#:property PublishAot=false

Untuk informasi selengkapnya tentang AOT asli, lihat Penyebaran AOT asli.

Rahasia pengguna

Aplikasi berbasis file menghasilkan ID rahasia pengguna yang stabil berdasarkan hash jalur file lengkap. ID ini memungkinkan Anda menyimpan konfigurasi sensitif secara terpisah dari kode sumber Anda.

Akses rahasia pengguna dengan cara yang sama seperti proyek tradisional:

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

Mencantumkan rahasia pengguna untuk aplikasi berbasis file:

dotnet user-secrets list --file file.cs

Perintah dotnet user-secrets list mencetak nilai rahasia Anda. Jangan letakkan perintah ini dalam skrip yang berjalan dalam konteks publik.

Untuk informasi selengkapnya, lihat Penyimpanan rahasia aplikasi yang aman dalam pengembangan.

Mulai profil

Aplikasi berbasis file mendukung profil peluncuran untuk mengonfigurasi cara aplikasi berjalan selama pengembangan. Alih-alih menempatkan profil peluncuran di Properties/launchSettings.json, aplikasi berbasis file dapat menggunakan file pengaturan peluncuran datar bernama [ApplicationName].run.json di direktori yang sama dengan file sumber.

Berkas pengaturan peluncuran standar

Buat file pengaturan peluncuran bernama sesuai aplikasi Anda. Misalnya, jika aplikasi berbasis file Anda adalah app.cs, buat app.run.json di direktori yang sama:

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

Beberapa aplikasi berbasis file

Saat Anda memiliki beberapa aplikasi berbasis file di direktori yang sama, setiap aplikasi dapat memiliki file pengaturan peluncurannya sendiri:

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

Pilihan profil

.NET CLI memilih profil peluncuran menggunakan prioritas berikut:

Profil yang ditentukan oleh --launch-profile opsi .
Profil yang ditentukan oleh DOTNET_LAUNCH_PROFILE variabel lingkungan.
Profil pertama yang ditentukan dalam file pengaturan peluncuran.

Untuk menjalankan dengan profil tertentu:

dotnet run app.cs --launch-profile https

Pengaturan peluncuran tradisional

Aplikasi berbasis file juga mendukung file tradisional Properties/launchSettings.json . Jika kedua file ada, lokasi tradisional lebih diprioritaskan. Jika kedua file ada, .NET CLI mencatat peringatan untuk mengklarifikasi file mana yang digunakan.

Eksekusi shell

Aktifkan eksekusi langsung aplikasi berbasis file pada sistem seperti Unix dengan menggunakan baris shebang dan izin yang dapat dieksekusi.

Tambahkan shebang di bagian paling atas dari file Anda:

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

using Spectre.Console;

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

Buat file dapat dieksekusi:

chmod +x file.cs

Jalankan secara langsung:

./file.cs

Nota

Gunakan LF akhiran baris alih-alih CRLF saat Anda menambahkan shebang. Jangan sertakan BOM dalam file.

File build implisit

Aplikasi berbasis file menghormati file konfigurasi MSBuild dan NuGet di direktori atau direktori induk yang sama. File-file ini memengaruhi cara SDK membangun aplikasi Anda. Perhatikan file-file ini saat mengatur aplikasi berbasis file Anda.

`Directory.Build.props`

Menentukan properti MSBuild yang berlaku untuk semua proyek di pohon direktori. Aplikasi berbasis file mewarisi properti ini.

`Directory.Build.targets`

Menentukan target MSBuild dan logika build kustom. Aplikasi berbasis file menjalankan target ini selama build.

`Directory.Packages.props`

Mengaktifkan manajemen paket pusat untuk dependensi NuGet. Aplikasi berbasis file dapat menggunakan versi paket yang dikelola secara terpusat.

`nuget.config`

Mengonfigurasi sumber dan pengaturan paket NuGet. Aplikasi berbasis file menggunakan konfigurasi ini saat memulihkan paket.

`global.json`

Menentukan versi .NET SDK yang akan digunakan. Aplikasi berbasis file menghormati pilihan versi ini.

Pembuatan cache

.NET SDK menyimpan cache hasil build untuk meningkatkan performa pada pemanggilan berikutnya dari dotnet run. Sistem cache ini unik untuk aplikasi berbasis file.

Perilaku cache

Cache SDK membuat output berdasarkan:

Konten file sumber.
Konfigurasi arahan.
Versi SDK
Keberadaan dan konten file build implisit.

Caching dapat meningkatkan performa build, tetapi juga bisa menyebabkan kebingungan ketika:

Perubahan pada file build implisit tidak memicu pembangunan ulang.
Memindahkan file ke direktori yang berbeda tidak membatalkan cache.

Penyelesaian masalah

Hapus artefak cache untuk aplikasi berbasis file dengan menggunakan perintah berikut:

dotnet clean file-based-apps

Lakukan build bersih untuk menghindari cache:
```
dotnet clean file.cs
dotnet build file.cs
```

Rekomendasi tata letak folder

Atur aplikasi berbasis file Anda dengan hati-hati untuk menghindari konflik dengan proyek tradisional dan file build implisit.

Hindari kerujut file proyek

Jangan menempatkan aplikasi berbasis file dalam struktur .csproj direktori proyek. File build implisit dan pengaturan dari file proyek dapat mengganggu aplikasi berbasis file Anda.

❌ Tidak disarankan:

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

✅ Direkomendasikan:

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

Perhatikan file implisit

File build implisit di direktori induk memengaruhi semua aplikasi berbasis file di subdirektori. Buat direktori terisolasi untuk aplikasi berbasis file saat Anda memerlukan konfigurasi build yang berbeda.