Dokumentacja OmsiLaunchW.exe

Dokumentacja wersji v0.1.0-beta.3Zobacz źródło na GitHubie

Tłumaczenie oryginalnej strony w języku angielskim dla OmsiLaunch 0.1.0-beta3. Wiążąca jest strona angielska: w razie rozbieżności obowiązują strona angielska i kod.

OmsiLaunchW.exe to host kontrolera OmsiLaunch działający w podsystemie Windows (GUI). Przyjmuje ten sam wiersz poleceń co OmsiLaunch.exe i wykonuje ten sam kod kontrolera (OmsiLaunch.Controller.dll). Jedyna różnica dotyczy sposobu raportowania: nie ma okna konsoli, błędy są pokazywane w oknach komunikatu, a działająca sesja jest widoczna wyłącznie dzięki swojej ikonie w obszarze powiadomień.

Źródła wiarygodne: tools\OmsiLaunch.Bootstrapper\OmsiLaunch.WindowsHost.cpp (natywny shim), tools\OmsiLaunch.Cli\WindowsHost.cs (WindowsHost, SessionTrayIndicator) i tools\OmsiLaunch.Cli\Program.cs (CliProgram.RunAsync, OwnerSession.RunAsync, CliInput.Write*).

Porównanie OmsiLaunch.exe i OmsiLaunchW.exe#

Jak się uruchamia#

1. Shim ustala własną ścieżkę (GetModuleFileNameW) i oczekuje OmsiLaunch.Controller.dll w tym samym katalogu.
2. Dzieli wiersz poleceń na tokeny (CommandLineToArgvW) i ustawia OMSILAUNCH_WINDOWS_HOST=1.
3. Lokalizuje hostfxr za pomocą dołączonego do pakietu nethost.dll, ładuje go, inicjalizuje kontroler z argumentami (ścieżka kontrolera nie jest częścią listy argumentów widzianej przez parser CLI) i uruchamia go.
4. Shim zwraca kod wyjścia kontrolera bez zmian.

Jeśli którykolwiek krok przed uruchomieniem kontrolera nie powiedzie się, shim pokazuje okno komunikatu z tytułem OmsiLaunch i tekstem OmsiLaunch could not start the .NET host (code N). (nie można uruchomić hosta .NET, kod N), a następnie kończy działanie z tym kodem:

OmsiLaunch.exe używa tej samej tabeli, ale niczego nie wypisuje. Te okna dialogowe nie zostały wywołane w czasie działania (zobacz stan weryfikacji w runtime).

Uruchamianie#

Uruchomienie bezpośrednie – ze skrótu, skryptu lub innego programu:

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

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

Za pośrednictwem OmsiLaunch.exe z /silent:

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

Pliki wykonywalne należy umieścić w instalacji OMSI 2 (układ pakietu, zobacz pakowanie); bez argumentu instalacji instalacją jest katalog zawierający plik wykonywalny. Jawnie wskazaną instalację przekazuje się jako pierwszy argument, tak jak w przypadku OmsiLaunch.exe (OmsiLaunchW.exe "<OMSI_PATH>" /new ...).

Ponieważ jest to program GUI, cmd.exe i Eksplorator nie czekają na jego zakończenie. Aby w skrypcie poczekać na zakończenie i odczytać kod wyjścia, należy użyć start /wait OmsiLaunchW.exe ... w cmd.exe lub Start-Process -Wait -PassThru w PowerShell:

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

Delegowanie /silent#

OmsiLaunch.exe ... /silent (lub --silent), jeśli nie działa już pod OmsiLaunchW.exe, wykonuje następujące kroki (CliProgram.RunAsync, CliProgram.SilentDelegation):

1. Szuka OmsiLaunchW.exe w katalogu OmsiLaunch.exe. Jeśli go brakuje: OL_E_WINDOWS_HOST_MISSING, wyjście 7.
2. Uruchamia OmsiLaunchW.exe przez ShellExecute (UseShellExecute = true) z bieżącym katalogiem i wszystkimi argumentami oprócz /silent/--silent, w oryginalnej kolejności. ShellExecute nie przekazuje uchwytów wywołującego do nowego procesu, więc kod wywołujący, który przechwytuje wyjście OmsiLaunch.exe /silent, nie jest blokowany przez cały czas trwania sesji (zamknięcie runtime BUG-03). Jeśli nie zostanie zwrócony żaden proces: OL_E_WINDOWS_HOST_START_FAILED, wyjście 7.
3. Zapisuje kopertę silent i natychmiast kończy działanie z kodem 0:

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

