From 828531a6412f360c80dac8e780ca51fa88d930ee Mon Sep 17 00:00:00 2001 From: Elinor Fung <47805090+elinor-fung@users.noreply.github.com> Date: Wed, 17 Apr 2019 19:35:00 -0700 Subject: [PATCH] Add documentation for existing hostfxr functions (dotnet/core-setup#5904) Commit migrated from https://github.com/dotnet/core-setup/commit/46210e5c170a5c4fd2aca61d5590c765955bdd03 --- docs/installer/design-docs/hosting-layer-apis.md | 129 ++++++++++++++++++++++- 1 file changed, 128 insertions(+), 1 deletion(-) diff --git a/docs/installer/design-docs/hosting-layer-apis.md b/docs/installer/design-docs/hosting-layer-apis.md index 68f85cf..c274d4e 100644 --- a/docs/installer/design-docs/hosting-layer-apis.md +++ b/docs/installer/design-docs/hosting-layer-apis.md @@ -11,6 +11,133 @@ The `char_t` strings in the below API descriptions are defined based on the plat All exported functions and function pointers in the `hostfxr` library use the `__cdecl` calling convention on the x86 platform. +### .NET Core 1.0+ + +``` C +int hostfxr_main(const int argc, const char_t *argv[]) +``` + +Run an application. +* `argc` / `argv` - command-line arguments + +This function does not return until the application completes execution. + +### .NET Core 2.0+ + +``` C +int32_t hostfxr_resolve_sdk( + const char_t *exe_dir, + const char_t *working_dir, + char_t buffer[], + int32_t buffer_size) +``` + +Obsolete. Use `hostfxr_resolve_sdk2`. + +### .NET Core 2.1+ + +``` C +int hostfxr_main_startupinfo( + const int argc, + const char_t *argv[], + const char_t *host_path, + const char_t *dotnet_root, + const char_t *app_path) +``` + +Run an application. +* `argc` / `argv` - command-line arguments +* `host_path` - path to the host application +* `dotnet_root` - path to the .NET Core installation root +* `app_path` - path to the application to run + +This function does not return until the application completes execution. + +``` C +enum hostfxr_resolve_sdk2_flags_t +{ + disallow_prerelease = 0x1, +}; + +enum hostfxr_resolve_sdk2_result_key_t +{ + resolved_sdk_dir = 0, + global_json_path = 1, +}; + +typedef void (*hostfxr_resolve_sdk2_result_fn)( + hostfxr_resolve_sdk2_result_key_t key, + const char_t* value); + +int32_t hostfxr_resolve_sdk2( + const char_t *exe_dir, + const char_t *working_dir, + int32_t flags, + hostfxr_resolve_sdk2_result_fn result) +``` + +Determine the directory location of the SDK, accounting for global.json and multi-level lookup policy. +* `exe_dir` - main directory where SDKs are located in `sdk\[version]` sub-folders. +* `working_dir` - directory where the search for `global.json` will start and proceed upwards +* `flags` - flags that influence resolution + * `disallow_prerelease` - do not allow resolution to return a pre-release SDK version unless a pre-release version was specified via `global.json` +* `result` - callback invoked to return resolved values. The callback may be invoked more than once. Strings passed to the callback are valid only for the duration of the call. + +If resolution succeeds, `result` will be invoked with `resolved_sdk_dir` key and the value will hold the path to the resolved SDK directory. If resolution does not succeed, `result` will be invoked with `resolved_sdk_dir` key and the value will be `nullptr`. + +If `global.json` is used, `result` will be invoked with `global_json_path` key and the value will hold the path to `global.json`. If there was no `global.json` found, or the contents of global.json did not impact resolution (e.g. no version specified), then `result` will not be invoked with `global_json_path` key. + +``` C +typedef void (*hostfxr_get_available_sdks_result_fn)( + int32_t sdk_count, + const char_t *sdk_dirs[]); + +int32_t hostfxr_get_available_sdks( + const char_t *exe_dir, + hostfxr_get_available_sdks_result_fn result) +``` + +Get the list of all available SDKs ordered by ascending version. +* `exe_dir` - path to the dotnet executable +* `result` - callback invoked to return the list of SDKs by their directory paths. String array and its elements are valid only for the duration of the call. + +``` C +int32_t hostfxr_get_native_search_directories( + const int argc, + const char_t *argv[], + char_t buffer[], + int32_t buffer_size, + int32_t *required_buffer_size) +``` + +Get the native search directories of the runtime based upon the specified app. +* `argc` / `argv` - command-line arguments +* `buffer` - buffer to populate with the native search directories (including a null terminator). +* `buffer_size` - size of `buffer` in `char_t` units +* `required_buffer_size` - if `buffer` is too small, this will be populated with the minimum required buffer size (including a null terminator). Otherwise, this will be set to 0. + +The native search directories will be a list of paths separated by `PATH_SEPARATOR`, which is a semicolon (;) on Windows and a colon (:) otherwise. + +If `buffer_size` is less than the minimum required buffer size, this function will return `HostApiBufferTooSmall` and `buffer` will be unchanged. + +### .NET Core 3.0+ + +``` C +typedef void(*hostfxr_error_writer_fn)(const char_t *message); + +hostfxr_error_writer_fn hostfxr_set_error_writer(hostfxr_error_writer_fn error_writer) +``` + +Set a callback which will be used to report error messages. By default no callback is registered and the errors are written to standard error. +* `error_writer` - callback function which will be invoked every time an error is reported. When set to `nullptr`, this function unregisters any previously registered callback and the default behaviour is restored. + +The return value is the previously registered callback (which is now unregistered) or `nullptr` if there was no previously registered callback. + +The error writer is registered per-thread. On each thread, only one callback can be registered. Subsequent registrations overwrite the previous ones. + +If `hostfxr` invokes functions in `hostpolicy` as part of its operation, the error writer will be propagated to `hostpolicy` for the duration of the call. This means that errors from both `hostfxr` and `hostpolicy` will be reported through the same error writer. + + ## Host Policy All exported functions and function pointers in the `hostpolicy` library use the `__cdecl` calling convention on the x86 platform. @@ -170,4 +297,4 @@ int corehost_close_context(corehost_context_contract *context_contract) ``` Closes the host context. -* `context_contract` - contract of the context to close. \ No newline at end of file +* `context_contract` - contract of the context to close. -- 2.7.4