Dosya tabanlı uygulamalar

Bu makale şunlar için geçerlidir: .NET 10 SDK ve sonraki sürümleri ✔️

Dosya tabanlı uygulamalar, geleneksel bir proje dosyası oluşturmadan tek bir C# dosyasından .NET uygulamaları oluşturmanıza, çalıştırmanıza ve yayımlamanıza olanak tanır. Geleneksel .NET projelerine basit bir alternatif sunar. Bu yaklaşım betikler, yardımcı programlar ve küçük uygulamalar için geliştirmeyi kolaylaştırır. .NET SDK'sı, kaynak dosyanızdaki yönergeleri temel alarak gerekli proje yapılandırmasını otomatik olarak oluşturur.

Başlıca avantajlar şunlardır:

Basit uygulamalar için azaltılmış önceden hazırlanmış kod.
Ekli yapılandırmaya sahip bağımsız kaynak dosyaları.
Yerel AOT yayımlama varsayılan olarak etkindir.
.NET araçları şeklinde otomatik paketleme.

Bu makalede, dosya tabanlı uygulamaları etkili bir şekilde oluşturmayı, yapılandırmayı ve bunlarla çalışmayı öğrenin.

Desteklenen yönergeler

Dosya tabanlı uygulamalar, derlemeyi yapılandırmak ve uygulamayı çalıştırmak için ön ekli #: yönergeleri kullanır. Desteklenen yönergeler şunlardır: #:package, #:project, #:propertyve #:sdk. Bu yönergeleri C# dosyasının en üstüne yerleştirin.

`#:package`

Uygulamanıza bir NuGet paket başvurusu ekler.

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

Uyarı

Paket adından sonraki sürüm numarasının atlanması şu anda yalnızca bir Directory.Packages.props dosyayla merkezi paket yönetimi kullandığınızda çalışır. Aksi takdirde, sürüm numarasını açıkça belirtin veya en son sürümü kullanmak için paket adının arkasına ekleyin @* .

`#:project`

Proje dosyası içeren başka bir proje dosyasına veya dizine başvurur.

#:project ../SharedLibrary/SharedLibrary.csproj

`#:property`

MSBuild özellik değerini ayarlar.

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

`#:sdk`

Kullanılacak SDK'yi belirtir. Varsayılan olarak Microsoft.NET.Sdk değerini alır.

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

CLI komutları

.NET CLI, tanıdık komutlar aracılığıyla dosya tabanlı uygulamalar için tam destek sağlar.

Uygulamaları çalıştırma

dotnet run komutunu --file seçeneğiyle kullanarak dosya tabanlı bir uygulama çalıştırın.

dotnet run --file file.cs

Veya dotnet run komutunu ve ardından dosyanın adını kullanın.

dotnet run file.cs

Veya kısaltma sözdizimini kullanın:

dotnet file.cs

Argümanları geçirme

Uygulamanıza bağımsız değişkenleri, --'den sonra yerleştirerek geçirin.

dotnet run file.cs -- arg1 arg2

Stdin'den boru kodu

Bağımsız değişkenle standart girişi kullanarak C# kodunu doğrudan dotnet run adresine yöneltin - . - bağımsız değişkeni, kodu dosya yerine standart girişten okuduğunu gösterirdotnet run. Belirli bir - bağımsız değişkeni ile, dotnet run geçerli çalışma dizininde başlatma profilleri gibi diğer dosyaları aramaz. Geçerli dizin hala programı derlemek ve çalıştırmak için çalışan dizindir.

PowerShell:

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

Bash:

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

Bu yaklaşım hızlı test etmek, tek seferlik komutları çalıştırmak veya C# kodunu dinamik olarak oluşturan kabuk betikleriyle tümleştirmek için kullanışlıdır.

Uygulama oluşturma

Komutunu kullanarak dosya tabanlı uygulamanızı derleyin dotnet build :

dotnet build file.cs

SDK bir sanal proje oluşturur ve uygulamanızı oluşturur. Varsayılan olarak, derleme çıkışı <temp>/dotnet/runfile/<appname>-<appfilesha>/bin/<configuration>/ sistemin geçici dizinine gider.

--output seçeneğini farklı bir yol belirtmek için dotnet build komutuyla kullanın. Yeni bir varsayılan çıkış yolu tanımlamak için şu yönergeyi OutputPath kullanarak dosyanızın en üstünde özelliğini ayarlayın: #:property OutputPath=./output.

Derleme çıkışlarını temizleme

dotnet clean komutunu kullanarak derleme nesnelerini kaldırın.

dotnet clean file.cs

Dizindeki dosya tabanlı uygulamalar için önbelleği silme:

dotnet clean file-based-apps

--days Kaldırmadan önce bir yapıt klasörünün kaç gün kullanılmaması gerektiğini belirtmek için yukarıdaki komutla seçeneğini kullanın. Varsayılan gün sayısı 30'dur.