Wyjście 0 oznacza jedynie, że OmsiLaunchW.exe został uruchomiony. Wynik sesji (błędy planowania, już aktywny właściciel, nieudany start) zgłasza OmsiLaunchW.exe we własnych oknach dialogowych i komunikatach diagnostycznych, a oba procesy są od tej chwili niezależne: OmsiLaunch.exe zakończył działanie, a OmsiLaunchW.exe jest właścicielem sesji. Do podglądu sesji służy OmsiLaunch.exe session status.

/silent jest stosowane przed każdym innym poleceniem, więc OmsiLaunch.exe /silent session status również wykonuje session status wewnątrz OmsiLaunchW.exe, gdzie jego wyjście jest pomijane. /silent należy używać wyłącznie do uruchamiania sesji.

Działanie poszczególnych poleceń pod OmsiLaunchW.exe#

Okna dialogowe błędów#

Każdy błąd, który OmsiLaunch.exe by wypisał, jest również pokazywany jako modalne okno komunikatu (WindowsHost.ShowFailure), nawet gdy podano --json:

Title:  OmsiLaunch            (error icon)

<message>

Code: OL_E_<CODE>

See .omsilaunch\diagnostics for details.

<message> to komunikat błędu, a w przypadku błędu sesji – komunikat ostatniego komunikatu diagnostycznego OL_E_. Znane ograniczenie: dla błędu zgłoszonego przez wtyczkę komunikatem jest surowy ładunek błędu wtyczki (na przykład {"name":"world.failed",...}); wiersz Code: jest poprawny (zobacz znane ograniczenia). Okno dialogowe jest modalne, a proces kończy działanie po jego zamknięciu. Dowody z runtime: błąd argumentu, brak aktywnej sesji oraz błąd przed rozpoczęciem rozgrywki (zamknięcie runtime T04).

Sesja, obszar powiadomień i zakończenie#

Sesja, której właścicielem jest OmsiLaunchW.exe, zachowuje się dokładnie tak samo jak sesja należąca do OmsiLaunch.exe (zobacz cykl życia sesji):

• Ikona w obszarze powiadomień pojawia się, gdy tylko sesja zostanie uruchomiona, zanim OMSI osiągnie rozgrywkę, chyba że w pliku /spec ustawiono Presentation.SuppressTrayIcon. Przy SuppressTrayIcon nie ma żadnego widocznego elementu; sesję zatrzymuje się poleceniem OmsiLaunch.exe session stop lub przez zamknięcie OMSI.
• Sesja kończy się, gdy OMSI zakończy działanie, gdy w obszarze powiadomień zostanie potwierdzone End session (Zakończ sesję), gdy klient wyśle session stop lub gdy upłynie czas /observe-seconds. OmsiLaunch kończy wtedy OMSI, jeśli nadal działa, przywraca każdy zmieniony przez siebie plik, zwalnia dzierżawę instalacji, usuwa ikonę z obszaru powiadomień i kończy działanie.
• Jeśli sam proces OmsiLaunchW.exe zostanie zabity, następne uruchomienie OmsiLaunch dla tej instalacji odzyskuje oczekującą transakcję (zobacz transakcje i odzyskiwanie).

Szybki start#

1. Zainstaluj pakiet w katalogu OMSI 2 (instalacja).
2. Utwórz skrót do OmsiLaunchW.exe z argumentami sesji, na przykład /new /map:maps\Grundorf\global.cfg /entrypoint-index:1.
3. Uruchom go. OMSI startuje bez okna konsoli; ikona OmsiLaunch pojawia się w obszarze powiadomień.
4. Kliknij ikonę prawym przyciskiem myszy → Status (Stan), aby zobaczyć sesję, lub End session → End session (Zakończ sesję → Zakończ sesję), aby ją zakończyć.
5. Jeśli coś pójdzie nie tak, okno dialogowe pokazuje kod błędu; szczegóły znajdują się w <OMSI_PATH>\.omsilaunch\diagnostics.