Add comments to host error_codes.h (#107775)

Include basic descriptions of host error codes in `error_codes.h`. Slight clean-up (and some renames) of some error codes - these are all failures with no expected programmatic recovery, so the value change should be fine:
- Merged `LibHostCurExeFindFailure` with `CurrentHostFindFailure`
- Merged `LibHostSdkFindFailure` with `SdkResolveFailure`
- Merged `LibHostUnknownCommand` with `LibHostInvalidArgs`

src/installer/tests/HostActivation.Tests/NativeHosting/HostContext.cs

@@ -54,7 +54,7 @@ public enum CommandLine
         private const int InvalidArgFailure = unchecked((int)0x80008081);
         private const int HostInvalidState = unchecked((int)0x800080a3);
         private const int HostPropertyNotFound = unchecked((int)0x800080a4);
-        private const int CoreHostIncompatibleConfig = unchecked((int)0x800080a5);
+        private const int HostIncompatibleConfig = unchecked((int)0x800080a5);
         private const int Success_HostAlreadyInitialized = 0x00000001;
         private const int Success_DifferentRuntimeProperties = 0x00000002;
 
@@ -420,14 +420,14 @@ public void CompatibilityCheck_Frameworks(string scenario, FrameworkCompatibilit
                 else
                 {
                     result.Should().Fail()
-                        .And.FailToInitializeContextForConfig(CoreHostIncompatibleConfig)
+                        .And.FailToInitializeContextForConfig(HostIncompatibleConfig)
                         .And.HaveStdErrMatching($".*The specified framework '{frameworkName}', version '{version}', apply_patches=[0-1], version_compatibility_range=[^ ]* is incompatible with the previously loaded version '{SharedTestState.NetCoreAppVersion}'.*");
                 }
             }
             else
             {
                 result.Should().Fail()
-                    .And.FailToInitializeContextForConfig(CoreHostIncompatibleConfig)
+                    .And.FailToInitializeContextForConfig(HostIncompatibleConfig)
                     .And.HaveStdErrContaining($"The specified framework '{frameworkName}' is not present in the previously loaded runtime");
             }
         }

src/native/corehost/corehost.cpp

@@ -118,7 +118,7 @@ int exe_start(const int argc, const pal::char_t* argv[])
     if (!pal::get_own_executable_path(&host_path) || !pal::realpath(&host_path))
     {
         trace::error(_X("Failed to resolve full path of the current executable [%s]"), host_path.c_str());
-        return StatusCode::CoreHostCurHostFindFailure;
+        return StatusCode::CurrentHostFindFailure;
     }
 
     pal::string_t app_path;
@@ -153,7 +153,7 @@ int exe_start(const int argc, const pal::char_t* argv[])
     else if (!pal::fullpath(&app_path))
     {
         trace::error(_X("The application to execute does not exist: '%s'."), app_path.c_str());
-        return StatusCode::LibHostAppRootFindFailure;
+        return StatusCode::AppPathFindFailure;
     }
 
     app_root.assign(get_directory(app_path));

src/native/corehost/error_codes.h