Uygulamaları yayımlama

Dosya tabanlı uygulamalar, yerel AOT yayımlamayı varsayılan olarak etkinleştirir ve iyileştirilmiş, bağımsız yürütülebilir dosyalar oluşturur. Dosyanızın en üstüne ekleyerek #:property PublishAot=false bu özelliği devre dışı bırakın.

dotnet publish Bağımsız bir yürütülebilir dosya oluşturmak için komutunu kullanın:

dotnet publish file.cs

Yürütülebilir dosyanın varsayılan konumu, dosyanın yanında artifacts bulunan ve .cs uygulamanın adını taşıyan bir alt dizini olan bir dizindir. --output seçeneğini farklı bir yol belirtmek için dotnet publish komutuyla kullanın.

Paketle ve araç olarak kullan

Komutunu kullanarak dosya tabanlı uygulamanızı .NET aracı olarak paketleyin dotnet pack :

dotnet pack file.cs

Dosya tabanlı uygulamalar varsayılan olarak ayarlanır PackAsTool=true . Dosyanızın en üstüne #:property PackAsTool=false ekleyerek bu ayarı devre dışı bırakın.

Projeye dönüştür

komutunu kullanarak dosya tabanlı uygulamanızı geleneksel bir projeye dönüştürün dotnet project convert :

dotnet project convert file.cs

Bu komut dosyanın bir kopyasını .cs oluşturur ve özgün dosyanın yönergelerine göre eşdeğer SDK öğeleri, özellikleri ve paket başvuruları içeren bir .csproj dosya #: oluşturur. Her iki dosya da özgün .cs dosyanın yanındaki uygulama için adlı bir dizine yerleştirilir ve bu dizine dokunulmaz.

Bağımlılıkları geri yükleme

komutunu kullanarak dotnet restore dosyanızda başvuruda bulunılan NuGet paketlerini geri yükleyin:

dotnet restore file.cs

Varsayılan olarak, uygulamanızı derlediğinizde veya çalıştırdığınızda geri yükleme örtük olarak çalışır. Ancak, --no-restore komutunu hem dotnet build hem de dotnet run komutlarına geçirerek örtük olarak geri yüklemeden derleyebilir veya çalıştırabilirsiniz.

Varsayılan eklenen öğeler

Dosya tabanlı uygulamalar otomatik olarak derleme ve paketleme için belirli dosya türlerini içerir.

Varsayılan olarak, tek bir C# dosyası eklenir.

Farklı SDK'lar diğer dosya türlerini içerir:

Microsoft.NET.Sdk.Web yapılandırma dosyalarını içerir *.json .
Varsayılan olmayan SDK'lar ResX kaynak dosyalarını içerir.

Yerel AOT yayımlama

Dosya tabanlı uygulamalar varsayılan olarak yerel önceden derleme (AOT) işlemini etkinleştirir. Bu özellik, daha hızlı başlatma ve daha küçük bir bellek ayak izi ile iyileştirilmiş, bağımsız yürütülebilir dosyalar oluşturur.

Yerel AOT'yi devre dışı bırakmanız gerekiyorsa aşağıdaki ayarı kullanın:

#:property PublishAot=false

Yerel AOT hakkında daha fazla bilgi için bkz. Yerel AOT dağıtımı.

Kullanıcı sırları

Dosya tabanlı uygulamalar, tam dosya yolunun karması temelinde sabit bir kullanıcı sırları kimliği oluşturur. Bu kimlik, hassas yapılandırmayı kaynak kodunuzdan ayrı olarak depolamanıza olanak tanır.

Kullanıcı gizli dizilerine geleneksel projelerde olduğu gibi erişin:

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

Dosya tabanlı uygulamalar için kullanıcı gizli bilgilerini listele.

dotnet user-secrets list --file file.cs

dotnet user-secrets list komutu, gizli bilgilerinizin değerini yazdırır. Bu komutu genel bağlamlarda çalışan betiklere koymayın.

Daha fazla bilgi için bkz. Geliştirme aşamasındaki uygulama gizli dizilerinin güvenli bir şekilde depolanması.

Profilleri başlatma

Dosya tabanlı uygulamalar, geliştirme sırasında uygulamanın nasıl çalıştırıldığını yapılandırmak için başlatma profillerini destekler. Dosya tabanlı uygulamalar, başlatma profillerini içine Properties/launchSettings.jsonyerleştirmek yerine, kaynak dosyayla aynı dizinde adlı [ApplicationName].run.json düz başlatma ayarları dosyasını kullanabilir.

Düz başlatma ayarları dosyası

Uygulamanızın adını taşıyan bir başlatma ayarları dosyası oluşturun. Örneğin, dosya tabanlı uygulamanız ise app.csaynı dizinde oluşturun app.run.json :

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

Birden çok dosya tabanlı uygulama

