Códigos de salida

Documentación de la versión v0.1.0-beta.3Ver código fuente en GitHub

Traducción de la página original en inglés de OmsiLaunch 0.1.0-beta3. La página en inglés es la referencia normativa: si hay diferencias, prevalecen la página en inglés y el código.

Esta página enumera cada código de salida de proceso que pueden devolver OmsiLaunch.exe y OmsiLaunchW.exe: el contrato administrado público PublicExitCode (src\OmsiLaunch.Api\PublicControlContract.cs), los códigos del shim nativo 100..106 (tools\OmsiLaunch.Bootstrapper\OmsiLaunch.Bootstrapper.cpp y OmsiLaunch.WindowsHost.cpp) y las reglas de clasificación que CliProgram.Classify aplica a cualquier excepción que escape (tools\OmsiLaunch.Cli\Program.cs). Los llamadores deben inferir la semántica a partir del código y del envoltorio de error estructurado, nunca a partir del texto del mensaje. Los códigos de error se catalogan en errores; los comandos que producen cada código están en la referencia de la CLI.

Códigos de salida públicos (PublicExitCode)#

CódigoNombre del enumSignificadoCuándo
0SuccessEl comando se completó./version, capabilities, help, profiles, detect, /list, /recovery-status; /plan//validate con un plan ejecutable; una sesión que terminó en Completed; /silent una vez iniciado OmsiLaunchW.exe; un comando de cliente reenviado al que el propietario respondió con Ok=true; /recover cuando no había nada pendiente o la restauración se completó.
1SessionFailedUn plan no era ejecutable, o una sesión propia terminó en Failed./plan que informa NOT RUNNABLE; un inicio cuyo plan no es ejecutable (OL_E_UNSUPPORTED_BUILD, OL_E_MAP_NOT_FOUND, OL_E_ENTRYPOINT_REQUIRED, OL_E_CAPABILITY_UNAVAILABLE, OL_E_PERMANENT_PLUGIN_*, ...; OmsiLaunchW.exe además muestra el último diagnóstico OL_E_ en un cuadro de mensaje); OL_E_PLAN_NOT_RUNNABLE generado por StartSessionAsync (nueva planificación al iniciar); la sesión no llegó a Running dentro del timeout de arranque; la sesión terminó en Failed.
2InvalidArgumentsLa línea de comandos, la especificación, el perfil o los argumentos de runtime se rechazaron antes o durante el despacho.Flag o ruta desconocidos, valor faltante, valor fuera de rango; SessionProfileException (OL_E_SESSION_PROFILE_*); OL_E_SPEC_TOO_LARGE, OL_E_SPEC_INVALID, OL_E_SPEC_UNKNOWN_PROPERTY; OL_E_UNKNOWN_SETTING, OL_E_SETTING_NOT_WRITABLE, OL_E_INVALID_SETTING_VALUE; OL_E_ITX_PROFILE_REQUIRED; OL_E_RUNTIME_OPERATION_UNKNOWN y OL_E_RUNTIME_ARGUMENT_REQUIRED (localmente o devueltos por el propietario); uso impreso para un comando que no se puede despachar; cualquier ArgumentException, FormatException, InvalidDataException u OverflowException.
3UnsupportedProfileLa plataforma o el build de OMSI no es compatible.Una excepción que escapa cuyo código empieza con OL_E_UNSUPPORTED_ (OL_E_UNSUPPORTED_BUILD, OL_E_UNSUPPORTED_OPERATING_SYSTEM, OL_E_UNSUPPORTED_OS_ARCHITECTURE). Tenga en cuenta que las mismas condiciones detectadas durante la planificación hacen que el plan no sea ejecutable y devuelven 1 en su lugar.
4NoActiveSessionUn comando de cliente no encontró ningún propietario.session status, session stop, events read, events watch o una operación de runtime reenviada cuando el endpoint de control local de esta instalación no responde (OL_E_NO_ACTIVE_SESSION).
5RuntimeUnavailableUn timeout escapó como excepción.Cualquier TimeoutException (OL_E_TIMEOUT cuando el mensaje no incluye ningún código; de lo contrario, el código incrustado, como OL_E_RUNTIME_REQUEST_TIMEOUT). El propietario responde a los timeouts de cliente reenviados con Ok=false, que devuelven 7, no 5.
6NotFoundNo se encontró un archivo o directorio.FileNotFoundException / DirectoryNotFoundException (OL_E_NOT_FOUND de forma predeterminada), por ejemplo OL_E_SPEC_NOT_FOUND, OL_E_ITX_PROFILE_MISSING cuando se genera como excepción, un directorio de instalación faltante durante /list.
7OperationRejectedEl comando era válido pero se rechazó, o un comando reenviado falló en el propietario.OL_E_SESSION_ALREADY_ACTIVE, OL_E_INSTALLATION_BUSY, OL_E_RUNTIME_INSTALLATION_INCOMPLETE, OL_E_WINDOWS_HOST_MISSING, OL_E_WINDOWS_HOST_START_FAILED, OL_E_CANCELLED; cada respuesta de control Ok=false distinta de los dos códigos de argumento (OL_E_CONTROL_*, OL_E_RUNTIME_*, OL_E_SESSION_NOT_RUNNING); cualquier otra excepción que escape con un código OL_E_ que no esté clasificado en otro lugar (OL_E_PERMANENT_PLUGIN_HASH_MISMATCH, OL_E_PERMANENT_PLUGIN_MISSING, OL_E_RELEASE_MANIFEST_INVALID, OL_E_PROCESS_*, ...).
8TransactionRecoveryFailedNo se pudo restaurar una transacción persistente./recover cuando el journal estaba pendiente y sigue pendiente; cualquier excepción que escape cuyo código empiece con OL_E_RECOVERY_ o sea OL_E_RESTORE_FAILED (por ejemplo OL_E_RECOVERY_BACKUP_CORRUPT, OL_E_RECOVERY_ABSENT_OWNERSHIP_MISMATCH durante la propia restauración de una sesión).
10InternalErrorUna excepción inesperada sin código OL_E_.Se informa como OL_E_INTERNAL con la categoría internal; el mensaje es el texto de la excepción.