@@ -8,50 +8,50 @@
 enum StatusCode
 {
     // Success
-    Success                             = 0,
-    Success_HostAlreadyInitialized      = 0x00000001,
-    Success_DifferentRuntimeProperties  = 0x00000002,
+    Success                             = 0,            // Operation was successful
+    Success_HostAlreadyInitialized      = 0x00000001,   // Initialization was successful, but another host context is already initialized
+    Success_DifferentRuntimeProperties  = 0x00000002,   // Initialization was successful, but another host context is already initialized and the requested context specified runtime properties which are not the same
 
     // Failure
-    InvalidArgFailure                   = 0x80008081,
-    CoreHostLibLoadFailure              = 0x80008082,
-    CoreHostLibMissingFailure           = 0x80008083,
-    CoreHostEntryPointFailure           = 0x80008084,
-    CoreHostCurHostFindFailure          = 0x80008085,
+    InvalidArgFailure                   = 0x80008081,   // One or more arguments are invalid
+    CoreHostLibLoadFailure              = 0x80008082,   // Failed to load a hosting component
+    CoreHostLibMissingFailure           = 0x80008083,   // One of the hosting components is missing
+    CoreHostEntryPointFailure           = 0x80008084,   // One of the hosting components is missing a required entry point
+    CurrentHostFindFailure              = 0x80008085,   // Failed to get the path of the current hosting component and determine the .NET installation location
     // unused                           = 0x80008086,
-    CoreClrResolveFailure               = 0x80008087,
-    CoreClrBindFailure                  = 0x80008088,
-    CoreClrInitFailure                  = 0x80008089,
-    CoreClrExeFailure                   = 0x8000808a,
-    ResolverInitFailure                 = 0x8000808b,
-    ResolverResolveFailure              = 0x8000808c,
-    LibHostCurExeFindFailure            = 0x8000808d,
-    LibHostInitFailure                  = 0x8000808e,
+    CoreClrResolveFailure               = 0x80008087,   // The `coreclr` library could not be found
+    CoreClrBindFailure                  = 0x80008088,   // Failed to load the `coreclr` library or finding one of the required entry points
+    CoreClrInitFailure                  = 0x80008089,   // Call to `coreclr_initialize` failed
+    CoreClrExeFailure                   = 0x8000808a,   // Call to `coreclr_execute_assembly` failed
+    ResolverInitFailure                 = 0x8000808b,   // Initialization of the `hostpolicy` dependency resolver failed
+    ResolverResolveFailure              = 0x8000808c,   // Resolution of dependencies in `hostpolicy` failed
+    // unused                           = 0x8000808d,
+    LibHostInitFailure                  = 0x8000808e,   // Initialization of the `hostpolicy` library failed
     // unused                           = 0x8000808f,
-    LibHostExecModeFailure              = 0x80008090,
-    LibHostSdkFindFailure               = 0x80008091,
-    LibHostInvalidArgs                  = 0x80008092,
-    InvalidConfigFile                   = 0x80008093,
-    AppArgNotRunnable                   = 0x80008094,
-    AppHostExeNotBoundFailure           = 0x80008095,
-    FrameworkMissingFailure             = 0x80008096,
-    HostApiFailed                       = 0x80008097,
-    HostApiBufferTooSmall               = 0x80008098,
-    LibHostUnknownCommand               = 0x80008099,
-    LibHostAppRootFindFailure           = 0x8000809a,
-    SdkResolverResolveFailure           = 0x8000809b,
-    FrameworkCompatFailure              = 0x8000809c,
-    FrameworkCompatRetry                = 0x8000809d,
+    // unused                           = 0x80008090,
+    // unused                           = 0x80008091,
+    LibHostInvalidArgs                  = 0x80008092,   // Arguments to `hostpolicy` are invalid
+    InvalidConfigFile                   = 0x80008093,   // The `.runtimeconfig.json` file is invalid
+    AppArgNotRunnable                   = 0x80008094,   // [internal usage only]
+    AppHostExeNotBoundFailure           = 0x80008095,   // `apphost` failed to determine which application to run
+    FrameworkMissingFailure             = 0x80008096,   // Failed to find a compatible framework version
+    HostApiFailed                       = 0x80008097,   // Host command failed
+    HostApiBufferTooSmall               = 0x80008098,   // Buffer provided to a host API is too small to fit the requested value
+    // unused                           = 0x80008099,
+    AppPathFindFailure                  = 0x8000809a,   // Application path imprinted in `apphost` doesn't exist
+    SdkResolveFailure                   = 0x8000809b,   // Failed to find the requested SDK
+    FrameworkCompatFailure              = 0x8000809c,   // Application has multiple references to the same framework which are not compatible
+    FrameworkCompatRetry                = 0x8000809d,   // [internal usage only]
     // unused                           = 0x8000809e,
-    BundleExtractionFailure             = 0x8000809f,
-    BundleExtractionIOError             = 0x800080a0,
-    LibHostDuplicateProperty            = 0x800080a1,
-    HostApiUnsupportedVersion           = 0x800080a2,
-    HostInvalidState                    = 0x800080a3,
-    HostPropertyNotFound                = 0x800080a4,
-    CoreHostIncompatibleConfig          = 0x800080a5,
-    HostApiUnsupportedScenario          = 0x800080a6,
-    HostFeatureDisabled                 = 0x800080a7,
+    BundleExtractionFailure             = 0x8000809f,   // Error extracting single-file bundle
+    BundleExtractionIOError             = 0x800080a0,   // Error reading or writing files during single-file bundle extraction
+    LibHostDuplicateProperty            = 0x800080a1,   // The application's `.runtimeconfig.json` contains a runtime property which is produced by the hosting layer
+    HostApiUnsupportedVersion           = 0x800080a2,   // Feature which requires certain version of the hosting layer was used on a version which doesn't support it
+    HostInvalidState                    = 0x800080a3,   // Current state is incompatible with the requested operation
+    HostPropertyNotFound                = 0x800080a4,   // Property requested by `hostfxr_get_runtime_property_value` doesn't exist
+    HostIncompatibleConfig              = 0x800080a5,   // Host configuration is incompatible with existing host context
+    HostApiUnsupportedScenario          = 0x800080a6,   // Hosting API does not support the requested scenario
+    HostFeatureDisabled                 = 0x800080a7,   // Support for a requested feature is disabled
 };
 
 #define STATUS_CODE_SUCCEEDED(status_code) ((static_cast<int>(static_cast<StatusCode>(status_code))) >= 0)