Aynı dizinde birden çok dosya tabanlı uygulamanız olduğunda, her uygulamanın kendi başlatma ayarları dosyası olabilir:

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

Profil seçimi

.NET CLI, aşağıdaki önceliği kullanarak başlatma profillerini seçer:

--launch-profile seçeneği ile belirtilen profil.
Ortam değişkeni tarafından DOTNET_LAUNCH_PROFILE belirtilen profil.
Başlatma ayarları dosyasında tanımlanan ilk profil.

Belirli bir profille çalıştırmak için:

dotnet run app.cs --launch-profile https

Geleneksel başlatma ayarları

Dosya tabanlı uygulamalar geleneksel Properties/launchSettings.json dosyayı da destekler. Her iki dosya da varsa, geleneksel konum önceliklidir. Her iki dosya da varsa, .NET CLI hangi dosyanın kullanıldığını netleştirmek için bir uyarı günlüğe kaydeder.

Kabuk yürütme

Shebang satırı ve yürütülebilir izinler kullanarak Unix benzeri sistemlerde dosya tabanlı uygulamaların doğrudan çalıştırılmasını sağlayın.

Dosyanızın en üstüne shebang ekleyin:

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

using Spectre.Console;

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

Dosyayı yürütülebilir hale getirin:

chmod +x file.cs

Doğrudan çalıştır:

./file.cs

Uyarı

Shebang eklerken LF yerine CRLF satır sonlarını kullanın. Dosyaya bir BOM (Bait Sırası İmi) eklemeyin.

Gizli derleme dosyaları

Dosya tabanlı uygulamalar, aynı dizin veya üst dizinlerdeki MSBuild ve NuGet yapılandırma dosyalarına saygı gösterir. Bu dosyalar SDK'nın uygulamanızı nasıl derleyeceğini etkiler. Dosya tabanlı uygulamalarınızı düzenlerken bu dosyalara dikkat edin.

`Directory.Build.props`

Bir dizin ağacındaki tüm projelere uygulanan MSBuild özelliklerini tanımlar. Dosya tabanlı uygulamalar bu özellikleri devralır.

`Directory.Build.targets`

MSBuild hedeflerini ve özel derleme mantığını tanımlar. Dosya tabanlı uygulamalar derleme sırasında bu hedefleri yürütür.

`Directory.Packages.props`

NuGet bağımlılıkları için merkezi paket yönetimini etkinleştirir. Dosya tabanlı uygulamalar merkezi olarak yönetilen paket sürümlerini kullanabilir.

`nuget.config`

NuGet paket kaynaklarını ve ayarlarını yapılandırır. Dosya tabanlı uygulamalar paketleri geri yüklerken bu yapılandırmaları kullanır.

`global.json`

Kullanılacak .NET SDK sürümünü belirtir. Dosya tabanlı uygulamalar bu sürüm seçimine uyar.

Derleme önbelleği

.NET SDK'sı, sonraki çağrılarında performansı artırmak için derleme çıkışlarını önbelleğe alır dotnet run. Bu önbelleğe alma sistemi, dosya tabanlı uygulamalar için benzersizdir.

Önbellek davranışı

SDK, derleme çıkışlarını aşağıdakilere göre önbelleğe alır:

Kaynak dosya içeriği.
Yönerge yapılandırması.
SDK sürümü.
Örtük derleme dosyası varlığı ve içeriği.

Önbelleğe alma, derleme performansını artırır ancak şu durumlarda karışıklığa neden olabilir:

Örtük derleme dosyalarındaki değişiklikler yeniden derlemeleri tetiklemez.
Dosyaları farklı dizinlere taşımak önbelleği geçersiz kılmaz.

Geçici Çözümler

Aşağıdaki komutu kullanarak dosya tabanlı uygulamalar için önbellek yapıtlarını temizleyin:

dotnet clean file-based-apps

Önbelleği atlamak için temiz bir derlemeyi zorla yapın.
```
dotnet clean file.cs
dotnet build file.cs
```

Klasör düzeni önerileri

Geleneksel projelerle ve örtük derleme dosyalarıyla çakışmaları önlemek için dosya tabanlı uygulamalarınızı dikkatli bir şekilde düzenleyin.

Proje dosyası külahlarından kaçının

Dosya tabanlı uygulamaları projenin .csproj dizin yapısına yerleştirmeyin. Proje dosyasının örtük derleme dosyaları ve ayarları dosya tabanlı uygulamanızı etkileyebilir.

❌ Önerilmez:

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

✅ Önerilen:

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

Örtük dosyalara dikkat edin

Üst dizinlerdeki örtük derleme dosyaları, alt dizinlerdeki tüm dosya tabanlı uygulamaları etkiler. Farklı derleme yapılandırmalarına ihtiyacınız olduğunda dosya tabanlı uygulamalar için yalıtılmış dizinler oluşturun.