Support custom hosting a hybrid between app and component

[rseanhall]

In .NET Core 3.x, work was done to make custom hosting easier. Support was added for an "application" and a "component". I need support for a hybrid between these two.

The general use case is for an application where its features are spread across native and managed code, with the entry point being in native code. The details of my specific use case are here: #34946.

It's like an "application" but not "component":

• This is the main application.
  -Missing dependencies are an error.
  -Loading into default ALC is expected.
  -Any isolation must be implemented by the app itself.
• It may be deployed as self-contained or framework-dependent.

It's like a "component" but not an "application":

• No static void Main(string[] args), no concept of args
• Entry point is custom
• Managed code needs to continue running after execution has passed back to native code

Unique aspects for this hybrid scenario:

• The native code portion will initialize the .NET Core runtime very early in the lifetime of the process.
• If deployed as self-contained, then it was published with a RID compatible with the native code portion of the application.

Reasons to be implemented in .NET Core instead of by the custom host using coreclr directly:

• Logic to find the framework requested by the app is very complex and is subject to change with each new release of the framework.
• Building the TPA list from deps.json files is very complex and is subject to change with each new release of the framework.
• Various documentation discourages using coreclr directly, and some even make it seem like it could be deprecated in the future.

Proposal

Original proposal

Add two new exported functions to `hostfxr` - `hostfxr_initialize_for_managed_host` and `hostfxr_create_delegate`. These two functions are similar to the existing `hostfxr_initialize_for_dotnet_command_line`/`hostfxr_run_app` and `hostfxr_initialize_for_runtime_config`/`hostfxr_get_runtime_delegate` function pairs in that the handle created from `hostfxr_initialize_for_managed_host` can only be used with `hostfxr_create_delegate`.

//
// Initializes the hosting components using an application
//
// Parameters:
//    managed_host_path
//      Path to the managed host assembly file
//    deps_json_path
//      Optional. Path to the .deps.json file
//    runtime_config_path
//      Optional. Path to the .runtimeconfig.json file
//    parameters
//      Optional. Additional parameters for initialization
//    host_context_handle
//      On success, this will be populated with an opaque value representing the initialized host context
//
// Return value:
//    Success          - Hosting components were successfully initialized
//    HostInvalidState - Hosting components are already initialized
//
// This function will find the .runtimeconfig.json and .deps.json corresponding to the given 
     application
// with which to resolve frameworks and dependencies and prepare everything needed to load the runtime.
//
// This function does not load the runtime.
//
typedef int32_t(HOSTFXR_CALLTYPE *hostfxr_initialize_for_managed_host_fn)(
    const char_t *managed_host_path,
    const char_t *deps_json_path,
    const char_t *runtime_config_path,
    const struct hostfxr_initialize_parameters *parameters,
    /*out*/ hostfxr_handle *host_context_handle);

//
// Create a native callable function pointer for a managed method from the currently loaded CoreCLR or from a newly created one.
//
// Parameters:
//     host_context_handle
//       Handle to the initialized host context
//     entry_point_assembly_name
//       Name of the assembly which holds the custom entry point
//     entry_point_type_name
//       Name of the type which holds the custom entry point
//     entry_point_method_name
//       Name of the method which is the custom entry point
//     delegate
//       Output parameter, the function stores a native callable function pointer to the delegate at the specified address
//
// Returns:
//     The error code result.
//
// The host_context_handle must have been initialized using hostfxr_initialize_for_managed_host.
// The assembly is loaded into the default AssemblyLoadContext.
//
typedef int32_t(HOSTFXR_CALLTYPE *hostfxr_create_delegate_fn)(
    const hostfxr_handle host_context_handle,
    const char_t *entry_point_assembly_name,
    const char_t *entry_point_type_name,
    const char_t *entry_point_method_name,
    /*out*/ void **delegate);

hostfxr_initialize_for_managed_host is essentially the same as hostfxr_initialize_for_dotnet_command_line but instead of argc/argv, it takes the application, deps.json, and runtimeconfig.json as explicit parameters.

hostfxr_create_delegate is simply a wrapper around the create delegate functionality of coreclr. hostfxr_get_runtime_delegate could not be reused since it always loads the target assembly into an isolated ALC (which is why it requires a handle from hostfxr_initialize_for_runtime_config - isolation is not supported in self-contained applications and it blocks on SCD).

Design document update and discussion: #36990

Tagging subscribers to this area: @vitek-karas, @swaroop-sridhar
Notify danmosemsft if you want to be subscribed.