src/native/corehost/fxr/fx_muxer.cpp

@@ -666,13 +666,13 @@ namespace
         {
             // Framework dependent apps always know their frameworks
             if (!fx_resolver_t::is_config_compatible_with_frameworks(app_config, existing_context->fx_versions_by_name))
-                return StatusCode::CoreHostIncompatibleConfig;
+                return StatusCode::HostIncompatibleConfig;
         }
         else if (!existing_context->included_fx_versions_by_name.empty())
         {
             // Self-contained apps can include information about their frameworks in `includedFrameworks` property in runtime config
             if (!fx_resolver_t::is_config_compatible_with_frameworks(app_config, existing_context->included_fx_versions_by_name))
-                return StatusCode::CoreHostIncompatibleConfig;
+                return StatusCode::HostIncompatibleConfig;
         }
         else
         {
@@ -1067,7 +1067,7 @@ int fx_muxer_t::handle_cli(
             app_candidate.c_str());
         resolver.print_resolution_error(host_info.dotnet_root, _X("      "));
 
-        return StatusCode::LibHostSdkFindFailure;
+        return StatusCode::SdkResolveFailure;
     }
 
     append_path(&sdk_dotnet, SDK_DOTNET_DLL);

src/native/corehost/fxr/hostfxr.cpp

@@ -230,7 +230,7 @@ typedef void (HOSTFXR_CALLTYPE *hostfxr_resolve_sdk2_result_fn)(
 //
 // Return value:
 //   0 on success, otherwise failure
-//   0x8000809b - SDK could not be resolved (SdkResolverResolveFailure)
+//   0x8000809b - SDK could not be resolved (SdkResolveFailure)
 //
 // String encoding:
 //   Windows     - UTF-16 (pal::char_t is 2 byte wchar_t)
@@ -289,7 +289,7 @@ SHARED_API int32_t HOSTFXR_CALLTYPE hostfxr_resolve_sdk2(
 
     return !resolved_sdk_dir.empty()
         ? StatusCode::Success
-        : StatusCode::SdkResolverResolveFailure;
+        : StatusCode::SdkResolveFailure;
 }
 
 
@@ -550,21 +550,21 @@ namespace
             if (!pal::get_own_executable_path(&startup_info.host_path) || !pal::fullpath(&startup_info.host_path))
             {
                 trace::error(_X("Failed to resolve full path of the current host [%s]"), startup_info.host_path.c_str());
-                return StatusCode::CoreHostCurHostFindFailure;
+                return StatusCode::CurrentHostFindFailure;
             }
         }
 
         if (startup_info.dotnet_root.empty())
         {
             pal::string_t mod_path;
             if (!pal::get_method_module_path(&mod_path, (void*)&hostfxr_set_error_writer))
-                return StatusCode::CoreHostCurHostFindFailure;
+                return StatusCode::CurrentHostFindFailure;
 
             startup_info.dotnet_root = get_dotnet_root_from_fxr_path(mod_path);
             if (!pal::fullpath(&startup_info.dotnet_root))
             {
                 trace::error(_X("Failed to resolve full path of dotnet root [%s]"), startup_info.dotnet_root.c_str());
-                return StatusCode::CoreHostCurHostFindFailure;
+                return StatusCode::CurrentHostFindFailure;
             }
         }
 

src/native/corehost/fxr_resolver.h

