Filbaserade appar

Den här artikeln gäller för: ✔️ .NET 10 SDK och senare versioner

Med filbaserade appar kan du skapa, köra och publicera .NET-program från en enda C#-fil utan att skapa en traditionell projektfil. De erbjuder ett enkelt alternativ till traditionella .NET-projekt. Den här metoden förenklar utvecklingen för skript, verktyg och små program. .NET SDK genererar automatiskt den nödvändiga projektkonfigurationen baserat på direktiven i källfilen.

Viktiga fördelar är:

Minskad schablon för enkla applikationer.
Fristående källfiler med inbäddad konfiguration.
Intern AOT-publicering aktiverad som standard.
Automatisk paketering som .NET-verktyg.

I den här artikeln lär du dig att skapa, konfigurera och arbeta effektivt med filbaserade appar.

Direktiv som stöds

Filbaserade appar använder direktiv som föregås av #: för att konfigurera bygget och köra programmet. De direktiv som stöds omfattar: #:package, #:project, #:propertyoch #:sdk. Placera dessa direktiv överst i C#-filen.

`#:package`

Lägger till en NuGet-paketreferens till ditt program.

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

Anmärkning

Att utelämna versionsnumret efter paketnamnet fungerar för närvarande bara när du använder central pakethantering med en Directory.Packages.props fil. Annars anger du versionsnumret explicit eller lägger till @* efter paketnamnet för att använda den senaste versionen.

`#:project`

Refererar till en annan projektfil eller katalog som innehåller en projektfil.

#:project ../SharedLibrary/SharedLibrary.csproj

`#:property`

Anger ett MSBuild-egenskapsvärde.

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

`#:sdk`

Anger vilken SDK som ska användas. Standardinställningen är Microsoft.NET.Sdk.

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

CLI-kommandon

.NET CLI ger fullständigt stöd för filbaserade appar via välbekanta kommandon.

Köra program

Kör en filbaserad app genom att använda dotnet run kommandot med --file alternativet:

dotnet run --file file.cs

Eller använd dotnet run kommandot följt av namnet på filen:

dotnet run file.cs

Eller använd den korta syntaxen:

dotnet file.cs

Ange argument

Skicka argument till ditt program genom att placera dem efter --:

dotnet run file.cs -- arg1 arg2

Rörkod från stdin

Skicka C#-kod direkt till dotnet run med standardindata med - argumentet . Argumentet - anger att dotnet run läser koden från standardindata i stället för en fil. - Med argumentet dotnet run söker inte den aktuella arbetskatalogen efter andra filer, till exempel startprofiler. Den aktuella katalogen är fortfarande arbetskatalogen för att skapa och köra programmet.

PowerShell:

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

Bash:

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

Den här metoden är användbar för snabb testning, körning av engångskommandon eller integrering med gränssnittsskript som genererar C#-kod dynamiskt.

Skapa applikationer

Kompilera din filbaserade app med hjälp dotnet build av kommandot :

dotnet build file.cs

SDK:et genererar ett virtuellt projekt och skapar ditt program. Som standard går byggutdata till systemets temporära katalog under <temp>/dotnet/runfile/<appname>-<appfilesha>/bin/<configuration>/.

Använd alternativet --output med dotnet build kommandot för att ange en annan sökväg. Om du vill definiera en ny standardutdatasökväg anger du OutputPath egenskapen överst i filen med hjälp av direktivet: #:property OutputPath=./output.

Rensa byggresultat

Ta bort kompileringsartefakter med hjälp dotnet clean av kommandot :

dotnet clean file.cs

Ta bort cache för filbaserade appar i en katalog:

dotnet clean file-based-apps

Använd alternativet --days med föregående kommando för att ange hur många dagar en artefaktmapp måste vara oanvänd innan den tas bort. Standardantalet dagar är 30.

Publicera applikationer

Filbaserade appar möjliggör intern AOT-publicering som standard, vilket ger optimerade, fristående körbara filer. Inaktivera den här funktionen genom att lägga till #:property PublishAot=false överst i filen.

dotnet publish Använd kommandot för att skapa en oberoende körbar fil:

dotnet publish file.cs

Standardplatsen för den körbara filen är en artifacts katalog bredvid .cs filen, med en underkatalog med namnet efter programmet. Använd alternativet --output med dotnet publish kommandot för att ange en annan sökväg.

Paketera som ett verktyg

Paketera din filbaserade app som ett .NET-verktyg med hjälp dotnet pack av kommandot :

dotnet pack file.cs

Filbaserade appar ställs in som standard PackAsTool=true. Inaktivera den här inställningen genom att lägga till #:property PackAsTool=false överst i filen.

Konvertera till projekt

Konvertera din filbaserade app till ett traditionellt projekt med hjälp dotnet project convert av kommandot :

dotnet project convert file.cs

Det här kommandot gör en kopia av .cs filen och skapar en .csproj fil med motsvarande SDK-objekt, egenskaper och paketreferenser baserat på den ursprungliga filens #: direktiv. Båda filerna placeras i en katalog med namnet för programmet bredvid den ursprungliga .cs filen, som lämnas orörd.

Återställa beroenden

Återställ NuGet-paket som refereras till i filen med hjälp dotnet restore av kommandot :

dotnet restore file.cs

Som standard körs återställning implicit när du skapar eller kör ditt program. Du kan dock skicka --no-restore både till dotnet build och dotnet run-kommandona för att bygga eller köra utan att implicit återställa.

Standardobjekt som ingår

