Op bestanden gebaseerde apps

Dit artikel is van toepassing op: ✔️ .NET 10 SDK en latere versies

Met op bestanden gebaseerde apps kunt u .NET-toepassingen bouwen, uitvoeren en publiceren vanuit één C#-bestand zonder een traditioneel projectbestand te maken. Ze bieden een lichtgewicht alternatief voor traditionele .NET-projecten. Deze aanpak vereenvoudigt de ontwikkeling voor scripts, hulpprogramma's en kleine toepassingen. De .NET SDK genereert automatisch de benodigde projectconfiguratie op basis van de instructies in uw bronbestand.

Belangrijke voordelen zijn onder andere:

Verminderde boilerplatecode voor eenvoudige toepassingen.
Zelfstandige bronbestanden met ingesloten configuratie.
Systeemeigen AOT-publicatie is standaard ingeschakeld.
Automatische verpakking als .NET-tools.

In dit artikel leert u hoe u effectief apps op basis van bestanden kunt maken, configureren en ermee kunt werken.

Ondersteunde directieven

Op bestanden gebaseerde apps maken gebruik van instructies die voorafgegaan worden door #: om de build te configureren en de toepassing uit te voeren. Ondersteunde richtlijnen zijn onder andere: #:package, #:project, #:propertyen #:sdk. Plaats deze instructies boven aan het C#-bestand.

`#:package`

Voegt een NuGet-pakketreferentie toe aan uw toepassing.

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

Opmerking

Het weglaten van het versienummer na de pakketnaam werkt momenteel alleen wanneer u centraal pakketbeheer met een Directory.Packages.props bestand gebruikt. Geef anders expliciet het versienummer op of voeg @* het toe na de pakketnaam om de nieuwste versie te gebruiken.

`#:project`

Verwijst naar een ander projectbestand of een andere map die een projectbestand bevat.

#:project ../SharedLibrary/SharedLibrary.csproj

`#:property`

Hiermee stelt u een MSBuild-eigenschapswaarde in.

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

`#:sdk`

Hiermee specificeert u de te gebruiken SDK. Standaardwaarde is Microsoft.NET.Sdk.

#:sdk Microsoft.NET.Sdk.Web

CLI-opdrachten

De .NET CLI biedt volledige ondersteuning voor op bestanden gebaseerde apps via vertrouwde opdrachten.

Toepassingen uitvoeren

Voer een app op basis van bestanden rechtstreeks uit met behulp van de dotnet run opdracht:

dotnet run file.cs

Of gebruik de verkorte syntaxis:

dotnet file.cs

Argumenten doorgeven

Geef argumenten op verschillende manieren door aan uw toepassing:

dotnet run file.cs -- arg1 arg2

Pijpcode van stdin

Pijp C#-code rechtstreeks naar dotnet run met behulp van standaard invoer met het - argument. Het - argument geeft aan dat dotnet run de code uit standaardinvoer wordt gelezen in plaats van een bestand. Met het - argument dotnet run zoekt u niet in de huidige werkmap naar andere bestanden, zoals startprofielen. De huidige map is nog steeds de werkmap om het programma te bouwen en uit te voeren.

PowerShell:

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

Bash:

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

Deze methode is handig voor snelle tests, het uitvoeren van eenmalige opdrachten of het integreren met shellscripts waarmee C#-code dynamisch wordt gegenereerd.

Bouw applicaties

Compileer uw app op basis van bestanden met behulp van de dotnet build opdracht:

dotnet build file.cs

De SDK genereert een tijdelijk project en bouwt uw toepassing.

Build-uitvoer opschonen

Verwijder buildartefacten met behulp van de dotnet clean opdracht:

dotnet clean file.cs

Alle op bestanden gebaseerde apps in een map opschonen:

dotnet clean file-based-apps

Toepassingen publiceren

Maak een implementatiepakket met behulp van de dotnet publish opdracht:

dotnet publish file.cs

Op bestanden gebaseerde apps maken standaard systeemeigen AOT-publicatie mogelijk, waardoor geoptimaliseerde, zelfstandige uitvoerbare bestanden worden geproduceerd.

Pakket als gereedschap

Uw app op basis van bestanden verpakken als een .NET-hulpprogramma met behulp van de dotnet pack opdracht:

dotnet pack file.cs

Op bestanden gebaseerde apps zijn standaard ingesteld PackAsTool=true .

Converteer naar project

Converteer uw app op basis van bestanden naar een traditioneel project met behulp van de dotnet project convert opdracht:

dotnet project convert file.cs

Met deze opdracht maakt u een .csproj bestand met equivalente SDK en eigenschappen. Alle # instructies worden uit het .cs bestand verwijderd en omgezet in elementen in het bijbehorende .csproj bestand.

Afhankelijkheden herstellen

Herstel NuGet-pakketten waarnaar in uw bestand wordt verwezen met behulp van de dotnet restore opdracht:

dotnet restore file.cs

Herstel wordt impliciet uitgevoerd wanneer u uw toepassing bouwt of uitvoert.

Standaard opgenomen items

Op bestanden gebaseerde apps bevatten automatisch specifieke bestandstypen voor compilatie en verpakking.

Standaard is het enkele C#-bestand opgenomen.

Verschillende SDK's bevatten andere bestandstypen:

Microsoft.NET.Sdk.Web bevat *.json configuratiebestanden.
Niet-standaard-SDK's bevatten ResX-resourcebestanden.

Systeemeigen AOT-publicatie

Op bestanden gebaseerde apps maken standaard systeemeigen AOT-compilatie (ahead-of-time) mogelijk. Deze functie produceert geoptimaliseerde, zelfstandige uitvoerbare bestanden met een snellere opstartbewerking en een kleinere geheugenvoetafdruk.

