Add startup hook design document (dotnet/core-setup#4421)
authorSven Boemer <sbomer@gmail.com>
Fri, 31 Aug 2018 00:24:02 +0000 (17:24 -0700)
committerGitHub <noreply@github.com>
Fri, 31 Aug 2018 00:24:02 +0000 (17:24 -0700)
commit14981a57c2bc765870d83041554bd0fa29980d7e
tree004711c69c58003d22fb3001e2b1136487187bce
parent84355d2bea367f88edf0f251219a6447fc6d0299
Add startup hook design document (dotnet/core-setup#4421)

* Add startup hook design document

This adds a proposal for an early startup hook that allows managed
code to run before the entry point.

* Change env var behavior and clarify version constraints

* Fix formatting, specify Initialize() signature

* Update spec for multiple hooks in environment variable

- Move the configuration to a single environment variable,
  DOTNET_STARTUP_HOOKS
- Introduce syntax to allow multiple hooks to be defined
- Remove .runtimeconfig file options
  This will only support the environment variable, since
  this is a low-level feature that should only be used when implicit
  injection of code is desired.
- Update implementation details

* Remove default type name and other fixes

- Require an explicit type name for each startup hook
- Fix Initialize() signature (it must be static)
- Clarify that the Initialize() methods are called synchronously

* Require full path, clarify syntax, and change TPA behavior

- Relative paths to the assemblies are not allowed
- Use platform-specific path separator
- Clarify restrictions on the syntax (no empty entries, trailing separator)
- Startup assemblies will not be placed on TPA list
  Instead, they will be loaded directly using LoadFromAssemblyPath in
  the implementation.

* Add guidance, error behavior, and thread behavior

* Remove specific error text, fix typos and formatting

* Remove type name from synax

The type must now be called StartupHook, and can not be set by the
environment variable. The descriptions and examples were updated to
reflect this.

Also:
- add a few notes about the visibility of this type
- describe behavior of uncaught exceptions in startup hooks
- give example with platform-specific separators
- fix some typos

* Change startup hook to run closer to Main

Instead of the host creating a delegate and inoking it,
ExecuteMainMethod in the runtime will call the System.Private.CoreLib
function that processes startup hooks. This allows the thread
apartment state to be set based on any attributes in the Main method,
before startup hooks execute.

* Clarify apartment threading state behavior

* Specify the property name passed to the runtime

Commit migrated from https://github.com/dotnet/core-setup/commit/c245dc40c4830443e5a4d720c94ebd08f606a6e7
docs/installer/design-docs/host-startup-hook.md [new file with mode: 0644]