Filbaserade appar innehåller automatiskt specifika filtyper för kompilering och paketering.

Som standard ingår den enda C#-filen.

Olika SDK:er innehåller andra filtyper:

Microsoft.NET.Sdk.Web innehåller *.json konfigurationsfiler.
SDK:er som inte är standard innehåller ResX-resursfiler.

Native AOT-publicering

Filbaserade appar aktiverar intern AOT-kompilering (i förväg) som standard. Den här funktionen ger optimerade, fristående körbara filer med snabbare start och ett mindre minnesavtryck.

Om du behöver inaktivera intern AOT använder du följande inställning:

#:property PublishAot=false

Mer information om intern AOT finns i Intern AOT-distribution.

Användarhemligheter

Filbaserade appar genererar ett stabilt användarhemlighets-ID baserat på en hash för den fullständiga filsökvägen. Med det här ID:t kan du lagra känslig konfiguration separat från källkoden.

Få åtkomst till användarhemligheter på samma sätt som traditionella projekt:

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

Lista användarhemligheter för filbaserade appar:

dotnet user-secrets list --file file.cs

Kommandot dotnet user-secrets list skriver ut värdet för dina hemligheter. Placera inte det här kommandot i skript som körs i offentliga kontexter.

Mer information finns i Säker lagring av apphemligheter under utveckling.

Starta profiler

Filbaserade appar stöder startprofiler för att konfigurera hur programmet körs under utvecklingen. I stället för att placera startprofiler i Properties/launchSettings.jsonkan filbaserade appar använda en flat startinställningsfil med namnet [ApplicationName].run.json i samma katalog som källfilen.

Inställningsfil för platt start

Skapa en startinställningsfil med namnet efter ditt program. Om din filbaserade app till exempel är app.csskapar du app.run.json i samma katalog:

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

Flera filbaserade appar

När du har flera filbaserade appar i samma katalog kan varje app ha en egen startinställningsfil:

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

Profilval

.NET CLI väljer startprofiler med följande prioritet:

Profilen som specificeras i --launch-profile-alternativet.
Profilen som anges av DOTNET_LAUNCH_PROFILE miljövariabeln.
Den första profilen som definierats i startinställningsfilen.

Så här kör du med en specifik profil:

dotnet run app.cs --launch-profile https

Traditionella startinställningar

Filbaserade appar stöder också den traditionella Properties/launchSettings.json filen. Om båda filerna finns prioriteras den traditionella platsen. Om båda filerna finns loggar .NET CLI en varning för att klargöra vilken fil som används.

Shell-körning

Aktivera direkt körning av filbaserade appar i Unix-liknande system med hjälp av en shebang-rad och körbara behörigheter.

Lägg till en shebang överst i filen:

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

using Spectre.Console;

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

Gör filen körbar:

chmod +x file.cs

Kör omedelbart

./file.cs

Anmärkning

Använd LF radslut istället för CRLF när du lägger till en shebang. Inkludera inte en BOM (Byte Order Mark) i filen.

Implicita byggfiler

Filbaserade appar respekterar MSBuild- och NuGet-konfigurationsfiler i samma katalog eller överordnade kataloger. Dessa filer påverkar hur SDK:et skapar ditt program. Tänk på de här filerna när du organiserar dina filbaserade appar.

`Directory.Build.props`

Definierar MSBuild-egenskaper som gäller för alla projekt i ett katalogträd. Filbaserade appar ärver dessa egenskaper.

`Directory.Build.targets`

Definierar MSBuild-mål och anpassad bygglogik. Filbaserade appar kör dessa mål under bygget.

`Directory.Packages.props`

Aktiverar central pakethantering för NuGet-beroenden. Filbaserade appar kan använda centralt hanterade paketversioner.

`nuget.config`

Konfigurerar NuGet-paketkällor och -inställningar. Filbaserade appar använder dessa konfigurationer när paket återställs.

`global.json`

Anger den .NET SDK-version som ska användas. Filbaserade appar respekterar det här versionsvalet.

Skapa cachelagring

.NET SDK cachelagrar build-utdata för att förbättra prestanda för efterföljande anrop av dotnet run. Det här cachelagringssystemet är unikt för filbaserade appar.

Cachebeteende

SDK cachelagrar build-utdata baserat på:

Källfilinnehåll.
Konfiguration av direktiv.
SDK-version
implicit byggfilsexistens och innehåll.

Cachelagring förbättrar byggprestanda men kan orsaka förvirring när:

Ändringar i implicita byggfiler utlöser inte återskapanden.
Om du flyttar filer till olika kataloger ogiltigförklaras inte cacheminnet.

Lösningar

Rensa cacheartefakter för filbaserade appar med hjälp av följande kommando:

dotnet clean file-based-apps

Framtvinga en ren version för att kringgå cacheminnet:
```
dotnet clean file.cs
dotnet build file.cs
```

Rekommendationer för mappstruktur

Organisera dina filbaserade appar noggrant för att undvika konflikter med traditionella projekt och implicita byggfiler.

Undvik projektfilkoner

Placera inte filbaserade appar i katalogstrukturen i ett .csproj projekt. Projektfilens implicita byggfiler och inställningar kan störa din filbaserade app.

❌ Rekommenderas inte:

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

✅ Rekommenderas:

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

Tänk på implicita filer

Implicita byggfiler i överordnade kataloger påverkar alla filbaserade appar i underkataloger. Skapa isolerade kataloger för filbaserade appar när du behöver olika byggkonfigurationer.