Errore “RD Web Access does not appear to be installed” su Windows Server 2019: guida definitiva al publish del RD Web Client HTML5

Durante la pubblicazione del client HTML5 di Remote Desktop su Windows Server 2019 può apparire l’errore “RD Web Access does not appear to be installed”. In questa guida trovi cause, diagnosi e una procedura completa e ripetibile per risolvere il problema e portare online /RDWeb/webclient.

Indice

Scenario e sintomi

Un amministratore tenta di aggiornare o distribuire il client HTML5 su un server con il ruolo RD Web Access (RDS) eseguendo:

Publish-RDWebClientPackage -Type Production -Latest

La console restituisce:

WARNING: The requested Remote Desktop web client is already installed.
ERROR: RD Web Access does not appear to be installed on the system.

Il ruolo RD Web Access risulta installato, IIS è operativo, e il modulo RDWebClientManagement è presente. Nonostante ciò, il publishing fallisce.

Perché succede

Shell sbagliata: il modulo RDWebClientManagement è progettato per Windows PowerShell 5.x. Se lo esegui da PowerShell 7/Core (pwsh.exe), alcune dipendenze (moduli IIS e RDS legacy) non vengono risolte correttamente e la rilevazione di RD Web Access fallisce.
Distribuzione RDS “non registrata”: se hai aggiunto i ruoli RDS con “Add Roles and Features” anziché usare il wizard RDS (Quick Start o Standard Deployment), la topologia potrebbe non essere registrata nel database di gestione RDS. Il modulo non “vede” RD Web Access anche se il ruolo c’è.
Stato incoerente dopo tentativi precedenti: file residui in RDWeb\WebClient, versioni multiple del modulo o un certificato del Broker non importato possono generare warning/errore e bloccare il publish.

Soluzione passo‑passo (sintesi)

#	Azione	Motivo
1	Usa Windows PowerShell 5.x (non PowerShell 7/Core).	Il modulo RDWebClientManagement non rileva RD Web Access se lanciato da PowerShell 7; passare alla shell legacy elimina l’errore.
2	Verifica che RD Web Access sia dentro a una distribuzione RDS creata dal wizard (Quick Start/Standard).	Un’installazione dei ruoli “a mano” può non registrare la topologia, impedendo al modulo di trovare RD Web Access.
3	Esegui l’installazione/publishing sul server che ospita RD Web Access.	Segue il flusso ufficiale: moduli aggiornati, download pacchetto, import del certificato del Broker, publish.
4	Se ci sono stati tentativi falliti, ripulisci e riparti.	Eviti conflitti di versione e residui in IIS e file‑system.
5	Esegui controlli supplementari su Server Manager, IIS e servizi.	Ripristini installazioni corrotte o incomplete e validi prerequisiti fondamentali.

Procedure dettagliate

Usa la shell corretta: Windows PowerShell 5.x

Apri Windows PowerShell (icona blu, non “PowerShell 7”). Su Server Core, avvia powershell.exe e non pwsh.exe.
Controlla la versione: $PSVersionTable.PSVersion Deve essere 5.x (tipicamente 5.1.x). Se non lo è, chiudi e riapri la shell corretta.

Assicurati che RD Web Access sia in un deployment RDS valido

Il modulo verifica la distribuzione attraverso i servizi RDS. Per evitare la mancata rilevazione:

Apri Server Manager → Remote Desktop Services → Overview.
Conferma che i ruoli siano distribuiti tramite wizard:
- RD Connection Broker
- RD Web Access (il server su cui stai pubblicando)
- RD Gateway (consigliato/necessario per il web client)
Se i ruoli sono stati aggiunti con “Add Roles and Features”, crea una distribuzione RDS Standard e sposta/assicura i ruoli all’interno di questa. In alternativa, registra i server nel deployment con i cmdlet RDS (da un Broker) per allineare la topologia.

Installazione e publishing puliti (sul server RD Web Access)

Esegui come amministratore in Windows PowerShell 5.x:

# Facoltativo ma consigliato: abilita TLS 1.2 per la PowerShell Gallery
[Net.ServicePointManager]::SecurityProtocol = `
    [Net.ServicePointManager]::SecurityProtocol -bor `
    [Net.SecurityProtocolType]::Tls12

Aggiorna PowerShellGet/NuGet se obsoleti

Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force
Install-Module -Name PowerShellGet -Force -AllowClobber
Set-PSRepository -Name 'PSGallery' -InstallationPolicy Trusted

Installa/aggiorna il modulo di gestione del web client

Install-Module -Name RDWebClientManagement -Force

Scarica il pacchetto del client web HTML5

Install-RDWebClientPackage

Importa il certificato pubblico del Connection Broker (formato .cer, Base-64)

Copia sul server RD Web Access il .cer del Broker e specificane il percorso:

$BrokerCertPath = 'C:\Temp\BrokerCert.cer'
Import-RDWebClientBrokerCert $BrokerCertPath

Pubblica il client (ambiente di produzione)

Publish-RDWebClientPackage -Type Production -Latest

Note importanti:

