263 lines
14 KiB
Markdown
263 lines
14 KiB
Markdown
# Runtime Configuration Files
|
|
|
|
The runtime configuration files store the dependencies of an application (formerly stored in the `.deps` file). They also include runtime configuration options, such as the Garbage Collector mode. Optionally they can also include data for runtime compilation (compilation settings used to compile the original application, and reference assemblies used by the application).
|
|
|
|
**Note:** This document doesn't provide full explanations as to why individual items are needed in this file. That is covered in the [`corehost` spec](corehost.md) and via the `Microsoft.Extensions.DependencyModel` assembly.
|
|
|
|
## What produces the files and where are they?
|
|
|
|
There are two runtime configuration files for a particular application. Given a project named `MyApp`, the compilation process produces the following files (on Windows, other platforms are similar):
|
|
|
|
* `MyApp.dll` - The managed assembly for `MyApp`, including an ECMA-compliant entry point token.
|
|
* `MyApp.exe` - A copy of the `corehost.exe` executable.
|
|
* `MyApp.config.json` - An **optional** configuration file containing runtime configuration settings.
|
|
* `MyApp.deps.json` - A list of dependencies, as well as compilation context data and compilation dependencies. Not technically required, but required to use the servicing or package cache/shared package install features.
|
|
|
|
## File format
|
|
|
|
The files are both JSON files stored in UTF-8 encoding. Below are sample files. Note that not all sections are required and some will be opt-in only (see below for more details). The `.config.json` file is completely optional, and in the `.deps.json` file, only the `runtimeTarget`, `targets` and `libraries` sections are required (and within the `targets` section, only the runtime-specific target is required).
|
|
|
|
### [appname].config.json
|
|
```json
|
|
{
|
|
"runtimeConfig": {
|
|
"gcServer": true,
|
|
"gcConcurrent": false
|
|
}
|
|
}
|
|
```
|
|
|
|
### [appname].deps.json
|
|
```json
|
|
{
|
|
"runtimeTarget": "DNXCore,Version=v5.0/osx.10.10-x64",
|
|
"compilationOptions": {
|
|
"defines": [ "DEBUG" ]
|
|
},
|
|
"targets": {
|
|
"DNXCore,Version=v5.0": {
|
|
"MyApp/1.0": {
|
|
"type": "project",
|
|
"dependencies": {
|
|
"AspNet.Mvc": "1.0.0"
|
|
}
|
|
},
|
|
"System.Foo/1.0.0": {
|
|
"type": "package",
|
|
},
|
|
"System.Banana/1.0.0": {
|
|
"type": "package",
|
|
"dependencies": {
|
|
"System.Foo": "1.0.0"
|
|
},
|
|
"compile": {
|
|
"ref/dotnet5.4/System.Banana.dll": { }
|
|
}
|
|
}
|
|
},
|
|
"DNXCore,Version=v5.0/osx.10.10-x64": {
|
|
"MyApp/1.0": {
|
|
"type": "project",
|
|
"dependencies": {
|
|
"AspNet.Mvc": "1.0.0"
|
|
}
|
|
},
|
|
"System.Foo/1.0.0": {
|
|
"type": "package",
|
|
"runtime": {
|
|
"lib/dnxcore50/System.Foo.dll": { }
|
|
}
|
|
},
|
|
"System.Banana/1.0.0": {
|
|
"type": "package",
|
|
"dependencies": {
|
|
"System.Foo": "1.0.0"
|
|
},
|
|
"runtime": {
|
|
"lib/dnxcore50/System.Banana.dll": { }
|
|
},
|
|
"resources": {
|
|
"lib/dnxcore50/fr-FR/System.Banana.resources.dll": { "locale": "fr-FR" }
|
|
},
|
|
"native": {
|
|
"runtimes/osx.10.10-x64/native/libbananahelper.dylib": { }
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"libraries": {
|
|
"MyApp/1.0": {
|
|
"type": "project"
|
|
},
|
|
"System.Foo/1.0": {
|
|
"type": "package",
|
|
"serviceable": true,
|
|
"sha512": "[base64 string]"
|
|
},
|
|
"System.Banana/1.0": {
|
|
"type": "package",
|
|
"sha512": "[base64 string]"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Sections
|
|
|
|
### `runtimeConfig` Section (`.config.json`)
|
|
|
|
This section is copied verbatim from an identical section in the input `project.json` file (with the exception of the `target` parameter which is generated by the compilation process). The `runtimeConfig` section specifies parameters to be provided to the runtime during initialization. Known parameters include:
|
|
|
|
* `gcServer` - Boolean indicating if the server GC should be used (Default: _TBD_). Note: This is designed to mirror the existing [app.config](https://msdn.microsoft.com/en-us/library/ms229357.aspx) setting)
|
|
* `gcConcurrent` - Boolean indicating if background garbage collection should be used (Default: _TBD_). Note: This is designed to mirror the existing [app.config](https://msdn.microsoft.com/en-us/library/yhwwzef8.aspx) setting).
|
|
* Others _TBD_
|
|
|
|
These settings are read by `corehost` to determine how to initialize the runtime. All versions of `corehost` **must ignore** settings in this section that they do not understand (thus allowing new settings to be added in later versions).
|
|
|
|
### `compilationOptions` Section (`.deps.json`)
|
|
|
|
This section is copied by storing the merged `compilationOptions` from the input `project.json`. The `project.json` can define three sets of compilation options: Global, Per-Configuration, and Per-Framework. However, the `runtime.config.json` is specific to a configuration and framework so there is only one merged section here.
|
|
|
|
The exact settings found here are specific to the compiler that produced the original application binary. Some example settings include: `defines`, `languageVersion` (C#/VB), `allowUnsafe` (C#), etc.
|
|
|
|
As an example, here is a possible `project.json` file:
|
|
|
|
```json
|
|
{
|
|
"compilationOptions": {
|
|
"allowUnsafe": true
|
|
},
|
|
|
|
"frameworks": {
|
|
"net451": {
|
|
"compilationOptions": {
|
|
"defines": [ "DESKTOP_CLR" ]
|
|
}
|
|
},
|
|
"dnxcore50": {
|
|
"compilationOptions": {
|
|
"defines": [ "CORE_CLR" ]
|
|
}
|
|
}
|
|
},
|
|
|
|
"configurations": {
|
|
"Debug": {
|
|
"compilationOptions": {
|
|
"defines": [ "DEBUG_MODE" ]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
When this project is built for `dnxcore50` in the `Debug` configuration, the outputted `MyApp.deps.json` file will have the following `compilationOptions` section:
|
|
|
|
```json
|
|
{
|
|
"compilationOptions": {
|
|
"allowUnsafe": true,
|
|
"defines": [ "CORE_CLR", "DEBUG_MODE" ]
|
|
}
|
|
}
|
|
```
|
|
|
|
### `runtimeTarget` property (`.deps.json`)
|
|
|
|
This property contains the name of the target from `targets` that should be used by the runtime. This is present to simplify `corehost` so that it does not have to parse or understand target names.
|
|
|
|
### `targets` Section (`.deps.json`)
|
|
|
|
This section contains subsetted data from the input `project.lock.json`.
|
|
|
|
Each property under `targets` describes a "target", which is a collection of libraries required by the application when run or compiled in a certain framework and platform context. A target **must** specify a Framework name, and **may** specify a Runtime Identifier. Targets without Runtime Identifiers represent the dependencies and assets used for compiling the application for a particular framework. Targets with Runtime Identifiers represent the dependencies and assets used for running the application under a particular framework and on the platform defined by the Runtime Identifier. In the example above, the `DNXCore,Version=v5.0` target lists the dependencies and assets used to compile the application for `dnxcore50`, and the `DNXCore,Version=v5.0/osx.10.10-x64` target lists the dependencies and assets used to run the application on `dnxcore50` on a 64-bit Mac OS X 10.10 machine.
|
|
|
|
There will always be two targets in the `runtime.config.json` file: A compilation target, and a runtime target. The compilation target will be named with the framework name used for the compilation (`DNXCore,Version=v5.0` in the example above). The runtime target will be named with the framework name and runtime identifier used to execute the application (`DNXCore,Version=v5.0/osx.10.10-x64` in the example above). However, the runtime target will also be identified by name in the `runtimeOptions` section, so that `corehost` need not parse and understand target names.
|
|
|
|
The content of each target property in the JSON is a JSON object. Each property of that JSON object represents a single dependency required by the application when compiled for/run on that target. The name of the property contains the ID and Version of the dependency in the form `[Id]/[Version]`. The content of the property is another JSON object containing metadata about the dependency.
|
|
|
|
The `type` property of a dependency object defines what kind of entity satisfied the dependency. Possible values include `project` and `package` (further comments on dependency types below).
|
|
|
|
**Open Question:** `type` is also present in the `libraries` section. We don't really need it in both. It's in both now because the lock file does that and we want the formats to be similar. Should we remove it?
|
|
|
|
The `dependencies` property of a dependency object defines the ID and Version of direct dependencies of this node. It is a JSON object where the property names are the ID of the dependency and the content of each property is the Version of the dependency.
|
|
|
|
The `runtime` property of a dependency object lists the relative paths to Managed Assemblies required to be available at runtime in order to satisfy this dependency. The paths are relative to the location of the Dependency (see below for further details on locating a dependency).
|
|
|
|
The `resources` property of a dependency object lists the relative paths and locales of Managed Satellite Assemblies which provide resources for other languages. Each item contains a `locale` property specifying the [IETF Language Tag](https://en.wikipedia.org/wiki/IETF_language_tag) for the satellite assembly (or more specifically, a value usable in the Culture field for a CLR Assembly Name).
|
|
|
|
The `native` property of a dependency object lists the relative paths to Native Libraries required to be available at runtime in order to satisfy this dependency. The paths are relative to the location of the Dependency (see below for further details on locating a dependency).
|
|
|
|
In compilation targets, the `runtime`, `resources` and `native` properties of a dependency are omitted, because they are not relevant to compilation. Similarly, in runtime targets, the `compile` property is omitted, because it is not relevant to runtime.
|
|
|
|
Only dependencies with a `type` value of `package` will have asset lists (`compile`, `runtime`, `resources`, `native`). Dependencies which are satisfied by projects will have all of their assets copied to the output directory, so they will not be listed in this file.
|
|
|
|
### `libraries` Section (`.deps.json`)
|
|
|
|
This section contains a union of all the dependencies found in the various targets, and contains common metadata for them. Specifically, it contains the `type`, as well as a boolean indicating if the library can be serviced (`servicable`, only for `package`-typed libraries) and a SHA-512 hash of the package file (`sha512`, only for `package`-typed libraries.
|
|
|
|
**Open Question**: We could probably exclude projects from this set in order to reduce duplication. The main reason this is a separate section is because that's how the lock file is formatted and we want to try an keep this format the same if possible.
|
|
|
|
## How the file is used
|
|
|
|
The file is read by two different components:
|
|
|
|
* `corehost` uses it to determine what to place on the TPA and Native Library Search Path lists, as well as what runtime settings to apply (GC type, etc.). See [the `corehost` spec](corehost.md).
|
|
* `Microsoft.Extensions.DependencyModel` uses it to allow a running managed application to query various data about it's dependencies. For example:
|
|
* To find all dependencies that depend on a particular package (used by ASP.NET MVC and other plugin-based systems to identify assemblies that should be searched for possible plugin implementations)
|
|
* To determine the reference assemblies used by the application when it was compiled in order to allow runtime compilation to use the same reference assemblies (used by ASP.NET Razor to compile views)
|
|
* To determine the compilation settings used by the application in order to allow runtime compilation to use the same settings (also used by ASP.NET Razor views).
|
|
|
|
## Opt-In Compilation Data
|
|
|
|
Some of the sections in the `.deps.json` file contain data used for runtime compilation. This data is not provided in the file by default. Instead, a project.json setting `preserveCompilationContext` must be set to true in order to ensure this data is added. Without this setting, the `compilationOptions` will not be present in the file, and the `targets` section will contain only the runtime target. For example, if the `preserveCompilationContext` setting was not present in the `project.json` that generated the above example, the `.deps.json` file would only contain the following content:
|
|
|
|
```json
|
|
{
|
|
"targets": {
|
|
"DNXCore,Version=v5.0/osx.10.10-x64": {
|
|
"MyApp/1.0": {
|
|
"type": "project",
|
|
"dependencies": {
|
|
"AspNet.Mvc": "1.0.0"
|
|
}
|
|
},
|
|
"System.Foo/1.0.0": {
|
|
"type": "package",
|
|
"runtime": {
|
|
"lib/dnxcore50/System.Foo.dll": { }
|
|
}
|
|
},
|
|
"System.Banana/1.0.0": {
|
|
"type": "package",
|
|
"dependencies": {
|
|
"System.Foo": "1.0.0"
|
|
},
|
|
"runtime": {
|
|
"lib/dnxcore50/System.Banana.dll": { }
|
|
},
|
|
"resources": {
|
|
"lib/dnxcore50/fr-FR/System.Banana.resources.dll": { "locale": "fr-FR" }
|
|
},
|
|
"native": {
|
|
"runtimes/osx.10.10-x64/native/libbananahelper.dylib": { }
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"libraries": {
|
|
"MyApp/1.0": {
|
|
"type": "project"
|
|
},
|
|
"System.Foo/1.0": {
|
|
"type": "package",
|
|
"serviceable": true,
|
|
"sha512": "[base64 string]"
|
|
},
|
|
"System.Banana/1.0": {
|
|
"type": "package",
|
|
"sha512": "[base64 string]"
|
|
}
|
|
}
|
|
}
|
|
```
|