@@ -37,7 +37,7 @@ int load_fxr_and_get_delegate(hostfxr_delegate_type type, THostPathToConfigCallb
     if (!pal::get_own_module_path(&host_path) || !pal::fullpath(&host_path))
     {
         trace::error(_X("Failed to resolve full path of the current host module [%s]"), host_path.c_str());
-        return StatusCode::CoreHostCurHostFindFailure;
+        return StatusCode::CurrentHostFindFailure;
     }
 
     pal::string_t dotnet_root;

src/native/corehost/host_startup_info.cpp

@@ -89,7 +89,7 @@ const pal::string_t host_startup_info_t::get_app_name() const
     if (host_path->empty() && (!pal::get_own_executable_path(host_path) || !pal::fullpath(host_path)))
     {
         trace::error(_X("Failed to resolve full path of the current executable [%s]"), host_path->c_str());
-        return StatusCode::LibHostCurExeFindFailure;
+        return StatusCode::CurrentHostFindFailure;
     }
 
     return 0;

src/native/corehost/hostfxr.h

@@ -130,7 +130,7 @@ typedef int32_t(HOSTFXR_CALLTYPE *hostfxr_initialize_for_dotnet_command_line_fn)
 //    Success                            - Hosting components were successfully initialized
 //    Success_HostAlreadyInitialized     - Config is compatible with already initialized hosting components
 //    Success_DifferentRuntimeProperties - Config has runtime properties that differ from already initialized hosting components
-//    CoreHostIncompatibleConfig         - Config is incompatible with already initialized hosting components
+//    HostIncompatibleConfig             - Config is incompatible with already initialized hosting components
 //
 // This function will process the .runtimeconfig.json to resolve frameworks and prepare everything needed
 // to load the runtime. It will only process the .deps.json from frameworks (not any app/component that

src/native/corehost/hostpolicy/hostpolicy.cpp

@@ -463,7 +463,7 @@ SHARED_API int HOSTPOLICY_CALLTYPE corehost_main_with_output_buffer(const int ar
     else
     {
         trace::error(_X("Unknown command: %s"), g_init.host_command.c_str());
-        rc = StatusCode::LibHostUnknownCommand;
+        rc = StatusCode::LibHostInvalidArgs;
     }
 
     return rc;

src/native/corehost/hostpolicy/standalone/coreclr_resolver.cpp

@@ -25,10 +25,13 @@ bool coreclr_resolver_t::resolve_coreclr(const pal::string_t& libcoreclr_path, c
     coreclr_resolver_contract.coreclr_create_delegate = reinterpret_cast<coreclr_create_delegate_fn>(pal::get_symbol(coreclr_resolver_contract.coreclr, "coreclr_create_delegate"));
 
     // Only the coreclr_set_error_writer is optional
-    assert(coreclr_resolver_contract.coreclr_initialize != nullptr
-        && coreclr_resolver_contract.coreclr_shutdown != nullptr
-        && coreclr_resolver_contract.coreclr_execute_assembly != nullptr
-        && coreclr_resolver_contract.coreclr_create_delegate != nullptr);
+    if (coreclr_resolver_contract.coreclr_initialize == nullptr
+        || coreclr_resolver_contract.coreclr_shutdown == nullptr
+        || coreclr_resolver_contract.coreclr_execute_assembly == nullptr
+        || coreclr_resolver_contract.coreclr_create_delegate == nullptr)
+    {
+        return false;
+    }
 
     return true;
 }

src/native/corehost/ijwhost/ijwhost.cpp

@@ -31,7 +31,7 @@ pal::hresult_t get_load_in_memory_assembly_delegate(pal::dll_t handle, load_in_m
             if (!pal::get_module_path(handle, &mod_path))
             {
                 trace::error(_X("Failed to resolve full path of the current mixed-mode module [%s]"), host_path.c_str());
-                return StatusCode::LibHostCurExeFindFailure;
+                return StatusCode::CurrentHostFindFailure;
             }
 
             pal::string_t config_path_local { strip_file_ext(mod_path) };

src/native/corehost/ijwhost/ijwthunk.cpp

@@ -143,7 +143,7 @@ extern "C" std::uintptr_t __stdcall start_runtime_and_get_target_address(std::ui
     {
 #pragma warning (push)
 #pragma warning (disable: 4297)
-        throw StatusCode::LibHostCurExeFindFailure;
+        throw StatusCode::CurrentHostFindFailure;
 #pragma warning (pop)
     }