Riferimento di OmsiLaunchW.exe

Documentazione della versione v0.1.0-beta.3Vedi il sorgente su GitHub

Traduzione della pagina originale in inglese di OmsiLaunch 0.1.0-beta3. La pagina inglese è normativa: in caso di differenze prevalgono la pagina inglese e il codice.

OmsiLaunchW.exe è l'host del controller OmsiLaunch per il sottosistema Windows (GUI). Accetta la stessa riga di comando di OmsiLaunch.exe ed esegue lo stesso codice del controller (OmsiLaunch.Controller.dll). L'unica differenza è il modo in cui comunica l'esito: non c'è alcuna finestra della console, gli errori vengono mostrati come finestre di messaggio e una sessione in esecuzione è visibile solo tramite la sua icona nell'area di notifica.

Fonti autorevoli: tools\OmsiLaunch.Bootstrapper\OmsiLaunch.WindowsHost.cpp (lo shim nativo), tools\OmsiLaunch.Cli\WindowsHost.cs (WindowsHost, SessionTrayIndicator) e tools\OmsiLaunch.Cli\Program.cs (CliProgram.RunAsync, OwnerSession.RunAsync, CliInput.Write*).

Confronto tra OmsiLaunch.exe e OmsiLaunchW.exe#

Come si avvia#

