App basate su file

Questo articolo si applica a: ✔️ .NET 10 SDK e versioni successive

Le app basate su file consentono di compilare, eseguire e pubblicare applicazioni .NET da un singolo file C# senza creare un file di progetto tradizionale. Offrono un'alternativa leggera ai progetti .NET tradizionali. Questo approccio semplifica lo sviluppo per script, utilità e applicazioni di piccole dimensioni. .NET SDK genera automaticamente la configurazione del progetto necessaria in base alle direttive nel file di origine.

I vantaggi principali includono:

Codice standard ridotto per applicazioni semplici.
File di origine indipendenti con configurazione incorporata.
Pubblicazione AOT nativa abilitata per impostazione predefinita.
Creazione automatica dei pacchetti come strumenti .NET.

Questo articolo illustra come creare, configurare e usare in modo efficace le app basate su file.

Direttive supportate

Le app basate su file usano direttive precedute da #: per configurare la compilazione ed eseguire l'applicazione. Le direttive supportate includono: #:package, #:project, #:propertye #:sdk. Inserire queste direttive all'inizio del file C#.

`#:package`

Aggiunge un riferimento al pacchetto NuGet all'applicazione.

#:package Newtonsoft.Json
#:package Serilog version="3.1.1"

`#:project`

Fa riferimento a un altro file di progetto o a un'altra directory che contiene un file di progetto.

#:project ../SharedLibrary/SharedLibrary.csproj

`#:property`

Imposta il valore di una proprietà MSBuild.

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

`#:sdk`

Specifica l'SDK da usare. Il valore predefinito è Microsoft.NET.Sdk.

#:sdk Microsoft.NET.Sdk.Web

Comandi della CLI

L'interfaccia della riga di comando di .NET offre supporto completo per le app basate su file tramite comandi noti.

Eseguire applicazioni

Eseguire un'app basata su file direttamente usando il dotnet run comando :

dotnet run file.cs

In alternativa, usare la sintassi abbreviata:

dotnet file.cs

Passaggio di argomenti

Trasmettere argomenti all'applicazione in diversi modi:

dotnet run file.cs -- arg1 arg2

Gli argomenti dopo -- vengono passati alla tua applicazione. Senza --, gli argomenti passano al dotnet run comando :

dotnet run file.cs arg1 arg2

Tuttavia, con la sintassi abbreviata, tutti gli argomenti passano all'applicazione:

dotnet file.cs arg1 arg2

Compilare applicazioni

Compilare l'app basata su file usando il comando dotnet build

dotnet build file.cs

L'SDK genera un progetto temporaneo e compila l'applicazione.

Pulire gli output di compilazione

Rimuovere gli artefatti di compilazione usando il dotnet clean comando :

dotnet clean file.cs

Pulire tutte le app basate su file in una directory:

dotnet clean file-based-apps

Pubblicare applicazioni

Creare un pacchetto di distribuzione usando il dotnet publish comando :

dotnet publish file.cs

Le app basate su file consentono la pubblicazione AOT nativa per impostazione predefinita, producendo eseguibili ottimizzati e indipendenti.

Pacchetto come strumento

Per creare un pacchetto dell'app basata su file come strumento .NET, usa il comando dotnet pack:

dotnet pack file.cs

Le app basate su file sono impostate PackAsTool=true per impostazione predefinita.

Converti in progetto

Convertire l'app basata su file in un progetto tradizionale usando il dotnet project convert comando :

dotnet project convert file.cs

Questo comando crea un .csproj file con SDK e proprietà equivalenti. Tutte le # direttive vengono rimosse dal .cs file e trasformate in elementi nel file corrispondente .csproj .

Ripristinare le dipendenze

Ripristinare i pacchetti NuGet a cui si fa riferimento nel file usando il dotnet restore comando :

dotnet restore file.cs

Il ripristino viene eseguito in modo implicito quando si compila o si esegue l'applicazione.

Elementi inclusi predefiniti

Le app basate su file includono automaticamente tipi di file specifici per la compilazione e la creazione di pacchetti.

Per impostazione predefinita, sono inclusi gli elementi seguenti:

Il singolo file C#
File di risorse ResX nella stessa directory.

Gli SDK diversi includono altri tipi di file:

Microsoft.NET.Sdk.Web comprende *.json file di configurazione.
Altri SDK specializzati potrebbero includere altri modelli.

Pubblicazione AOT nativa

Per impostazione predefinita, le app basate su file consentono la compilazione anticipata (AOT) nativa. Questa funzionalità produce eseguibili ottimizzati e indipendenti con un'avvio più veloce e un footprint di memoria inferiore.

Se è necessario disabilitare AOT nativo, usare l'impostazione seguente:

#:property PublishAot=false

Per altre informazioni sull'AOT nativo, vedere Distribuzione AOT nativa.

