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

Anmärkning

När en projektfil finns i den aktuella arbetskatalogendotnet run file.cs körs projektet utan --file-alternativet och file.cs skickas som ett argument till målappen för att bevara bakåtkompatibilitet.

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.

Anmärkning

Samtidiga anrop av en filbaserad app (till exempel att köra mer än en instans av samma filbaserade app parallellt) kan orsaka fel på grund av konkurrens om byggutdatafilerna. Undvik detta genom att först skapa den filbaserade appen via dotnet build file.cs innan du startar de samtidiga instanserna via dotnet run file.cs --no-build.

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.

❌ Rekommenderas inte:

📁 repo/
├── Directory.Build.props  // Affects everything below
├── app1.cs
└── app2.cs

✅ Rekommenderas:

📁 repo/
├── Directory.Build.props
├──📁 projects/
│   └── MyProject.csproj
└──📁 scripts/
    ├── Directory.Build.props  // Isolated configuration
    ├── app1.cs
    └── app2.cs

Se även

Feedback

Var den här sidan hjälpsam?

Last updated on 2026-02-04

Dela via

Filbaserade appar

Direktiv som stöds

#:package

#:project

#:property

#:sdk

CLI-kommandon

Köra program

Ange argument

Rörkod från stdin

Skapa applikationer

Rensa byggresultat

Publicera applikationer

Paketera som ett verktyg

Konvertera till projekt

Återställa beroenden

Standardobjekt som ingår

Native AOT-publicering

Användarhemligheter

Starta profiler

Inställningsfil för platt start

Flera filbaserade appar

Profilval

Traditionella startinställningar

Shell-körning

Implicita byggfiler

Directory.Build.props

Directory.Build.targets

Directory.Packages.props

nuget.config

global.json

Skapa cachelagring

Cachebeteende

Lösningar

Rekommendationer för mappstruktur

Undvik projektfilkoner

Tänk på implicita filer

Se även

Feedback

Ytterligare resurser

`#:package`

`#:project`

`#:property`

`#:sdk`

`Directory.Build.props`

`Directory.Build.targets`

`Directory.Packages.props`

`nuget.config`

`global.json`