Condividi tramite

Creare un contenitore di riferimento per un'app .NET

  • Articolo

Questo articolo di riferimento illustra come configurare l'immagine del contenitore generata quando si pubblica un'app .NET come contenitore. Questo articolo illustra le varie proprietà che è possibile impostare per controllare l'immagine, l'ambiente di esecuzione e i comandi eseguiti all'avvio del contenitore.

Configurare l'immagine del contenitore

È possibile controllare molti aspetti del contenitore generato tramite le proprietà di MSBuild. In generale, se è possibile usare un comando in un Dockerfile per impostare alcune configurazioni, è possibile eseguire la stessa operazione tramite MSBuild.

Nota

Le uniche eccezioni a questo sono RUN comandi. A causa del modo in cui vengono compilati i contenitori, questi non possono essere emulati. Se è necessaria questa funzionalità, è possibile prendere in considerazione l'uso di un Dockerfile per compilare le immagini del contenitore.

Non è possibile eseguire comandi RUN con .NET SDK. Questi comandi vengono spesso usati per installare alcuni pacchetti del sistema operativo o creare un nuovo utente del sistema operativo o un numero qualsiasi di elementi arbitrari. Se si vuole continuare a usare la funzionalità di compilazione del contenitore .NET SDK, è invece possibile creare un'immagine di base personalizzata con queste modifiche e quindi usare questa immagine di base. Per altre informazioni, vedere ContainerBaseImage.

ContainerArchiveOutputPath

Per creare un'immagine del contenitore all'interno di un archivio tar.gz, usare la proprietà ContainerArchiveOutputPath. Questa funzionalità è utile se il flusso di lavoro non è semplice e richiede, ad esempio, di eseguire uno strumento di analisi sulle immagini prima di eseguirne il push. Dopo aver creato l'archivio, è possibile spostarlo, analizzarlo o caricarlo in una toolchain Docker locale.

Per pubblicare in un archivio, aggiungere la proprietà ContainerArchiveOutputPath al comando dotnet publish, ad esempio:

dotnet publish \
  -p PublishProfile=DefaultContainer \
  -p ContainerArchiveOutputPath=./images/sdk-container-demo.tar.gz

È possibile specificare un nome di cartella o un percorso con un nome di file specifico. Se si specifica il nome della cartella, il nome file generato per il file di archivio immagini viene denominato $(ContainerRepository).tar.gz. Questi archivi possono contenere più tag all'interno di essi, solo quando viene creato un singolo file per tutti i ContainerImageTags.

Configurazione dei nomi delle immagini del contenitore

Le immagini del contenitore seguono una convenzione di denominazione specifica. Il nome dell'immagine è costituito da diverse parti, dal Registro di sistema, dalla porta facoltativa, dal repository e da tag e famiglia facoltativi.

REGISTRY[:PORT]/REPOSITORY[:TAG[-FAMILY]]

Si consideri ad esempio il nome completo dell'immagine mcr.microsoft.com/dotnet/runtime:8.0-alpine:

  • mcr.microsoft.com è il registro (e in questo caso rappresenta il registro contenitori Microsoft).
  • dotnet/runtime è il repository ( ma alcuni considerano questo user/repository).
  • 8.0-alpine è il tag e la famiglia (la famiglia è un identificatore facoltativo che aiuta a disambiguare la creazione di pacchetti del sistema operativo).

Alcune proprietà descritte nelle sezioni seguenti corrispondono alla gestione delle parti del nome dell'immagine generata. Si consideri la tabella seguente che esegue il mapping della relazione tra il nome dell'immagine e le proprietà di compilazione:

Parte nome immagine Proprietà MSBuild Valori di esempio
REGISTRY[:PORT] ContainerRegistry mcr.microsoft.com:443
PORT ContainerPort :443
REPOSITORY ContainerRepository dotnet/runtime
TAG ContainerImageTag 8.0
FAMILY ContainerFamily -alpine

Le sezioni seguenti descrivono le varie proprietà che possono essere usate per controllare l'immagine del contenitore generata.

ContainerBaseImage