El código 9 no está asignado.

Códigos de salida del shim nativo#

Los devuelven OmsiLaunch.exe / OmsiLaunchW.exe antes de que se ejecute el controlador administrado. No se superponen con PublicExitCode, de modo que un llamador puede distinguir un fallo de arranque del host de un resultado del controlador. OmsiLaunchW.exe además muestra OmsiLaunch could not start the .NET host (code N). en un cuadro de mensaje.

CódigoSignificadoCausa
100No se pudo resolver la ruta del ejecutableGetModuleFileNameW falló.
101No se pudo dividir la línea de comandos en tokensCommandLineToArgvW devolvió null.
102Falló la búsqueda de la ubicación de hostfxrFalló la consulta de tamaño de get_hostfxr_path: no hay ningún runtime de .NET correspondiente instalado (se requiere el runtime .NET 6 x64).
103No se pudo obtener la ruta de hostfxrFalló la segunda llamada a get_hostfxr_path.
104No se pudo cargar la biblioteca hostfxrFalló LoadLibraryW sobre el hostfxr.dll resuelto.
105Faltan exportaciones requeridas de hostfxrNo se encontró hostfxr_initialize_for_dotnet_command_line, hostfxr_run_app o hostfxr_close.
106No se pudo inicializar el host administradohostfxr_initialize_for_dotnet_command_line falló para OmsiLaunch.Controller.dll (falta OmsiLaunch.Controller.runtimeconfig.json, falta Microsoft.WindowsDesktop.App 6.0 x64 o el paquete está dañado).

Reglas de clasificación (CliProgram.Classify)#

Cada excepción que escapa de CliProgram.RunAsync se convierte en un envoltorio de error (CliInput.WriteError) y en un código de salida mediante CliProgram.ReportFailure, que llama a Classify. Los fallos de análisis se tratan de la misma manera antes del despacho (salida 2). Las reglas se aplican en este orden:

  1. Se extrae el primer token OL_E_ del mensaje de la excepción (ExtractCode): el código es la secuencia máxima de letras ASCII, dígitos y _ que empieza en OL_E_. Los códigos se exponen literalmente en error.code.
  2. SessionProfileException → su propio Code, categoría invalid_argument, salida 2.
  3. ArgumentException, FormatException, InvalidDataException, OverflowException → código extraído u OL_E_INVALID_ARGUMENT, categoría invalid_argument, salida 2.
  4. FileNotFoundException, DirectoryNotFoundException → código extraído u OL_E_NOT_FOUND, categoría not_found, salida 6.
  5. TimeoutException → código extraído u OL_E_TIMEOUT, categoría runtime, salida 5.
  6. OperationCanceledException → OL_E_CANCELLED, categoría session, salida 7.
  7. En los demás casos, cuando se extrajo un código:
    • empieza con OL_E_RECOVERY_ o es igual a OL_E_RESTORE_FAILED → categoría transaction, salida 8;
    • OL_E_INSTALLATION_BUSY, OL_E_SESSION_ALREADY_ACTIVE → categoría session, salida 7;
    • OL_E_PLAN_NOT_RUNNABLE → categoría session, salida 1;
    • OL_E_UNKNOWN_SETTING, OL_E_SETTING_NOT_WRITABLE, OL_E_ITX_PROFILE_REQUIRED → categoría invalid_argument, salida 2;
    • empieza con OL_E_UNSUPPORTED_ → categoría unsupported_profile, salida 3;
    • cualquier otro código → categoría runtime para InvalidOperationException e IOException; en otro caso, internal; salida 7.
  8. Ningún código → OL_E_INTERNAL, categoría internal, salida 10.

Las respuestas de cliente reenviadas no pasan por Classify: CliProgram.ReportForwarded devuelve 4 cuando no hay endpoint, 2 para OL_E_RUNTIME_OPERATION_UNKNOWN / OL_E_RUNTIME_ARGUMENT_REQUIRED, 7 para cualquier otra respuesta Ok=false y 0 para Ok=true.

Recomendaciones para scripts#

  • Trate 0 como éxito y todo lo demás como fallo; bifurque según el código numérico y luego según error.code del envoltorio --json.
  • Un inicio de sesión regresa solo después de que la sesión terminó y sus archivos se restauraron; 1 significa que la transacción se ejecutó pero OMSI falló o el plan se rechazó, no que quedaron archivos modificados (/recovery-status informa un journal residual).
  • 100..106 significan que el paquete o el runtime de .NET está dañado; consulte instalación y empaquetado.