Als u systeemeigen AOT wilt uitschakelen, gebruikt u de volgende instelling:

#:property PublishAot=false

Zie Systeemeigen AOT-implementatie voor meer informatie over systeemeigen AOT.

Gebruikersgeheimen

Op bestanden gebaseerde apps genereren een stabiele gebruikersgeheim-id op basis van een hash van het volledige bestandspad. Met deze id kunt u gevoelige configuratie afzonderlijk van uw broncode opslaan.

Toegang tot gebruikersgeheimen op dezelfde manier als traditionele projecten:

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

Zie Veilige opslag van app-geheimen in ontwikkeling voor meer informatie.

Profielen lanceren

Op bestanden gebaseerde apps ondersteunen startprofielen voor het configureren van de werking van de toepassing tijdens de ontwikkeling. In plaats van startprofielen in Properties/launchSettings.jsonte plaatsen, kunnen op bestanden gebaseerde apps een plat startinstellingenbestand gebruiken met de naam [ApplicationName].run.json in dezelfde map als het bronbestand.

Flat launch instellingenbestand

Maak een opstartinstellingenbestand met de naam van uw toepassing. Als uw app op basis van bestanden bijvoorbeeld is app.cs, maakt u deze app.run.json in dezelfde map:

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

Meerdere op bestanden gebaseerde apps

Wanneer u meerdere op bestanden gebaseerde apps in dezelfde map hebt, kan elke app een eigen startinstellingenbestand hebben:

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

Profielselectie

De .NET CLI selecteert startprofielen met de volgende prioriteit:

Het profiel dat is opgegeven door de --launch-profile optie.
Het profiel dat is opgegeven door de DOTNET_LAUNCH_PROFILE omgevingsvariabele.
Het eerste profiel dat is gedefinieerd in het startinstellingenbestand.

Uitvoeren met een specifiek profiel:

dotnet run app.cs --launch-profile https

Traditionele startinstellingen

Op bestanden gebaseerde apps ondersteunen ook het traditionele Properties/launchSettings.json bestand. Als beide bestanden bestaan, heeft de traditionele locatie prioriteit. Als beide bestanden aanwezig zijn, registreert de .NET CLI een waarschuwing om te verduidelijken welk bestand wordt gebruikt.

Shell-uitvoering

Schakel de directe uitvoering van op bestanden gebaseerde apps op Unix-achtige systemen in met behulp van een shebangregel en uitvoerbare machtigingen.

Voeg een shebang toe bovenaan uw bestand:

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

using Spectre.Console;

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

Maak het bestand uitvoerbaar:

chmod +x file.cs

Rechtstreeks uitvoeren:

./file.cs

Impliciete buildbestanden

Bestand-gebaseerde apps houden rekening met MSBuild- en NuGet-configuratiebestanden in dezelfde map of bovenliggende mappen. Deze bestanden zijn van invloed op de wijze waarop de SDK uw toepassing bouwt. Houd rekening met deze bestanden bij het ordenen van uw apps op basis van bestanden.

`Directory.Build.props`

Hiermee worden MSBuild-eigenschappen gedefinieerd die van toepassing zijn op alle projecten in een mapstructuur. Op bestanden gebaseerde apps nemen deze eigenschappen over.

`Directory.Build.targets`

Definieert MSBuild-doelen en aangepaste buildlogica. Op bestanden gebaseerde apps voeren deze doelen uit tijdens de build.

`Directory.Packages.props`

Hiermee schakelt u centraal pakketbeheer in voor NuGet-afhankelijkheden. Op bestanden gebaseerde apps kunnen centraal beheerde pakketversies gebruiken.

`nuget.config`

Hiermee configureert u NuGet-pakketbronnen en -instellingen. Op bestanden gebaseerde apps gebruiken deze configuraties bij het herstellen van pakketten.

`global.json`

Hiermee specificeert u de te gebruiken .NET SDK-versie. Op bestanden gebaseerde apps respecteren deze versieselectie.

Cache bouwen

De .NET SDK slaat build-uitvoer op in de cache om de prestaties van volgende builds te verbeteren. Op bestanden gebaseerde apps nemen deel aan dit cachesysteem.

Cachegedrag

De SDK slaat buildresultaten op op basis van:

Inhoud van bronbestand.
Configuratie van richtlijn.
SDK-versie.
Impliciete buildbestanden.

Caching verbetert de prestaties van de build, maar kan verwarring veroorzaken wanneer:

Wijzigingen in impliciete buildbestanden activeren geen herbouwbewerkingen.
Als u bestanden naar verschillende mappen verplaatst, wordt de cache niet ongeldig.

Tijdelijke oplossingen

Wis cache-artifacten voor bestandsgebaseerde apps met behulp van de volgende opdracht:
```
dotnet clean file-based-apps
```
Dwing een schone build af om de cache te omzeilen.
```
dotnet clean file.cs
dotnet build file.cs
```

Aanbevelingen voor mapindeling

Organiseer uw op bestanden gebaseerde apps zorgvuldig om conflicten met traditionele projecten en impliciete buildbestanden te voorkomen.

Vermijd conische projectbestanden

Plaats geen apps op basis van bestanden in de mapstructuur van een .csproj project. De impliciete buildbestanden en -instellingen van het projectbestand kunnen uw app op basis van bestanden verstoren.

❌ Niet aanbevolen:

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

✅ Aanbevolen:

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

Houd rekening met impliciete bestanden

Impliciete buildbestanden in bovenliggende mappen zijn van invloed op alle bestandgebaseerde applicaties in submappen. Maak geïsoleerde mappen voor op bestanden gebaseerde apps wanneer u verschillende buildconfiguraties nodig hebt.