Segreti utente

Le app basate su file generano un ID segreto utente stabile basato su un hash del percorso completo del file. Questo ID consente di archiviare la configurazione sensibile separatamente dal codice sorgente.

Accedere ai segreti utente allo stesso modo dei progetti tradizionali:

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

Per altre informazioni, vedere Archiviazione sicura dei segreti delle app in fase di sviluppo.

Profili di avvio

Le app basate su file supportano i profili di avvio per configurare la modalità di esecuzione dell'applicazione durante lo sviluppo. Invece di posizionare i profili di avvio in Properties/launchSettings.json, le app basate su file possono usare un file di impostazioni di avvio flat denominato [ApplicationName].run.json nella stessa directory del file di origine.

File delle impostazioni piatte di lancio

Creare un file di impostazioni di avvio denominato dopo l'applicazione. Ad esempio, se l'app basata su file è app.cs, creare app.run.json nella stessa directory:

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

Più app basate su file

Quando si dispone di più app basate su file nella stessa directory, ogni app può avere un proprio file di impostazioni di avvio:

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

Selezione profilo

L'interfaccia della riga di comando di .NET seleziona i profili di avvio usando la priorità seguente:

Profilo specificato dall'opzione --launch-profile .
Profilo specificato dalla variabile di DOTNET_LAUNCH_PROFILE ambiente.
Primo profilo definito nel file delle impostazioni di avvio.

Per eseguire con un profilo specifico:

dotnet run app.cs --launch-profile https

Impostazioni di avvio tradizionali

Le app basate su file supportano anche il file tradizionale Properties/launchSettings.json . Se esistono entrambi i file, il percorso tradizionale ha la priorità. Se sono presenti entrambi i file, l'interfaccia della riga di comando di .NET registra un avviso per chiarire quale file viene usato.

Esecuzione della shell

Abilitare l'esecuzione diretta di applicazioni basate su file nei sistemi simili a Unix utilizzando una riga shebang e permessi di esecuzione.

Aggiungere un shebang nella parte superiore del file:

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

using Spectre.Console;

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

Rendere eseguibile il file:

chmod +x file.cs

Esegui direttamente:

./file.cs

File di compilazione impliciti

Le app basate su file rispettano i file di configurazione di MSBuild e NuGet nella stessa directory o directory superiori. Questi file influiscono sul modo in cui l'SDK compila l'applicazione. Tenere presente questi file quando si organizzano le app basate su file.

`Directory.Build.props`

Definisce le proprietà di MSBuild che si applicano a tutti i progetti in un albero di directory. Le app basate su file ereditano queste proprietà.

`Directory.Build.targets`

Definisce le destinazioni MSBuild e la logica di compilazione personalizzata. Le app basate su file eseguono questi target durante il build.

`Directory.Packages.props`

Abilita la gestione centrale dei pacchetti per le dipendenze NuGet. Le app basate su file possono usare versioni di pacchetti gestite centralmente.

`nuget.config`

Configura le origini e le impostazioni dei pacchetti NuGet. Le app basate su file usano queste configurazioni durante il ripristino dei pacchetti.

`global.json`

Specifica la versione di .NET SDK da usare. Le app basate su file rispettano questa selezione di versione.

Memorizzazione nella cache della compilazione

.NET SDK memorizza nella cache gli output di compilazione per migliorare le prestazioni nelle build successive. Le app basate su file partecipano a questo sistema di memorizzazione nella cache.

Comportamento della cache

L'SDK memorizza nella cache gli output di compilazione in base a:

Contenuto del file di origine.
Configurazione della direttiva.
La versione dell'SDK.
File di compilazione impliciti.

La memorizzazione nella cache migliora le prestazioni di compilazione, ma può causare confusione quando:

Le modifiche apportate ai file di compilazione impliciti non attivano la ricompilazione.
Lo spostamento di file in directory diverse non invalida la cache.

Soluzioni alternative

Eseguire una compilazione completa usando il --no-cache flag :
```
dotnet build file.cs --no-cache
```
Forzare una compilazione pulita per ignorare la cache:
```
dotnet clean file.cs
dotnet build file.cs
```

Suggerimenti sul layout delle cartelle

Organizzare attentamente le app basate su file per evitare conflitti con i progetti tradizionali e i file di compilazione impliciti.

Evitare i coni dei file di progetto

Non inserire app basate su file all'interno della struttura di directory di un .csproj progetto. I file di compilazione e le impostazioni impliciti del file di progetto possono interferire con l'app basata su file.

❌ Non consigliato:

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

✅ Consigliato:

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

Tenere presente i file impliciti

I file di compilazione impliciti nelle directory padre influiscono su tutte le app basate su file nelle sottodirectory. Creare directory isolate per le app basate su file quando sono necessarie configurazioni di compilazione diverse.