Come risolvere l’errore che richiede .NET Core su Windows

Quando Windows chiede .NET Core, il punto vero è capire quale runtime manca

Se un’applicazione Windows apre una finestra che invita a installare .NET Core, la lettura corretta non è “manca .NET in generale”, ma “l’eseguibile sta cercando un runtime preciso e non lo trova”. In pratica il problema può essere nel framework richiesto, nell’architettura, nella pubblicazione dell’app o nel modo in cui è stata distribuita. La correzione giusta dipende da quale di questi quattro casi stai guardando.

© TrgtKLS • Tech, Sicurezza e Strumenti & guide per Webmaster — https://trgtkls.it — tutti i diritti riservati.

Il primo errore da evitare è installare componenti a caso. Su Windows convivono runtime diversi, e una versione presente non garantisce che l’app parta. Un’app compilata per x64 non si accontenta di un runtime x86; un’app che richiede .NET Desktop Runtime non parte con il solo ASP.NET Runtime; un binario self-contained non dovrebbe chiedere nulla, mentre uno framework-dependent sì.

Per questo conviene trattare l’errore come un piccolo incidente di compatibilità, non come un guasto generico. Il flusso corretto è: identificare il messaggio esatto, verificare i runtime installati, confrontare architettura e versione, poi applicare la correzione minima e reversibile.

Il sintomo cambia, ma le cause ricorrenti sono sempre poche

Le formulazioni più comuni sono queste: “You must install or update .NET to run this application”, “A fatal error was encountered”, “The framework ‘Microsoft.NETCore.App’ was not found”, oppure una finestra che indica una specifica versione, per esempio 6.0.x o 8.0.x. In alcuni casi compare anche il riferimento a Microsoft.WindowsDesktop.App, che segnala un’app desktop basata su WPF o WinForms.

La distinzione è importante perché non tutti i runtime sono equivalenti. Microsoft.NETCore.App copre il runtime base. Microsoft.WindowsDesktop.App aggiunge ciò che serve alle app desktop. ASP.NET Core Runtime serve alle applicazioni web hostate localmente o a servizi che usano quel stack. Se installi il runtime sbagliato, l’errore resta identico.

Un’altra causa ricorrente è la mancanza del runtime hosting bundle quando l’app viene eseguita dietro IIS o da un contesto che si appoggia al modulo ASP.NET Core. In quel caso il problema non è l’applicazione in sé, ma l’infrastruttura che la ospita.

Prima verifica: capire cosa sta davvero cercando l’eseguibile

Il modo più rapido è leggere il messaggio completo o la finestra di errore fino in fondo. Se c’è un riferimento a una versione precisa, quella è la prima pista. Se compare un nome come Microsoft.NETCore.App 6.0.0, l’app richiede almeno quel runtime major/minor. Se invece il messaggio è generico, bisogna passare al controllo locale dei runtime installati.

Su una macchina Windows puoi verificare i runtime con il tool ufficiale dotnet, se già presente. Il comando utile è questo:

dotnet --list-runtimes

Se il comando restituisce un elenco di runtime, controlla tre cose: nome del pacchetto, versione e cartella di installazione. Un output tipico mostra righe come Microsoft.NETCore.App 8.0.5 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]. Se la versione richiesta dall’app non compare, il problema è confermato.

Se dotnet non è disponibile, non è ancora una prova del problema: può significare che il runtime non è installato oppure che il percorso non è nel PATH. In quel caso va verificata la presenza della cartella C:\Program Files\dotnet\ e, su sistemi a 64 bit, anche C:\Program Files (x86)\dotnet\.

La trappola più comune: architettura sbagliata

Molti ticket vengono chiusi male perché si installa “il runtime giusto” ma nella variante sbagliata. Un eseguibile compilato per x86 può girare con runtime x86 anche su Windows a 64 bit; un eseguibile x64 vuole il runtime x64. Se l’app è stata distribuita senza chiarire l’architettura, il messaggio di errore può sembrare identico a quello di una versione mancante.