[vitek-karas]

We've been discussing something like this recently, thanks for bringing this up again and actually starting the technical solution.

I do like the description of "it's like app and it's like component at the same time" 👍 . Although these two are very related I think it might be beneficial to handle them separately:

Allow self-contained runtime in more scenarios

This can be achieved in two ways:

• Allow loading a self-contained runtime via hostfxr_initialize_for_runtime_config.
• Allow using hostfxr_initialize_for_dotnet_command_line with hostfxr_get_runtime_delegate.

Both can be done, the main differences are:

• hostfxr_initialize_for_dotnet_command_line effectively require the managed "component" to be built like an application (`.exe)
• hostfxr_initialize_for_dotnet_command_line assumes a command line on the input and support parsing some of the hosting layer command line options.
• Going forward we may add support for single-file .exe into the hostfxr_intialize_for_dotnet_command_line, but not the other API.

The one which I've seen recent requests for is much more in line allowing SCD with hostfxr_initialize_for_runtime_config.

The obvious limitation would be that SCD .runtimeconfig.json is the only one allowed to be loaded (so it has to be the first and the only one, we would not allow combining SCD and FDD in any way).

Note: Technically it might be possible to allow SCD to be loaded first and then any number of FDDs if they match as that is basically the same scenario as loading plugins to SCD app - which is supported. But for now we can disallow that for simplicity and for lack of scenarios.

Scenario where this ability is useful without the second (loading into default load context): Native app which needs to load multiple managed components which are all implemented together in one "large" SCD project but still want ALC isolation for some reason (maybe in the future combined with unloadability). I don't have a specific example in mind right now - but it doesn't sound too crazy.

Allow loading "components" into the default load context

This has been actually discussed during the initial proposal for the new hosting APIs. In the end we decided not to do this as we didn't have enough scenarios to justify the added complexity. But it is a natural extension. To make this possible we actually designed the API to allow it in the future. The load_assembly_and_get_function_pointer_fn takes a void * reserved parameter which was intentionally added to allow extending the capabilities of this method in the future. When this was added we had in mind mostly two cases:

• Allow loading into default load context (what you're looking for)
• Allow loading into collectible load context (allow unloading the secondary load context)

Please note that while load_assembly_and_get_function_pointer_fn currently always loads into secondary ALC, there's nothing in the hosting layer which assumes that's the case. The hostfxr_get_runtime_delegate makes no assumptions for this (so we don't need a new hostfxr entry point) and the load_assembly_and_get_function_pointer_fn also doesn't hardcode this in the API in any way (other than it's the only one which works right now).

I would probably do this by defining a new struct to pass in the reserved parameter:

struct load_assembly_and_get_function_pointer_parameters
{
    size_t size; // Acts as a version number effectively
    bool load_into_default_load_context;
}

And then redefine the load_assembly_and_get_function_pointer_fn like this:

typedef int (CORECLR_DELEGATE_CALLTYPE *load_assembly_and_get_function_pointer_fn)(
    const char_t *assembly_path      /* Fully qualified path to assembly */,
    const char_t *type_name          /* Assembly qualified type name */,
    const char_t *method_name        /* Public static method name compatible with delegateType */,
    const char_t *delegate_type_name /* Assembly qualified delegate type name or null */,
    const load_assembly_and_get_function_pointer_parameters *parameters /* additional parameters */,
    /*out*/ void **delegate          /* Pointer where to store the function pointer result */);

Existing code would keep working as-is, and new code can pass in the parameters and alter the behavior.

This behavior has actually been asked for already without the SCD support - so we know there are scenario which want this regardless of the first change.

Given that this is a non-trivial change to the native hosting design, could you please start a separate PR (separate from the implementation PR) to update the design doc. That would be a good place to have the detailed design discussion. The doc also has some more details on interactions of the various APIs and hosting modes and it should help us make sure that the proposed changes play nice with the existing functionality.

[vitek-karas]

/cc @elinor-fung @swaroop-sridhar @jkoritzinsky @AaronRobinsonMSFT

[rseanhall]

Can you give me an idea of whether this can make it in .NET 5? Will the added complexity of getting this working in the existing API's affect if it does? To be honest, using your proposal would require a lot of additional work and I don't want to spend time on this right now if it has to wait for .NET 6.

[vitek-karas]

This can definitely make 5.0 (there's still probably around 2 months before any kind of lock down for the release). I'll have to think about this some more:

• I would like to avoid introducing new APIs unless absolutely necessary (it makes it hard to explain which APIs should be used for what).
• I realized that my proposal introduces a weird discrepancy with regard to TPA behavior - for FDD TPA would have just frameworks, for SCD it would have everything. Fixing that basically means fixing Add ability to differentiate framework assemblies in self-contained apps sdk#3339 and teaching how to initialize hostfxr in libhost mode over SCD.
• What you're proposing is basically hostfxr_intitialize_for_runtime_config but with running the hostfxr in something like an application mode (you introduced a new mode, maybe that's the best option - I don't know yet). Maybe this should be explicit, use hostfxr_initialize_for_runtime_config and add an option to run in this new mode (either app mode, or completely new).
• One way to do that would be to add a deps.json path parameter to hostfxr_initialize_parameters - this could be used even for hostfxr_intialize_for_dotnet_command_line, there's no discrepancy there. Naming would be key here, to make it clear that this changes how the system behaves (to a degree).

Honestly the cleanest way to fix this would be to fix the SDK issue described above, but that's not easy to coordinate.

I assume you have a specific scenario in mind when proposing this - what are the aspects of this which you need:

• Is SCD a must?
• Loading into default ALC - this can be done with the current design - it's just a bit cumbersome (load a small shim into custom ALC -> that loads the main thing into default ALC - needs custom resolver event handler, but doable).
• Why is it important to load into default ALC? (Most things should by now work in custom ALC - although there are some known limitations).
• Could you use a slightly different approach? Basically up side down. Managed would be the main driver and it would call into native. You could even have native init (using the hostfxr APIs), but the main thread would be owned by the managed Main.

I understand that adding new APIs to solve the problem is relatively clean in this case, but it would mean to maintain those going forward (basically forever). So we need to make sure that whatever new concepts we introduce make good sense and play well with everything else.

[rseanhall]

The specific scenario is the one in the issue I linked to - the Wix Toolset's bootstrapper functionality. It must start native because it's an installer, so it can't rely on anything being on the target machine. SCD support is a must - this allows users to write the BA in managed code without any dependencies being on the target machine.

Loading into the default ALC is required to be able to workaround any bugs, limitations, etc. around running in a non-default ALC that are lurking in .NET Core. I also feel like I need to point out that you can't currently shim around this in the SCD scenario because you can't even call hostfxr_get_runtime_delegate.

Do we need to decide on using the existing APIs vs new ones here or should I figure out how to write both of them up in a design PR?

[vitek-karas]

I'll discuss this with couple of people on our end (calls - as that's faster and I will update the issue with any notes I'll have).

Over night I realized two additional things we need to consider:

SDK support for SCD components

.NET Core SDK currently doesn't really support building self-contained "components" - that is classlib projects. Unfortunately this has been "broken" for a while: dotnet/sdk#2549. It's possible to force it on the command line, but the result is "unknown" - it might work, but it might not - we simply don't test this scenario. So in this sense the only "good" way to produce an SCD is building it as an application.

Allow usage of hostfxr_initialize_for_dotnet_command_line together with hostfxr_get_runtime_delegate

This might be actually an easier way to enable the scenario. There are some complexities in hostpolicy around synchronization of the contexts, but other than that it might be relatively easy to enable this. This would also naturally lead to loading everything (the app as well) into the TPA and then just adding an option to load the "component" from the default ALC.
Given the SDK support mentioned above - since the right way to build SCD is to build an app, it feels natural that such payload should be initialized via hostfxr_initialize_for_dotnet_command_line.

[rseanhall]

I can't help but notice that you seem to keep on trying to frame this hybrid scenario as a component, but it really doesn't fit into any of the design decisions that have been made around them. It is essentially an application. hostfxr_get_runtime_delegate was designed and implemented around components. There are many assumptions and limitations in the implementation that it would only be used for components. So I don't think it's a good idea to try to use that for this scenario.

I don't mind reusing the hostfxr_initialize_for_dotnet_command_line entry point for initialization for this hybrid scenario, this is actually what I'm going to use so I can support 3.x (and then I'll load coreclr.dll directly and use CreateDelegate from there). The only problem I have with it is that it's not very discoverable - the args parameter makes it seem like you have to know a lot of internal details to know what to pass in. I would really like to see the CreateDelegate functionality from coreclr exposed from hostfxr since it's much nicer to use. The types don't have to be assembly qualified, and the implementation is powerful enough for you not to have to define your own delegate if you need a custom signature.