Il certificato deve corrispondere al nome FQDN del Broker che i client contatteranno. Usa un certificato pubblico con catena valida per evitare errori lato browser.
Per test: -Type Test pubblica sotto /webclient-test/ senza impattare la produzione.

Hai già provato e fallito? Pulisci prima di ripetere

Per rimuovere residui di tentativi precedenti:

# Rimuove il client da IIS (cartella e virtual dir)
Uninstall-RDWebClient

Disinstalla il modulo (se richiesto)

Uninstall-Module RDWebClientManagement -AllVersions -Force

(Facoltativo) Pulisci eventuali cartelle residue

Remove-Item 'C:\Windows\Web\RDWeb\WebClient' -Recurse -Force -ErrorAction SilentlyContinue

Riavvia IIS

iisreset

Dopo la pulizia, ripeti i passaggi di installazione/publishing.

Controlli supplementari utili

Server Manager: in RDS → Overview il ruolo RD Web Access deve risultare Installed.
IIS: verifica che esista la virtual directory /RDWeb/Pages e, dopo il publish, /RDWeb/webclient (o /webclient-test).
Servizi:
- World Wide Web Publishing (W3SVC): Running
- Remote Desktop Services (TermService): Running
- Remote Desktop Connection Broker (Tssdis, sul Broker): Running
- Remote Desktop Gateway (se usato): Running

Diagnostica rapida: comandi pronti all’uso

Esegui in Windows PowerShell 5.x con privilegi elevati.

Verifica shell e moduli

# Versione PowerShell
$PSVersionTable.PSVersion

Modulo RDWebClientManagement installato/visibile

Get-Module -ListAvailable RDWebClientManagement | `
Sort-Object Version -Descending | Select-Object -First 1 Name,Version,Path

Controlla i ruoli RDS installati

Import-Module ServerManager
Get-WindowsFeature RDS-Connection-Broker, RDS-Web-Access, RDS-Gateway | `
  Format-Table DisplayName, Name, InstallState

Verifica la presenza del client web in IIS

Test-Path 'C:\Windows\Web\RDWeb\Pages'
Test-Path 'C:\Windows\Web\RDWeb\WebClient'  # dopo la pubblicazione

Controlla la topologia (da un Connection Broker)

Import-Module RemoteDesktop
Get-RDServer
Get-RDDeploymentGateway

Se esegui questi cmdlet non dal Broker, specifica il parametro -ConnectionBroker con l’FQDN del Broker per ogni comando.

Log di sistema utili

Event Viewer → Applications and Services Logs → Microsoft → Windows → RemoteDesktopServices-RdpWebAccess → Operational
Event Viewer → Windows Logs → Application e System (IIS/W3SVC, Schannel, ecc.)

Checklist operativa (one‑page)

Apri Windows PowerShell 5.x come amministratore (powershell.exe).
Verifica che la distribuzione RDS esista (Server Manager) e che il server sia effettivamente il nodo RD Web Access.
Assicurati che il Broker sia raggiungibile e in esecuzione.
Installa/aggiorna RDWebClientManagement e scarica il pacchetto del client.
Importa il certificato pubblico del Broker (.cer Base‑64) sul server RD Web Access.
Esegui Publish-RDWebClientPackage -Type Production -Latest.
Se fallisce, Uninstall‑RDWebClient, riavvia IIS e ripeti.
Apri https://<FQDN>/RDWeb/webclient/index.html e verifica l’accesso.

FAQ ed errori ricorrenti

“RD Web Access does not appear to be installed”, ma il ruolo è presente

Quasi sempre è perché stai usando PowerShell 7/Core o perché il ruolo è fuori da una distribuzione RDS ufficiale. Passa a Windows PowerShell 5.x e verifica la topologia in Server Manager.

Il warning “already installed” appare insieme all’errore

Significa che in IIS o nel file-system ci sono artefatti di una precedente pubblicazione. Esegui Uninstall‑RDWebClient, pulisci RDWeb\WebClient se esiste, riavvia IIS e riprova.

Nessun accesso Internet dal server: come installo i moduli?

Usa un host con Internet per scaricare i moduli:

# Su un PC connesso:
Save-Module -Name RDWebClientManagement -Path C:\Temp\Modules

Copia su server (ad es. C:\Temp\Modules), poi:

$dest = "$env:ProgramFiles\WindowsPowerShell\Modules"
Copy-Item 'C:\Temp\Modules\RDWebClientManagement' $dest -Recurse
Import-Module RDWebClientManagement

Il browser mostra errore di certificato

Il certificato del Broker importato per il web client deve essere pubblico/attendibile e includere l’FQDN con cui i client raggiungono il Broker. Rigenera o sostituisci il certificato e riesegui Import‑RDWebClientBrokerCert quindi il publish.

404 su `/RDWeb/webclient` dopo il publish

Controlla che C:\Windows\Web\RDWeb\WebClient esista e che in IIS sia presente la virtual directory webclient sotto /RDWeb. In caso negativo, ripeti il publish dopo Uninstall‑RDWebClient e iisreset.

Il deployment non include RD Gateway

Il client HTML5 richiede instradamento tramite RD Gateway per le sessioni. Aggiungi RD Gateway alla distribuzione RDS, configura il certificato pubblico e assicurati che la porta HTTPS sia raggiungibile dall’esterno.