Per distinguere i due casi, osserva dove è installato il runtime e che tipo di binario stai lanciando. Se l’app è in Program Files e il runtime presente è solo in Program Files (x86), hai già un indizio forte. Se disponi del pacchetto originale, controlla le proprietà del file o la documentazione di rilascio per l’architettura target.

In ambienti aziendali capita anche il contrario: runtime x64 installato, ma l’app è stata pubblicata come x86 per abitudine o per dipendenza da componenti legacy. In quel caso la soluzione non è “mettere più .NET”, ma allineare compilazione e distribuzione al target corretto.

Se l’app è desktop, il runtime corretto spesso è WindowsDesktop

Le app WinForms e WPF non si accontentano del runtime base. Se il messaggio richiama Microsoft.WindowsDesktop.App, installare solo .NET Runtime non basta. Serve il .NET Desktop Runtime della stessa major version richiesta. È una differenza piccola all’apparenza, ma è quella che blocca molti utenti finali.

Per verificare, apri la lista dei runtime installati e cerca la voce desktop. Se manca, scarica il pacchetto Desktop Runtime dal sito Microsoft, scegliendo la versione coerente con il messaggio. Se l’app richiede 8.0.x, non installare una 7.0.x sperando in compatibilità implicita: il roll-forward non è garantito fuori dai casi previsti dalla configurazione dell’app.

Se invece l’errore compare su una macchina dove il Desktop Runtime c’è già, il problema può essere una pubblicazione corrotta o una dipendenza mancante nel profilo utente. In quel caso conviene testare l’eseguibile da una cartella locale semplice, per esempio C:\Temp\AppTest\, così da escludere permessi, percorsi lunghi o policy di sicurezza.

Se l’app passa da IIS, il controllo cambia: hosting bundle e modulo ASP.NET Core

Quando il problema appare su un sito o su un servizio web ospitato in IIS, la domanda non è solo “c’è il runtime?”, ma anche “c’è il modulo di hosting?”. In questo scenario serve il .NET Hosting Bundle, che installa runtime e componenti necessari per l’integrazione con IIS.

Un controllo rapido è verificare che il sito abbia il corretto web.config generato dalla pubblicazione e che il modulo AspNetCoreModuleV2 sia presente sul server. Se il modulo manca o la pipeline è rotta, il sito può restituire errore prima ancora che l’applicazione venga caricata.

Qui la correzione minima è installare il hosting bundle compatibile con la versione dell’app, poi riciclare l’application pool o riavviare IIS solo quanto basta per rileggere la configurazione. Se fai cambiamenti, tieni presente il blast radius: tocchi il layer di hosting, quindi possono essere impattati più siti sullo stesso server.

Checklist pratica per isolare il problema in pochi minuti

Prima di installare altro software, conviene seguire una sequenza ordinata. È veloce e riduce il rischio di introdurre confusione ulteriore.

1. Leggi il messaggio completo e annota la versione richiesta: cerca riferimenti a Microsoft.NETCore.App, Microsoft.WindowsDesktop.App o ASP.NET Core.
2. Verifica i runtime installati con dotnet --list-runtimes e controlla se la versione richiesta compare davvero.
3. Controlla l’architettura dell’app: x86, x64 o arm64. Un runtime presente ma di architettura diversa non risolve l’errore.
4. Se l’app è desktop, conferma che sia installato il Desktop Runtime, non solo il runtime base.
5. Se l’app gira dietro IIS, verifica il Hosting Bundle e il modulo AspNetCoreModuleV2.

Se uno di questi punti fallisce, hai già una diagnosi credibile. Non serve andare subito a toccare il codice o ricompilare il progetto: nella maggior parte dei casi il problema è di distribuzione, non di sviluppo.

Soluzione corretta: installare solo ciò che serve, nella versione giusta

La correzione migliore è quasi sempre una di queste tre: installare il runtime mancante, installare il Desktop Runtime oppure installare l’Hosting Bundle. La scelta dipende dal tipo di app e dal messaggio esatto. Non c’è motivo di fare un’installazione “completa” se basta un componente preciso.

Se l’app è una console o una libreria avviata da un exe framework-dependent, installa il runtime base della stessa major version. Se è desktop, aggiungi il Desktop Runtime. Se è web su IIS, usa il Hosting Bundle. In tutti i casi scarica i pacchetti solo dai canali ufficiali Microsoft, perché versioni alterate o mirror non affidabili introducono un rischio inutile.