La proprietà dell'immagine di base del contenitore controlla l'immagine usata come base per l'immagine. Per impostazione predefinita, i valori seguenti vengono dedotti in base alle proprietà del progetto:

  • Se il progetto è autonomo, l'immagine mcr.microsoft.com/dotnet/runtime-deps viene usata come immagine di base.
  • Se il progetto è un progetto ASP.NET Core, l'immagine mcr.microsoft.com/dotnet/aspnet viene usata come immagine di base.
  • In caso contrario, l'immagine mcr.microsoft.com/dotnet/runtime viene usata come immagine di base.

Il tag dell'immagine viene dedotto come componente numerico del TargetFrameworkscelto. Ad esempio, un progetto destinato a net6.0 restituisce il tag 6.0 dell'immagine di base dedotta e un progetto net7.0-linux usa il tag 7.0 e così via.

Se si imposta un valore qui, è necessario impostare il nome completo dell'immagine da usare come base, incluso qualsiasi tag preferito:

<PropertyGroup>
    <ContainerBaseImage>mcr.microsoft.com/dotnet/runtime:8.0</ContainerBaseImage>
</PropertyGroup>

Con .NET SDK versione 8.0.200, l'inferenza ContainerBaseImage è migliorata per ottimizzare le dimensioni e la sicurezza:

  • La destinazione dei linux-musl-x64 o linux-musl-arm64 identificatori di runtime sceglie automaticamente le varianti dell'immagine alpine per garantire l'esecuzione del progetto:
    • Se il progetto usa PublishAot=true, la variante nightly/runtime-depsjammy-chiseled-aot dell'immagine di base per ottenere dimensioni e sicurezza ottimali.
    • Se il progetto usa InvariantGlobalization=false, le varianti di -extra vengono usate per garantire il funzionamento della localizzazione.

Per altre informazioni sulle dimensioni e le caratteristiche delle varianti di immagine, vedere Report dimensioni immagine contenitore .NET 8.0.

ContainerFamily

A partire da .NET 8, è possibile usare la proprietà ContainerFamily MSBuild per scegliere una famiglia diversa di immagini del contenitore fornite da Microsoft come immagine di base per l'app. Se impostato, questo valore viene aggiunto alla fine del tag specifico di TFM selezionato, modificando il tag specificato. Ad esempio, per usare le varianti Alpine Linux delle immagini di base .NET, è possibile impostare ContainerFamily su alpine:

<PropertyGroup>
    <ContainerFamily>alpine</ContainerFamily>
</PropertyGroup>

La configurazione del progetto precedente genera un tag finale di 8.0-alpine per un'app di destinazione .NET 8.

Questo campo è in formato libero e spesso può essere usato per selezionare diverse distribuzioni del sistema operativo, configurazioni predefinite dei pacchetti o qualsiasi altra sapore delle modifiche apportate a un'immagine di base. Questo campo viene ignorato quando viene impostato ContainerBaseImage. Per altre informazioni, vedere immagini del contenitore .NET.

ContainerRuntimeIdentifier(s)

La proprietà ContainerRuntimeIdentifier specifica il sistema operativo e l'architettura per il contenitore se il ContainerBaseImage supporta più piattaforme. Ad esempio, l'immagine di mcr.microsoft.com/dotnet/runtime supporta linux-x64, linux-arm, linux-arm64e win10-x64. Per impostazione predefinita, questa opzione è impostata sul RuntimeIdentifier usato durante la pubblicazione del contenitore. In genere, non è necessario impostare questa proprietà in modo esplicito; Usare invece l'opzione -r con il comando dotnet publish. Se l'immagine scelta non supporta il RuntimeIdentifierspecificato, un errore indica gli identificatori supportati.

È sempre possibile impostare la proprietà ContainerBaseImage su un nome di immagine completo, incluso il tag, per evitare di usare questa proprietà.

<PropertyGroup>
    <ContainerRuntimeIdentifier>linux-arm64</ContainerRuntimeIdentifier>
</PropertyGroup>

Per specificare più identificatori di runtime del contenitore per le immagini con più architetture, usare un set delimitato da punto e virgola di identificatori di runtime nella proprietà ContainerRuntimeIdentifiers, simile all'impostazione di più TargetFrameworks:

<PropertyGroup>
    <ContainerRuntimeIdentifiers>linux-x64;linux-arm64</ContainerRuntimeIdentifiers>
</PropertyGroup>

Per altre informazioni sugli identificatori di runtime supportati da .NET, vedere catalogo RID.

ContainerRegistry

La proprietà del registro contenitori controlla il Registro di sistema di destinazione, ovvero la posizione in cui verrà eseguito il push dell'immagine appena creata. Per impostazione predefinita, viene eseguito il push nel daemon Docker locale, ma è anche possibile specificare un registro remoto. Quando si usa un registro remoto che richiede l'autenticazione, si esegue l'autenticazione usando i meccanismi di docker login noti. Per altre informazioni, vedere 'autenticazione ai registri contenitori per altri dettagli. Per un esempio concreto di utilizzo di questa proprietà, considerare l'esempio XML seguente:

<PropertyGroup>
    <ContainerRegistry>registry.mycorp.com:1234</ContainerRegistry>
</PropertyGroup>

Questo strumento supporta la pubblicazione in qualsiasi registro che supporta l'API HTTP del Registro di sistema Docker V2. Sono inclusi i registri seguenti in modo esplicito (e probabilmente molti altri in modo implicito):

Per le note sull'uso di questi registri, vedere le note specifiche del Registro di sistema .

ContainerRepository

Il repository di contenitori è il nome dell'immagine stessa, ad esempio dotnet/runtime o my-app. Per impostazione predefinita, viene utilizzata la AssemblyName del progetto.

<PropertyGroup>
    <ContainerRepository>my-app</ContainerRepository>
</PropertyGroup>

I nomi delle immagini sono costituiti da uno o più segmenti delimitati da barre, ognuno dei quali può contenere solo caratteri alfanumerici minuscoli, punti, caratteri di sottolineatura e trattini e deve iniziare con una lettera o un numero. Tutti gli altri caratteri generano un errore.

ContainerImageTag(s)

La proprietà tag dell'immagine del contenitore controlla i tag generati per l'immagine. Per specificare un singolo tag, usare ContainerImageTag e per più tag usare ContainerImageTags.

Importante

Quando si usa ContainerImageTags, si otterranno più immagini, una per ogni tag univoco.

I tag vengono spesso usati per fare riferimento a versioni diverse di un'app, ma possono anche fare riferimento a distribuzioni diverse del sistema operativo o anche a configurazioni diverse.

A partire da .NET 8, quando non viene fornito un tag, il valore predefinito è latest.

Per eseguire l'override del valore predefinito, specificare una delle opzioni seguenti:

<PropertyGroup>
    <ContainerImageTag>1.2.3-alpha2</ContainerImageTag>
</PropertyGroup>

Per specificare più tag, usare un set di tag delimitato da punto e virgola nella proprietà ContainerImageTags, in modo analogo all'impostazione di più TargetFrameworks:

<PropertyGroup>
    <ContainerImageTags>1.2.3-alpha2;latest</ContainerImageTags>
</PropertyGroup>

I tag possono contenere solo fino a 127 caratteri alfanumerici, punti, caratteri di sottolineatura e trattini. Devono iniziare con un carattere alfanumerico o un carattere di sottolineatura. Qualsiasi altro modulo genera un errore.

Nota

Quando si usano ContainerImageTags o qualsiasi proprietà MSBuild che deve configurare ; valori delimitati. Se si chiama dotnet publish dalla riga di comando (come nel caso della maggior parte degli ambienti CI/CD), è necessario comprendere le limitazioni dell'impossibilità dell'ambiente di disambiguare delimitatori e virgolette, richiedendo così un'escape appropriato. Questa differenza è tra PowerShell e Bash. Considerare i comandi dotnet publish seguenti nei rispettivi ambienti:

dotnet publish --os linux --arch x64 /t:PublishContainer /p:ContainerImageTags=`"1.2.3-alpha2`;latest`"

In PowerShell è necessario eseguire l'escape sia dei caratteri ; che di ".

dotnet publish --os linux --arch x64 /t:PublishContainer /p:ContainerImageTags=\"1.2.3-alpha2;latest\"

In Bash è necessario eseguire l'escape solo il carattere ".

Ciò comporta la generazione di due immagini: my-app:1.2.3-alpha2 e my-app:latest.

Mancia

Se si verificano problemi con la proprietà ContainerImageTags, prendere in considerazione l'ambito di una variabile di ambiente ContainerImageTags:

$Env:ContainerImageTags='1.2.3;latest'; dotnet publish --os linux --arch x64 /t:PublishContainer

ContainerLabel

L'etichetta del contenitore aggiunge un'etichetta di metadati al contenitore. Le etichette vengono spesso usate per archiviare i metadati di versione e creazione per l'uso da parte degli scanner di sicurezza e di altri strumenti di infrastruttura. È possibile specificare un numero qualsiasi di etichette del contenitore.

Il nodo ContainerLabel ha due attributi:

  • Include: chiave dell'etichetta.
  • Value: valore dell'etichetta (potrebbe essere vuoto).
<ItemGroup>
    <ContainerLabel Include="org.contoso.businessunit" Value="contoso-university" />
</ItemGroup>

Per un elenco di etichette create per impostazione predefinita, vedere etichette dei contenitori predefinite.

Configurare l'esecuzione del contenitore

Per controllare l'esecuzione del contenitore, è possibile usare le proprietà MSBuild seguenti.

ContainerWorkingDirectory

Il nodo della directory di lavoro del contenitore controlla la directory di lavoro del contenitore, la directory in cui vengono eseguiti i comandi se non viene eseguito un altro comando.

Per impostazione predefinita, il valore della directory /app viene usato come directory di lavoro.

<PropertyGroup>
    <ContainerWorkingDirectory>/bin</ContainerWorkingDirectory>
</PropertyGroup>

ContainerPort

La porta del contenitore aggiunge le porte TCP (Transmission Control Protocol) o UDP (User Datagram Protocol) all'elenco di porte note per il contenitore. Ciò consente ai runtime di contenitori come Docker di eseguire automaticamente il mapping di queste porte al computer host. Questa operazione viene spesso usata come documentazione per il contenitore, ma può essere usata anche per abilitare il mapping automatico delle porte.

Il nodo ContainerPort ha due attributi:

  • Include: numero di porta da esporre.
  • Type: il valore predefinito è tcp, i valori validi sono tcp o udp.
<ItemGroup>
    <ContainerPort Include="80" Type="tcp" />
</ItemGroup>

A partire da .NET 8, il ContainerPort viene dedotto quando non viene fornito in modo esplicito in base a diverse variabili di ambiente ASP.NET note:

  • ASPNETCORE_URLS
  • ASPNETCORE_HTTP_PORTS
  • ASPNETCORE_HTTPS_PORTS

Se queste variabili di ambiente sono presenti, i relativi valori vengono analizzati e convertiti in mapping delle porte TCP. Queste variabili di ambiente vengono lette dall'immagine di base, se presente o dalle variabili di ambiente definite nel progetto tramite ContainerEnvironmentVariable elementi. Per altre informazioni, vedere ContainerEnvironmentVariable.

ContainerEnvironmentVariable

Il nodo della variabile di ambiente del contenitore consente di aggiungere variabili di ambiente al contenitore. Le variabili di ambiente sono accessibili all'app in esecuzione immediatamente nel contenitore e vengono spesso usate per modificare il comportamento di runtime dell'app in esecuzione.

Il nodo ContainerEnvironmentVariable ha due attributi:

  • Include: nome della variabile di ambiente.
  • Value: valore della variabile di ambiente.
<ItemGroup>
  <ContainerEnvironmentVariable Include="LOGGER_VERBOSITY" Value="Trace" />
</ItemGroup>

Per altre informazioni, vedere variabili di ambiente .NET.

Nota

Non è attualmente possibile impostare le variabili di ambiente dall'interfaccia della riga di comando di .NET durante la pubblicazione di un'immagine del contenitore. Per altre informazioni, vedere GitHub: compilazioni di contenitori .NET SDK.

Configurare i comandi del contenitore

Per impostazione predefinita, gli strumenti contenitore avviano l'app usando il file binario AppHost generato per l'app (se l'app usa un AppHost) o il comando dotnet più la DLL dell'app.

Tuttavia, puoi controllare come viene eseguita l'app usando una combinazione di ContainerAppCommand, ContainerAppCommandArgs, ContainerDefaultArgse ContainerAppCommandInstruction.

Questi diversi punti di configurazione esistono perché diverse immagini di base usano combinazioni diverse delle proprietà di ENTRYPOINT e COMMAND del contenitore e si vuole poter supportare tutte. Le impostazioni predefinite devono essere utilizzabili per la maggior parte delle app, ma se vuoi personalizzare il comportamento di avvio dell'app devi:

  • Identificare il file binario da eseguire e impostarlo come ContainerAppCommand
  • Identificare gli argomenti necessari per l'esecuzione dell'applicazione e impostarli come ContainerAppCommandArgs
  • Identificare quali argomenti (se presenti) sono facoltativi e possono essere sottoposti a override da un utente e impostarli come ContainerDefaultArgs
  • Impostare ContainerAppCommandInstruction su DefaultArgs

Per altre informazioni, vedere gli elementi di configurazione seguenti.

ContainerAppCommand

L'elemento di configurazione del comando dell'app è il punto di ingresso logico dell'app. Per la maggior parte delle app, questo è AppHost, il file binario eseguibile generato per l'app. Se l'app non genera un AppHost, questo comando viene in genere dotnet <your project dll>. Questi valori vengono applicati dopo qualsiasi ENTRYPOINT nel contenitore di base o direttamente se non è definita alcuna ENTRYPOINT.

La configurazione ContainerAppCommand ha una singola proprietà Include, che rappresenta il comando, l'opzione o l'argomento da usare nel comando del punto di ingresso:

<ItemGroup Label="ContainerAppCommand Assignment">
  <!-- This is how you would start the dotnet ef tool in your container -->
  <ContainerAppCommand Include="dotnet" />
  <ContainerAppCommand Include="ef" />

  <!-- This shorthand syntax means the same thing, note the semicolon separating the tokens. -->
  <ContainerAppCommand Include="dotnet;ef" />
</ItemGroup>

ContainerAppCommandArgs

Questo elemento di configurazione args del comando dell'app rappresenta tutti gli argomenti necessari logicamente per l'app che devono essere applicati al ContainerAppCommand. Per impostazione predefinita, nessuna viene generata per un'app. Quando presente, gli argomenti vengono applicati al contenitore quando viene eseguito.

La configurazione ContainerAppCommandArgs dispone di una singola proprietà Include, che rappresenta l'opzione o l'argomento da applicare al comando ContainerAppCommand.

<ItemGroup>
  <!-- Assuming the ContainerAppCommand defined above,
       this would be the way to force the database to update.
  -->
  <ContainerAppCommandArgs Include="database" />
  <ContainerAppCommandArgs Include="update" />

  <!-- This is the shorthand syntax for the same idea -->
  <ContainerAppCommandArgs Include="database;update" />
</ItemGroup>

ContainerDefaultArgs

Questo elemento di configurazione args predefinito rappresenta tutti gli argomenti sostituibili dall'utente per l'app. Questo è un buon modo per fornire le impostazioni predefinite che l'app potrebbe dover eseguire in modo da semplificare l'avvio, ma ancora facile da personalizzare.

La configurazione ContainerDefaultArgs dispone di una singola proprietà Include, che rappresenta l'opzione o l'argomento da applicare al comando ContainerAppCommand.

<ItemGroup>
  <!-- Assuming the ContainerAppCommand defined above,
       this would be the way to force the database to update.
  -->
  <ContainerDefaultArgs Include="database" />
  <ContainerDefaultArgs Include="update" />

  <!-- This is the shorthand syntax for the same idea -->
  <ContainerDefaultArgs Include="database;update" />
</ItemGroup>

ContainerAppCommandInstruction

La configurazione dell'istruzione del comando dell'app consente di controllare il modo in cui le ContainerEntrypoint, ContainerEntrypointArgs, ContainerAppCommand, ContainerAppCommandArgse ContainerDefaultArgs vengono combinate per formare il comando finale eseguito nel contenitore. Questo dipende notevolmente da se un ENTRYPOINT è presente nell'immagine di base. Questa proprietà accetta uno dei tre valori seguenti: "DefaultArgs", "Entrypoint"o "None".

  • Entrypoint:
    • In questa modalità, il punto di ingresso viene definito da ContainerAppCommand, ContainerAppCommandArgse ContainerDefaultArgs.
  • None:
    • In questa modalità, il punto di ingresso viene definito da ContainerEntrypoint, ContainerEntrypointArgse ContainerDefaultArgs.
  • DefaultArgs:
    • Questa è la modalità più complessa: se nessuno degli elementi ContainerEntrypoint[Args] è presente, i ContainerAppCommand[Args] e i ContainerDefaultArgs vengono usati per creare il punto di ingresso e il comando. Il punto di ingresso dell'immagine di base per le immagini di base che lo hanno hardcoded per dotnet o /usr/bin/dotnet viene ignorato in modo da avere il controllo completo.
    • Se sono presenti sia ContainerEntrypoint che ContainerAppCommand, ContainerEntrypoint diventa il punto di ingresso e ContainerAppCommand diventa il comando.

Nota

Gli elementi di configurazione ContainerEntrypoint e ContainerEntrypointArgs sono deprecati a partire da .NET 8.

Importante

Questo è per le app avanzate che la maggior parte degli utenti non deve personalizzare il punto di ingresso in questo modo. Per altre informazioni e per fornire casi d'uso per gli scenari, vedere GitHub: .NET SDK container build discussions.

ContainerUser

La proprietà di configurazione utente controlla l'utente predefinito eseguito dal contenitore. Viene spesso usato per eseguire il contenitore come utente non radice, che è una procedura consigliata per la sicurezza. Per questa configurazione è necessario tenere presenti alcuni vincoli:

  • Può assumere varie forme: nome utente, ID utente linux, nome del gruppo, ID gruppo linux, username:groupnamee altre varianti ID.
  • Non esiste alcuna verifica che l'utente o il gruppo specificato esista nell'immagine.
  • La modifica dell'utente può modificare il comportamento dell'app, in particolare per quanto riguarda elementi come file system autorizzazioni.

Il valore predefinito di questo campo varia in base al progetto TFM e al sistema operativo di destinazione:

  • Se si usa .NET 8 o versione successiva e si usano le immagini di Runtime Microsoft, procedere come destinazione:
    • in Linux, l'utente senza radice app viene usato (anche se fa riferimento al relativo ID utente)
    • in Windows viene usato il ContainerUser utente senza radice
  • In caso contrario, non viene usato alcun ContainerUser predefinito
<PropertyGroup>
  <ContainerUser>my-existing-app-user</ContainerUser>
</PropertyGroup>

Mancia

La variabile di ambiente APP_UID viene usata per impostare le informazioni utente nel contenitore. Questo valore può provenire da variabili di ambiente definite nell'immagine di base (come le immagini Microsoft .NET) oppure è possibile impostarlo manualmente tramite la sintassi ContainerEnvironmentVariable.

Per configurare l'app per l'esecuzione come utente radice, impostare la proprietà ContainerUser su root. Nel file di progetto aggiungere quanto segue:

<PropertyGroup>
  <ContainerUser>root</ContainerUser>
</PropertyGroup>

In alternativa, è possibile impostare questo valore quando si chiama dotnet publish dalla riga di comando:

dotnet publish -p ContainerUser=root

Etichette dei contenitori predefinite

Le etichette vengono spesso usate per fornire metadati coerenti sulle immagini del contenitore. Questo pacchetto fornisce alcune etichette predefinite per incoraggiare una migliore manutenibilità delle immagini generate.

  • org.opencontainers.image.created è impostato sul formato ISO 8601 del valore corrente di DateTime.UtcNow.

Per altre informazioni, vedere Implementare le etichette convenzionali sopra l'infrastruttura di etichette esistente.

Vedere anche