Sicurezza e migliori pratiche

Certificati pubblici per Broker e Gateway, con catena completa e SAN coerenti.
TLS 1.2 abilitato a livello di sistema e in PowerShell quando scarichi moduli.
Aggiornamenti: mantieni aggiornati Windows Server, ruolo RD Gateway e il modulo RDWebClientManagement.
Least privilege: esegui le attività con un account amministratore locale/di dominio solo quando necessario.
Firewall: consenti HTTP(S) verso RD Web Access e RD Gateway; limita sorgenti e usa WAF dove possibile.

Appendice A — Script end‑to‑end commentato

# Esegui in Windows PowerShell 5.x come amministratore

Impostazioni preliminari (TLS, repo)

[Net.ServicePointManager]::SecurityProtocol = `  [Net.ServicePointManager]::SecurityProtocol -bor`
[Net.SecurityProtocolType]::Tls12
Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force
Install-Module PowerShellGet -Force -AllowClobber
Set-PSRepository -Name PSGallery -InstallationPolicy Trusted

Modulo gestione web client

Install-Module RDWebClientManagement -Force
Import-Module RDWebClientManagement

Verifica prerequisiti principali

Import-Module ServerManager
Get-WindowsFeature RDS-Web-Access, RDS-Connection-Broker, RDS-Gateway | `
Format-Table DisplayName, Name, InstallState

Download pacchetto

Install-RDWebClientPackage

Import certificato del Broker (pubblico .cer)

$BrokerCertPath = 'C:\Temp\BrokerCert.cer'   # aggiorna il percorso
Import-RDWebClientBrokerCert -Path $BrokerCertPath

Publishing in produzione

Publish-RDWebClientPackage -Type Production -Latest

Verifica: cartella e URL

Test-Path 'C:\Windows\Web\RDWeb\WebClient'

Apri: https://<FQDN>/RDWeb/webclient/index.html

Appendice B — Esportare il certificato del Connection Broker

Il certificato richiesto è il pubblico utilizzato dal Connection Broker per l’identità pubblicata ai client. Puoi esportarlo così:

Dal Broker, apri certlm.msc → Personal → Certificates.
Individua il certificato usato dal Broker (Subject/SAN = FQDN del Broker).
Tasto destro → All Tasks → Export… → No, do not export the private key → formato Base‑64 (.CER).
Copia il .cer sul server RD Web Access ed esegui Import‑RDWebClientBrokerCert come indicato sopra.

In alternativa, con PowerShell sul Broker:

$fqdn = (Get-WmiObject Win32_ComputerSystem).DNSHostName + '.' + `
        (Get-WmiObject Win32_ComputerSystem).Domain
$cert = Get-ChildItem Cert:\LocalMachine\My | `
        Where-Object { $_.Subject -like "CN=$fqdn" } | Select-Object -First 1
$cerPath = "C:\Temp\BrokerCert.cer"
Export-Certificate -Cert $cert -FilePath $cerPath -Type CERT

Appendice C — Riparare un’installazione corrotta di RD Web Access

Se il ruolo sembra danneggiato:

# Attenzione: valuta l’impatto in produzione!
Remove-WindowsFeature RDS-Web-Access -Restart

Dopo il riavvio:

Install-WindowsFeature RDS-Web-Access -IncludeManagementTools

Quindi registra/valida la topologia nel deployment RDS e ripeti il publishing del web client.

Risultato atteso e verifica

Il comando Publish‑RDWebClientPackage completa senza errori.
La cartella C:\Windows\Web\RDWeb\WebClient esiste e contiene i file della SPA (client HTML5).
Il portale di produzione risponde su https://<FQDN>/RDWeb/webclient/index.html.
Per test, usa -Type Test e verifica su /RDWeb/webclient-test/.

Conclusioni

L’errore “RD Web Access does not appear to be installed” durante il publish del client HTML5 è quasi sempre riconducibile alla shell sbagliata (PowerShell 7 invece di Windows PowerShell 5.x) o a una distribuzione RDS non registrata correttamente. Lavorando dalla shell legacy, assicurando che RD Web Access faccia parte di un deployment RDS creato dal wizard, ripulendo residui di tentativi precedenti e importando il certificato corretto del Broker, la pubblicazione si completa in modo affidabile e ripetibile. I blocchi più ostinati si risolvono rimuovendo e reinstallando il ruolo o ricreando la topologia RDS, sempre con attenzione all’ambiente di produzione.

Riepilogo rapido

Shell: usa Windows PowerShell 5.x (powershell.exe).
Deployment: RD Web Access deve stare in un’installazione RDS fatta dal wizard.
Comandi chiave: Install‑RDWebClientPackage, Import‑RDWebClientBrokerCert, Publish‑RDWebClientPackage.
Cleanup: Uninstall‑RDWebClient, pulizia cartelle e iisreset.
URL finale: /RDWeb/webclient/ (o /webclient-test/).

Seguendo la procedura, ripristini il publish del web client HTML5 e garantisci un accesso remoto moderno, via browser, ai desktop e alle app RDS.