Dopo l’installazione, rilancia l’app senza fare altri cambiamenti. Se il problema sparisce, hai chiuso il caso con una modifica minima e reversibile. Se persiste, il runtime non era l’unico problema oppure stai guardando il layer sbagliato.

Quando il runtime c’è ma l’errore resta

Se dotnet --list-runtimes mostra la versione attesa ma l’app continua a fallire, le ipotesi più probabili sono tre. La prima è che l’app sia pubblicata per un’architettura diversa. La seconda è che manchi una dipendenza nativa, per esempio un pacchetto VC++ richiesto da un componente esterno. La terza è che il pacchetto distribuito sia corrotto o incompleto.

Per falsificare rapidamente la prima ipotesi, controlla l’architettura del processo o del file eseguibile. Per la seconda, prova ad avviare l’app in un ambiente pulito dove sai che i prerequisiti sono presenti. Per la terza, confronta hash o ridistribuisci una copia nota buona del pacchetto. Se il problema si risolve con una nuova copia, il runtime non era il vero difetto.

Un’altra pista utile è il Visualizzatore eventi di Windows. In Registri di Windows > Applicazione puoi trovare il dettaglio dell’errore con un codice più preciso rispetto alla finestra mostrata all’utente. Se l’app termina subito, quel log spesso dà il nome del framework richiesto o della DLL mancante.

Il caso peggiore: app pubblicata male, runtime giusto, dipendenza sbagliata

In alcune distribuzioni il messaggio su .NET è solo la punta dell’iceberg. L’app è stata compilata con riferimenti incoerenti, oppure il publish ha escluso file necessari. In questi casi il runtime installato è corretto, ma l’eseguibile fallisce perché non trova asset, librerie native o configurazioni attese dal progetto.

Qui serve una verifica più strutturata. Se hai accesso al pacchetto di rilascio, controlla che la cartella contenga i file attesi e che il *.runtimeconfig.json punti alla versione giusta. Se il file di configurazione richiede una versione non presente, hai trovato il motivo dell’errore. Se invece la configurazione è corretta, il problema va cercato nei log applicativi o nel codice di avvio.

Per un team di supporto, la regola pratica è questa: il runtime si installa, ma il publish si corregge. Se l’errore ritorna dopo ogni reinstallazione, la distribuzione è probabilmente il vero punto da sistemare.

Buone pratiche per non ritrovarsi nello stesso guaio al prossimo rilascio

La prevenzione è semplice e vale più di un fix spot. Prima di distribuire un’app .NET su Windows, definisci chiaramente se sarà framework-dependent o self-contained. Se scegli framework-dependent, documenta la versione esatta del runtime richiesta e l’architettura. Se scegli self-contained, verifica che il pacchetto includa davvero tutto ciò che serve e che il risultato venga testato su una macchina pulita.

Per ambienti gestiti, conviene mantenere un inventario dei runtime installati sulle workstation o sui server di produzione. Non serve un sistema complesso: basta sapere quali versioni sono presenti, quali sono supportate e quali applicazioni dipendono da esse. Quando una versione entra in fine supporto, la migrazione non va rimandata fino al primo ticket utente.

Infine, nei pacchetti di distribuzione inserisci sempre un file di note tecniche con prerequisiti minimi, architettura, versione target e percorso dei log. È un dettaglio banale, ma riduce molto i tempi di diagnosi quando il problema emerge su una macchina che non controlli direttamente.

La regola pratica da tenere a mente

Se Windows chiede .NET Core, non partire dal presupposto che “manca qualcosa di generico”. Parti dal messaggio preciso, confrontalo con i runtime presenti e verifica che versione, architettura e tipo di runtime coincidano con ciò che l’app richiede. Nella maggior parte dei casi la soluzione è installare il componente giusto, non cambiare mezzo sistema.

Assunzione operativa: il problema è stato trattato come incidente di compatibilità applicativa su Windows e le verifiche suggerite sono state pensate per evitare modifiche inutili o invasive.