1. Lo shim risolve il proprio percorso (GetModuleFileNameW) e si aspetta OmsiLaunch.Controller.dll nella stessa directory.
2. Suddivide la riga di comando in token (CommandLineToArgvW) e imposta OMSILAUNCH_WINDOWS_HOST=1.
3. Individua hostfxr tramite il nethost.dll incluso nel pacchetto, lo carica, inizializza il controller con gli argomenti (il percorso del controller non fa parte dell'elenco di argomenti visto dal parser della CLI) e lo esegue.
4. Lo shim restituisce invariato il codice di uscita del controller.

Se uno qualsiasi dei passaggi precedenti all'esecuzione del controller non riesce, lo shim mostra una finestra di messaggio intitolata OmsiLaunch con il testo OmsiLaunch could not start the .NET host (code N). ed esce con quel codice:

OmsiLaunch.exe usa la stessa tabella ma non stampa nulla. Queste finestre di dialogo non sono state prodotte a runtime (vedere stato della validazione a runtime).

Avvio#

Avvio diretto, da un collegamento, da uno script o da un altro programma:

OmsiLaunchW.exe /new /map:maps\Grundorf\global.cfg /entrypoint-index:1

OmsiLaunchW.exe /predefined-profile:<PROFILE_NAME> /predefined-profile-index:1 /new

Tramite OmsiLaunch.exe con /silent:

OmsiLaunch.exe /silent /new /map:maps\Grundorf\global.cfg /entrypoint-index:1

Collocare gli eseguibili nell'installazione di OMSI 2 (la struttura del pacchetto, vedere pacchetti); senza argomento di installazione, l'installazione è la directory che contiene l'eseguibile. Un'installazione esplicita viene passata come primo argomento, come con OmsiLaunch.exe (OmsiLaunchW.exe "<OMSI_PATH>" /new ...).

Poiché si tratta di un programma GUI, cmd.exe ed Esplora risorse non ne attendono la conclusione. Per attenderla e leggere il codice di uscita da uno script, usare start /wait OmsiLaunchW.exe ... in cmd.exe oppure Start-Process -Wait -PassThru in PowerShell:

$p = Start-Process -FilePath .\OmsiLaunchW.exe -ArgumentList '/new','/map:maps\Grundorf\global.cfg','/entrypoint-index:1' -Wait -PassThru
$p.ExitCode

Delega con /silent#

OmsiLaunch.exe ... /silent (o --silent), quando non è già in esecuzione sotto OmsiLaunchW.exe, esegue le operazioni seguenti (CliProgram.RunAsync, CliProgram.SilentDelegation):

1. Cerca OmsiLaunchW.exe nella directory di OmsiLaunch.exe. Se manca: OL_E_WINDOWS_HOST_MISSING, uscita 7.
2. Avvia OmsiLaunchW.exe tramite ShellExecute (UseShellExecute = true) con la directory corrente e tutti gli argomenti tranne /silent/--silent, nell'ordine originale. ShellExecute non passa gli handle del chiamante al nuovo processo, quindi un chiamante che cattura l'output di OmsiLaunch.exe /silent non resta bloccato per tutta la durata della sessione (chiusura di runtime BUG-03). Se non viene restituito alcun processo: OL_E_WINDOWS_HOST_START_FAILED, uscita 7.
3. Scrive l'envelope silent ed esce immediatamente con 0:

{"ok": true, "command": "silent", "protocol_version": "0.1", "result": {"delegated": true, "host_process_id": 12345}}

L'uscita 0 significa soltanto che OmsiLaunchW.exe è stato avviato. L'esito della sessione (errori di pianificazione, un owner già attivo, un avvio non riuscito) viene comunicato da OmsiLaunchW.exe con le proprie finestre di dialogo e diagnostiche, e da quel momento i due processi sono indipendenti: OmsiLaunch.exe è terminato e OmsiLaunchW.exe è il proprietario della sessione (owner). Usare OmsiLaunch.exe session status per vedere la sessione.

/silent viene applicato prima di ogni altro comando, quindi anche OmsiLaunch.exe /silent session status esegue session status all'interno di OmsiLaunchW.exe, dove il suo output viene soppresso. Usare /silent solo per gli avvii.

Effetto di ogni comando sotto OmsiLaunchW.exe#

Finestre di dialogo di errore#

Ogni errore che OmsiLaunch.exe stamperebbe viene mostrato anche come finestra di messaggio modale (WindowsHost.ShowFailure), anche quando è indicato --json:

Title:  OmsiLaunch            (error icon)

<message>

Code: OL_E_<CODE>

See .omsilaunch\diagnostics for details.

<message> è il messaggio di errore oppure, per un errore della sessione, il messaggio dell'ultima diagnostica OL_E_. Limitazione nota: per un errore segnalato dal plugin, il messaggio è il payload di errore grezzo del plugin (ad esempio {"name":"world.failed",...}); la riga Code: è corretta (vedere limitazioni note). La finestra di dialogo è modale e il processo esce dopo la sua chiusura. Evidenza di runtime: errore di argomento, nessuna sessione attiva ed errore prima del gameplay (chiusura di runtime T04).

Sessione, area di notifica e uscita#

Una sessione di proprietà di OmsiLaunchW.exe si comporta esattamente come una di proprietà di OmsiLaunch.exe (vedere ciclo di vita della sessione):

• L'icona nell'area di notifica compare non appena la sessione è stata avviata, prima che OMSI raggiunga il gameplay, a meno che in un file /spec non sia impostato Presentation.SuppressTrayIcon. Con SuppressTrayIcon non c'è alcuna superficie visibile; arrestare la sessione con OmsiLaunch.exe session stop o chiudendo OMSI.
• La sessione termina quando OMSI esce, quando End session viene confermato nell'area di notifica, quando un client invia session stop o quando trascorre il tempo di /observe-seconds. OmsiLaunch quindi termina OMSI se è ancora in esecuzione, ripristina ogni file che ha modificato, rilascia il lease dell'installazione, rimuove l'icona dall'area di notifica ed esce.
• Se lo stesso OmsiLaunchW.exe viene terminato forzatamente, il successivo avvio di OmsiLaunch per quell'installazione recupera la transazione in sospeso (vedere transazioni e recupero).

Avvio rapido#

1. Installare il pacchetto nella directory di OMSI 2 (installazione).
2. Creare un collegamento a OmsiLaunchW.exe con gli argomenti della sessione, ad esempio /new /map:maps\Grundorf\global.cfg /entrypoint-index:1.
3. Avviarlo. OMSI si avvia senza finestra della console; l'icona di OmsiLaunch compare nell'area di notifica.
4. Fare clic con il pulsante destro sull'icona → Status per vedere la sessione, oppure End session → End session per terminarla.
5. Se qualcosa va storto, la finestra di dialogo mostra il codice di errore; i dettagli si trovano in <OMSI_PATH>\.omsilaunch\diagnostics.