From d4e1df06c84483da1372612389b804f95c3c4ff6 Mon Sep 17 00:00:00 2001 From: Genevieve Warren Date: Tue, 12 Nov 2019 16:37:22 -0800 Subject: [PATCH 01/18] Revert "remove core config files from this pr" This reverts commit d9abdea441e96e7a0a4c95b477a721913ff80fb0. --- docs/core/runtime-config/envvars.md | 63 +++++++++++++++++++++++ docs/core/runtime-config/index.md | 56 ++++++++++++++++++++ docs/core/runtime-config/runtimeconfig.md | 49 ++++++++++++++++++ docs/core/toc.yml | 10 +++- 4 files changed, 177 insertions(+), 1 deletion(-) create mode 100644 docs/core/runtime-config/envvars.md create mode 100644 docs/core/runtime-config/index.md create mode 100644 docs/core/runtime-config/runtimeconfig.md diff --git a/docs/core/runtime-config/envvars.md b/docs/core/runtime-config/envvars.md new file mode 100644 index 0000000000000..12d168bfbc736 --- /dev/null +++ b/docs/core/runtime-config/envvars.md @@ -0,0 +1,63 @@ +--- +title: "Run-time configuration with environment variables" +description: "Use environment variables to configure the run-time behavior of .NET Core apps." +ms.date: "11/08/2019" +--- +# Run-time configuration with environment variables + +.NET Core supports a number of environment variables that you can use to configure your applications. + +The following sections list selected supported environment variables by category. For a complete list of supported, as well as unsupported and internal environment variables, see [Configuration knobs](https://github.com/dotnet/coreclr/blob/master/Documentation/project-docs/clr-configuration-knobs.md). + +> [!NOTE] +> This documentation is a work in progress. If you notice that the information presented here is either incomplete or inaccurate, either [open an issue](https://github.com/dotnet/docs/issues) to let us know about it, or [submit a pull request](https://github.com/dotnet/docs/pulls) to add or correct the information. For information on submitting pull requests for the dotnet/docs repo, see the [contributor's guide](https://github.com/dotnet/docs/blob/master/CONTRIBUTING.md). + +## Debugging + +|Variable name|Variable value|Description| +|--|--|--| +|`COMPlus_EnableDiagnostics`|0 or 1|Enables (1) or disables (0) debugger and profiler diagnostics.| + +## Garbage collection + +|Variable name|Variable value|Description| +|--|--|--| +|`COMPlus_gcAllowVeryLargeObjects`|0 or 1|Enables (1, the default value) or Disables (0) support on 64-bit platforms for arrays that are greater than 2 gigabytes (GB) in total size.| +|`COMPlus_GCCpuGroup`|0 or 1|Enables (1) or disables (0, the default value) support for CPU groups by the garbage collector if server garbage collection is enabled.| +|`COMPlus_GCLatencyLevel`|see |Adjusts the intrusiveness of the garbage collector. The default value is 1 (). For more information, see [Latency modes](../../standard/garbage-collection/latency.md). +|`COMPlus_GCName`|*string_path*|Specifies a path to the library containing the GC that the runtime intends to load. For more information, see [Standalone GC Loader Design](https://github.com/dotnet/coreclr/blob/4c7c066d0bacdb86a2311333de1ca73d94ae5280/Documentation/design-docs/standalone-gc-loading.md).| + +## Networking + +|Variable name|Variable value|Description| +|--|--|--| +|`DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP2SUPPORT`|0 or 1|Starting with .NET Core 3.0, indicates whether support for the HTTP/2 protocol is enabled (1) or disabled (0, the default value).| +|`DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER`|0 or 1|`1`, the default value, enables the use of with high-level networking APIs. `0` enables the implementation of that's based on [libcurl](https://curl.haxx.se/libcurl/).| + +## Profiling + +|Variable name|Variable value|Description| +|--|--|--| +|`CORECLR_ENABLE_PROFILING`|0 or 1|Enables (1) or disables (0, the default value) profiling for the currently running process.| +|`CORECLR_PROFILER`|*string-guid*|Specifies the GUID of the profiler to load into the currently running process.| +|`CORECLR_PROFILER_PATH`|*string-path*|Specifies the path to the profiler DLL to load into the currently running process.| +|`CORECLR_PROFILER_PATH_32`|*string-path*|Specifies the path to the profiler DLL to load into the currently running 32-bit process.| +|`CORECLR_PROFILER_PATH_64`|*string-path*|Specifies the path to the profiler DLL to load into the currently running 64-bit process.| +|`PerfMapEnabled`|0 or 1|Enables (1) or disables (0, the default value) writing */tmp/perf-$pid.map* on Linux systems.| +|`PerfMapIgnoreSignal`|0 or 1|When `PerfMapEnabled` is set to 1, enables (1) or disables (0, the default value) the specified signal to be accepted and ignored as a marker in the perf logs.| + +## Threading + +|Variable name|Variable value|Description| +|--|--|--| +|`COMPlus_Thread_UseAllCpuGroups`|0 or 1|Enables (1) or disables (0, the default value) automatic distribution threads across CPU groups.| + +## Tiered compilation + +|Variable name|Variable value|Description| +|--|--|--| +|`COMPlus_TieredCompilation`|Enables (1, the default value starting with .NET Core 3.0) or disables (0, the default value in .NET Core 2.1 and 2.2) tiered compilation.| + +## See also + +- [NET Core runtime configuration settings](index.md) diff --git a/docs/core/runtime-config/index.md b/docs/core/runtime-config/index.md new file mode 100644 index 0000000000000..537324da7a6d4 --- /dev/null +++ b/docs/core/runtime-config/index.md @@ -0,0 +1,56 @@ +--- +title: "Runtime configuration settings" +description: "Learn how to configure .NET Core applications by using runtime configuration settings." +ms.date: "06/19/2019" +--- +# .NET Core runtime configuration settings + +.NET Core supports the use of configuration files and environment variables to configure the behavior of .NET Core applications at runtime. Runtime configuration is an attractive option if: + +- You do not own or control the source code for an application and therefore are unable to configure it programmatically. + +- Multiple instances of your application may run at a single time on the same system, and you want to configure each for optimum performance. + +> [!NOTE] +> This documentation is a work in progress. If you notice that the information presented here is either incomplete or inaccurate, either [open an issue](https://github.com/dotnet/docs/issues) to let us know about it, or [submit a pull request](https://github.com/dotnet/docs/pulls) to address the issue. For information on submitting pull requests for the dotnet/docs repo, see the [contributor's guide](https://github.com/dotnet/docs/blob/master/CONTRIBUTING.md). + +.NET Core provides the following mechanisms for configuring applications at runtime: + +- The **configProperties** section of the *runtimeconfig.json* file. This section has the form: + + ```json + { + "runtimeOptions": { + "configProperties": { + "config-property-name1": "config-value1", + "config-property-name2": "config-value2" + } + } + } + ``` + + For example: + + ```json + { + "runtimeOptions": { + "configProperties": { + "System.GC.Concurrent": true, + "System.GC.RetainVM": true, + "System.Threading.ThreadPool.MinThreads": "4", + "System.Threading.ThreadPool.MaxThreads": "25" + } + } + ``` + + The *runtimeconfig.json* file is automatically created in the build directory by the [dotnet build](../tools/dotnet-build.md) command as well as by selecting the **Build** menu option in Visual Studio. You can then edit he file once it is created. + + Some configuration values can also be set programmatically by calling the method. + + See [Runtime configuration with runtimeconfig.json](runtimeconfig.md) for information on the available configuration options in *runtimeconfig.json*. + +- Environment variables. + + You can define an environment variable to supply runtime configuration information. Environment variables can be defined at the command line either interactively or by using a script. They can also be defined programmatically by calling the method on both Windows and Unix-based systems. + + See [Runtime configuration with environment variables](envvars.md) for a selection of the environment variables supported by .NET Core. diff --git a/docs/core/runtime-config/runtimeconfig.md b/docs/core/runtime-config/runtimeconfig.md new file mode 100644 index 0000000000000..62015f2ec4cd3 --- /dev/null +++ b/docs/core/runtime-config/runtimeconfig.md @@ -0,0 +1,49 @@ +--- +title: "Runtime configuration with runtimeconfig.json" +description: "Use the runtime.config.json file to configure the runtime behavior of .NET Core applications." +ms.date: "06/19/2019" +--- +# Runtime configuration with runtimeconfig.json + +You can use the **configProperties** section of the *runtimeconfig.json* file to set designated properties at runtime. + +> [!NOTE] +> This documentation is a work in progress. If you notice that the information presented here is either incomplete or inaccurate, either [open an issue](https://github.com/dotnet/docs/issues) to let us know about it, or [submit a pull request](https://github.com/dotnet/docs/pulls) to add or correct the information. For information on submitting pull requests for the dotnet/docs repo, see the [contributor's guide](https://github.com/dotnet/docs/blob/master/CONTRIBUTING.md). + +## File format + +The *runtimeconfig.json* file has the following format: + +```json +{ + "runtimeOptions": { + "configProperties": { + "config-property-name1": config-value1, + "config-property-name2": config-value2 + } + } +} +``` + +## Individual configuration settings + +The *runtimeconfig.json* file supports the following configuration settings: + +|Name|Value|Description| +|--|--|--| +|"Switch.System.Globalization.EnforceJapaneseEraYearRange"|true | false|Determines whether range checks for calendars that support multiple eras are relaxed (`false`, the default value) or whether dates that overflow an era's date range throw an (`true`). For more information, see [Calendars, eras, and date ranges: Relaxed range checks](../../standard/datetime/working-with-calendars.md#calendars-eras-and-date-ranges-relaxed-range-checks).| +|"Switch.System.Globalization.EnforceLegacyJapaneseDateParsing"|true | false|Determines whether a string that contains either "1" or "Gannen" as the year parses successfully (`false`, the default), or whether only "1" is supported (`true`). For more information, see [Representing dates in calendars with multiple eras](../../standard/datetime/working-with-calendars.md#representing-dates-in-calendars-with-multiple-eras).| +|"Switch.System.Globalization.FormatJapaneseFirstYearAsANumber"|true | false|Determines whether the first year of a Japanese calendar era is formatted as "gannen" (`false`, the default) or as a number. For more information, see [Representing dates in calendars with multiple eras](../../standard/datetime/working-with-calendars.md#representing-dates-in-calendars-with-multiple-eras).| +|"System.GC.Concurrent"|true | false|Determines whether background garbage collection is enabled (`true`, the default value) or disabled (`false`). For more information, see [Background workstation garbage collection](../../standard/garbage-collection/fundamentals.md#background-workstation-garbage-collection) and [Background server garbage collection](../../standard/garbage-collection/fundamentals.md#background-server-garbage-collection).| +|"System.GC.RetainVM"|true | false|Determines whether segments that should be deleted are put on a standby list for future use (`true`) or are released back to the operating system (`false`, the default value).| +|"System.GC.Server"|true | false|Determines whether the application uses server garbage collection (`true`) or workstation garbage collection (`false`, the default value). For more information, see [Configuring garbage collection](../../standard/garbage-collection/fundamentals.md#configuring-garbage-collection).| +|"System.Globalization.Invariant"|true | false|Determines whether a .NET Core application runs in globalization invariant mode without access to culture-specific data and behavior (`true`), or whether it has accesses to cultural data (`false`, the default). For more information, see [.NET Core Globalization Invariant Mode](https://github.com/dotnet/corefx/blob/master/Documentation/architecture/globalization-invariant-mode.md).| +|"System.Net.Http.SocketsHttpHandler.Http2Support"|true | false|Determines whether high-level networking APIs such as use (true, the default value) or the legacy >xref:System.Net.Http.HttpClientHandler> (false).

You can also configure this setting programmatically by calling the method.| +|"System.Net.Http.UseSocketsHttpHandler"|true | false|Determines whether high-level networking APIs such as use (`true`, the default value) or the implementation of that's based on [libcurl](https://curl.haxx.se/libcurl/) (`false`).

You can also configure this setting programmatically by calling the method.| +|"System.Runtime.TieredCompilation"|true | false|Determines whether the JIT compiler uses tiered compilation (`true`, the default value starting with .NET Core 3.0) or disables tiered compilation (`false`, the default value in .NET Core 2.1 and .NET Core 2.2). For more information, see [Tiered compilation](../whats-new/dotnet-core-3-0.md#tiered-compilation).| +|"System.Threading.ThreadPool.MinThreads"|*n*|Specifies the minimum number of threads for the worker threadpool, where *n* is an integer that represents the minimum number of threads. This setting corresponds to the method.| +|"System.Threading.ThreadPool.MaxThreads"|*n*|Specifies the maximum number of threads for the worker threadpool, where *n* is an integer that represents the maximum number of threads. This setting corresponds to the method.| + +## See also + +- [NET Core runtime configuration settings](index.md) diff --git a/docs/core/toc.yml b/docs/core/toc.yml index 02cce242e49df..a667fde7056c7 100644 --- a/docs/core/toc.yml +++ b/docs/core/toc.yml @@ -65,11 +65,19 @@ - name: Developing Libraries with Cross Platform Tools href: tutorials/libraries.md - name: Create a .NET Core application with plugins - href: tutorials/creating-app-with-plugin-support.md + href: tutorials/creating-app-with-plugin-support.md - name: Developing ASP.NET Core applications href: tutorials/aspnet-core.md - name: Hosting .NET Core from native code href: tutorials/netcore-hosting.md +- name: Runtime configuration + items: + - name: Runtime configuration settings + href: runtime-config/index.md + - name: Runtime configuration with runtimeconfig.json + href: runtime-config/runtimeconfig.md + - name: Runtime configuration with environment variables + href: runtime-config/envvars.md - name: Native Interoperability items: - name: Exposing .NET Core Components to COM From 93dedea0636f27a9c6c71df87adbdd96342658cb Mon Sep 17 00:00:00 2001 From: Genevieve Warren Date: Tue, 12 Nov 2019 22:30:06 -0800 Subject: [PATCH 02/18] remove separate ev/json files; add new files for each category --- docs/core/run-time-config/compilation.md | 14 +++++ docs/core/run-time-config/date-time.md | 16 +++++ docs/core/run-time-config/debugging.md | 10 +++ .../core/run-time-config/garbage-collector.md | 42 +++++++++++++ docs/core/run-time-config/globalization.md | 12 ++++ docs/core/run-time-config/index.md | 60 ++++++++++++++++++ docs/core/run-time-config/networking.md | 24 +++++++ docs/core/run-time-config/profiling.md | 31 +++++++++ docs/core/run-time-config/threading.md | 19 ++++++ docs/core/runtime-config/envvars.md | 63 ------------------- docs/core/runtime-config/index.md | 56 ----------------- docs/core/runtime-config/runtimeconfig.md | 49 --------------- docs/core/toc.yml | 46 +++++++++----- 13 files changed, 257 insertions(+), 185 deletions(-) create mode 100644 docs/core/run-time-config/compilation.md create mode 100644 docs/core/run-time-config/date-time.md create mode 100644 docs/core/run-time-config/debugging.md create mode 100644 docs/core/run-time-config/garbage-collector.md create mode 100644 docs/core/run-time-config/globalization.md create mode 100644 docs/core/run-time-config/index.md create mode 100644 docs/core/run-time-config/networking.md create mode 100644 docs/core/run-time-config/profiling.md create mode 100644 docs/core/run-time-config/threading.md delete mode 100644 docs/core/runtime-config/envvars.md delete mode 100644 docs/core/runtime-config/index.md delete mode 100644 docs/core/runtime-config/runtimeconfig.md diff --git a/docs/core/run-time-config/compilation.md b/docs/core/run-time-config/compilation.md new file mode 100644 index 0000000000000..afbd4e7458434 --- /dev/null +++ b/docs/core/run-time-config/compilation.md @@ -0,0 +1,14 @@ +--- + +--- +# Run-time configuration options for compilation + +## Tiered compilation + +- Configures whether the JIT compiler uses [tiered compilation](../whats-new/dotnet-core-3-0.md#tiered-compilation). +- In .NET Core 3.0 and later, tiered compilation is enabled by default. +- In .NET Core 2.1 and 2.2, tiered compilation is disabled by default. + +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| "System.Runtime.TieredCompilation" | `true` - enabled

`false` - disabled | `COMPlus_TieredCompilation` | 1 - enabled

0 - disabled | diff --git a/docs/core/run-time-config/date-time.md b/docs/core/run-time-config/date-time.md new file mode 100644 index 0000000000000..25d27bcb5e28c --- /dev/null +++ b/docs/core/run-time-config/date-time.md @@ -0,0 +1,16 @@ +--- + +--- +# Run-time configuration options for dates and times + +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| | | + +runtimeconfig.json: + +|"Switch.System.Globalization.EnforceJapaneseEraYearRange"|true | false|Determines whether range checks for calendars that support multiple eras are relaxed (`false`, the default value) or whether dates that overflow an era's date range throw an (`true`). For more information, see [Calendars, eras, and date ranges: Relaxed range checks](../../standard/datetime/working-with-calendars.md#calendars-eras-and-date-ranges-relaxed-range-checks).| + +|"Switch.System.Globalization.EnforceLegacyJapaneseDateParsing"|true | false|Determines whether a string that contains either "1" or "Gannen" as the year parses successfully (`false`, the default), or whether only "1" is supported (`true`). For more information, see [Representing dates in calendars with multiple eras](../../standard/datetime/working-with-calendars.md#representing-dates-in-calendars-with-multiple-eras).| + +|"Switch.System.Globalization.FormatJapaneseFirstYearAsANumber"|true | false|Determines whether the first year of a Japanese calendar era is formatted as "gannen" (`false`, the default) or as a number. For more information, see [Representing dates in calendars with multiple eras](../../standard/datetime/working-with-calendars.md#representing-dates-in-calendars-with-multiple-eras).| diff --git a/docs/core/run-time-config/debugging.md b/docs/core/run-time-config/debugging.md new file mode 100644 index 0000000000000..5c6312417527f --- /dev/null +++ b/docs/core/run-time-config/debugging.md @@ -0,0 +1,10 @@ +--- + +--- +# Run-time configuration settings for debugging + +## Debugger and profiler diagnostics + +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| | | `COMPlus_EnableDiagnostics` | 0 - disabled

1 - enabled | diff --git a/docs/core/run-time-config/garbage-collector.md b/docs/core/run-time-config/garbage-collector.md new file mode 100644 index 0000000000000..8b0e940ea6e00 --- /dev/null +++ b/docs/core/run-time-config/garbage-collector.md @@ -0,0 +1,42 @@ +--- + +--- +# Run-time configuration options for garbage collection + +## Large objects + +- Configures garbage collector support on 64-bit platforms for arrays that are greater than 2 gigabytes (GB) in total size. +- Enabled by default. + +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| | | `COMPlus_gcAllowVeryLargeObjects` | 0 - disabled

1 - enabled | + +## CPU groups + +|`COMPlus_GCCpuGroup`|0 or 1|Enables (1) or disables (0, the default value) support for CPU groups by the garbage collector if server garbage collection is enabled.| + +## Latency level + +|`COMPlus_GCLatencyLevel`|see |Adjusts the intrusiveness of the garbage collector. The default value is 1 (). For more information, see [Latency modes](../../standard/garbage-collection/latency.md). + +## GC name + +|`COMPlus_GCName`|*string_path*|Specifies a path to the library containing the GC that the runtime intends to load. For more information, see [Standalone GC Loader Design](https://github.com/dotnet/coreclr/blob/4c7c066d0bacdb86a2311333de1ca73d94ae5280/Documentation/design-docs/standalone-gc-loading.md).| + +runtimeconfig.json + +|"System.GC.Concurrent"|true | false|Determines whether background garbage collection is enabled (`true`, the default value) or disabled (`false`). For more information, see [Background workstation garbage collection](../../standard/garbage-collection/fundamentals.md#background-workstation-garbage-collection) and [Background server garbage collection](../../standard/garbage-collection/fundamentals.md#background-server-garbage-collection).| + +|"System.GC.RetainVM"|true | false|Determines whether segments that should be deleted are put on a standby list for future use (`true`) or are released back to the operating system (`false`, the default value).| + +|"System.GC.Server"|true | false|Determines whether the application uses server garbage collection (`true`) or workstation garbage collection (`false`, the default value). For more information, see [Configuring garbage collection](../../standard/garbage-collection/fundamentals.md#configuring-garbage-collection).| + +json/ev/app.config: + +System.GC.HeapAffinitizeMask//GCHeapAffinitizeMask +System.GC.HeapHardLimit/COMPlus_GCHeapHardLimit/ +System.GC.HeapHardLimitPercent +System.GC.LOHThreshold +System.GC.NoAffinitize//GCNoAffinitize +System.GC.HeapCount//GCHeapCount diff --git a/docs/core/run-time-config/globalization.md b/docs/core/run-time-config/globalization.md new file mode 100644 index 0000000000000..afa38baed434a --- /dev/null +++ b/docs/core/run-time-config/globalization.md @@ -0,0 +1,12 @@ +--- + +--- +# Run-time configuration options for globalization + +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| | | + +runtimeconfig.json + +|"System.Globalization.Invariant"|true | false|Determines whether a .NET Core application runs in globalization invariant mode without access to culture-specific data and behavior (`true`), or whether it has accesses to cultural data (`false`, the default). For more information, see [.NET Core Globalization Invariant Mode](https://github.com/dotnet/corefx/blob/master/Documentation/architecture/globalization-invariant-mode.md).| diff --git a/docs/core/run-time-config/index.md b/docs/core/run-time-config/index.md new file mode 100644 index 0000000000000..bd6ee6f0f7b1a --- /dev/null +++ b/docs/core/run-time-config/index.md @@ -0,0 +1,60 @@ +--- +title: Run-time config +description: Learn how to configure .NET Core applications by using run-time configuration settings. +ms.date: 11/192/2019 +--- +# .NET Core run-time configuration settings + +.NET Core supports the use of configuration files and environment variables to configure the behavior of .NET Core applications at run time. Run-time configuration is an attractive option if: + +- You don't own or control the source code for an application and therefore are unable to configure it programmatically. + +- Multiple instances of your application run at the same time on a single system, and you want to configure each for optimum performance. + +> [!NOTE] +> This documentation is a work in progress. If you notice that the information presented here is either incomplete or inaccurate, either [open an issue](https://github.com/dotnet/docs/issues) to let us know about it, or [submit a pull request](https://github.com/dotnet/docs/pulls) to address the issue. For information on submitting pull requests for the dotnet/docs repo, see the [contributor's guide](https://github.com/dotnet/docs/blob/master/CONTRIBUTING.md). + +.NET Core provides the following mechanisms for configuring applications at run time: + +- The [runtimeconfig.json file](#runtimeconfig-json) + +- [Environment variables](#environment-variables) + +The articles in this section of the documentation include are organized by category, for example, debugging and garbage collection. Available configuration options are shown for *runtimeconfig.json* (.NET Core only), *app.config* (.NET Framework only), and environment variables. + +## runtimeconfig.json + +Specify run-time configuration options in the **configProperties** section of the *runtimeconfig.json* file. This section has the form: + +```json +{ + "runtimeOptions": { + "configProperties": { + "config-property-name1": "config-value1", + "config-property-name2": "config-value2" + } + } +} +``` + +Here is an example file: + +```json +{ + "runtimeOptions": { + "configProperties": { + "System.GC.Concurrent": true, + "System.GC.RetainVM": true, + "System.Threading.ThreadPool.MinThreads": "4", + "System.Threading.ThreadPool.MaxThreads": "25" + } +} +``` + +The *runtimeconfig.json* file is automatically created in the build directory by the [dotnet build](../tools/dotnet-build.md) command. It's also created when you select the **Build** menu option in Visual Studio. You can then edit the file once it's created. + +Some configuration values can also be set programmatically by calling the method. + +## Environment variables + +Environment variables can be used to to supply some run-time configuration information. You can define environment variables from the Windows Control Panel, at the command line, or programmatically by calling on both Windows and Unix-based systems. diff --git a/docs/core/run-time-config/networking.md b/docs/core/run-time-config/networking.md new file mode 100644 index 0000000000000..9f9cca417e185 --- /dev/null +++ b/docs/core/run-time-config/networking.md @@ -0,0 +1,24 @@ +--- + +--- +# Run-time configuration options for networking + +## HTTP/2 protocol + +- Configures whether support for the HTTP/2 protocol is enabled. +- Disabled by default. +- Introduced in .NET Core 3.0. + +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| "System.Net.Http.SocketsHttpHandler.Http2Support" | true

false | `DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP2SUPPORT` | 0 - disabled

1 - enabled | + +## Sockets HTTP handler + +- Configures whether high-level networking APIs, such as , use or the implementation of that's based on [libcurl](https://curl.haxx.se/libcurl/). +- The default is to use . +- You can configure this setting programmatically by calling the method. + +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| "System.Net.Http.UseSocketsHttpHandler" | true

false | `DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER` | 0 - enables the use of

1 - enables the use of | diff --git a/docs/core/run-time-config/profiling.md b/docs/core/run-time-config/profiling.md new file mode 100644 index 0000000000000..eb3e8e62d126b --- /dev/null +++ b/docs/core/run-time-config/profiling.md @@ -0,0 +1,31 @@ +--- + +--- +# Run-time configuration options for profiling + +## Enable profiling + +- Configures whether profiling is enabled for the currently running process. +- Disabled by default. + +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| | | `CORECLR_ENABLE_PROFILING` | 0 - disabled

1 - enabled | + +## Profiler GUID + +|`CORECLR_PROFILER`|*string-guid*|Specifies the GUID of the profiler to load into the currently running process.| + +## Profiler location + +|`CORECLR_PROFILER_PATH`|*string-path*|Specifies the path to the profiler DLL to load into the currently running process.| + +|`CORECLR_PROFILER_PATH_32`|*string-path*|Specifies the path to the profiler DLL to load into the currently running 32-bit process.| + +|`CORECLR_PROFILER_PATH_64`|*string-path*|Specifies the path to the profiler DLL to load into the currently running 64-bit process.| + +## PerfMap + +|`PerfMapEnabled`|0 or 1|Enables (1) or disables (0, the default value) writing */tmp/perf-$pid.map* on Linux systems.| + +|`PerfMapIgnoreSignal`|0 or 1|When `PerfMapEnabled` is set to 1, enables (1) or disables (0, the default value) the specified signal to be accepted and ignored as a marker in the perf logs.| diff --git a/docs/core/run-time-config/threading.md b/docs/core/run-time-config/threading.md new file mode 100644 index 0000000000000..d96811ca3b29a --- /dev/null +++ b/docs/core/run-time-config/threading.md @@ -0,0 +1,19 @@ +--- + +--- +# Run-time configuration options for threading + +## CPU groups + +- Configures whether threads are automatically distributed across CPU groups. +- Disabled by default. + +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| | | `COMPlus_Thread_UseAllCpuGroups` | 0 - disabled
<
1 - enabled | + +runtimeconfig.json: + +|"System.Threading.ThreadPool.MinThreads"|*n*|Specifies the minimum number of threads for the worker threadpool, where *n* is an integer that represents the minimum number of threads. This setting corresponds to the method.| + +|"System.Threading.ThreadPool.MaxThreads"|*n*|Specifies the maximum number of threads for the worker threadpool, where *n* is an integer that represents the maximum number of threads. This setting corresponds to the method.| diff --git a/docs/core/runtime-config/envvars.md b/docs/core/runtime-config/envvars.md deleted file mode 100644 index 12d168bfbc736..0000000000000 --- a/docs/core/runtime-config/envvars.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: "Run-time configuration with environment variables" -description: "Use environment variables to configure the run-time behavior of .NET Core apps." -ms.date: "11/08/2019" ---- -# Run-time configuration with environment variables - -.NET Core supports a number of environment variables that you can use to configure your applications. - -The following sections list selected supported environment variables by category. For a complete list of supported, as well as unsupported and internal environment variables, see [Configuration knobs](https://github.com/dotnet/coreclr/blob/master/Documentation/project-docs/clr-configuration-knobs.md). - -> [!NOTE] -> This documentation is a work in progress. If you notice that the information presented here is either incomplete or inaccurate, either [open an issue](https://github.com/dotnet/docs/issues) to let us know about it, or [submit a pull request](https://github.com/dotnet/docs/pulls) to add or correct the information. For information on submitting pull requests for the dotnet/docs repo, see the [contributor's guide](https://github.com/dotnet/docs/blob/master/CONTRIBUTING.md). - -## Debugging - -|Variable name|Variable value|Description| -|--|--|--| -|`COMPlus_EnableDiagnostics`|0 or 1|Enables (1) or disables (0) debugger and profiler diagnostics.| - -## Garbage collection - -|Variable name|Variable value|Description| -|--|--|--| -|`COMPlus_gcAllowVeryLargeObjects`|0 or 1|Enables (1, the default value) or Disables (0) support on 64-bit platforms for arrays that are greater than 2 gigabytes (GB) in total size.| -|`COMPlus_GCCpuGroup`|0 or 1|Enables (1) or disables (0, the default value) support for CPU groups by the garbage collector if server garbage collection is enabled.| -|`COMPlus_GCLatencyLevel`|see |Adjusts the intrusiveness of the garbage collector. The default value is 1 (). For more information, see [Latency modes](../../standard/garbage-collection/latency.md). -|`COMPlus_GCName`|*string_path*|Specifies a path to the library containing the GC that the runtime intends to load. For more information, see [Standalone GC Loader Design](https://github.com/dotnet/coreclr/blob/4c7c066d0bacdb86a2311333de1ca73d94ae5280/Documentation/design-docs/standalone-gc-loading.md).| - -## Networking - -|Variable name|Variable value|Description| -|--|--|--| -|`DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP2SUPPORT`|0 or 1|Starting with .NET Core 3.0, indicates whether support for the HTTP/2 protocol is enabled (1) or disabled (0, the default value).| -|`DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER`|0 or 1|`1`, the default value, enables the use of with high-level networking APIs. `0` enables the implementation of that's based on [libcurl](https://curl.haxx.se/libcurl/).| - -## Profiling - -|Variable name|Variable value|Description| -|--|--|--| -|`CORECLR_ENABLE_PROFILING`|0 or 1|Enables (1) or disables (0, the default value) profiling for the currently running process.| -|`CORECLR_PROFILER`|*string-guid*|Specifies the GUID of the profiler to load into the currently running process.| -|`CORECLR_PROFILER_PATH`|*string-path*|Specifies the path to the profiler DLL to load into the currently running process.| -|`CORECLR_PROFILER_PATH_32`|*string-path*|Specifies the path to the profiler DLL to load into the currently running 32-bit process.| -|`CORECLR_PROFILER_PATH_64`|*string-path*|Specifies the path to the profiler DLL to load into the currently running 64-bit process.| -|`PerfMapEnabled`|0 or 1|Enables (1) or disables (0, the default value) writing */tmp/perf-$pid.map* on Linux systems.| -|`PerfMapIgnoreSignal`|0 or 1|When `PerfMapEnabled` is set to 1, enables (1) or disables (0, the default value) the specified signal to be accepted and ignored as a marker in the perf logs.| - -## Threading - -|Variable name|Variable value|Description| -|--|--|--| -|`COMPlus_Thread_UseAllCpuGroups`|0 or 1|Enables (1) or disables (0, the default value) automatic distribution threads across CPU groups.| - -## Tiered compilation - -|Variable name|Variable value|Description| -|--|--|--| -|`COMPlus_TieredCompilation`|Enables (1, the default value starting with .NET Core 3.0) or disables (0, the default value in .NET Core 2.1 and 2.2) tiered compilation.| - -## See also - -- [NET Core runtime configuration settings](index.md) diff --git a/docs/core/runtime-config/index.md b/docs/core/runtime-config/index.md deleted file mode 100644 index 537324da7a6d4..0000000000000 --- a/docs/core/runtime-config/index.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: "Runtime configuration settings" -description: "Learn how to configure .NET Core applications by using runtime configuration settings." -ms.date: "06/19/2019" ---- -# .NET Core runtime configuration settings - -.NET Core supports the use of configuration files and environment variables to configure the behavior of .NET Core applications at runtime. Runtime configuration is an attractive option if: - -- You do not own or control the source code for an application and therefore are unable to configure it programmatically. - -- Multiple instances of your application may run at a single time on the same system, and you want to configure each for optimum performance. - -> [!NOTE] -> This documentation is a work in progress. If you notice that the information presented here is either incomplete or inaccurate, either [open an issue](https://github.com/dotnet/docs/issues) to let us know about it, or [submit a pull request](https://github.com/dotnet/docs/pulls) to address the issue. For information on submitting pull requests for the dotnet/docs repo, see the [contributor's guide](https://github.com/dotnet/docs/blob/master/CONTRIBUTING.md). - -.NET Core provides the following mechanisms for configuring applications at runtime: - -- The **configProperties** section of the *runtimeconfig.json* file. This section has the form: - - ```json - { - "runtimeOptions": { - "configProperties": { - "config-property-name1": "config-value1", - "config-property-name2": "config-value2" - } - } - } - ``` - - For example: - - ```json - { - "runtimeOptions": { - "configProperties": { - "System.GC.Concurrent": true, - "System.GC.RetainVM": true, - "System.Threading.ThreadPool.MinThreads": "4", - "System.Threading.ThreadPool.MaxThreads": "25" - } - } - ``` - - The *runtimeconfig.json* file is automatically created in the build directory by the [dotnet build](../tools/dotnet-build.md) command as well as by selecting the **Build** menu option in Visual Studio. You can then edit he file once it is created. - - Some configuration values can also be set programmatically by calling the method. - - See [Runtime configuration with runtimeconfig.json](runtimeconfig.md) for information on the available configuration options in *runtimeconfig.json*. - -- Environment variables. - - You can define an environment variable to supply runtime configuration information. Environment variables can be defined at the command line either interactively or by using a script. They can also be defined programmatically by calling the method on both Windows and Unix-based systems. - - See [Runtime configuration with environment variables](envvars.md) for a selection of the environment variables supported by .NET Core. diff --git a/docs/core/runtime-config/runtimeconfig.md b/docs/core/runtime-config/runtimeconfig.md deleted file mode 100644 index 62015f2ec4cd3..0000000000000 --- a/docs/core/runtime-config/runtimeconfig.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: "Runtime configuration with runtimeconfig.json" -description: "Use the runtime.config.json file to configure the runtime behavior of .NET Core applications." -ms.date: "06/19/2019" ---- -# Runtime configuration with runtimeconfig.json - -You can use the **configProperties** section of the *runtimeconfig.json* file to set designated properties at runtime. - -> [!NOTE] -> This documentation is a work in progress. If you notice that the information presented here is either incomplete or inaccurate, either [open an issue](https://github.com/dotnet/docs/issues) to let us know about it, or [submit a pull request](https://github.com/dotnet/docs/pulls) to add or correct the information. For information on submitting pull requests for the dotnet/docs repo, see the [contributor's guide](https://github.com/dotnet/docs/blob/master/CONTRIBUTING.md). - -## File format - -The *runtimeconfig.json* file has the following format: - -```json -{ - "runtimeOptions": { - "configProperties": { - "config-property-name1": config-value1, - "config-property-name2": config-value2 - } - } -} -``` - -## Individual configuration settings - -The *runtimeconfig.json* file supports the following configuration settings: - -|Name|Value|Description| -|--|--|--| -|"Switch.System.Globalization.EnforceJapaneseEraYearRange"|true | false|Determines whether range checks for calendars that support multiple eras are relaxed (`false`, the default value) or whether dates that overflow an era's date range throw an (`true`). For more information, see [Calendars, eras, and date ranges: Relaxed range checks](../../standard/datetime/working-with-calendars.md#calendars-eras-and-date-ranges-relaxed-range-checks).| -|"Switch.System.Globalization.EnforceLegacyJapaneseDateParsing"|true | false|Determines whether a string that contains either "1" or "Gannen" as the year parses successfully (`false`, the default), or whether only "1" is supported (`true`). For more information, see [Representing dates in calendars with multiple eras](../../standard/datetime/working-with-calendars.md#representing-dates-in-calendars-with-multiple-eras).| -|"Switch.System.Globalization.FormatJapaneseFirstYearAsANumber"|true | false|Determines whether the first year of a Japanese calendar era is formatted as "gannen" (`false`, the default) or as a number. For more information, see [Representing dates in calendars with multiple eras](../../standard/datetime/working-with-calendars.md#representing-dates-in-calendars-with-multiple-eras).| -|"System.GC.Concurrent"|true | false|Determines whether background garbage collection is enabled (`true`, the default value) or disabled (`false`). For more information, see [Background workstation garbage collection](../../standard/garbage-collection/fundamentals.md#background-workstation-garbage-collection) and [Background server garbage collection](../../standard/garbage-collection/fundamentals.md#background-server-garbage-collection).| -|"System.GC.RetainVM"|true | false|Determines whether segments that should be deleted are put on a standby list for future use (`true`) or are released back to the operating system (`false`, the default value).| -|"System.GC.Server"|true | false|Determines whether the application uses server garbage collection (`true`) or workstation garbage collection (`false`, the default value). For more information, see [Configuring garbage collection](../../standard/garbage-collection/fundamentals.md#configuring-garbage-collection).| -|"System.Globalization.Invariant"|true | false|Determines whether a .NET Core application runs in globalization invariant mode without access to culture-specific data and behavior (`true`), or whether it has accesses to cultural data (`false`, the default). For more information, see [.NET Core Globalization Invariant Mode](https://github.com/dotnet/corefx/blob/master/Documentation/architecture/globalization-invariant-mode.md).| -|"System.Net.Http.SocketsHttpHandler.Http2Support"|true | false|Determines whether high-level networking APIs such as use (true, the default value) or the legacy >xref:System.Net.Http.HttpClientHandler> (false).

You can also configure this setting programmatically by calling the method.| -|"System.Net.Http.UseSocketsHttpHandler"|true | false|Determines whether high-level networking APIs such as use (`true`, the default value) or the implementation of that's based on [libcurl](https://curl.haxx.se/libcurl/) (`false`).

You can also configure this setting programmatically by calling the method.| -|"System.Runtime.TieredCompilation"|true | false|Determines whether the JIT compiler uses tiered compilation (`true`, the default value starting with .NET Core 3.0) or disables tiered compilation (`false`, the default value in .NET Core 2.1 and .NET Core 2.2). For more information, see [Tiered compilation](../whats-new/dotnet-core-3-0.md#tiered-compilation).| -|"System.Threading.ThreadPool.MinThreads"|*n*|Specifies the minimum number of threads for the worker threadpool, where *n* is an integer that represents the minimum number of threads. This setting corresponds to the method.| -|"System.Threading.ThreadPool.MaxThreads"|*n*|Specifies the maximum number of threads for the worker threadpool, where *n* is an integer that represents the maximum number of threads. This setting corresponds to the method.| - -## See also - -- [NET Core runtime configuration settings](index.md) diff --git a/docs/core/toc.yml b/docs/core/toc.yml index a667fde7056c7..3d5e6882e1659 100644 --- a/docs/core/toc.yml +++ b/docs/core/toc.yml @@ -54,35 +54,47 @@ href: tutorials/cli-templates-create-template-pack.md - name: Get started with .NET Core on macOS href: tutorials/using-on-macos.md - - name: Get started with .NET Core on macOS using Visual Studio for Mac + - name: Get started with .NET Core using Visual Studio for Mac href: tutorials/using-on-mac-vs.md - - name: Building a complete .NET Core solution on macOS using Visual Studio for Mac + - name: Build a complete .NET Core solution on macOS href: tutorials/using-on-mac-vs-full-solution.md - name: Get started with .NET Core using the CLI tools href: tutorials/using-with-xplat-cli.md - - name: Organizing and testing projects with the .NET Core command line + - name: Organize and test projects with the .NET Core CLI href: tutorials/testing-with-cli.md - - name: Developing Libraries with Cross Platform Tools + - name: Develop libraries with cross-platform tools href: tutorials/libraries.md - - name: Create a .NET Core application with plugins + - name: Create a .NET Core app with plugins href: tutorials/creating-app-with-plugin-support.md - - name: Developing ASP.NET Core applications + - name: Develop ASP.NET Core apps href: tutorials/aspnet-core.md - - name: Hosting .NET Core from native code + - name: Host .NET Core from native code href: tutorials/netcore-hosting.md -- name: Runtime configuration +- name: Run-time configuration items: - - name: Runtime configuration settings - href: runtime-config/index.md - - name: Runtime configuration with runtimeconfig.json - href: runtime-config/runtimeconfig.md - - name: Runtime configuration with environment variables - href: runtime-config/envvars.md -- name: Native Interoperability + - name: Settings + href: run-time-config/index.md + - name: Compilation settings + href: run-time-config/compilation.md + - name: Date and time settings + href: run-time-config/date-time.md + - name: Debugging settings + href: run-time-config/debugging.md + - name: Garbage collector settings + href: run-time-config/garbage-collector.md + - name: Globalization settings + href: run-time-config/globalization.md + - name: Networking settings + href: run-time-config/networking.md + - name: Profiling settings + href: run-time-config/profiling.md + - name: Threading settings + href: run-time-config/threading.md +- name: Native interoperability items: - - name: Exposing .NET Core Components to COM + - name: Expose .NET Core components to COM href: native-interop/expose-components-to-com.md -- name: Packages, Metapackages and Frameworks +- name: Packages, Metapackages, and Frameworks href: packages.md - name: Changes in CLI overview href: tools/cli-msbuild-architecture.md From 5c418b6982db0eec223ec855befcedd75bec3a36 Mon Sep 17 00:00:00 2001 From: Genevieve Warren Date: Wed, 13 Nov 2019 16:40:50 -0800 Subject: [PATCH 03/18] first draft of config knobs --- docs/core/run-time-config/compilation.md | 5 +- docs/core/run-time-config/date-time.md | 16 -- docs/core/run-time-config/debugging.md | 5 +- .../core/run-time-config/garbage-collector.md | 145 ++++++++++++++++-- docs/core/run-time-config/globalization.md | 43 +++++- docs/core/run-time-config/index.md | 15 +- docs/core/run-time-config/networking.md | 5 +- docs/core/run-time-config/profiling.md | 37 ++++- docs/core/run-time-config/threading.md | 23 ++- docs/core/toc.yml | 2 - .../datetime/working-with-calendars.md | 64 ++++---- 11 files changed, 275 insertions(+), 85 deletions(-) delete mode 100644 docs/core/run-time-config/date-time.md diff --git a/docs/core/run-time-config/compilation.md b/docs/core/run-time-config/compilation.md index afbd4e7458434..6a31d32a132ef 100644 --- a/docs/core/run-time-config/compilation.md +++ b/docs/core/run-time-config/compilation.md @@ -1,5 +1,8 @@ --- - +title: Compilation config settings +description: Learn about run-time settings for configuring how the JIT compiler works. +ms.date: 11/13/2019 +ms.topic: reference --- # Run-time configuration options for compilation diff --git a/docs/core/run-time-config/date-time.md b/docs/core/run-time-config/date-time.md deleted file mode 100644 index 25d27bcb5e28c..0000000000000 --- a/docs/core/run-time-config/date-time.md +++ /dev/null @@ -1,16 +0,0 @@ ---- - ---- -# Run-time configuration options for dates and times - -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| | | - -runtimeconfig.json: - -|"Switch.System.Globalization.EnforceJapaneseEraYearRange"|true | false|Determines whether range checks for calendars that support multiple eras are relaxed (`false`, the default value) or whether dates that overflow an era's date range throw an (`true`). For more information, see [Calendars, eras, and date ranges: Relaxed range checks](../../standard/datetime/working-with-calendars.md#calendars-eras-and-date-ranges-relaxed-range-checks).| - -|"Switch.System.Globalization.EnforceLegacyJapaneseDateParsing"|true | false|Determines whether a string that contains either "1" or "Gannen" as the year parses successfully (`false`, the default), or whether only "1" is supported (`true`). For more information, see [Representing dates in calendars with multiple eras](../../standard/datetime/working-with-calendars.md#representing-dates-in-calendars-with-multiple-eras).| - -|"Switch.System.Globalization.FormatJapaneseFirstYearAsANumber"|true | false|Determines whether the first year of a Japanese calendar era is formatted as "gannen" (`false`, the default) or as a number. For more information, see [Representing dates in calendars with multiple eras](../../standard/datetime/working-with-calendars.md#representing-dates-in-calendars-with-multiple-eras).| diff --git a/docs/core/run-time-config/debugging.md b/docs/core/run-time-config/debugging.md index 5c6312417527f..ec6d8793901fa 100644 --- a/docs/core/run-time-config/debugging.md +++ b/docs/core/run-time-config/debugging.md @@ -1,5 +1,8 @@ --- - +title: Debugging config settings +description: Learn about run-time settings for configuring debugging. +ms.date: 11/13/2019 +ms.topic: reference --- # Run-time configuration settings for debugging diff --git a/docs/core/run-time-config/garbage-collector.md b/docs/core/run-time-config/garbage-collector.md index 8b0e940ea6e00..baafdeb80dba3 100644 --- a/docs/core/run-time-config/garbage-collector.md +++ b/docs/core/run-time-config/garbage-collector.md @@ -1,5 +1,8 @@ --- - +title: Garbage collector config settings +description: Learn about run-time settings for configuring how the garbage collector manages memory. +ms.date: 11/13/2019 +ms.topic: reference --- # Run-time configuration options for garbage collection @@ -14,29 +17,141 @@ ## CPU groups -|`COMPlus_GCCpuGroup`|0 or 1|Enables (1) or disables (0, the default value) support for CPU groups by the garbage collector if server garbage collection is enabled.| +- Apples to server garbage collection (GC) only. +- Configures whether the garbage collector uses CPU groups or not. When a computer has multiple CPU groups, enabling this element extends garbage collection across all CPU groups. The garbage collector uses all cores to create and balance heaps. +- Disabled by default. +- The corresponding setting for .NET Framework apps is [GCCpuGroup](../../framework/configure-apps/file-schema/runtime/gccpugroup-element.md). + +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| | | `COMPlus_GCCpuGroup` | 0 - disabled

1 - enabled | ## Latency level -|`COMPlus_GCLatencyLevel`|see |Adjusts the intrusiveness of the garbage collector. The default value is 1 (). For more information, see [Latency modes](../../standard/garbage-collection/latency.md). +- Adjusts the intrusiveness of the garbage collector into running apps. +- The default latency level is . +- For more information, see [Latency modes](../../standard/garbage-collection/latency.md). + +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| | | `COMPlus_GCLatencyLevel` | 0 -

1 -

2 -

3 - | ## GC name -|`COMPlus_GCName`|*string_path*|Specifies a path to the library containing the GC that the runtime intends to load. For more information, see [Standalone GC Loader Design](https://github.com/dotnet/coreclr/blob/4c7c066d0bacdb86a2311333de1ca73d94ae5280/Documentation/design-docs/standalone-gc-loading.md).| +- Specifies a path to the library containing the garbage collector that the runtime intends to load. +- For more information, see [Standalone GC Loader Design](https://github.com/dotnet/coreclr/blob/master/Documentation/design-docs/standalone-gc-loading.md). + +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| | | `COMPlus_GCName` | *string_path* | + +## Background versus non-concurrent + +- Configures whether background (concurrent) garbage collection is enabled. +- Enabled by default. +- For more information, see [Background garbage collection](../../standard/garbage-collection/fundamentals.md#background-garbage-collection) and [Background server garbage collection](../../standard/garbage-collection/fundamentals.md#background-server-garbage-collection). +- The corresponding setting for .NET Framework apps is [gcConcurrent](../../framework/configure-apps/file-schema/runtime/gcconcurrent-element.md). + +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| "System.GC.Concurrent" | true - background GC

false - non-concurrent GC | `COMPlus_gcConcurrent` | | + +## Retain virtual memory + +- Configures whether segments that should be deleted are put on a standby list for future use or are released back to the operating system (OS). +- By default, segments are released back to the operating system. + +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| "System.GC.RetainVM" | true - put on standby

false - release to OS | `COMPlus_GCRetainVM` | 0

1 | + +## Workstation versus server + +- Configures whether the application uses server garbage collection or workstation garbage collection. +- Workstation garbage collection is the default. +- For more information, see [Configure garbage collection](../../standard/garbage-collection/fundamentals.md#configure-garbage-collection). +- The corresponding setting for .NET Framework apps is [GCServer](../../framework/configure-apps/file-schema/runtime/gcserver-element.md). + +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| "System.GC.Server" | true - server

false - workstation | `COMPlus_gcServer` | 0

1 | + +## Specific processors + +- Applies to server garbage collection (GC) only. +- If processor affinity is enabled, specifies the exact processors for which a GC heap and threads are created. +- The decimal value is a mask that defines the processors that are available to the process. +- Introduced in .NET Core 3.0. +- The corresponding setting for .NET Framework apps is [GCHeapAffinitizeMask](../../framework/configure-apps/file-schema/runtime/gcheapaffinitizemask-element.md). + +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| "System.GC.HeapAffinitizeMask" | *decimal value* | `COMPlus_GCHeapAffinitizeMask` | | + +## No processor affinity + +- Applies to server garbage collection (GC) only. +- Specifies whether to affinitize garbage collection threads with processors. That is, whether to create a dedicated heap, GC thread, and background GC thread (if background garbage collection is enabled) for each processor. +- By default, garbage collection threads are affinitized with processors (value = `false`). Because the garbage collector uses all available processors in server GC, this can result in poor performance, particularly on systems with multiple running instances of a server application. +- Introduced in .NET Core 3.0. +- The corresponding setting for .NET Framework apps is [GCNoAffinitize](../../framework/configure-apps/file-schema/runtime/gcnoaffinitize-element.md). + +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| "System.GC.NoAffinitize" | true - don't affinitize

false - affinitize | `COMPlus_GCNoAffinitize` | 0

1 | + +## Limit number of heaps + +- Applies to server garbage collection (GC) only. +- Limits the number of heaps created by the garbage collector. +- If GC thread/processor affinity is disabled, this setting limits the number of GC heaps. If GC thread/processor affinity is enabled, this setting limits the number of GC heaps to the processors 0 to one-less-than its specified value. +- This setting is typically used together with "System.GC.HeapAffinitizeMask" and "System.GC.NoAffinitize". For more information, see the [GCHeapCount remarks](../../framework/configure-apps/file-schema/runtime/gcheapcount-element.md#remarks). +- Introduced in .NET Core 3.0. +- The corresponding setting for .NET Framework apps is [GCHeapCount](../../framework/configure-apps/file-schema/runtime/gcheapcount-element.md). + +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| "System.GC.HeapCount" | *number* | `COMPlus_GCHeapCount` | | + +## Processor numbers + +- Applies to server garbage collection (GC) only. +- Specifies the list of processors to use for garbage collector threads. + +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| "System.GC.GCHeapAffinitizeRanges" | Comma-separated list of processor numbers or ranges of processor numbers.

Example: "1,3,7-9,12" | `COMPlus_GCHeapAffinitizeRanges` | | + +## Heap size limit + +- Specifies the maximum commit size for the GC heap. +- Introduced in .NET Core 3.0. + +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| "System.GC.HeapHardLimit" | *number* | `COMPlus_GCHeapHardLimit` | *number* | -runtimeconfig.json +## Heap usage as percentage -|"System.GC.Concurrent"|true | false|Determines whether background garbage collection is enabled (`true`, the default value) or disabled (`false`). For more information, see [Background workstation garbage collection](../../standard/garbage-collection/fundamentals.md#background-workstation-garbage-collection) and [Background server garbage collection](../../standard/garbage-collection/fundamentals.md#background-server-garbage-collection).| +- Specifies the GC heap usage as a percentage of the total memory. +- Introduced in .NET Core 3.0. -|"System.GC.RetainVM"|true | false|Determines whether segments that should be deleted are put on a standby list for future use (`true`) or are released back to the operating system (`false`, the default value).| +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| "System.GC.HeapHardLimitPercent" | | `COMPlus_GCHeapHardLimitPercent` | | -|"System.GC.Server"|true | false|Determines whether the application uses server garbage collection (`true`) or workstation garbage collection (`false`, the default value). For more information, see [Configuring garbage collection](../../standard/garbage-collection/fundamentals.md#configuring-garbage-collection).| +## Large object heap size limit -json/ev/app.config: +- Specifies the threshold size that causes objects to go on the large object heap (LOH). -System.GC.HeapAffinitizeMask//GCHeapAffinitizeMask -System.GC.HeapHardLimit/COMPlus_GCHeapHardLimit/ -System.GC.HeapHardLimitPercent -System.GC.LOHThreshold -System.GC.NoAffinitize//GCNoAffinitize -System.GC.HeapCount//GCHeapCount +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| "System.GC.LOHThreshold" | | `COMPlus_GCLOHThreshold` | | + +## Large pages + +- Specifies whether large pages should be used when a heap hard limit is set. + +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| "System.GC.GCLargePages" | | `COMPlus_GCLargePages` | | diff --git a/docs/core/run-time-config/globalization.md b/docs/core/run-time-config/globalization.md index afa38baed434a..34a5f3a680059 100644 --- a/docs/core/run-time-config/globalization.md +++ b/docs/core/run-time-config/globalization.md @@ -1,12 +1,47 @@ --- - +title: Globalization config settings +description: Learn about run-time settings for configuring globalization aspects of an app, for example, how it parses Japanese dates. +ms.date: 11/13/2019 +ms.topic: reference --- # Run-time configuration options for globalization +## Invariant mode + +- Determines whether a .NET Core app runs in globalization invariant mode without access to culture-specific data and behavior or whether it has access to cultural data. +- The default is to run the app with access to cultural data (value = `false`). +- For more information, see [.NET Core Globalization Invariant Mode](https://github.com/dotnet/corefx/blob/master/Documentation/architecture/globalization-invariant-mode.md). + +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| "System.Globalization.Invariant" | true - no access to cultural data

false - access to cultural data | | | + +## Era year ranges + +- Determines whether range checks for calendars that support multiple eras are relaxed or whether dates that overflow an era's date range throw an . +- The default value is that range check are relaxed (value = `false`). +- For more information, see [Calendars, eras, and date ranges: Relaxed range checks](../../standard/datetime/working-with-calendars.md#calendars-eras-and-date-ranges-relaxed-range-checks). + | runtimeconfig.json | Values | Environment variable | Values | | - | - | - | - | -| | | +| "Switch.System.Globalization.EnforceJapaneseEraYearRange" | true - overflows cause an exception

false - relaxed range checks | | | -runtimeconfig.json +## Japanese date parsing -|"System.Globalization.Invariant"|true | false|Determines whether a .NET Core application runs in globalization invariant mode without access to culture-specific data and behavior (`true`), or whether it has accesses to cultural data (`false`, the default). For more information, see [.NET Core Globalization Invariant Mode](https://github.com/dotnet/corefx/blob/master/Documentation/architecture/globalization-invariant-mode.md).| +- Determines whether a string that contains either "1" or "Gannen" as the year parses successfully or whether only "1" is supported. +- The default value is to parse strings that contain either "1" or "Gannen" as the year (value = `false`). +- For more information, see [Represent dates in calendars with multiple eras](../../standard/datetime/working-with-calendars.md#represent-dates-in-calendars-with-multiple-eras). + +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| "Switch.System.Globalization.EnforceLegacyJapaneseDateParsing" | true - only "1" is supported

false - "Gannen" or "1" is supported | | | + +## Japanese year format + +- Determines whether the first year of a Japanese calendar era is formatted as "gannen" or as a number. +- The default is to format the first year as "gannen" (value = `false`). +- For more information, see [Represent dates in calendars with multiple eras](../../standard/datetime/working-with-calendars.md#represent-dates-in-calendars-with-multiple-eras). + +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| "Switch.System.Globalization.FormatJapaneseFirstYearAsANumber" | true - format as number

false - format as "gannen" | | | diff --git a/docs/core/run-time-config/index.md b/docs/core/run-time-config/index.md index bd6ee6f0f7b1a..e3b2e6530e63a 100644 --- a/docs/core/run-time-config/index.md +++ b/docs/core/run-time-config/index.md @@ -57,4 +57,17 @@ Some configuration values can also be set programmatically by calling the on both Windows and Unix-based systems. +Environment variables can be used to to supply some run-time configuration information. Configuration knobs specified as environment variables generally have the prefix **COMPlus_**. + +You can define environment variables from the Windows Control Panel, at the command line, or programmatically by calling on both Windows and Unix-based systems. The following examples show how to set an environment variable at the command line: + +```shell +# Windows +set COMPlus_GCRetainVM=1 + +# Powershell +$env:COMPlus_GCRetainVM="1" + +# Unix +export COMPlus_GCRetainVM=1 +``` diff --git a/docs/core/run-time-config/networking.md b/docs/core/run-time-config/networking.md index 9f9cca417e185..1ab2b2232f70f 100644 --- a/docs/core/run-time-config/networking.md +++ b/docs/core/run-time-config/networking.md @@ -1,5 +1,8 @@ --- - +title: Networking config settings +description: Learn about run-time settings for configuring networking. +ms.date: 11/13/2019 +ms.topic: reference --- # Run-time configuration options for networking diff --git a/docs/core/run-time-config/profiling.md b/docs/core/run-time-config/profiling.md index eb3e8e62d126b..055b4064086ff 100644 --- a/docs/core/run-time-config/profiling.md +++ b/docs/core/run-time-config/profiling.md @@ -1,5 +1,8 @@ --- - +title: Profiling config settings +description: Learn about run-time settings for configuring profiling. +ms.date: 11/13/2019 +ms.topic: reference --- # Run-time configuration options for profiling @@ -14,18 +17,36 @@ ## Profiler GUID -|`CORECLR_PROFILER`|*string-guid*|Specifies the GUID of the profiler to load into the currently running process.| +- Specifies the GUID of the profiler to load into the currently running process. + +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| | | `CORECLR_PROFILER` | *string-guid* | ## Profiler location -|`CORECLR_PROFILER_PATH`|*string-path*|Specifies the path to the profiler DLL to load into the currently running process.| +- Specifies the path to the profiler DLL to load into the currently running process (or 32-bit or 64-bit process). -|`CORECLR_PROFILER_PATH_32`|*string-path*|Specifies the path to the profiler DLL to load into the currently running 32-bit process.| +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| | | `CORECLR_PROFILER_PATH` | *string-path* | +| | | `CORECLR_PROFILER_PATH_32` | *string-path* | +| | | `CORECLR_PROFILER_PATH_64` | *string-path* | -|`CORECLR_PROFILER_PATH_64`|*string-path*|Specifies the path to the profiler DLL to load into the currently running 64-bit process.| +## Write perf map -## PerfMap +- Enables or disables writing */tmp/perf-$pid.map* on Linux systems. +- Disabled by default -|`PerfMapEnabled`|0 or 1|Enables (1) or disables (0, the default value) writing */tmp/perf-$pid.map* on Linux systems.| +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| | | `PerfMapEnabled` | 0 - disable

1 - enable | + +## Perf log markers + +- When `PerfMapEnabled` is set to 1, enables or disables the specified signal to be accepted and ignored as a marker in the perf logs. +- Disabled by default. -|`PerfMapIgnoreSignal`|0 or 1|When `PerfMapEnabled` is set to 1, enables (1) or disables (0, the default value) the specified signal to be accepted and ignored as a marker in the perf logs.| +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| | | `PerfMapIgnoreSignal` | 0 - disable

1 - enable | diff --git a/docs/core/run-time-config/threading.md b/docs/core/run-time-config/threading.md index d96811ca3b29a..3968553787fc4 100644 --- a/docs/core/run-time-config/threading.md +++ b/docs/core/run-time-config/threading.md @@ -1,5 +1,8 @@ --- - +title: Threading config settings +description: Learn about run-time settings for configuring threading. +ms.date: 11/13/2019 +ms.topic: reference --- # Run-time configuration options for threading @@ -12,8 +15,20 @@ | - | - | - | - | | | | `COMPlus_Thread_UseAllCpuGroups` | 0 - disabled
<
1 - enabled | -runtimeconfig.json: +## Minimum threads + +- Specifies the minimum number of threads for the worker threadpool. +- Corresponds to the method. + +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| "System.Threading.ThreadPool.MinThreads" | An integer that represents the minimum number of threads | | | + +## Maximum threads -|"System.Threading.ThreadPool.MinThreads"|*n*|Specifies the minimum number of threads for the worker threadpool, where *n* is an integer that represents the minimum number of threads. This setting corresponds to the method.| +- Specifies the maximum number of threads for the worker threadpool. +- Corresponds to the method. -|"System.Threading.ThreadPool.MaxThreads"|*n*|Specifies the maximum number of threads for the worker threadpool, where *n* is an integer that represents the maximum number of threads. This setting corresponds to the method.| +| runtimeconfig.json | Values | Environment variable | Values | +| - | - | - | - | +| "System.Threading.ThreadPool.MaxThreads" | An integer that represents the maximum number of threads | | | diff --git a/docs/core/toc.yml b/docs/core/toc.yml index 3d5e6882e1659..1e2b73a5bca50 100644 --- a/docs/core/toc.yml +++ b/docs/core/toc.yml @@ -76,8 +76,6 @@ href: run-time-config/index.md - name: Compilation settings href: run-time-config/compilation.md - - name: Date and time settings - href: run-time-config/date-time.md - name: Debugging settings href: run-time-config/debugging.md - name: Garbage collector settings diff --git a/docs/standard/datetime/working-with-calendars.md b/docs/standard/datetime/working-with-calendars.md index 5d1e2f218df03..11b5bf3ba033b 100644 --- a/docs/standard/datetime/working-with-calendars.md +++ b/docs/standard/datetime/working-with-calendars.md @@ -14,7 +14,7 @@ helpviewer_keywords: - "culture, calendars" ms.assetid: 0c1534e5-979b-4c8a-a588-1c24301aefb3 --- -# Working with calendars +# Work with calendars Although a date and time value represents a moment in time, its string representation is culture-sensitive and depends both on the conventions used for displaying date and time values by a specific culture and on the calendar used by that culture. This topic explores the support for calendars in .NET and discusses the use of the calendar classes when working with date values. @@ -86,7 +86,7 @@ The following example illustrates this difference between [!code-csharp[Conceptual.Calendars#3](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.calendars/cs/datesandcalendars2.cs#3)] [!code-vb[Conceptual.Calendars#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.calendars/vb/datesandcalendars2.vb#3)] -### Instantiating dates based on a calendar +### Instantiate dates based on a calendar Because and values are based on the Gregorian calendar, you must call an overloaded constructor that includes a parameter of type to instantiate a date value if you want to use the day, month, or year values from a different calendar. You can also call one of the overloads of a specific calendar's method to instantiate a object based on the values of a particular calendar. @@ -95,7 +95,7 @@ The following example instantiates one value by passing a [!code-csharp[Conceptual.Calendars#4](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.calendars/cs/instantiatehcdate1.cs#4)] [!code-vb[Conceptual.Calendars#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.calendars/vb/instantiatehcdate1.vb#4)] -### Representing dates in the current calendar +### Represent dates in the current calendar Date and time formatting methods always use the current calendar when converting dates to strings. This means that the string representation of the year, the month, and the day of the month reflect the current calendar, and do not necessarily reflect the Gregorian calendar. @@ -104,7 +104,7 @@ The following example shows how the current calendar affects the string represen [!code-csharp[Conceptual.Calendars#5](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.calendars/cs/currentcalendar1.cs#5)] [!code-vb[Conceptual.Calendars#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.calendars/vb/currentcalendar1.vb#5)] -### Representing dates in a non-current calendar +### Represent dates in a non-current calendar To represent a date using a calendar that is not the current calendar of a particular culture, you must call methods of that object. For example, the , , and methods convert the year, month, and day to values that reflect a particular calendar. @@ -125,7 +125,7 @@ However, there is one important exception. The default (uninitialized) value of [!code-csharp[Conceptual.Calendars#11](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.calendars/cs/minsupporteddatetime1.cs#11)] [!code-vb[Conceptual.Calendars#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.calendars/vb/minsupporteddatetime1.vb#11)] -## Working with eras +## Work with eras Calendars typically divide dates into eras. However, the classes in .NET do not support every era defined by a calendar, and most of the classes support only a single era. Only the and classes support multiple eras. @@ -163,7 +163,7 @@ The name that corresponds to a particular era number can be retrieved by passing In addition, the "g" custom date and time format string includes a calendar's era name in the string representation of a date and time. For more information, see [Custom date and time format strings](../../../docs/standard/base-types/custom-date-and-time-format-strings.md). -### Instantiating a date with an era +### Instantiatie a date with an era For the two classes that support multiple eras, a date that consists of a particular year, month, and day of the month value can be ambiguous. For example, all eras supported by the have years whose number is 1. Ordinarily, if an era is not specified, both date and time and calendar methods assume that values belong to the current era. This is true of the and constructors that include parameters of type , as well as the [JapaneseCalendar.ToDateTime](xref:System.Globalization.Calendar.ToDateTime(System.Int32,System.Int32,System.Int32,System.Int32,System.Int32,System.Int32,System.Int32)) and [JapaneseLunisolarCalendar.ToDateTime](xref:System.Globalization.Calendar.ToDateTime(System.Int32,System.Int32,System.Int32,System.Int32,System.Int32,System.Int32,System.Int32)) methods. The following example instantiates a date that represents January 1 of the second year of an unspecified era. If you execute the example when the Reiwa era is the current era, the date is interpreted as the second year of the Reiwa era. The era, 令和, precedes the year in the string returned by the method and corresponds to January 1, 2020, in the Gregorian calendar. (The Reiwa era begins in the year 2019 of the Gregorian calendar.) @@ -210,7 +210,7 @@ The following example attempts to instantiate a date in the 65th year of the Sho If relaxed range checks are undesirable, you can restore strict range checks in a number of ways, depending on the version of .NET on which your application is running: -- **.NET Core:** You can add the following to the *.netcore.runtime.json* config file: +- **.NET Core:** Add the following to the *.netcore.runtime.json* config file: ```json "runtimeOptions": { @@ -220,7 +220,7 @@ If relaxed range checks are undesirable, you can restore strict range checks in } ``` -- **.NET Framework 4.6 or later:** You can set the following AppContext switch: +- **.NET Framework 4.6 or later:** Set the following AppContext switch in the *app.config* file: ```xml @@ -231,14 +231,14 @@ If relaxed range checks are undesirable, you can restore strict range checks in ``` -- **.NET Framework 4.5.2 or earlier:** You can set the following registry value: +- **.NET Framework 4.5.2 or earlier:** Set the following registry value: | | | |--|--| - |Key | HKEY_LOCAL_MACHINE\Software\Microsoft\.NETFramework\AppContext | - |Name | Switch.System.Globalization.EnforceJapaneseEraYearRanges | - |Type | REG_SZ | - |Value | true | + | **Key** | **HKEY_LOCAL_MACHINE\Software\Microsoft\\.NETFramework\AppContext** | + | **Name** | Switch.System.Globalization.EnforceJapaneseEraYearRanges | + | **Type** | REG_SZ | + | **Value** | true | With strict range checks enabled, the previous example throws an and displays the following output: @@ -250,7 +250,7 @@ Parameter name: year at Example.Main() ``` -### Representing dates in calendars with multiple eras +### Represent dates in calendars with multiple eras If a object supports eras and is the current calendar of a object, the era is included in the string representation of a date and time value for the full date and time, long date, and short date patterns. The following example displays these date patterns when the current culture is Japan (Japanese) and the current calendar is the Japanese calendar. @@ -278,14 +278,14 @@ In the Japanese calendars, the first year of an era is called Gannen (元年). F - [The year/month pattern](../base-types/standard-date-and-time-format-strings.md#YearMonth), indicated by the Y" or "y" standard date and time format string. - [The "ggy'年'" or "ggy年" [custom date and time format string](../base-types/custom-date-and-time-format-strings.md). -For example, the following example displays a date in the first year of the Heisei era in the . +For example, the following example displays a date in the first year of the Heisei era in the . [!code-csharp[gannen](~/samples/snippets/standard/datetime/calendars/gannen/cs/program.cs)] [!code-vb[gannen](~/samples/snippets/standard/datetime/calendars/gannen/vb/gannen-fmt.vb)] -If this behavior is undesirable in formatting operations, you can restore the previous behavior, which always represents the first year of an era as “1” rather than “Gannen”, by doing the following, depending on the version of .NET: +If this behavior is undesirable in formatting operations, you can restore the previous behavior, which always represents the first year of an era as "1" rather than "Gannen", by doing the following, depending on the version of .NET: -- **.NET Core:** You can add the following to the *.netcore.runtime.json* config file: +- **.NET Core:** Add the following to the *.netcore.runtime.json* config file: ```json "runtimeOptions": { @@ -295,7 +295,7 @@ If this behavior is undesirable in formatting operations, you can restore the pr } ``` -- **.NET Framework 4.6 or later:** You can set the following AppContext switch: +- **.NET Framework 4.6 or later:** Set the following AppContext switch in the *app.config* file: ```xml @@ -306,14 +306,14 @@ If this behavior is undesirable in formatting operations, you can restore the pr ``` -- **.NET Framework 4.5.2 or earlier:** You can set the following registry value: +- **.NET Framework 4.5.2 or earlier:** Set the following registry value: | | | |--|--| - |Key | HKEY_LOCAL_MACHINE\Software\Microsoft\.NETFramework\AppContext | - |Name | Switch.System.Globalization.FormatJapaneseFirstYearAsANumber | - |Type | REG_SZ | - |Value | true | + | **Key** | **HKEY_LOCAL_MACHINE\Software\Microsoft\\.NETFramework\AppContext** | + | **Name** | Switch.System.Globalization.FormatJapaneseFirstYearAsANumber | + | **Type** | REG_SZ | + | **Value** | true | With gannen support in formatting operations disabled, the previous example displays the following output: @@ -321,9 +321,9 @@ With gannen support in formatting operations disabled, the previous example disp Japanese calendar date: 平成1年8月18日 (Gregorian: Friday, August 18, 1989) ``` -.NET has also been updated so that date and time parsing operations support strings that contain the year represented as either "1" or Gannen. Although you should not need to do this, you can restore the previous behavior to recognizes only “1” as the first year of an era. You can do this as follows, depending on the version of .NET: +.NET has also been updated so that date and time parsing operations support strings that contain the year represented as either "1" or Gannen. Although you should not need to do this, you can restore the previous behavior to recognizes only "1" as the first year of an era. You can do this as follows, depending on the version of .NET: -- **.NET Core:** You can add the following to the *.netcore.runtime.json* config file: +- **.NET Core:** Add the following to the *.netcore.runtime.json* config file: ```json "runtimeOptions": { @@ -333,7 +333,7 @@ Japanese calendar date: 平成1年8月18日 (Gregorian: Friday, August 18, 1989) } ``` -- **.NET Framework 4.6 or later:** You can set the following AppContext switch: +- **.NET Framework 4.6 or later:** Set the following AppContext switch in the *app.config* file: ```xml @@ -344,14 +344,14 @@ Japanese calendar date: 平成1年8月18日 (Gregorian: Friday, August 18, 1989) ``` -- **.NET Framework 4.5.2 or earlier:** You can set the following registry value: +- **.NET Framework 4.5.2 or earlier:** Set the following registry value: | | | - |--|--| - |Key | HKEY_LOCAL_MACHINE\Software\Microsoft\.NETFramework\AppContext | - |Name | Switch.System.Globalization.EnforceLegacyJapaneseDateParsing | - |Type | REG_SZ | - |Value | true | + |--|--| + | **Key** | **HKEY_LOCAL_MACHINE\Software\Microsoft\\.NETFramework\AppContext** | + | **Name** | Switch.System.Globalization.EnforceLegacyJapaneseDateParsing | + | **Type** | REG_SZ | + | **Value** | true | ## See also From 9b57e0e5fff6a94321f9245a0c3b9650de2d1ad5 Mon Sep 17 00:00:00 2001 From: Genevieve Warren Date: Wed, 13 Nov 2019 18:23:32 -0800 Subject: [PATCH 04/18] pivot the table format --- docs/core/run-time-config/compilation.md | 7 +- docs/core/run-time-config/debugging.md | 7 +- .../core/run-time-config/garbage-collector.md | 110 ++++++++++-------- docs/core/run-time-config/globalization.md | 28 +++-- docs/core/run-time-config/index.md | 8 +- docs/core/run-time-config/networking.md | 14 ++- docs/core/run-time-config/profiling.md | 39 ++++--- docs/core/run-time-config/threading.md | 21 ++-- 8 files changed, 134 insertions(+), 100 deletions(-) diff --git a/docs/core/run-time-config/compilation.md b/docs/core/run-time-config/compilation.md index 6a31d32a132ef..f73315fa04d5d 100644 --- a/docs/core/run-time-config/compilation.md +++ b/docs/core/run-time-config/compilation.md @@ -12,6 +12,7 @@ ms.topic: reference - In .NET Core 3.0 and later, tiered compilation is enabled by default. - In .NET Core 2.1 and 2.2, tiered compilation is disabled by default. -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| "System.Runtime.TieredCompilation" | `true` - enabled

`false` - disabled | `COMPlus_TieredCompilation` | 1 - enabled

0 - disabled | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | `System.Runtime.TieredCompilation` | `true` - enabled
`false` - disabled | +| **Environment variable** | `COMPlus_TieredCompilation` | (DWORD)
0 - disabled
1 - enabled | diff --git a/docs/core/run-time-config/debugging.md b/docs/core/run-time-config/debugging.md index ec6d8793901fa..a0aede2fc3771 100644 --- a/docs/core/run-time-config/debugging.md +++ b/docs/core/run-time-config/debugging.md @@ -8,6 +8,7 @@ ms.topic: reference ## Debugger and profiler diagnostics -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| | | `COMPlus_EnableDiagnostics` | 0 - disabled

1 - enabled | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | | | +| **Environment variable** | `COMPlus_EnableDiagnostics` | (DWORD)
0 - disabled
1 - enabled | diff --git a/docs/core/run-time-config/garbage-collector.md b/docs/core/run-time-config/garbage-collector.md index baafdeb80dba3..c06c3ca563297 100644 --- a/docs/core/run-time-config/garbage-collector.md +++ b/docs/core/run-time-config/garbage-collector.md @@ -11,9 +11,10 @@ ms.topic: reference - Configures garbage collector support on 64-bit platforms for arrays that are greater than 2 gigabytes (GB) in total size. - Enabled by default. -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| | | `COMPlus_gcAllowVeryLargeObjects` | 0 - disabled

1 - enabled | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | | | +| **Environment variable** | `COMPlus_gcAllowVeryLargeObjects` | (DWORD)
0 - disabled
1 - enabled | ## CPU groups @@ -22,9 +23,10 @@ ms.topic: reference - Disabled by default. - The corresponding setting for .NET Framework apps is [GCCpuGroup](../../framework/configure-apps/file-schema/runtime/gccpugroup-element.md). -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| | | `COMPlus_GCCpuGroup` | 0 - disabled

1 - enabled | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | | | +| **Environment variable** | `COMPlus_GCCpuGroup` | (DWORD)
0 - disabled
1 - enabled | ## Latency level @@ -32,49 +34,54 @@ ms.topic: reference - The default latency level is . - For more information, see [Latency modes](../../standard/garbage-collection/latency.md). -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| | | `COMPlus_GCLatencyLevel` | 0 -

1 -

2 -

3 - | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | | | +| **Environment variable** | `COMPlus_GCLatencyLevel` | (DWORD)
0 -
1 -
2 -
3 - | ## GC name - Specifies a path to the library containing the garbage collector that the runtime intends to load. - For more information, see [Standalone GC Loader Design](https://github.com/dotnet/coreclr/blob/master/Documentation/design-docs/standalone-gc-loading.md). -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| | | `COMPlus_GCName` | *string_path* | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | | | +| **Environment variable** | `COMPlus_GCName` | *string_path* | ## Background versus non-concurrent - Configures whether background (concurrent) garbage collection is enabled. - Enabled by default. -- For more information, see [Background garbage collection](../../standard/garbage-collection/fundamentals.md#background-garbage-collection) and [Background server garbage collection](../../standard/garbage-collection/fundamentals.md#background-server-garbage-collection). +- For more information, see [Background garbage collection](../../standard/garbage-collection/fundamentals.md#background-workstation-garbage-collection) and [Background server garbage collection](../../standard/garbage-collection/fundamentals.md#background-server-garbage-collection). - The corresponding setting for .NET Framework apps is [gcConcurrent](../../framework/configure-apps/file-schema/runtime/gcconcurrent-element.md). -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| "System.GC.Concurrent" | true - background GC

false - non-concurrent GC | `COMPlus_gcConcurrent` | | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | `System.GC.Concurrent` | true - background GC
false - non-concurrent GC | +| **Environment variable** | `COMPlus_gcConcurrent` | | ## Retain virtual memory - Configures whether segments that should be deleted are put on a standby list for future use or are released back to the operating system (OS). - By default, segments are released back to the operating system. -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| "System.GC.RetainVM" | true - put on standby

false - release to OS | `COMPlus_GCRetainVM` | 0

1 | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | `System.GC.RetainVM` | true - put on standby
false - release to OS | +| **Environment variable** | `COMPlus_GCRetainVM` | (DWORD)
0
1 | ## Workstation versus server - Configures whether the application uses server garbage collection or workstation garbage collection. - Workstation garbage collection is the default. -- For more information, see [Configure garbage collection](../../standard/garbage-collection/fundamentals.md#configure-garbage-collection). +- For more information, see [Configure garbage collection](../../standard/garbage-collection/fundamentals.md#configuring-garbage-collection). - The corresponding setting for .NET Framework apps is [GCServer](../../framework/configure-apps/file-schema/runtime/gcserver-element.md). -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| "System.GC.Server" | true - server

false - workstation | `COMPlus_gcServer` | 0

1 | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | `System.GC.Server` | true - server
false - workstation | +| **Environment variable** | `COMPlus_gcServer` | (DWORD)
0
1 | ## Specific processors @@ -84,9 +91,10 @@ ms.topic: reference - Introduced in .NET Core 3.0. - The corresponding setting for .NET Framework apps is [GCHeapAffinitizeMask](../../framework/configure-apps/file-schema/runtime/gcheapaffinitizemask-element.md). -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| "System.GC.HeapAffinitizeMask" | *decimal value* | `COMPlus_GCHeapAffinitizeMask` | | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | `System.GC.HeapAffinitizeMask` | *decimal value* | +| **Environment variable** | `COMPlus_GCHeapAffinitizeMask` | | ## No processor affinity @@ -96,9 +104,10 @@ ms.topic: reference - Introduced in .NET Core 3.0. - The corresponding setting for .NET Framework apps is [GCNoAffinitize](../../framework/configure-apps/file-schema/runtime/gcnoaffinitize-element.md). -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| "System.GC.NoAffinitize" | true - don't affinitize

false - affinitize | `COMPlus_GCNoAffinitize` | 0

1 | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | `System.GC.NoAffinitize` | true - don't affinitize
false - affinitize | +| **Environment variable** | `COMPlus_GCNoAffinitize` | (DWORD)
0
1 | ## Limit number of heaps @@ -109,49 +118,56 @@ ms.topic: reference - Introduced in .NET Core 3.0. - The corresponding setting for .NET Framework apps is [GCHeapCount](../../framework/configure-apps/file-schema/runtime/gcheapcount-element.md). -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| "System.GC.HeapCount" | *number* | `COMPlus_GCHeapCount` | | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | `System.GC.HeapCount` | *number* | +| **Environment variable** | `COMPlus_GCHeapCount` | | ## Processor numbers - Applies to server garbage collection (GC) only. - Specifies the list of processors to use for garbage collector threads. -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| "System.GC.GCHeapAffinitizeRanges" | Comma-separated list of processor numbers or ranges of processor numbers.

Example: "1,3,7-9,12" | `COMPlus_GCHeapAffinitizeRanges` | | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | `System.GC.GCHeapAffinitizeRanges` | Comma-separated list of processor numbers or ranges of processor numbers.
Example: "1,3,7-9,12" | +| **Environment variable** | `COMPlus_GCHeapAffinitizeRanges` | | ## Heap size limit - Specifies the maximum commit size for the GC heap. - Introduced in .NET Core 3.0. -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| "System.GC.HeapHardLimit" | *number* | `COMPlus_GCHeapHardLimit` | *number* | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | `System.GC.HeapHardLimit` | *number* | +| **Environment variable** | +| "System.GC.HeapHardLimit" | *number* | `COMPlus_GCHeapHardLimit` | (DWORD) *number* | ## Heap usage as percentage - Specifies the GC heap usage as a percentage of the total memory. - Introduced in .NET Core 3.0. -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| "System.GC.HeapHardLimitPercent" | | `COMPlus_GCHeapHardLimitPercent` | | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | `System.GC.HeapHardLimitPercent` | | +| **Environment variable** | `COMPlus_GCHeapHardLimitPercent` | | ## Large object heap size limit - Specifies the threshold size that causes objects to go on the large object heap (LOH). -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| "System.GC.LOHThreshold" | | `COMPlus_GCLOHThreshold` | | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | `System.GC.LOHThreshold` | | +| **Environment variable** | `COMPlus_GCLOHThreshold` | | ## Large pages - Specifies whether large pages should be used when a heap hard limit is set. -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| "System.GC.GCLargePages" | | `COMPlus_GCLargePages` | | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | `System.GC.GCLargePages` | | +| **Environment variable** | `COMPlus_GCLargePages` | | diff --git a/docs/core/run-time-config/globalization.md b/docs/core/run-time-config/globalization.md index 34a5f3a680059..86a2d7c76bf9d 100644 --- a/docs/core/run-time-config/globalization.md +++ b/docs/core/run-time-config/globalization.md @@ -12,9 +12,10 @@ ms.topic: reference - The default is to run the app with access to cultural data (value = `false`). - For more information, see [.NET Core Globalization Invariant Mode](https://github.com/dotnet/corefx/blob/master/Documentation/architecture/globalization-invariant-mode.md). -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| "System.Globalization.Invariant" | true - no access to cultural data

false - access to cultural data | | | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | `System.Globalization.Invariant` | true - no access to cultural data
false - access to cultural data | +| **Environment variable** | | | ## Era year ranges @@ -22,9 +23,10 @@ ms.topic: reference - The default value is that range check are relaxed (value = `false`). - For more information, see [Calendars, eras, and date ranges: Relaxed range checks](../../standard/datetime/working-with-calendars.md#calendars-eras-and-date-ranges-relaxed-range-checks). -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| "Switch.System.Globalization.EnforceJapaneseEraYearRange" | true - overflows cause an exception

false - relaxed range checks | | | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | `Switch.System.Globalization.EnforceJapaneseEraYearRange` | true - overflows cause an exception
false - relaxed range checks | +| **Environment variable** | | | ## Japanese date parsing @@ -32,9 +34,10 @@ ms.topic: reference - The default value is to parse strings that contain either "1" or "Gannen" as the year (value = `false`). - For more information, see [Represent dates in calendars with multiple eras](../../standard/datetime/working-with-calendars.md#represent-dates-in-calendars-with-multiple-eras). -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| "Switch.System.Globalization.EnforceLegacyJapaneseDateParsing" | true - only "1" is supported

false - "Gannen" or "1" is supported | | | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | `Switch.System.Globalization.EnforceLegacyJapaneseDateParsing` | true - only "1" is supported
false - "Gannen" or "1" is supported | +| **Environment variable** | | | ## Japanese year format @@ -42,6 +45,7 @@ ms.topic: reference - The default is to format the first year as "gannen" (value = `false`). - For more information, see [Represent dates in calendars with multiple eras](../../standard/datetime/working-with-calendars.md#represent-dates-in-calendars-with-multiple-eras). -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| "Switch.System.Globalization.FormatJapaneseFirstYearAsANumber" | true - format as number

false - format as "gannen" | | | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | `Switch.System.Globalization.FormatJapaneseFirstYearAsANumber` | true - format as number
false - format as "gannen" | +| **Environment variable** | | | diff --git a/docs/core/run-time-config/index.md b/docs/core/run-time-config/index.md index e3b2e6530e63a..aa3cb50b420dd 100644 --- a/docs/core/run-time-config/index.md +++ b/docs/core/run-time-config/index.md @@ -1,7 +1,7 @@ --- title: Run-time config description: Learn how to configure .NET Core applications by using run-time configuration settings. -ms.date: 11/192/2019 +ms.date: 11/13/2019 --- # .NET Core run-time configuration settings @@ -16,7 +16,7 @@ ms.date: 11/192/2019 .NET Core provides the following mechanisms for configuring applications at run time: -- The [runtimeconfig.json file](#runtimeconfig-json) +- The [runtimeconfig.json file](#runtimeconfigjson) - [Environment variables](#environment-variables) @@ -59,7 +59,9 @@ Some configuration values can also be set programmatically by calling the on both Windows and Unix-based systems. The following examples show how to set an environment variable at the command line: +You can define environment variables from the Windows Control Panel, at the command line, or programmatically by calling on both Windows and Unix-based systems. + +The following examples show how to set an environment variable at the command line: ```shell # Windows diff --git a/docs/core/run-time-config/networking.md b/docs/core/run-time-config/networking.md index 1ab2b2232f70f..2fc7c1e135ba2 100644 --- a/docs/core/run-time-config/networking.md +++ b/docs/core/run-time-config/networking.md @@ -12,9 +12,10 @@ ms.topic: reference - Disabled by default. - Introduced in .NET Core 3.0. -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| "System.Net.Http.SocketsHttpHandler.Http2Support" | true

false | `DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP2SUPPORT` | 0 - disabled

1 - enabled | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | `System.Net.Http.SocketsHttpHandler.Http2Support` | true
false | +| **Environment variable** | `DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP2SUPPORT` | (DWORD)
0 - disabled
1 - enabled | ## Sockets HTTP handler @@ -22,6 +23,7 @@ ms.topic: reference - The default is to use . - You can configure this setting programmatically by calling the method. -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| "System.Net.Http.UseSocketsHttpHandler" | true

false | `DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER` | 0 - enables the use of

1 - enables the use of | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | `System.Net.Http.UseSocketsHttpHandler` | true
false | +| **Environment variable** | `DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER` | (DWORD)
0 - enables the use of
1 - enables the use of | diff --git a/docs/core/run-time-config/profiling.md b/docs/core/run-time-config/profiling.md index 055b4064086ff..c8b4cecb688c2 100644 --- a/docs/core/run-time-config/profiling.md +++ b/docs/core/run-time-config/profiling.md @@ -11,42 +11,47 @@ ms.topic: reference - Configures whether profiling is enabled for the currently running process. - Disabled by default. -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| | | `CORECLR_ENABLE_PROFILING` | 0 - disabled

1 - enabled | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | | | +| **Environment variable** | `CORECLR_ENABLE_PROFILING` | (DWORD)
0 - disabled
1 - enabled | ## Profiler GUID - Specifies the GUID of the profiler to load into the currently running process. -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| | | `CORECLR_PROFILER` | *string-guid* | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | | | +| **Environment variable** | `CORECLR_PROFILER` | *string-guid* | ## Profiler location - Specifies the path to the profiler DLL to load into the currently running process (or 32-bit or 64-bit process). -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| | | `CORECLR_PROFILER_PATH` | *string-path* | -| | | `CORECLR_PROFILER_PATH_32` | *string-path* | -| | | `CORECLR_PROFILER_PATH_64` | *string-path* | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | | | +| **Environment variable** | `CORECLR_PROFILER_PATH` | *string-path* | +| **Environment variable** | `CORECLR_PROFILER_PATH_32` | *string-path* | +| **Environment variable** | `CORECLR_PROFILER_PATH_64` | *string-path* | ## Write perf map - Enables or disables writing */tmp/perf-$pid.map* on Linux systems. - Disabled by default -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| | | `PerfMapEnabled` | 0 - disable

1 - enable | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | | | +| **Environment variable** | `PerfMapEnabled` | (DWORD)
0 - disable
1 - enable | ## Perf log markers - When `PerfMapEnabled` is set to 1, enables or disables the specified signal to be accepted and ignored as a marker in the perf logs. - Disabled by default. -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| | | `PerfMapIgnoreSignal` | 0 - disable

1 - enable | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | | | +| **Environment variable** | `PerfMapIgnoreSignal` | (DWORD)
0 - disable
1 - enable | diff --git a/docs/core/run-time-config/threading.md b/docs/core/run-time-config/threading.md index 3968553787fc4..1bf88ee3f81a8 100644 --- a/docs/core/run-time-config/threading.md +++ b/docs/core/run-time-config/threading.md @@ -11,24 +11,27 @@ ms.topic: reference - Configures whether threads are automatically distributed across CPU groups. - Disabled by default. -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| | | `COMPlus_Thread_UseAllCpuGroups` | 0 - disabled
<
1 - enabled | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | | | +| **Environment variable** | `COMPlus_Thread_UseAllCpuGroups` | (DWORD)
0 - disabled<
1 - enabled | ## Minimum threads - Specifies the minimum number of threads for the worker threadpool. - Corresponds to the method. -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| "System.Threading.ThreadPool.MinThreads" | An integer that represents the minimum number of threads | | | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | `System.Threading.ThreadPool.MinThreads` | An integer that represents the minimum number of threads | +| **Environment variable** | | | ## Maximum threads - Specifies the maximum number of threads for the worker threadpool. - Corresponds to the method. -| runtimeconfig.json | Values | Environment variable | Values | -| - | - | - | - | -| "System.Threading.ThreadPool.MaxThreads" | An integer that represents the maximum number of threads | | | +| | Setting name | Values | +| - | - | - | +| **runtimeconfig.json** | `System.Threading.ThreadPool.MaxThreads` | An integer that represents the maximum number of threads | +| **Environment variable** | | | From da9bf211905941cf88ab7e70fad73601aeb44393 Mon Sep 17 00:00:00 2001 From: Genevieve Warren Date: Wed, 13 Nov 2019 18:32:48 -0800 Subject: [PATCH 05/18] add app.config to table --- docs/core/run-time-config/garbage-collector.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/core/run-time-config/garbage-collector.md b/docs/core/run-time-config/garbage-collector.md index c06c3ca563297..6e89ec6c9f2f4 100644 --- a/docs/core/run-time-config/garbage-collector.md +++ b/docs/core/run-time-config/garbage-collector.md @@ -21,12 +21,12 @@ ms.topic: reference - Apples to server garbage collection (GC) only. - Configures whether the garbage collector uses CPU groups or not. When a computer has multiple CPU groups, enabling this element extends garbage collection across all CPU groups. The garbage collector uses all cores to create and balance heaps. - Disabled by default. -- The corresponding setting for .NET Framework apps is [GCCpuGroup](../../framework/configure-apps/file-schema/runtime/gccpugroup-element.md). | | Setting name | Values | | - | - | - | | **runtimeconfig.json** | | | | **Environment variable** | `COMPlus_GCCpuGroup` | (DWORD)
0 - disabled
1 - enabled | +| **app.config for .NET Framework** | [GCCpuGroup](../../framework/configure-apps/file-schema/runtime/gccpugroup-element.md) | | ## Latency level @@ -54,12 +54,12 @@ ms.topic: reference - Configures whether background (concurrent) garbage collection is enabled. - Enabled by default. - For more information, see [Background garbage collection](../../standard/garbage-collection/fundamentals.md#background-workstation-garbage-collection) and [Background server garbage collection](../../standard/garbage-collection/fundamentals.md#background-server-garbage-collection). -- The corresponding setting for .NET Framework apps is [gcConcurrent](../../framework/configure-apps/file-schema/runtime/gcconcurrent-element.md). | | Setting name | Values | | - | - | - | | **runtimeconfig.json** | `System.GC.Concurrent` | true - background GC
false - non-concurrent GC | | **Environment variable** | `COMPlus_gcConcurrent` | | +| **app.config for .NET Framework** | [gcConcurrent](../../framework/configure-apps/file-schema/runtime/gcconcurrent-element.md) | | ## Retain virtual memory @@ -76,12 +76,12 @@ ms.topic: reference - Configures whether the application uses server garbage collection or workstation garbage collection. - Workstation garbage collection is the default. - For more information, see [Configure garbage collection](../../standard/garbage-collection/fundamentals.md#configuring-garbage-collection). -- The corresponding setting for .NET Framework apps is [GCServer](../../framework/configure-apps/file-schema/runtime/gcserver-element.md). | | Setting name | Values | | - | - | - | | **runtimeconfig.json** | `System.GC.Server` | true - server
false - workstation | | **Environment variable** | `COMPlus_gcServer` | (DWORD)
0
1 | +| **app.config for .NET Framework** | [GCServer](../../framework/configure-apps/file-schema/runtime/gcserver-element.md) | | ## Specific processors @@ -89,12 +89,12 @@ ms.topic: reference - If processor affinity is enabled, specifies the exact processors for which a GC heap and threads are created. - The decimal value is a mask that defines the processors that are available to the process. - Introduced in .NET Core 3.0. -- The corresponding setting for .NET Framework apps is [GCHeapAffinitizeMask](../../framework/configure-apps/file-schema/runtime/gcheapaffinitizemask-element.md). | | Setting name | Values | | - | - | - | | **runtimeconfig.json** | `System.GC.HeapAffinitizeMask` | *decimal value* | | **Environment variable** | `COMPlus_GCHeapAffinitizeMask` | | +| **app.config for .NET Framework** | [GCHeapAffinitizeMask](../../framework/configure-apps/file-schema/runtime/gcheapaffinitizemask-element.md) | | ## No processor affinity @@ -102,12 +102,12 @@ ms.topic: reference - Specifies whether to affinitize garbage collection threads with processors. That is, whether to create a dedicated heap, GC thread, and background GC thread (if background garbage collection is enabled) for each processor. - By default, garbage collection threads are affinitized with processors (value = `false`). Because the garbage collector uses all available processors in server GC, this can result in poor performance, particularly on systems with multiple running instances of a server application. - Introduced in .NET Core 3.0. -- The corresponding setting for .NET Framework apps is [GCNoAffinitize](../../framework/configure-apps/file-schema/runtime/gcnoaffinitize-element.md). | | Setting name | Values | | - | - | - | | **runtimeconfig.json** | `System.GC.NoAffinitize` | true - don't affinitize
false - affinitize | | **Environment variable** | `COMPlus_GCNoAffinitize` | (DWORD)
0
1 | +| **app.config for .NET Framework** | [GCNoAffinitize](../../framework/configure-apps/file-schema/runtime/gcnoaffinitize-element.md) | | ## Limit number of heaps @@ -116,12 +116,12 @@ ms.topic: reference - If GC thread/processor affinity is disabled, this setting limits the number of GC heaps. If GC thread/processor affinity is enabled, this setting limits the number of GC heaps to the processors 0 to one-less-than its specified value. - This setting is typically used together with "System.GC.HeapAffinitizeMask" and "System.GC.NoAffinitize". For more information, see the [GCHeapCount remarks](../../framework/configure-apps/file-schema/runtime/gcheapcount-element.md#remarks). - Introduced in .NET Core 3.0. -- The corresponding setting for .NET Framework apps is [GCHeapCount](../../framework/configure-apps/file-schema/runtime/gcheapcount-element.md). | | Setting name | Values | | - | - | - | | **runtimeconfig.json** | `System.GC.HeapCount` | *number* | | **Environment variable** | `COMPlus_GCHeapCount` | | +| **app.config for .NET Framework** | [GCHeapCount](../../framework/configure-apps/file-schema/runtime/gcheapcount-element.md) | | ## Processor numbers @@ -141,8 +141,7 @@ ms.topic: reference | | Setting name | Values | | - | - | - | | **runtimeconfig.json** | `System.GC.HeapHardLimit` | *number* | -| **Environment variable** | -| "System.GC.HeapHardLimit" | *number* | `COMPlus_GCHeapHardLimit` | (DWORD) *number* | +| **Environment variable** | `COMPlus_GCHeapHardLimit` | (DWORD) *number* | ## Heap usage as percentage From e46fa24e6646d6c0065e6a10e85676d3fadafa9e Mon Sep 17 00:00:00 2001 From: Genevieve Warren Date: Mon, 18 Nov 2019 11:51:15 -0800 Subject: [PATCH 06/18] remove non-gc config pages for a separate pr --- docs/core/run-time-config/compilation.md | 18 ------- docs/core/run-time-config/debugging.md | 14 ------ docs/core/run-time-config/globalization.md | 51 ------------------- docs/core/run-time-config/networking.md | 29 ----------- docs/core/run-time-config/profiling.md | 57 ---------------------- docs/core/run-time-config/threading.md | 37 -------------- docs/core/toc.yml | 12 ----- 7 files changed, 218 deletions(-) delete mode 100644 docs/core/run-time-config/compilation.md delete mode 100644 docs/core/run-time-config/debugging.md delete mode 100644 docs/core/run-time-config/globalization.md delete mode 100644 docs/core/run-time-config/networking.md delete mode 100644 docs/core/run-time-config/profiling.md delete mode 100644 docs/core/run-time-config/threading.md diff --git a/docs/core/run-time-config/compilation.md b/docs/core/run-time-config/compilation.md deleted file mode 100644 index f73315fa04d5d..0000000000000 --- a/docs/core/run-time-config/compilation.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Compilation config settings -description: Learn about run-time settings for configuring how the JIT compiler works. -ms.date: 11/13/2019 -ms.topic: reference ---- -# Run-time configuration options for compilation - -## Tiered compilation - -- Configures whether the JIT compiler uses [tiered compilation](../whats-new/dotnet-core-3-0.md#tiered-compilation). -- In .NET Core 3.0 and later, tiered compilation is enabled by default. -- In .NET Core 2.1 and 2.2, tiered compilation is disabled by default. - -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | `System.Runtime.TieredCompilation` | `true` - enabled
`false` - disabled | -| **Environment variable** | `COMPlus_TieredCompilation` | (DWORD)
0 - disabled
1 - enabled | diff --git a/docs/core/run-time-config/debugging.md b/docs/core/run-time-config/debugging.md deleted file mode 100644 index a0aede2fc3771..0000000000000 --- a/docs/core/run-time-config/debugging.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Debugging config settings -description: Learn about run-time settings for configuring debugging. -ms.date: 11/13/2019 -ms.topic: reference ---- -# Run-time configuration settings for debugging - -## Debugger and profiler diagnostics - -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | | | -| **Environment variable** | `COMPlus_EnableDiagnostics` | (DWORD)
0 - disabled
1 - enabled | diff --git a/docs/core/run-time-config/globalization.md b/docs/core/run-time-config/globalization.md deleted file mode 100644 index 86a2d7c76bf9d..0000000000000 --- a/docs/core/run-time-config/globalization.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Globalization config settings -description: Learn about run-time settings for configuring globalization aspects of an app, for example, how it parses Japanese dates. -ms.date: 11/13/2019 -ms.topic: reference ---- -# Run-time configuration options for globalization - -## Invariant mode - -- Determines whether a .NET Core app runs in globalization invariant mode without access to culture-specific data and behavior or whether it has access to cultural data. -- The default is to run the app with access to cultural data (value = `false`). -- For more information, see [.NET Core Globalization Invariant Mode](https://github.com/dotnet/corefx/blob/master/Documentation/architecture/globalization-invariant-mode.md). - -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | `System.Globalization.Invariant` | true - no access to cultural data
false - access to cultural data | -| **Environment variable** | | | - -## Era year ranges - -- Determines whether range checks for calendars that support multiple eras are relaxed or whether dates that overflow an era's date range throw an . -- The default value is that range check are relaxed (value = `false`). -- For more information, see [Calendars, eras, and date ranges: Relaxed range checks](../../standard/datetime/working-with-calendars.md#calendars-eras-and-date-ranges-relaxed-range-checks). - -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | `Switch.System.Globalization.EnforceJapaneseEraYearRange` | true - overflows cause an exception
false - relaxed range checks | -| **Environment variable** | | | - -## Japanese date parsing - -- Determines whether a string that contains either "1" or "Gannen" as the year parses successfully or whether only "1" is supported. -- The default value is to parse strings that contain either "1" or "Gannen" as the year (value = `false`). -- For more information, see [Represent dates in calendars with multiple eras](../../standard/datetime/working-with-calendars.md#represent-dates-in-calendars-with-multiple-eras). - -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | `Switch.System.Globalization.EnforceLegacyJapaneseDateParsing` | true - only "1" is supported
false - "Gannen" or "1" is supported | -| **Environment variable** | | | - -## Japanese year format - -- Determines whether the first year of a Japanese calendar era is formatted as "gannen" or as a number. -- The default is to format the first year as "gannen" (value = `false`). -- For more information, see [Represent dates in calendars with multiple eras](../../standard/datetime/working-with-calendars.md#represent-dates-in-calendars-with-multiple-eras). - -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | `Switch.System.Globalization.FormatJapaneseFirstYearAsANumber` | true - format as number
false - format as "gannen" | -| **Environment variable** | | | diff --git a/docs/core/run-time-config/networking.md b/docs/core/run-time-config/networking.md deleted file mode 100644 index 2fc7c1e135ba2..0000000000000 --- a/docs/core/run-time-config/networking.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Networking config settings -description: Learn about run-time settings for configuring networking. -ms.date: 11/13/2019 -ms.topic: reference ---- -# Run-time configuration options for networking - -## HTTP/2 protocol - -- Configures whether support for the HTTP/2 protocol is enabled. -- Disabled by default. -- Introduced in .NET Core 3.0. - -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | `System.Net.Http.SocketsHttpHandler.Http2Support` | true
false | -| **Environment variable** | `DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP2SUPPORT` | (DWORD)
0 - disabled
1 - enabled | - -## Sockets HTTP handler - -- Configures whether high-level networking APIs, such as , use or the implementation of that's based on [libcurl](https://curl.haxx.se/libcurl/). -- The default is to use . -- You can configure this setting programmatically by calling the method. - -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | `System.Net.Http.UseSocketsHttpHandler` | true
false | -| **Environment variable** | `DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER` | (DWORD)
0 - enables the use of
1 - enables the use of | diff --git a/docs/core/run-time-config/profiling.md b/docs/core/run-time-config/profiling.md deleted file mode 100644 index c8b4cecb688c2..0000000000000 --- a/docs/core/run-time-config/profiling.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: Profiling config settings -description: Learn about run-time settings for configuring profiling. -ms.date: 11/13/2019 -ms.topic: reference ---- -# Run-time configuration options for profiling - -## Enable profiling - -- Configures whether profiling is enabled for the currently running process. -- Disabled by default. - -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | | | -| **Environment variable** | `CORECLR_ENABLE_PROFILING` | (DWORD)
0 - disabled
1 - enabled | - -## Profiler GUID - -- Specifies the GUID of the profiler to load into the currently running process. - -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | | | -| **Environment variable** | `CORECLR_PROFILER` | *string-guid* | - -## Profiler location - -- Specifies the path to the profiler DLL to load into the currently running process (or 32-bit or 64-bit process). - -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | | | -| **Environment variable** | `CORECLR_PROFILER_PATH` | *string-path* | -| **Environment variable** | `CORECLR_PROFILER_PATH_32` | *string-path* | -| **Environment variable** | `CORECLR_PROFILER_PATH_64` | *string-path* | - -## Write perf map - -- Enables or disables writing */tmp/perf-$pid.map* on Linux systems. -- Disabled by default - -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | | | -| **Environment variable** | `PerfMapEnabled` | (DWORD)
0 - disable
1 - enable | - -## Perf log markers - -- When `PerfMapEnabled` is set to 1, enables or disables the specified signal to be accepted and ignored as a marker in the perf logs. -- Disabled by default. - -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | | | -| **Environment variable** | `PerfMapIgnoreSignal` | (DWORD)
0 - disable
1 - enable | diff --git a/docs/core/run-time-config/threading.md b/docs/core/run-time-config/threading.md deleted file mode 100644 index 1bf88ee3f81a8..0000000000000 --- a/docs/core/run-time-config/threading.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Threading config settings -description: Learn about run-time settings for configuring threading. -ms.date: 11/13/2019 -ms.topic: reference ---- -# Run-time configuration options for threading - -## CPU groups - -- Configures whether threads are automatically distributed across CPU groups. -- Disabled by default. - -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | | | -| **Environment variable** | `COMPlus_Thread_UseAllCpuGroups` | (DWORD)
0 - disabled<
1 - enabled | - -## Minimum threads - -- Specifies the minimum number of threads for the worker threadpool. -- Corresponds to the method. - -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | `System.Threading.ThreadPool.MinThreads` | An integer that represents the minimum number of threads | -| **Environment variable** | | | - -## Maximum threads - -- Specifies the maximum number of threads for the worker threadpool. -- Corresponds to the method. - -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | `System.Threading.ThreadPool.MaxThreads` | An integer that represents the maximum number of threads | -| **Environment variable** | | | diff --git a/docs/core/toc.yml b/docs/core/toc.yml index 1e2b73a5bca50..bdd26ed1d5b89 100644 --- a/docs/core/toc.yml +++ b/docs/core/toc.yml @@ -74,20 +74,8 @@ items: - name: Settings href: run-time-config/index.md - - name: Compilation settings - href: run-time-config/compilation.md - - name: Debugging settings - href: run-time-config/debugging.md - name: Garbage collector settings href: run-time-config/garbage-collector.md - - name: Globalization settings - href: run-time-config/globalization.md - - name: Networking settings - href: run-time-config/networking.md - - name: Profiling settings - href: run-time-config/profiling.md - - name: Threading settings - href: run-time-config/threading.md - name: Native interoperability items: - name: Expose .NET Core components to COM From 5803b6058e8271a97669337f82e359332eba382e Mon Sep 17 00:00:00 2001 From: Genevieve Warren Date: Mon, 18 Nov 2019 15:43:06 -0800 Subject: [PATCH 07/18] almost there --- .../core/run-time-config/garbage-collector.md | 254 ++++++++++-------- 1 file changed, 139 insertions(+), 115 deletions(-) diff --git a/docs/core/run-time-config/garbage-collector.md b/docs/core/run-time-config/garbage-collector.md index 6e89ec6c9f2f4..22772caf40ea4 100644 --- a/docs/core/run-time-config/garbage-collector.md +++ b/docs/core/run-time-config/garbage-collector.md @@ -6,167 +6,191 @@ ms.topic: reference --- # Run-time configuration options for garbage collection -## Large objects +This page contains information about garbage collector (GC) settings that can be changed at run time. If you're trying to achieve peak performance of a running app, consider using these settings. However, most users will not need to concern themselves with these settings. -- Configures garbage collector support on 64-bit platforms for arrays that are greater than 2 gigabytes (GB) in total size. -- Enabled by default. +On this page, settings are arranged into groups of settings that you can use in conjunction with each other to achieve a specific result. -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | | | -| **Environment variable** | `COMPlus_gcAllowVeryLargeObjects` | (DWORD)
0 - disabled
1 - enabled | +> [!NOTE] +> +> - These settings can also be changed dynamically by the app as it's running, so any run-time settings you set may be overridden. +> - Some settings, such as [latency level](../../standard/garbage-collection/latency.md)), are typically set only through the API at design time. Such settings are omitted from this page. -## CPU groups +## Flavors of garbage collection -- Apples to server garbage collection (GC) only. -- Configures whether the garbage collector uses CPU groups or not. When a computer has multiple CPU groups, enabling this element extends garbage collection across all CPU groups. The garbage collector uses all cores to create and balance heaps. -- Disabled by default. +The main two flavors of garbage collection are workstation and server. For more information about differences between the two, see [Fundamentals of garbage collection](../../standard/garbage-collection/fundamentals.md#workstation-and-server-garbage-collection). The sub-flavors of garbage collection are background and non-concurrent. Use the settings described in this section to select these flavors of garbage collection. -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | | | -| **Environment variable** | `COMPlus_GCCpuGroup` | (DWORD)
0 - disabled
1 - enabled | -| **app.config for .NET Framework** | [GCCpuGroup](../../framework/configure-apps/file-schema/runtime/gccpugroup-element.md) | | +### System.GC.Server/COMPlus_gcServer -## Latency level +- Configures whether the application uses workstation garbage collection or server garbage collection. +- Default: Workstation garbage collection (`false`). +- For more information, see [Configure garbage collection](../../standard/garbage-collection/fundamentals.md#configuring-garbage-collection). -- Adjusts the intrusiveness of the garbage collector into running apps. -- The default latency level is . -- For more information, see [Latency modes](../../standard/garbage-collection/latency.md). +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | `System.GC.Server` | `true` - server
`false` - workstation | .NET Core 1.0 | +| **Environment variable** | `COMPlus_gcServer` | 0 - workstation
1 - server | .NET Core 1.0 | +| **app.config for .NET Framework** | [GCServer](../../framework/configure-apps/file-schema/runtime/gcserver-element.md) | `true` - server
`false` - workstation | | -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | | | -| **Environment variable** | `COMPlus_GCLatencyLevel` | (DWORD)
0 -
1 -
2 -
3 - | +### System.GC.Concurrent/COMPlus_gcConcurrent -## GC name +- Configures whether background (concurrent) garbage collection is enabled. +- Default: Enabled (`true`). +- For more information, see [Background garbage collection](../../standard/garbage-collection/fundamentals.md#background-workstation-garbage-collection) and [Background server garbage collection](../../standard/garbage-collection/fundamentals.md#background-server-garbage-collection). -- Specifies a path to the library containing the garbage collector that the runtime intends to load. -- For more information, see [Standalone GC Loader Design](https://github.com/dotnet/coreclr/blob/master/Documentation/design-docs/standalone-gc-loading.md). +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | `System.GC.Concurrent` | `true` - background GC
`false` - non-concurrent GC | .NET Core 1.0 | +| **Environment variable** | `COMPlus_gcConcurrent` | `true` - background GC
`false` - non-concurrent GC | .NET Core 1.0 | +| **app.config for .NET Framework** | [gcConcurrent](../../framework/configure-apps/file-schema/runtime/gcconcurrent-element.md) | `true` - background GC
`false` - non-concurrent GC | | -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | | | -| **Environment variable** | `COMPlus_GCName` | *string_path* | +## Manage resource usage -## Background versus non-concurrent +Use the settings described in this section to manage the garbage collector's memory and processor usage. -- Configures whether background (concurrent) garbage collection is enabled. -- Enabled by default. -- For more information, see [Background garbage collection](../../standard/garbage-collection/fundamentals.md#background-workstation-garbage-collection) and [Background server garbage collection](../../standard/garbage-collection/fundamentals.md#background-server-garbage-collection). +For more information about some of these settings, see the [Middle ground between workstation and server GC](https://devblogs.microsoft.com/dotnet/middle-ground-between-server-and-workstation-gc/) blog entry. + +### System.GC.HeapCount/COMPlus_GCHeapCount + +- Limits the number of heaps created by the garbage collector. +- Applies to server garbage collection (GC) only. +- If GC thread/processor affinity is disabled, this setting limits the number of GC heaps. If GC thread/processor affinity is enabled, this setting limits the number of GC heaps to the processors 0 to one-less-than its specified value. +- For more information, see the [GCHeapCount remarks](../../framework/configure-apps/file-schema/runtime/gcheapcount-element.md#remarks). + +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | `System.GC.HeapCount` | *number* | .NET Core 3.0 | +| **Environment variable** | `COMPlus_GCHeapCount` | *number* | .NET Core 3.0 | +| **app.config for .NET Framework** | [GCHeapCount](../../framework/configure-apps/file-schema/runtime/gcheapcount-element.md) | *number* | | + +### System.GC.HeapHardLimit/COMPlus_GCHeapHardLimit + +- Specifies the maximum commit size for the GC heap. -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | `System.GC.Concurrent` | true - background GC
false - non-concurrent GC | -| **Environment variable** | `COMPlus_gcConcurrent` | | -| **app.config for .NET Framework** | [gcConcurrent](../../framework/configure-apps/file-schema/runtime/gcconcurrent-element.md) | | +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | `System.GC.HeapHardLimit` | *number* | .NET Core 3.0 | +| **Environment variable** | `COMPlus_GCHeapHardLimit` | *number* | .NET Core 3.0 | -## Retain virtual memory +### System.GC.HeapHardLimitPercent/COMPlus_GCHeapHardLimitPercent + +- Specifies the GC heap usage as a percentage of the total memory. + +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | `System.GC.HeapHardLimitPercent` | | .NET Core 3.0 | +| **Environment variable** | `COMPlus_GCHeapHardLimitPercent` | | .NET Core 3.0 | + +### System.GC.RetainVM/COMPlus_GCRetainVM - Configures whether segments that should be deleted are put on a standby list for future use or are released back to the operating system (OS). - By default, segments are released back to the operating system. -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | `System.GC.RetainVM` | true - put on standby
false - release to OS | -| **Environment variable** | `COMPlus_GCRetainVM` | (DWORD)
0
1 | +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | `System.GC.RetainVM` | `true` - put on standby
`false` - release to OS | .NET Core 1.0 | +| **Environment variable** | `COMPlus_GCRetainVM` | 0
1 | .NET Core 1.0 | -## Workstation versus server +### System.GC.HeapAffinitizeMask/COMPlus_GCHeapAffinitizeMask -- Configures whether the application uses server garbage collection or workstation garbage collection. -- Workstation garbage collection is the default. -- For more information, see [Configure garbage collection](../../standard/garbage-collection/fundamentals.md#configuring-garbage-collection). +- Specifies the exact processors that garbage collector threads should use as a bit mask. +- If processor affinity is disabled by setting `System.GC.NoAffinitize` to `true`, this setting is ignored. +- Applies to server garbage collection (GC) only. +- The decimal value is a bit mask that defines the processors that are available to the process. For example, a decimal value of 1023 is equivalent to 0x3FF in hexadecimal notation and 0011 1111 1111 in binary notation. This specifies that the first 10 processors are to be used. To specify the next 10 processors, that is, processors 10-19, specify a decimal value of 1047552, which is equivalent to 0xFFC00 in hexadecimal and 1111 1111 1100 0000 0000 in binary. -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | `System.GC.Server` | true - server
false - workstation | -| **Environment variable** | `COMPlus_gcServer` | (DWORD)
0
1 | -| **app.config for .NET Framework** | [GCServer](../../framework/configure-apps/file-schema/runtime/gcserver-element.md) | | +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | `System.GC.HeapAffinitizeMask` | *decimal value* | .NET Core 3.0 | +| **Environment variable** | `COMPlus_GCHeapAffinitizeMask` | *decimal value* | .NET Core 3.0 | +| **app.config for .NET Framework** | [GCHeapAffinitizeMask](../../framework/configure-apps/file-schema/runtime/gcheapaffinitizemask-element.md) | *decimal value* | | -## Specific processors +### System.GC.GCHeapAffinitizeRanges/COMPlus_GCHeapAffinitizeRanges +- Specifies the list of processors to use for garbage collector threads. +- This setting is similar to `System.GC.HeapAffinitizeMask`, except it allows you to specify more than 64 processors. +- For Windows operating systems, prefix the processor number or range with the corresponding [CPU group](/windows/win32/procthread/processor-groups), for example, "0:1-10,0:12,1:50-52,1:70". +- If processor affinity is disabled by setting `System.GC.NoAffinitize` to `true`, this setting is ignored. - Applies to server garbage collection (GC) only. -- If processor affinity is enabled, specifies the exact processors for which a GC heap and threads are created. -- The decimal value is a mask that defines the processors that are available to the process. -- Introduced in .NET Core 3.0. +- For more information, see [Maoni Stephens' blog entry](https://devblogs.microsoft.com/dotnet/making-cpu-configuration-better-for-gc-on-machines-with-64-cpus/). -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | `System.GC.HeapAffinitizeMask` | *decimal value* | -| **Environment variable** | `COMPlus_GCHeapAffinitizeMask` | | -| **app.config for .NET Framework** | [GCHeapAffinitizeMask](../../framework/configure-apps/file-schema/runtime/gcheapaffinitizemask-element.md) | | +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | `System.GC.GCHeapAffinitizeRanges` | Comma-separated list of processor numbers or ranges of processor numbers.
Unix example: "1-10,12,50-52,70"
Windows example: "0:1-10,0:12,1:50-52,1:70" | .NET Core 1.0 | +| **Environment variable** | `COMPlus_GCHeapAffinitizeRanges` | Comma-separated list of processor numbers or ranges of processor numbers.
Unix example: "1-10,12,50-52,70"
Windows example: "0:1-10,0:12,1:50-52,1:70" | .NET Core 1.0 | +| **app.config for .NET Framework** | N/A | N/A | N/A | -## No processor affinity +### COMPlus_GCCpuGroup -- Applies to server garbage collection (GC) only. -- Specifies whether to affinitize garbage collection threads with processors. That is, whether to create a dedicated heap, GC thread, and background GC thread (if background garbage collection is enabled) for each processor. -- By default, garbage collection threads are affinitized with processors (value = `false`). Because the garbage collector uses all available processors in server GC, this can result in poor performance, particularly on systems with multiple running instances of a server application. -- Introduced in .NET Core 3.0. +- Configures whether the garbage collector uses [CPU groups](/windows/win32/procthread/processor-groups) or not. + + When a 64-bit Windows computer has multiple CPU groups, that is, there are more than 64 processors, enabling this element extends garbage collection across all CPU groups. The garbage collector uses all cores to create and balance heaps. + +- Applies to server garbage collection (GC) on 64-bit Windows operation systems only. +- Default: Disabled (0). +- For more information, see [Maoni Stephens' blog entry](https://devblogs.microsoft.com/dotnet/making-cpu-configuration-better-for-gc-on-machines-with-64-cpus/). -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | `System.GC.NoAffinitize` | true - don't affinitize
false - affinitize | -| **Environment variable** | `COMPlus_GCNoAffinitize` | (DWORD)
0
1 | -| **app.config for .NET Framework** | [GCNoAffinitize](../../framework/configure-apps/file-schema/runtime/gcnoaffinitize-element.md) | | +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | N/A | N/A | N/A | +| **Environment variable** | `COMPlus_GCCpuGroup` | 0 - disabled
1 - enabled | .NET Core 1.0 | +| **app.config for .NET Framework** | [GCCpuGroup](../../framework/configure-apps/file-schema/runtime/gccpugroup-element.md) | `true` - enabled
`false` - disabled | | -## Limit number of heaps +### System.GC.NoAffinitize/COMPlus_GCNoAffinitize +- Specifies whether to affinitize garbage collection threads with processors. That is, whether to create a dedicated heap, GC thread, and background GC thread (if background garbage collection is enabled) for each processor. - Applies to server garbage collection (GC) only. -- Limits the number of heaps created by the garbage collector. -- If GC thread/processor affinity is disabled, this setting limits the number of GC heaps. If GC thread/processor affinity is enabled, this setting limits the number of GC heaps to the processors 0 to one-less-than its specified value. -- This setting is typically used together with "System.GC.HeapAffinitizeMask" and "System.GC.NoAffinitize". For more information, see the [GCHeapCount remarks](../../framework/configure-apps/file-schema/runtime/gcheapcount-element.md#remarks). -- Introduced in .NET Core 3.0. +- By default, garbage collection threads are affinitized with processors (value = `false`). -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | `System.GC.HeapCount` | *number* | -| **Environment variable** | `COMPlus_GCHeapCount` | | -| **app.config for .NET Framework** | [GCHeapCount](../../framework/configure-apps/file-schema/runtime/gcheapcount-element.md) | | +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | `System.GC.NoAffinitize` | `true` - don't affinitize
`false` - affinitize | .NET Core 3.0 | +| **Environment variable** | `COMPlus_GCNoAffinitize` | 0
1 | .NET Core 3.0 | +| **app.config for .NET Framework** | [GCNoAffinitize](../../framework/configure-apps/file-schema/runtime/gcnoaffinitize-element.md) | | | -## Processor numbers +## Large pages -- Applies to server garbage collection (GC) only. -- Specifies the list of processors to use for garbage collector threads. +### COMPlus_GCLargePages -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | `System.GC.GCHeapAffinitizeRanges` | Comma-separated list of processor numbers or ranges of processor numbers.
Example: "1,3,7-9,12" | -| **Environment variable** | `COMPlus_GCHeapAffinitizeRanges` | | +- Specifies whether large pages should be used when a heap hard limit is set. +- This is an experimental setting. -## Heap size limit +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | N/A | N/A | N/A | +| **Environment variable** | `COMPlus_GCLargePages` | | .NET Core 1.0 | +| **app.config for .NET Framework** | N/A | N/A | N/A | -- Specifies the maximum commit size for the GC heap. -- Introduced in .NET Core 3.0. +## Large objects -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | `System.GC.HeapHardLimit` | *number* | -| **Environment variable** | `COMPlus_GCHeapHardLimit` | (DWORD) *number* | +### COMPlus_gcAllowVeryLargeObjects -## Heap usage as percentage +- Configures garbage collector support on 64-bit platforms for arrays that are greater than 2 gigabytes (GB) in total size. +- Default: Enabled (1). +- This option may become obsolete in a future version of .NET. -- Specifies the GC heap usage as a percentage of the total memory. -- Introduced in .NET Core 3.0. +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | N/A | N/A | N/A | +| **Environment variable** | `COMPlus_gcAllowVeryLargeObjects` | 0 - disabled
1 - enabled | .NET Core 1.0 | -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | `System.GC.HeapHardLimitPercent` | | -| **Environment variable** | `COMPlus_GCHeapHardLimitPercent` | | +## Large object heap threshold -## Large object heap size limit +### System.GC.LOHThreshold/COMPlus_GCLOHThreshold - Specifies the threshold size that causes objects to go on the large object heap (LOH). -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | `System.GC.LOHThreshold` | | -| **Environment variable** | `COMPlus_GCLOHThreshold` | | +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | `System.GC.LOHThreshold` | | .NET Core 1.0 | +| **Environment variable** | `COMPlus_GCLOHThreshold` | | .NET Core 1.0 | -## Large pages +## Standalone GC -- Specifies whether large pages should be used when a heap hard limit is set. +### COMPlus_GCName + +- Specifies a path to the library containing the garbage collector that the runtime intends to load. +- For more information, see [Standalone GC loader design](https://github.com/dotnet/coreclr/blob/master/Documentation/design-docs/standalone-gc-loading.md). -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | `System.GC.GCLargePages` | | -| **Environment variable** | `COMPlus_GCLargePages` | | +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | N/A | N/A | N/A | +| **Environment variable** | `COMPlus_GCName` | *string_path* | .NET Core 1.0 | From 4225f27d79b08a8044682c1c03159150b9c2f633 Mon Sep 17 00:00:00 2001 From: Genevieve Warren Date: Mon, 18 Nov 2019 17:06:04 -0800 Subject: [PATCH 08/18] LOH capitalization --- .../performance-counters.md | 470 +++++++++--------- .../cor-prf-high-monitor-enumeration.md | 85 ++-- docs/framework/whats-new/index.md | 2 +- .../garbage-collection/large-object-heap.md | 2 +- docs/standard/garbage-collection/latency.md | 2 +- 5 files changed, 282 insertions(+), 279 deletions(-) diff --git a/docs/framework/debug-trace-profile/performance-counters.md b/docs/framework/debug-trace-profile/performance-counters.md index eff35b768a193..5dc7e4bcf0f1a 100644 --- a/docs/framework/debug-trace-profile/performance-counters.md +++ b/docs/framework/debug-trace-profile/performance-counters.md @@ -1,248 +1,248 @@ --- title: "Performance Counters in the .NET Framework" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "performance, .NET Framework applications" - "performance counters" - "performance monitoring, counters" ms.assetid: 06a4ae8c-eeb2-4d5a-817e-b1b95c0653e1 --- # Performance Counters in the .NET Framework -This topic provides a list of performance counters you can find in the [Windows Performance Monitor](https://docs.microsoft.com/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc749249%28v=ws.11%29). - -- [Exception performance counters](#exception) - -- [Interop performance counters](#interop) - -- [JIT performance counters](#jit) - -- [Loading performance counters](#loading) - -- [Lock and thread performance counters](#lockthread) - -- [Memory performance counters](#memory) - -- [Networking performance counters](#networking) - -- [Security performance counters](#security) - - -## Exception performance counters - The Performance console .NET CLR Exceptions category includes counters that provide information about the exceptions thrown by an application. The following table describes these performance counters. - -|Performance counter|Description| -|-------------------------|-----------------| -|**# of Exceps Thrown**|Displays the total number of exceptions thrown since the application started. This includes both .NET exceptions and unmanaged exceptions that are converted into .NET exceptions. For example, an HRESULT returned from unmanaged code is converted to an exception in managed code.

This counter includes both handled and unhandled exceptions. Exceptions that are rethrown are counted again.| -|**# of Exceps Thrown / Sec**|Displays the number of exceptions thrown per second. This includes both .NET exceptions and unmanaged exceptions that are converted into .NET exceptions. For example, an HRESULT returned from unmanaged code is converted to an exception in managed code.

This counter includes both handled and unhandled exceptions. It is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval. This counter is an indicator of potential performance problems if a large (>100s) number of exceptions are thrown.| -|**# of Filters / Sec**|Displays the number of .NET exception filters executed per second. An exception filter evaluates regardless of whether an exception is handled.

This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| -|**# of Finallys / Sec**|Displays the number of finally blocks executed per second. A finally block is guaranteed to be executed regardless of how the try block was exited. Only the finally blocks executed for an exception are counted; finally blocks on normal code paths are not counted by this counter.

This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| -|**Throw to Catch Depth / Sec**|Displays the number of stack frames traversed, from the frame that threw the exception to the frame that handled the exception, per second. This counter resets to zero when an exception handler is entered, so nested exceptions show the handler-to-handler stack depth.

This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| - - -## Interop performance counters - The Performance console .NET CLR Interop category includes counters that provide information about an application's interaction with COM components, COM+ services, and external type libraries. The following table describes these performance counters. - -|Performance counter|Description| -|-------------------------|-----------------| -|**# of CCWs**|Displays the current number of COM callable wrappers (CCWs). A CCW is a proxy for a managed object being referenced from an unmanaged COM client. This counter indicates the number of managed objects referenced by unmanaged COM code.| -|**# of marshaling**|Displays the total number of times arguments and return values have been marshaled from managed to unmanaged code, and vice versa, since the application started. This counter is not incremented if the stubs are inlined. (Stubs are responsible for marshaling arguments and return values). Stubs are usually inlined if the marshaling overhead is small.| -|**# of Stubs**|Displays the current number of stubs created by the common language runtime. Stubs are responsible for marshaling arguments and return values from managed to unmanaged code, and vice versa, during a COM interop call or a platform invoke call.| -|**# of TLB exports / sec**|Reserved for future use.| -|**# of TLB imports / sec**|Reserved for future use.| - - -## JIT performance counters - The Performance console .NET CLR JIT category includes counters that provide information about code that has been JIT-compiled. The following table describes these performance counters. - -|Performance counter|Description| -|-------------------------|-----------------| -|**# of IL Bytes JITted**|Displays the total number of Microsoft intermediate language (MSIL) bytes compiled by the just-in-time (JIT) compiler since the application started. This counter is equivalent to the **Total # of IL Bytes Jitted** counter.| -|**# of Methods JITted**|Displays the total number of methods JIT-compiled since the application started. This counter does not include pre-JIT-compiled methods.| -|**% Time in Jit**|Displays the percentage of elapsed time spent in JIT compilation since the last JIT compilation phase. This counter is updated at the end of every JIT compilation phase. A JIT compilation phase occurs when a method and its dependencies are compiled.| -|**IL Bytes Jitted / sec**|Displays the number of MSIL bytes that are JIT-compiled per second. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| -|**Standard Jit Failures**|Displays the peak number of methods the JIT compiler has failed to compile since the application started. This failure can occur if the MSIL cannot be verified or if there is an internal error in the JIT compiler.| -|**Total # of IL Bytes Jitted**|Displays the total MSIL bytes JIT-compiled since the application started. This counter is equivalent to the **# of IL Bytes Jitted** counter.| - - -## Loading performance counters - The Performance console .NET CLR Loading category includes counters that provide information about assemblies, classes, and application domains that are loaded. The following table describes these performance counters. - -|Performance counter|Description| -|-------------------------|-----------------| -|**% Time Loading**|Reserved for future use.| -|**Assembly Search Length**|Reserved for future use.| -|**Bytes in Loader Heap**|Displays the current size, in bytes, of the memory committed by the class loader across all application domains. Committed memory is the physical space reserved in the disk paging file.| -|**Current appdomains**|Displays the current number of application domains loaded in this application.| -|**Current Assemblies**|Displays the current number of assemblies loaded across all application domains in the currently running application. If the assembly is loaded as domain-neutral from multiple application domains, this counter is incremented only once.| -|**Current Classes Loaded**|Displays the current number of classes loaded in all assemblies.| -|**Rate of appdomains**|Displays the number of application domains loaded per second. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| -|**Rate of appdomains unloaded**|Displays the number of application domains unloaded per second. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| -|**Rate of Assemblies**|Displays the number of assemblies loaded per second across all application domains. If the assembly is loaded as domain-neutral from multiple application domains, this counter is incremented only once.

This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| -|**Rate of Classes Loaded**|Displays the number of classes loaded per second in all assemblies. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| -|**Rate of Load Failures**|Displays the number of classes that failed to load per second. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.

Load failures can occur for many reasons, such as inadequate security or invalid format. For details, see the profiling services Help.| -|**Total # of Load Failures**|Displays the peak number of classes that have failed to load since the application started.

Load failures can occur for many reasons, such as inadequate security or invalid format. For details, see the profiling services Help.| -|**Total Appdomains**|Displays the peak number of application domains loaded since the application started.| -|**Total appdomains unloaded**|Displays the total number of application domains unloaded since the application started. If an application domain is loaded and unloaded multiple times, this counter increments each time the application domain is unloaded.| -|**Total Assemblies**|Displays the total number of assemblies loaded since the application started. If the assembly is loaded as domain-neutral from multiple application domains, this counter is incremented only once.| -|**Total Classes Loaded**|Displays the cumulative number of classes loaded in all assemblies since the application started.| - - -## Lock and thread performance counters - The Performance console .NET CLR LocksAndThreads category includes counters that provide information about managed locks and threads that an application uses. The following table describes these performance counters. - -|Performance counter|Description| -|-------------------------|-----------------| -|**# of current logical Threads**|Displays the number of current managed thread objects in the application. This counter maintains the count of both running and stopped threads. This counter is not an average over time; it displays only the last observed value.| -|**# of current physical Threads**|Displays the number of native operating system threads created and owned by the common language runtime to act as underlying threads for managed thread objects. This counter's value does not include the threads used by the runtime in its internal operations; it is a subset of the threads in the operating system process.| -|**# of current recognized threads**|Displays the number of threads that are currently recognized by the runtime. These threads are associated with a corresponding managed thread object. The runtime does not create these threads, but they have run inside the runtime at least once.

Only unique threads are tracked; threads with the same thread ID that reenter the runtime or are recreated after the thread exits are not counted twice.| -|**# of total recognized Threads**|Displays the total number of threads that have been recognized by the runtime since the application started. These threads are associated with a corresponding managed thread object. The runtime does not create these threads, but they have run inside the runtime at least once.

Only unique threads are tracked; threads with the same thread ID that reenter the runtime or are recreated after the thread exits are not counted twice.| -|**Contention Rate / Sec**|Displays the rate at which threads in the runtime attempt to acquire a managed lock unsuccessfully.| -|**Current Queue Length**|Displays the total number of threads that are currently waiting to acquire a managed lock in the application. This counter is not an average over time; it displays the last observed value.| -|**Queue Length / sec**|Displays the number of threads per second that are waiting to acquire a lock in the application. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| -|**Queue Length Peak**|Displays the total number of threads that waited to acquire a managed lock since the application started.| -|**rate of recognized threads / sec**|Displays the number of threads per second that have been recognized by the runtime. These threads are associated with a corresponding managed thread object. The runtime does not create these threads, but they have run inside the runtime at least once.

Only unique threads are tracked; threads with the same thread ID that reenter the runtime or are recreated after the thread exits are not counted twice.

This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| -|**Total # of Contentions**|Displays the total number of times that threads in the runtime have attempted to acquire a managed lock unsuccessfully.| - - -## Memory performance counters - The Performance console .NET CLR Memory category includes counters that provide information about the garbage collector. The following table describes these performance counters. - -|Performance counter|Description| -|-------------------------|-----------------| -|**# Bytes in all Heaps**|Displays the sum of the **Gen 1 Heap Size**, **Gen 2 Heap Size**, and **Large Object Heap Size** counters. This counter indicates the current memory allocated in bytes on the garbage collection heaps.| -|**# GC Handles**|Displays the current number of garbage collection handles in use. Garbage collection handles are handles to resources external to the common language runtime and the managed environment.| -|**# Gen 0 Collections**|Displays the number of times the generation 0 objects (that is, the youngest, most recently allocated objects) are garbage collected since the application started.

Generation 0 garbage collection occurs when the available memory in generation 0 is not sufficient to satisfy an allocation request. This counter is incremented at the end of a generation 0 garbage collection. Higher generation garbage collections include all lower generation collections. This counter is explicitly incremented when a higher generation (generation 1 or 2) garbage collection occurs.

This counter displays the last observed value. The **_Global\_** counter value is not accurate and should be ignored.| -|**# Gen 1 Collections**|Displays the number of times the generation 1 objects are garbage collected since the application started.

The counter is incremented at the end of a generation 1 garbage collection. Higher generation garbage collections include all lower generation collections. This counter is explicitly incremented when a higher generation (generation 2) garbage collection occurs.

This counter displays the last observed value. The **_Global\_** counter value is not accurate and should be ignored.| -|**# Gen 2 Collections**|Displays the number of times the generation 2 objects are garbage collected since the application started. The counter is incremented at the end of a generation 2 garbage collection (also called a full garbage collection).

This counter displays the last observed value. The **_Global\_** counter value is not accurate and should be ignored.| -|**# Induced GC**|Displays the peak number of times garbage collection was performed because of an explicit call to . It is good practice to let the garbage collector tune the frequency of its collections.| -|**# of Pinned Objects**|Displays the number of pinned objects encountered in the last garbage collection. A pinned object is an object that the garbage collector cannot move in memory. This counter tracks pinned objects only in the heaps that are garbage collected. For example, a generation 0 garbage collection causes enumeration of pinned objects only in the generation 0 heap.| -|**# of Sink Blocks in use**|Displays the current number of synchronization blocks in use. Synchronization blocks are per-object data structures allocated for storing synchronization information. They hold weak references to managed objects and must be scanned by the garbage collector. Synchronization blocks are not limited to storing synchronization information; they can also store COM interop metadata. This counter indicates performance problems with heavy use of synchronization primitives.| -|**# Total committed Bytes**|Displays the amount of virtual memory, in bytes, currently committed by the garbage collector. Committed memory is the physical memory for which space has been reserved in the disk paging file.| -|**# Total reserved Bytes**|Displays the amount of virtual memory, in bytes, currently reserved by the garbage collector. Reserved memory is the virtual memory space reserved for the application when no disk or main memory pages have been used.| -|**% Time in GC**|Displays the percentage of elapsed time that was spent performing a garbage collection since the last garbage collection cycle. This counter usually indicates the work done by the garbage collector to collect and compact memory on behalf of the application. This counter is updated only at the end of every garbage collection. This counter is not an average; its value reflects the last observed value.| -|**Allocated Bytes/second**|Displays the number of bytes per second allocated on the garbage collection heap. This counter is updated at the end of every garbage collection, not at each allocation. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| -|**Finalization Survivors**|Displays the number of garbage-collected objects that survive a collection because they are waiting to be finalized. If these objects hold references to other objects, those objects also survive but are not counted by this counter. The **Promoted Finalization-Memory from Gen 0** counter represents all the memory that survived due to finalization.

This counter is not cumulative; it is updated at the end of every garbage collection with the count of the survivors during that particular collection only. This counter indicates the extra overhead that the application might incur because of finalization.| -|**Gen 0 heap size**|Displays the maximum bytes that can be allocated in generation 0; it does not indicate the current number of bytes allocated in generation 0.

A generation 0 garbage collection occurs when the allocations since the last collection exceed this size. The generation 0 size is tuned by the garbage collector and can change during the execution of the application. At the end of a generation 0 collection the size of the generation 0 heap is 0 bytes. This counter displays the size, in bytes, of allocations that invokes the next generation 0 garbage collection.

This counter is updated at the end of a garbage collection, not at each allocation.| -|**Gen 0 Promoted Bytes/Sec**|Displays the bytes per second that are promoted from generation 0 to generation 1. Memory is promoted when it survives a garbage collection. This counter is an indicator of relatively long-lived objects being created per second.

This counter displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| -|**Gen 1 heap size**|Displays the current number of bytes in generation 1; this counter does not display the maximum size of generation 1. Objects are not directly allocated in this generation; they are promoted from previous generation 0 garbage collections. This counter is updated at the end of a garbage collection, not at each allocation.| -|**Gen 1 Promoted Bytes/Sec**|Displays the bytes per second that are promoted from generation 1 to generation 2. Objects that are promoted only because they are waiting to be finalized are not included in this counter.

Memory is promoted when it survives a garbage collection. Nothing is promoted from generation 2 because it is the oldest generation. This counter is an indicator of very long-lived objects being created per second.

This counter displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| -|**Gen 2 heap size**|Displays the current number of bytes in generation 2. Objects are not directly allocated in this generation; they are promoted from generation 1 during previous generation 1 garbage collections. This counter is updated at the end of a garbage collection, not at each allocation.| -|**Large Object Heap size**|Displays the current size, in bytes, of the Large Object Heap. Objects that are greater than approximately 85,000 bytes are treated as large objects by the garbage collector and are directly allocated in a special heap; they are not promoted through the generations. This counter is updated at the end of a garbage collection, not at each allocation.| -|**Process ID**|Displays the process ID of the CLR process instance that is being monitored.| -|**Promoted Finalization-Memory from Gen 0**|Displays the bytes of memory that are promoted from generation 0 to generation 1 only because they are waiting to be finalized. This counter is not cumulative; it displays the value observed at the end of the last garbage collection.| -|**Promoted Memory from Gen 0**|Displays the bytes of memory that survive garbage collection and are promoted from generation 0 to generation 1. Objects that are promoted only because they are waiting to be finalized are not included in this counter. This counter is not cumulative; it displays the value observed at the end of the last garbage collection.| -|**Promoted Memory from Gen 1**|Displays the bytes of memory that survive garbage collection and are promoted from generation 1 to generation 2. Objects that are promoted only because they are waiting to be finalized are not included in this counter. This counter is not cumulative; it displays the value observed at the end of the last garbage collection. This counter is reset to 0 if the last garbage collection was a generation 0 collection only.| - - -## Networking performance counters - The Performance console .NET CLR Networking category includes counters that provide information about data that an application sends and receives over the network. The following table describes these performance counters. - -|Performance counter|Description| -|-------------------------|-----------------| -|**Bytes Received**|The cumulative total number of bytes received by all objects within the since the process started. This number includes data and any protocol information that is not defined by TCP/IP.| -|**Bytes Sent**|The cumulative number of bytes sent by all objects within the since the process started. This number includes data and any protocol information that is not defined by TCP/IP.| -|**Connections Established**|The cumulative total number of objects for stream sockets that were ever connected within the since the process started.| -|**Datagrams Received**|The cumulative total number of datagram packets received by all objects within the since the process started.| -|**Datagrams Sent**|The cumulative total number of datagram packets sent by all objects within the since the process started.| -|**HttpWebRequest Average Lifetime**|The average time to completion for all objects that ended in the last interval within the since the process started.| -|**HttpWebRequest Average Queue Time**|The average time-on-queue for all objects that left the queue in the last interval within the since the process started.| -|**HttpWebRequests Created/sec**|The number of objects created per second within the .| -|**HttpWebRequests Queued/sec**|The number of objects that were added to the queue per second within the .| -|**HttpWebRequests Aborted/sec**|The number of objects where the application called the method per second within the .| -|**HttpWebRequests Failed/sec**|The number of objects that received a failed status code from the server per second within the .| - - There are several classes of networking performance counters supported: - -- Event counters that measure the number of times some event occurred. - -- Data counters that measure the quantity of data sent or received. - -- Duration counters that measure how long different processes take. The times are measured on the objects each interval (usually in seconds) after they come out of different states. - -- Per-Interval counters that measure the number of objects that are making a particular transition per interval (normally per second). - - The networking performance counters for events include the following: - -- **Connections Established** - -- **Datagrams Received** - -- **Datagrams Sent** - - These performance counters provide counts since the process started. The counts of connections established includes explicit method calls by an application for a stream socket connection that was established as well as internal calls made by other classes (, , , and , for example) to class - - The counts for **Datagrams Received** and **Datagrams Sent** includes datagram packets sent or received using explicit method calls by an application as well internal calls made by other classes (, for example) to . class. The counts **Datagrams Received** and **Datagrams Sent** may also be used to provide a very crude measure of how many bytes were sent or received using datagrams by assuming an average size for a datagram. - - The networking performance counters for data include the following: - -- **Bytes Received** - -- **Bytes Sent** - - The above counters provide counts of bytes since the process started. - - There are two duration counters that measure how long it took for objects to pass through either their entire life cycle or just part of it: - -- **HttpWebRequest Average Lifetime** - -- **HttpWebRequest Average Queue Time** - - For the **HttpWebRequest Average Lifetime** counter, the lifetime of most objects always starts with the time that the object is created up until the time that the response stream is closed by the application. There are two uncommon cases: - -- If the application never calls the or methods, then the lifetime of the object is ignored. - -- If the object throws a when calling the or methods, the lifetime ends when the exception is thrown. Technically, the underlying response stream is also closed at that point (the response stream returned to the user is really a memory stream containing a copy of the response stream). - - There are four counters that track certain object issues per interval. These performance counters can help application developers, administrators, and support staff better understand what the objects are doing. The counters include the following: - -- **HttpWebRequests Created/sec** - -- **HttpWebRequests Queued/sec** - -- **HttpWebRequests Aborted/sec** - -- **HttpWebRequests Failed/sec** - - For the **HttpWebRequests Aborted/sec** counter, internal calls to are also counted. These internal calls are usually caused by timeouts that an application may want to measure. - - The **HttpWebRequests Failed/sec** counter contains the number of objects that received a failed status code from the server per second. This means that the status code received from the Http server at the end of the request was not in the range between 200 to 299. Status codes that are handled and result in a new request (many of the 401 Unauthorized status codes, for example) will fail or not fail based on the result of the retry. If the application would see an error based on the retry, then this counter is incremented. - - Networking performance counters can be accessed and managed using the and related classes in the namespace. Networking performance counters can also be viewed with the Windows Performance Monitor console. - - Networking performance counters need to be enabled in the configuration file to be used. All networking performance counters are enabled or disabled with a single setting in the configuration file. Individual networking performance counters cannot be enabled or disabled. For more information, see [\ Element (Network Settings)](../configure-apps/file-schema/network/performancecounter-element-network-settings.md). - - If networking counters are enabled, this will create and update both per-AppDomain and global performance counters. If disabled, the application will not provide any networking performance counter data. - - Performance counters are grouped into Categories. An application can list all of the categories with the following example code: - +This topic provides a list of performance counters you can find in the [Windows Performance Monitor](https://docs.microsoft.com/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc749249%28v=ws.11%29). + +- [Exception performance counters](#exception) + +- [Interop performance counters](#interop) + +- [JIT performance counters](#jit) + +- [Loading performance counters](#loading) + +- [Lock and thread performance counters](#lockthread) + +- [Memory performance counters](#memory) + +- [Networking performance counters](#networking) + +- [Security performance counters](#security) + + +## Exception performance counters + The Performance console .NET CLR Exceptions category includes counters that provide information about the exceptions thrown by an application. The following table describes these performance counters. + +|Performance counter|Description| +|-------------------------|-----------------| +|**# of Exceps Thrown**|Displays the total number of exceptions thrown since the application started. This includes both .NET exceptions and unmanaged exceptions that are converted into .NET exceptions. For example, an HRESULT returned from unmanaged code is converted to an exception in managed code.

This counter includes both handled and unhandled exceptions. Exceptions that are rethrown are counted again.| +|**# of Exceps Thrown / Sec**|Displays the number of exceptions thrown per second. This includes both .NET exceptions and unmanaged exceptions that are converted into .NET exceptions. For example, an HRESULT returned from unmanaged code is converted to an exception in managed code.

This counter includes both handled and unhandled exceptions. It is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval. This counter is an indicator of potential performance problems if a large (>100s) number of exceptions are thrown.| +|**# of Filters / Sec**|Displays the number of .NET exception filters executed per second. An exception filter evaluates regardless of whether an exception is handled.

This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| +|**# of Finallys / Sec**|Displays the number of finally blocks executed per second. A finally block is guaranteed to be executed regardless of how the try block was exited. Only the finally blocks executed for an exception are counted; finally blocks on normal code paths are not counted by this counter.

This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| +|**Throw to Catch Depth / Sec**|Displays the number of stack frames traversed, from the frame that threw the exception to the frame that handled the exception, per second. This counter resets to zero when an exception handler is entered, so nested exceptions show the handler-to-handler stack depth.

This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| + + +## Interop performance counters + The Performance console .NET CLR Interop category includes counters that provide information about an application's interaction with COM components, COM+ services, and external type libraries. The following table describes these performance counters. + +|Performance counter|Description| +|-------------------------|-----------------| +|**# of CCWs**|Displays the current number of COM callable wrappers (CCWs). A CCW is a proxy for a managed object being referenced from an unmanaged COM client. This counter indicates the number of managed objects referenced by unmanaged COM code.| +|**# of marshaling**|Displays the total number of times arguments and return values have been marshaled from managed to unmanaged code, and vice versa, since the application started. This counter is not incremented if the stubs are inlined. (Stubs are responsible for marshaling arguments and return values). Stubs are usually inlined if the marshaling overhead is small.| +|**# of Stubs**|Displays the current number of stubs created by the common language runtime. Stubs are responsible for marshaling arguments and return values from managed to unmanaged code, and vice versa, during a COM interop call or a platform invoke call.| +|**# of TLB exports / sec**|Reserved for future use.| +|**# of TLB imports / sec**|Reserved for future use.| + + +## JIT performance counters + The Performance console .NET CLR JIT category includes counters that provide information about code that has been JIT-compiled. The following table describes these performance counters. + +|Performance counter|Description| +|-------------------------|-----------------| +|**# of IL Bytes JITted**|Displays the total number of Microsoft intermediate language (MSIL) bytes compiled by the just-in-time (JIT) compiler since the application started. This counter is equivalent to the **Total # of IL Bytes Jitted** counter.| +|**# of Methods JITted**|Displays the total number of methods JIT-compiled since the application started. This counter does not include pre-JIT-compiled methods.| +|**% Time in Jit**|Displays the percentage of elapsed time spent in JIT compilation since the last JIT compilation phase. This counter is updated at the end of every JIT compilation phase. A JIT compilation phase occurs when a method and its dependencies are compiled.| +|**IL Bytes Jitted / sec**|Displays the number of MSIL bytes that are JIT-compiled per second. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| +|**Standard Jit Failures**|Displays the peak number of methods the JIT compiler has failed to compile since the application started. This failure can occur if the MSIL cannot be verified or if there is an internal error in the JIT compiler.| +|**Total # of IL Bytes Jitted**|Displays the total MSIL bytes JIT-compiled since the application started. This counter is equivalent to the **# of IL Bytes Jitted** counter.| + + +## Loading performance counters + The Performance console .NET CLR Loading category includes counters that provide information about assemblies, classes, and application domains that are loaded. The following table describes these performance counters. + +|Performance counter|Description| +|-------------------------|-----------------| +|**% Time Loading**|Reserved for future use.| +|**Assembly Search Length**|Reserved for future use.| +|**Bytes in Loader Heap**|Displays the current size, in bytes, of the memory committed by the class loader across all application domains. Committed memory is the physical space reserved in the disk paging file.| +|**Current appdomains**|Displays the current number of application domains loaded in this application.| +|**Current Assemblies**|Displays the current number of assemblies loaded across all application domains in the currently running application. If the assembly is loaded as domain-neutral from multiple application domains, this counter is incremented only once.| +|**Current Classes Loaded**|Displays the current number of classes loaded in all assemblies.| +|**Rate of appdomains**|Displays the number of application domains loaded per second. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| +|**Rate of appdomains unloaded**|Displays the number of application domains unloaded per second. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| +|**Rate of Assemblies**|Displays the number of assemblies loaded per second across all application domains. If the assembly is loaded as domain-neutral from multiple application domains, this counter is incremented only once.

This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| +|**Rate of Classes Loaded**|Displays the number of classes loaded per second in all assemblies. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| +|**Rate of Load Failures**|Displays the number of classes that failed to load per second. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.

Load failures can occur for many reasons, such as inadequate security or invalid format. For details, see the profiling services Help.| +|**Total # of Load Failures**|Displays the peak number of classes that have failed to load since the application started.

Load failures can occur for many reasons, such as inadequate security or invalid format. For details, see the profiling services Help.| +|**Total Appdomains**|Displays the peak number of application domains loaded since the application started.| +|**Total appdomains unloaded**|Displays the total number of application domains unloaded since the application started. If an application domain is loaded and unloaded multiple times, this counter increments each time the application domain is unloaded.| +|**Total Assemblies**|Displays the total number of assemblies loaded since the application started. If the assembly is loaded as domain-neutral from multiple application domains, this counter is incremented only once.| +|**Total Classes Loaded**|Displays the cumulative number of classes loaded in all assemblies since the application started.| + + +## Lock and thread performance counters + The Performance console .NET CLR LocksAndThreads category includes counters that provide information about managed locks and threads that an application uses. The following table describes these performance counters. + +|Performance counter|Description| +|-------------------------|-----------------| +|**# of current logical Threads**|Displays the number of current managed thread objects in the application. This counter maintains the count of both running and stopped threads. This counter is not an average over time; it displays only the last observed value.| +|**# of current physical Threads**|Displays the number of native operating system threads created and owned by the common language runtime to act as underlying threads for managed thread objects. This counter's value does not include the threads used by the runtime in its internal operations; it is a subset of the threads in the operating system process.| +|**# of current recognized threads**|Displays the number of threads that are currently recognized by the runtime. These threads are associated with a corresponding managed thread object. The runtime does not create these threads, but they have run inside the runtime at least once.

Only unique threads are tracked; threads with the same thread ID that reenter the runtime or are recreated after the thread exits are not counted twice.| +|**# of total recognized Threads**|Displays the total number of threads that have been recognized by the runtime since the application started. These threads are associated with a corresponding managed thread object. The runtime does not create these threads, but they have run inside the runtime at least once.

Only unique threads are tracked; threads with the same thread ID that reenter the runtime or are recreated after the thread exits are not counted twice.| +|**Contention Rate / Sec**|Displays the rate at which threads in the runtime attempt to acquire a managed lock unsuccessfully.| +|**Current Queue Length**|Displays the total number of threads that are currently waiting to acquire a managed lock in the application. This counter is not an average over time; it displays the last observed value.| +|**Queue Length / sec**|Displays the number of threads per second that are waiting to acquire a lock in the application. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| +|**Queue Length Peak**|Displays the total number of threads that waited to acquire a managed lock since the application started.| +|**rate of recognized threads / sec**|Displays the number of threads per second that have been recognized by the runtime. These threads are associated with a corresponding managed thread object. The runtime does not create these threads, but they have run inside the runtime at least once.

Only unique threads are tracked; threads with the same thread ID that reenter the runtime or are recreated after the thread exits are not counted twice.

This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| +|**Total # of Contentions**|Displays the total number of times that threads in the runtime have attempted to acquire a managed lock unsuccessfully.| + + +## Memory performance counters + The Performance console .NET CLR Memory category includes counters that provide information about the garbage collector. The following table describes these performance counters. + +|Performance counter|Description| +|-------------------------|-----------------| +|**# Bytes in all Heaps**|Displays the sum of the **Gen 1 Heap Size**, **Gen 2 Heap Size**, and **Large Object Heap Size** counters. This counter indicates the current memory allocated in bytes on the garbage collection heaps.| +|**# GC Handles**|Displays the current number of garbage collection handles in use. Garbage collection handles are handles to resources external to the common language runtime and the managed environment.| +|**# Gen 0 Collections**|Displays the number of times the generation 0 objects (that is, the youngest, most recently allocated objects) are garbage collected since the application started.

Generation 0 garbage collection occurs when the available memory in generation 0 is not sufficient to satisfy an allocation request. This counter is incremented at the end of a generation 0 garbage collection. Higher generation garbage collections include all lower generation collections. This counter is explicitly incremented when a higher generation (generation 1 or 2) garbage collection occurs.

This counter displays the last observed value. The **_Global\_** counter value is not accurate and should be ignored.| +|**# Gen 1 Collections**|Displays the number of times the generation 1 objects are garbage collected since the application started.

The counter is incremented at the end of a generation 1 garbage collection. Higher generation garbage collections include all lower generation collections. This counter is explicitly incremented when a higher generation (generation 2) garbage collection occurs.

This counter displays the last observed value. The **_Global\_** counter value is not accurate and should be ignored.| +|**# Gen 2 Collections**|Displays the number of times the generation 2 objects are garbage collected since the application started. The counter is incremented at the end of a generation 2 garbage collection (also called a full garbage collection).

This counter displays the last observed value. The **_Global\_** counter value is not accurate and should be ignored.| +|**# Induced GC**|Displays the peak number of times garbage collection was performed because of an explicit call to . It is good practice to let the garbage collector tune the frequency of its collections.| +|**# of Pinned Objects**|Displays the number of pinned objects encountered in the last garbage collection. A pinned object is an object that the garbage collector cannot move in memory. This counter tracks pinned objects only in the heaps that are garbage collected. For example, a generation 0 garbage collection causes enumeration of pinned objects only in the generation 0 heap.| +|**# of Sink Blocks in use**|Displays the current number of synchronization blocks in use. Synchronization blocks are per-object data structures allocated for storing synchronization information. They hold weak references to managed objects and must be scanned by the garbage collector. Synchronization blocks are not limited to storing synchronization information; they can also store COM interop metadata. This counter indicates performance problems with heavy use of synchronization primitives.| +|**# Total committed Bytes**|Displays the amount of virtual memory, in bytes, currently committed by the garbage collector. Committed memory is the physical memory for which space has been reserved in the disk paging file.| +|**# Total reserved Bytes**|Displays the amount of virtual memory, in bytes, currently reserved by the garbage collector. Reserved memory is the virtual memory space reserved for the application when no disk or main memory pages have been used.| +|**% Time in GC**|Displays the percentage of elapsed time that was spent performing a garbage collection since the last garbage collection cycle. This counter usually indicates the work done by the garbage collector to collect and compact memory on behalf of the application. This counter is updated only at the end of every garbage collection. This counter is not an average; its value reflects the last observed value.| +|**Allocated Bytes/second**|Displays the number of bytes per second allocated on the garbage collection heap. This counter is updated at the end of every garbage collection, not at each allocation. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| +|**Finalization Survivors**|Displays the number of garbage-collected objects that survive a collection because they are waiting to be finalized. If these objects hold references to other objects, those objects also survive but are not counted by this counter. The **Promoted Finalization-Memory from Gen 0** counter represents all the memory that survived due to finalization.

This counter is not cumulative; it is updated at the end of every garbage collection with the count of the survivors during that particular collection only. This counter indicates the extra overhead that the application might incur because of finalization.| +|**Gen 0 heap size**|Displays the maximum bytes that can be allocated in generation 0; it does not indicate the current number of bytes allocated in generation 0.

A generation 0 garbage collection occurs when the allocations since the last collection exceed this size. The generation 0 size is tuned by the garbage collector and can change during the execution of the application. At the end of a generation 0 collection the size of the generation 0 heap is 0 bytes. This counter displays the size, in bytes, of allocations that invokes the next generation 0 garbage collection.

This counter is updated at the end of a garbage collection, not at each allocation.| +|**Gen 0 Promoted Bytes/Sec**|Displays the bytes per second that are promoted from generation 0 to generation 1. Memory is promoted when it survives a garbage collection. This counter is an indicator of relatively long-lived objects being created per second.

This counter displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| +|**Gen 1 heap size**|Displays the current number of bytes in generation 1; this counter does not display the maximum size of generation 1. Objects are not directly allocated in this generation; they are promoted from previous generation 0 garbage collections. This counter is updated at the end of a garbage collection, not at each allocation.| +|**Gen 1 Promoted Bytes/Sec**|Displays the bytes per second that are promoted from generation 1 to generation 2. Objects that are promoted only because they are waiting to be finalized are not included in this counter.

Memory is promoted when it survives a garbage collection. Nothing is promoted from generation 2 because it is the oldest generation. This counter is an indicator of very long-lived objects being created per second.

This counter displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| +|**Gen 2 heap size**|Displays the current number of bytes in generation 2. Objects are not directly allocated in this generation; they are promoted from generation 1 during previous generation 1 garbage collections. This counter is updated at the end of a garbage collection, not at each allocation.| +|**Large Object Heap size**|Displays the current size, in bytes, of the large object heap. Objects that are greater than approximately 85,000 bytes are treated as large objects by the garbage collector and are directly allocated in a special heap. They are not promoted through the generations. This counter is updated at the end of a garbage collection, not at each allocation.| +|**Process ID**|Displays the process ID of the CLR process instance that is being monitored.| +|**Promoted Finalization-Memory from Gen 0**|Displays the bytes of memory that are promoted from generation 0 to generation 1 only because they are waiting to be finalized. This counter is not cumulative; it displays the value observed at the end of the last garbage collection.| +|**Promoted Memory from Gen 0**|Displays the bytes of memory that survive garbage collection and are promoted from generation 0 to generation 1. Objects that are promoted only because they are waiting to be finalized are not included in this counter. This counter is not cumulative; it displays the value observed at the end of the last garbage collection.| +|**Promoted Memory from Gen 1**|Displays the bytes of memory that survive garbage collection and are promoted from generation 1 to generation 2. Objects that are promoted only because they are waiting to be finalized are not included in this counter. This counter is not cumulative; it displays the value observed at the end of the last garbage collection. This counter is reset to 0 if the last garbage collection was a generation 0 collection only.| + + +## Networking performance counters + The Performance console .NET CLR Networking category includes counters that provide information about data that an application sends and receives over the network. The following table describes these performance counters. + +|Performance counter|Description| +|-------------------------|-----------------| +|**Bytes Received**|The cumulative total number of bytes received by all objects within the since the process started. This number includes data and any protocol information that is not defined by TCP/IP.| +|**Bytes Sent**|The cumulative number of bytes sent by all objects within the since the process started. This number includes data and any protocol information that is not defined by TCP/IP.| +|**Connections Established**|The cumulative total number of objects for stream sockets that were ever connected within the since the process started.| +|**Datagrams Received**|The cumulative total number of datagram packets received by all objects within the since the process started.| +|**Datagrams Sent**|The cumulative total number of datagram packets sent by all objects within the since the process started.| +|**HttpWebRequest Average Lifetime**|The average time to completion for all objects that ended in the last interval within the since the process started.| +|**HttpWebRequest Average Queue Time**|The average time-on-queue for all objects that left the queue in the last interval within the since the process started.| +|**HttpWebRequests Created/sec**|The number of objects created per second within the .| +|**HttpWebRequests Queued/sec**|The number of objects that were added to the queue per second within the .| +|**HttpWebRequests Aborted/sec**|The number of objects where the application called the method per second within the .| +|**HttpWebRequests Failed/sec**|The number of objects that received a failed status code from the server per second within the .| + + There are several classes of networking performance counters supported: + +- Event counters that measure the number of times some event occurred. + +- Data counters that measure the quantity of data sent or received. + +- Duration counters that measure how long different processes take. The times are measured on the objects each interval (usually in seconds) after they come out of different states. + +- Per-Interval counters that measure the number of objects that are making a particular transition per interval (normally per second). + + The networking performance counters for events include the following: + +- **Connections Established** + +- **Datagrams Received** + +- **Datagrams Sent** + + These performance counters provide counts since the process started. The counts of connections established includes explicit method calls by an application for a stream socket connection that was established as well as internal calls made by other classes (, , , and , for example) to class + + The counts for **Datagrams Received** and **Datagrams Sent** includes datagram packets sent or received using explicit method calls by an application as well internal calls made by other classes (, for example) to . class. The counts **Datagrams Received** and **Datagrams Sent** may also be used to provide a very crude measure of how many bytes were sent or received using datagrams by assuming an average size for a datagram. + + The networking performance counters for data include the following: + +- **Bytes Received** + +- **Bytes Sent** + + The above counters provide counts of bytes since the process started. + + There are two duration counters that measure how long it took for objects to pass through either their entire life cycle or just part of it: + +- **HttpWebRequest Average Lifetime** + +- **HttpWebRequest Average Queue Time** + + For the **HttpWebRequest Average Lifetime** counter, the lifetime of most objects always starts with the time that the object is created up until the time that the response stream is closed by the application. There are two uncommon cases: + +- If the application never calls the or methods, then the lifetime of the object is ignored. + +- If the object throws a when calling the or methods, the lifetime ends when the exception is thrown. Technically, the underlying response stream is also closed at that point (the response stream returned to the user is really a memory stream containing a copy of the response stream). + + There are four counters that track certain object issues per interval. These performance counters can help application developers, administrators, and support staff better understand what the objects are doing. The counters include the following: + +- **HttpWebRequests Created/sec** + +- **HttpWebRequests Queued/sec** + +- **HttpWebRequests Aborted/sec** + +- **HttpWebRequests Failed/sec** + + For the **HttpWebRequests Aborted/sec** counter, internal calls to are also counted. These internal calls are usually caused by timeouts that an application may want to measure. + + The **HttpWebRequests Failed/sec** counter contains the number of objects that received a failed status code from the server per second. This means that the status code received from the Http server at the end of the request was not in the range between 200 to 299. Status codes that are handled and result in a new request (many of the 401 Unauthorized status codes, for example) will fail or not fail based on the result of the retry. If the application would see an error based on the retry, then this counter is incremented. + + Networking performance counters can be accessed and managed using the and related classes in the namespace. Networking performance counters can also be viewed with the Windows Performance Monitor console. + + Networking performance counters need to be enabled in the configuration file to be used. All networking performance counters are enabled or disabled with a single setting in the configuration file. Individual networking performance counters cannot be enabled or disabled. For more information, see [\ Element (Network Settings)](../configure-apps/file-schema/network/performancecounter-element-network-settings.md). + + If networking counters are enabled, this will create and update both per-AppDomain and global performance counters. If disabled, the application will not provide any networking performance counter data. + + Performance counters are grouped into Categories. An application can list all of the categories with the following example code: + ```csharp -PerformanceCounterCategory[] Array = PerformanceCounterCategory.GetCategories(); -for (int i = 0; i < Array.Length; i++) -{ - Console.Out.WriteLine("{0}. Name={1} Help={2}", i, Array[i].CategoryName, Array[i].CategoryHelp); -} -``` - - The networking performance counters are listed in two categories: - -- ".NET CLR Networking" - the original performance counters introduced on .NET Framework Version 2 and supported on .NET Framework Version 2 and later. - -- ".NET CLR Networking 4.0.0.0" - All of the above socket counters plus the new performance counters supported on .NET Framework Version 4 and later. These new counters provide performance information on objects. - - For more information on accessing and managing performance counters in an application, see [Performance Counters](performance-counters.md). - - -## Security performance counters - The Performance console .NET CLR Security category includes counters that provide information about the security checks that the common language runtime performs for an application. The following table describes these performance counters. - -|Performance counter|Description| -|-------------------------|-----------------| -|**# Link Time Checks**|Displays the total number of link-time code access security checks since the application started. Link-time code access security checks are performed when a caller demands a particular permission at just-in-time (JIT) compile time. A link-time check is performed once per caller. This count is not indicative of serious performance issues; it is merely indicative of the security system activity.| -|**% Time in RT checks**|Displays the percentage of elapsed time spent performing runtime code access security checks since the last sample. This counter is updated at the end of a .NET Framework security check. It is not an average; it represents the last observed value.| -|**% Time Sig Authenticating**|Reserved for future use.| -|**Stack Walk Depth**|Displays the depth of the stack during that last runtime code access security check. Runtime code access security checks are performed by walking the stack. This counter is not an average; it displays only the last observed value.| -|**Total Runtime Checks**|Displays the total number of runtime code access security checks performed since the application started. Runtime code access security checks are performed when a caller demands a particular permission. The runtime check is made on every call by the caller and examines the current thread stack of the caller. When used with the **Stack Walk Depth** counter, this counter indicates the performance penalty that occurs for security checks.| - +PerformanceCounterCategory[] Array = PerformanceCounterCategory.GetCategories(); +for (int i = 0; i < Array.Length; i++) +{ + Console.Out.WriteLine("{0}. Name={1} Help={2}", i, Array[i].CategoryName, Array[i].CategoryHelp); +} +``` + + The networking performance counters are listed in two categories: + +- ".NET CLR Networking" - the original performance counters introduced on .NET Framework Version 2 and supported on .NET Framework Version 2 and later. + +- ".NET CLR Networking 4.0.0.0" - All of the above socket counters plus the new performance counters supported on .NET Framework Version 4 and later. These new counters provide performance information on objects. + + For more information on accessing and managing performance counters in an application, see [Performance Counters](performance-counters.md). + + +## Security performance counters + The Performance console .NET CLR Security category includes counters that provide information about the security checks that the common language runtime performs for an application. The following table describes these performance counters. + +|Performance counter|Description| +|-------------------------|-----------------| +|**# Link Time Checks**|Displays the total number of link-time code access security checks since the application started. Link-time code access security checks are performed when a caller demands a particular permission at just-in-time (JIT) compile time. A link-time check is performed once per caller. This count is not indicative of serious performance issues; it is merely indicative of the security system activity.| +|**% Time in RT checks**|Displays the percentage of elapsed time spent performing runtime code access security checks since the last sample. This counter is updated at the end of a .NET Framework security check. It is not an average; it represents the last observed value.| +|**% Time Sig Authenticating**|Reserved for future use.| +|**Stack Walk Depth**|Displays the depth of the stack during that last runtime code access security check. Runtime code access security checks are performed by walking the stack. This counter is not an average; it displays only the last observed value.| +|**Total Runtime Checks**|Displays the total number of runtime code access security checks performed since the application started. Runtime code access security checks are performed when a caller demands a particular permission. The runtime check is made on every call by the caller and examines the current thread stack of the caller. When used with the **Stack Walk Depth** counter, this counter indicates the performance penalty that occurs for security checks.| + ## See also - [Performance Counters](performance-counters.md) diff --git a/docs/framework/unmanaged-api/profiling/cor-prf-high-monitor-enumeration.md b/docs/framework/unmanaged-api/profiling/cor-prf-high-monitor-enumeration.md index 34657c43ae4de..d0200ce8b536d 100644 --- a/docs/framework/unmanaged-api/profiling/cor-prf-high-monitor-enumeration.md +++ b/docs/framework/unmanaged-api/profiling/cor-prf-high-monitor-enumeration.md @@ -4,64 +4,67 @@ ms.date: "04/10/2018" ms.assetid: 3ba543d8-15e5-4322-b6e7-1ebfc92ed7dd --- # COR_PRF_HIGH_MONITOR Enumeration -[Supported in the .NET Framework 4.5.2 and later versions] - - Provides flags in addition to those found in the [COR_PRF_MONITOR](../../../../docs/framework/unmanaged-api/profiling/cor-prf-monitor-enumeration.md) enumeration that the profiler can specify to the [ICorProfilerInfo5::SetEventMask2](../../../../docs/framework/unmanaged-api/profiling/icorprofilerinfo5-seteventmask2-method.md) method when it is loading. - -## Syntax - + +[Supported in the .NET Framework 4.5.2 and later versions] + +Provides flags in addition to those found in the [COR_PRF_MONITOR](../../../../docs/framework/unmanaged-api/profiling/cor-prf-monitor-enumeration.md) enumeration that the profiler can specify to the [ICorProfilerInfo5::SetEventMask2](../../../../docs/framework/unmanaged-api/profiling/icorprofilerinfo5-seteventmask2-method.md) method when it is loading. + +## Syntax + ```cpp -typedef enum { - COR_PRF_HIGH_MONITOR_NONE = 0x00000000, - COR_PRF_HIGH_ADD_ASSEMBLY_REFERENCES = 0x00000001, +typedef enum { + COR_PRF_HIGH_MONITOR_NONE = 0x00000000, + COR_PRF_HIGH_ADD_ASSEMBLY_REFERENCES = 0x00000001, COR_PRF_HIGH_IN_MEMORY_SYMBOLS_UPDATED = 0x00000002, COR_PRF_HIGH_MONITOR_DYNAMIC_FUNCTION_UNLOADS = 0x00000004, COR_PRF_HIGH_DISABLE_TIERED_COMPILATION = 0x00000008, COR_PRF_HIGH_BASIC_GC = 0x00000010, COR_PRF_HIGH_MONITOR_GC_MOVED_OBJECTS = 0x00000020, COR_PRF_HIGH_MONITOR_LARGEOBJECT_ALLOCATED = 0x00000040, - COR_PRF_HIGH_REQUIRE_PROFILE_IMAGE = 0, - COR_PRF_HIGH_ALLOWABLE_AFTER_ATTACH = COR_PRF_HIGH_IN_MEMORY_SYMBOLS_UPDATED | + COR_PRF_HIGH_REQUIRE_PROFILE_IMAGE = 0, + COR_PRF_HIGH_ALLOWABLE_AFTER_ATTACH = COR_PRF_HIGH_IN_MEMORY_SYMBOLS_UPDATED | COR_PRF_HIGH_MONITOR_DYNAMIC_FUNCTION_UNLOADS | COR_PRF_HIGH_BASIC_GC | COR_PRF_HIGH_MONITOR_GC_MOVED_OBJECTS | - COR_PRF_HIGH_MONITOR_LARGEOBJECT_ALLOCATED, - COR_PRF_HIGH_MONITOR_IMMUTABLE = COR_PRF_HIGH_DISABLE_TIERED_COMPILATION -} COR_PRF_HIGH_MONITOR; -``` - -## Members - -|Member|Description| -|------------|-----------------| -|`COR_PRF_HIGH_MONITOR_NONE`|No flags are set.| -|`COR_PRF_HIGH_ADD_ASSEMBLY_REFERENCES`|Controls the [ICorProfilerCallback6::GetAssemblyReference](../../../../docs/framework/unmanaged-api/profiling/icorprofilercallback6-getassemblyreferences-method.md) callback for adding assembly references during the CLR assembly reference closure walk.| -|`COR_PRF_HIGH_IN_MEMORY_SYMBOLS_UPDATED`|Controls the [ICorProfilerCallback7::ModuleInMemorySymbolsUpdated](../../../../docs/framework/unmanaged-api/profiling/icorprofilercallback7-moduleinmemorysymbolsupdated-method.md) callback for updates to the symbol stream associated with an in-memory module.| + COR_PRF_HIGH_MONITOR_LARGEOBJECT_ALLOCATED, + COR_PRF_HIGH_MONITOR_IMMUTABLE = COR_PRF_HIGH_DISABLE_TIERED_COMPILATION +} COR_PRF_HIGH_MONITOR; +``` + +## Members + +|Member|Description| +|------------|-----------------| +|`COR_PRF_HIGH_MONITOR_NONE`|No flags are set.| +|`COR_PRF_HIGH_ADD_ASSEMBLY_REFERENCES`|Controls the [ICorProfilerCallback6::GetAssemblyReference](../../../../docs/framework/unmanaged-api/profiling/icorprofilercallback6-getassemblyreferences-method.md) callback for adding assembly references during the CLR assembly reference closure walk.| +|`COR_PRF_HIGH_IN_MEMORY_SYMBOLS_UPDATED`|Controls the [ICorProfilerCallback7::ModuleInMemorySymbolsUpdated](../../../../docs/framework/unmanaged-api/profiling/icorprofilercallback7-moduleinmemorysymbolsupdated-method.md) callback for updates to the symbol stream associated with an in-memory module.| |`COR_PRF_HIGH_MONITOR_DYNAMIC_FUNCTION_UNLOADS`|Controls the [ICorProfilerCallback9::DynamicMethodUnloaded](icorprofilercallback9-dynamicmethodunloaded-method.md) callback for indicating when a dynamic method has been garbage collected and unloaded.
[!INCLUDE[net_current_v472plus](../../../../includes/net-current-v472plus.md)]| |`COR_PRF_HIGH_DISABLE_TIERED_COMPILATION`|.NET Core 3.0 and later versions only: Disables [tiered compilation](../../../core/whats-new/dotnet-core-3-0.md) for profilers.| |`COR_PRF_HIGH_BASIC_GC`|.NET Core 3.0 and later versions only: Provides a lightweight GC profiling option compared to [`COR_PRF_MONITOR_GC`](cor-prf-monitor-enumeration.md). Controls only the [GarbageCollectionStarted](../../../../docs/framework/unmanaged-api/profiling/icorprofilercallback2-garbagecollectionstarted-method.md), [GarbageCollectionFinished](../../../../docs/framework/unmanaged-api/profiling/icorprofilercallback2-garbagecollectionfinished-method.md), and [GetGenerationBounds](icorprofilerinfo2-getgenerationbounds-method.md) callbacks. Unlike the `COR_PRF_MONITOR_GC` flag, `COR_PRF_HIGH_BASIC_GC` does not disable concurrent garbage collection.| |`COR_PRF_HIGH_MONITOR_GC_MOVED_OBJECTS`|.NET Core 3.0 and later versions only: Enables the [MovedReferences](icorprofilercallback-movedreferences-method.md) and [MovedReferences2](icorprofilercallback4-movedreferences2-method.md) callbacks for compacting GCs only.| -|`COR_PRF_HIGH_MONITOR_LARGEOBJECT_ALLOCATED`|.NET Core 3.0 and later versions only: Similar to [`COR_PRF_MONITOR_OBJECT_ALLOCATED`](cor-prf-monitor-enumeration.md), but provides information on object allocations for the Large Object Heap (LOH) only.| -|`COR_PRF_HIGH_REQUIRE_PROFILE_IMAGE`|Represents all `COR_PRF_HIGH_MONITOR` flags that require profile-enhanced images. It corresponds to the `COR_PRF_REQUIRE_PROFILE_IMAGE` flag in the [COR_PRF_MONITOR](../../../../docs/framework/unmanaged-api/profiling/cor-prf-monitor-enumeration.md) enumeration.| -|`COR_PRF_HIGH_ALLOWABLE_AFTER_ATTACH`|Represents all `COR_PRF_HIGH_MONITOR` flags that can be set after the profiler is attached to a running app.| -|`COR_PRF_HIGH_MONITOR_IMMUTABLE`|Represents all `COR_PRF_HIGH_MONITOR` flags that can be set only during initialization. Trying to change any of these flags elsewhere results in an `HRESULT` value that indicates failure.| - -## Remarks - The `COR_PRF_HIGH_MONITOR` flags are used with the `pdwEventsHigh` parameter of the [ICorProfilerInfo5::GetEventMask2](../../../../docs/framework/unmanaged-api/profiling/icorprofilerinfo5-geteventmask2-method.md) and [ICorProfilerInfo5::SetEventMask2](../../../../docs/framework/unmanaged-api/profiling/icorprofilerinfo5-seteventmask2-method.md) methods. - -Starting with the .NET Framework 4.6.1, the value of the `COR_PRF_HIGH_ALLOWABLE_AFTER_ATTACH` changed from 0 to `COR_PRF_HIGH_IN_MEMORY_SYMBOLS_UPDATED` (0x00000002). Starting with the .NET Framework 4.7.2, its value changed from `COR_PRF_HIGH_IN_MEMORY_SYMBOLS_UPDATED` to `COR_PRF_HIGH_IN_MEMORY_SYMBOLS_UPDATED | COR_PRF_HIGH_MONITOR_DYNAMIC_FUNCTION_UNLOADS`. +|`COR_PRF_HIGH_MONITOR_LARGEOBJECT_ALLOCATED`|.NET Core 3.0 and later versions only: Similar to [`COR_PRF_MONITOR_OBJECT_ALLOCATED`](cor-prf-monitor-enumeration.md), but provides information on object allocations for the large object heap (LOH) only.| +|`COR_PRF_HIGH_REQUIRE_PROFILE_IMAGE`|Represents all `COR_PRF_HIGH_MONITOR` flags that require profile-enhanced images. It corresponds to the `COR_PRF_REQUIRE_PROFILE_IMAGE` flag in the [COR_PRF_MONITOR](../../../../docs/framework/unmanaged-api/profiling/cor-prf-monitor-enumeration.md) enumeration.| +|`COR_PRF_HIGH_ALLOWABLE_AFTER_ATTACH`|Represents all `COR_PRF_HIGH_MONITOR` flags that can be set after the profiler is attached to a running app.| +|`COR_PRF_HIGH_MONITOR_IMMUTABLE`|Represents all `COR_PRF_HIGH_MONITOR` flags that can be set only during initialization. Trying to change any of these flags elsewhere results in an `HRESULT` value that indicates failure.| + +## Remarks + +The `COR_PRF_HIGH_MONITOR` flags are used with the `pdwEventsHigh` parameter of the [ICorProfilerInfo5::GetEventMask2](../../../../docs/framework/unmanaged-api/profiling/icorprofilerinfo5-geteventmask2-method.md) and [ICorProfilerInfo5::SetEventMask2](../../../../docs/framework/unmanaged-api/profiling/icorprofilerinfo5-seteventmask2-method.md) methods. + +Starting with the .NET Framework 4.6.1, the value of the `COR_PRF_HIGH_ALLOWABLE_AFTER_ATTACH` changed from 0 to `COR_PRF_HIGH_IN_MEMORY_SYMBOLS_UPDATED` (0x00000002). Starting with the .NET Framework 4.7.2, its value changed from `COR_PRF_HIGH_IN_MEMORY_SYMBOLS_UPDATED` to `COR_PRF_HIGH_IN_MEMORY_SYMBOLS_UPDATED | COR_PRF_HIGH_MONITOR_DYNAMIC_FUNCTION_UNLOADS`. `COR_PRF_HIGH_MONITOR_IMMUTABLE` is intended to be a bitmask that represents all flags that can only be set during initialization. Trying to change any of these flags elsewhere results in a failed `HRESULT`. -## Requirements - **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). - - **Header:** CorProf.idl, CorProf.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v452plus](../../../../includes/net-current-v452plus-md.md)] - +## Requirements + +**Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). + +**Header:** CorProf.idl, CorProf.h + +**Library:** CorGuids.lib + +**.NET Framework Versions:** [!INCLUDE[net_current_v452plus](../../../../includes/net-current-v452plus-md.md)] + ## See also - [Profiling Enumerations](../../../../docs/framework/unmanaged-api/profiling/profiling-enumerations.md) diff --git a/docs/framework/whats-new/index.md b/docs/framework/whats-new/index.md index 2e8e24c71100a..fda43be51b170 100644 --- a/docs/framework/whats-new/index.md +++ b/docs/framework/whats-new/index.md @@ -621,7 +621,7 @@ Starting with .NET Framework 4.7.1, diff --git a/docs/standard/garbage-collection/large-object-heap.md b/docs/standard/garbage-collection/large-object-heap.md index 18c2afdeb6780..4cccc332d15c0 100644 --- a/docs/standard/garbage-collection/large-object-heap.md +++ b/docs/standard/garbage-collection/large-object-heap.md @@ -27,7 +27,7 @@ Small objects are always allocated in generation 0 and, depending on their lifet Large objects belong to generation 2 because they are collected only during a generation 2 collection. When a generation is collected, all its younger generation(s) are also collected. For example, when a generation 1 GC happens, both generation 1 and 0 are collected. And when a generation 2 GC happens, the whole heap is collected. For this reason, a generation 2 GC is also called a *full GC*. This article refers to generation 2 GC instead of full GC, but the terms are interchangeable. -Generations provide a logical view of the GC heap. Physically, objects live in managed heap segments. A *managed heap segment* is a chunk of memory that the GC reserves from the OS by calling the [VirtualAlloc function](/windows/desktop/api/memoryapi/nf-memoryapi-virtualalloc) on behalf of managed code. When the CLR is loaded, the GC allocates two initial heap segments: one for small objects (the Small Object Heap, or SOH), and one for large objects (the Large Object Heap). +Generations provide a logical view of the GC heap. Physically, objects live in managed heap segments. A *managed heap segment* is a chunk of memory that the GC reserves from the OS by calling the [VirtualAlloc function](/windows/desktop/api/memoryapi/nf-memoryapi-virtualalloc) on behalf of managed code. When the CLR is loaded, the GC allocates two initial heap segments: one for small objects (the small object heap, or SOH), and one for large objects (the large object heap). The allocation requests are then satisfied by putting managed objects on these managed heap segments. If the object is less than 85,000 bytes, it is put on the segment for the SOH; otherwise, it is put on an LOH segment. Segments are committed (in smaller chunks) as more and more objects are allocated onto them. For the SOH, objects that survive a GC are promoted to the next generation. Objects that survive a generation 0 collection are now considered generation 1 objects, and so on. However, objects that survive the oldest generation are still considered to be in the oldest generation. In other words, survivors from generation 2 are generation 2 objects; and survivors from the LOH are LOH objects (which are collected with gen2). diff --git a/docs/standard/garbage-collection/latency.md b/docs/standard/garbage-collection/latency.md index 7001250cff7f2..12afaeb3dee6d 100644 --- a/docs/standard/garbage-collection/latency.md +++ b/docs/standard/garbage-collection/latency.md @@ -48,7 +48,7 @@ When you use [GCLatencyMode.LowLatency](xref:System.Runtime.GCLatencyMode.LowLat - Avoid allocating high amounts of memory during low latency periods. Low memory notifications can occur because garbage collection reclaims fewer objects. -- While in the low latency mode, minimize the number of new allocations, in particular allocations onto the Large Object Heap and pinned objects. +- While in the low latency mode, minimize the number of new allocations, in particular allocations onto the large object heap and pinned objects. - Be aware of threads that could be allocating. Because the property setting is process-wide, exceptions can be generated on any thread that is allocating. From 7280f5640502a6795fe8e1d0dff14fed9587fa92 Mon Sep 17 00:00:00 2001 From: Genevieve Warren Date: Mon, 18 Nov 2019 17:27:36 -0800 Subject: [PATCH 09/18] finish describing values --- .../core/run-time-config/garbage-collector.md | 25 +++++++++++-------- .../garbage-collection/large-object-heap.md | 9 +++---- 2 files changed, 18 insertions(+), 16 deletions(-) diff --git a/docs/core/run-time-config/garbage-collector.md b/docs/core/run-time-config/garbage-collector.md index 22772caf40ea4..81f312fa3edc7 100644 --- a/docs/core/run-time-config/garbage-collector.md +++ b/docs/core/run-time-config/garbage-collector.md @@ -65,6 +65,7 @@ For more information about some of these settings, see the [Middle ground betwee ### System.GC.HeapHardLimit/COMPlus_GCHeapHardLimit - Specifies the maximum commit size for the GC heap. +- The value can range from 0 to 18446744073709551615. | | Setting name | Values | Version introduced | | - | - | - | - | @@ -74,21 +75,22 @@ For more information about some of these settings, see the [Middle ground betwee ### System.GC.HeapHardLimitPercent/COMPlus_GCHeapHardLimitPercent - Specifies the GC heap usage as a percentage of the total memory. +- Example value: 25 | | Setting name | Values | Version introduced | | - | - | - | - | -| **runtimeconfig.json** | `System.GC.HeapHardLimitPercent` | | .NET Core 3.0 | -| **Environment variable** | `COMPlus_GCHeapHardLimitPercent` | | .NET Core 3.0 | +| **runtimeconfig.json** | `System.GC.HeapHardLimitPercent` | *percentage* | .NET Core 3.0 | +| **Environment variable** | `COMPlus_GCHeapHardLimitPercent` | *percentage* | .NET Core 3.0 | ### System.GC.RetainVM/COMPlus_GCRetainVM - Configures whether segments that should be deleted are put on a standby list for future use or are released back to the operating system (OS). -- By default, segments are released back to the operating system. +- Default: Release segments back to the operating system (`false`). | | Setting name | Values | Version introduced | | - | - | - | - | | **runtimeconfig.json** | `System.GC.RetainVM` | `true` - put on standby
`false` - release to OS | .NET Core 1.0 | -| **Environment variable** | `COMPlus_GCRetainVM` | 0
1 | .NET Core 1.0 | +| **Environment variable** | `COMPlus_GCRetainVM` | 0 - release to OS
1 - put on standby | .NET Core 1.0 | ### System.GC.HeapAffinitizeMask/COMPlus_GCHeapAffinitizeMask @@ -138,25 +140,26 @@ For more information about some of these settings, see the [Middle ground betwee - Specifies whether to affinitize garbage collection threads with processors. That is, whether to create a dedicated heap, GC thread, and background GC thread (if background garbage collection is enabled) for each processor. - Applies to server garbage collection (GC) only. -- By default, garbage collection threads are affinitized with processors (value = `false`). +- Default: Affinitize garbage collection threads with processors (`false`). | | Setting name | Values | Version introduced | | - | - | - | - | | **runtimeconfig.json** | `System.GC.NoAffinitize` | `true` - don't affinitize
`false` - affinitize | .NET Core 3.0 | -| **Environment variable** | `COMPlus_GCNoAffinitize` | 0
1 | .NET Core 3.0 | -| **app.config for .NET Framework** | [GCNoAffinitize](../../framework/configure-apps/file-schema/runtime/gcnoaffinitize-element.md) | | | +| **Environment variable** | `COMPlus_GCNoAffinitize` | 0 - affinitize
1 - don't affinitize | .NET Core 3.0 | +| **app.config for .NET Framework** | [GCNoAffinitize](../../framework/configure-apps/file-schema/runtime/gcnoaffinitize-element.md) | `true` - don't affinitize
`false` - affinitize | | ## Large pages ### COMPlus_GCLargePages - Specifies whether large pages should be used when a heap hard limit is set. +- Default: Disabled (0). - This is an experimental setting. | | Setting name | Values | Version introduced | | - | - | - | - | | **runtimeconfig.json** | N/A | N/A | N/A | -| **Environment variable** | `COMPlus_GCLargePages` | | .NET Core 1.0 | +| **Environment variable** | `COMPlus_GCLargePages` | 0 - disabled
1 - enabled | .NET Core 1.0 | | **app.config for .NET Framework** | N/A | N/A | N/A | ## Large objects @@ -176,12 +179,12 @@ For more information about some of these settings, see the [Middle ground betwee ### System.GC.LOHThreshold/COMPlus_GCLOHThreshold -- Specifies the threshold size that causes objects to go on the large object heap (LOH). +- Specifies the threshold size, in bytes, that causes objects to go on the large object heap (LOH). | | Setting name | Values | Version introduced | | - | - | - | - | -| **runtimeconfig.json** | `System.GC.LOHThreshold` | | .NET Core 1.0 | -| **Environment variable** | `COMPlus_GCLOHThreshold` | | .NET Core 1.0 | +| **runtimeconfig.json** | `System.GC.LOHThreshold` | *size in bytes* | .NET Core 1.0 | +| **Environment variable** | `COMPlus_GCLOHThreshold` | *size in bytes* | .NET Core 1.0 | ## Standalone GC diff --git a/docs/standard/garbage-collection/large-object-heap.md b/docs/standard/garbage-collection/large-object-heap.md index 4cccc332d15c0..1d5f4459edfbd 100644 --- a/docs/standard/garbage-collection/large-object-heap.md +++ b/docs/standard/garbage-collection/large-object-heap.md @@ -1,5 +1,5 @@ --- -title: "The large object heap on Windows systems" +title: LOH on Windows ms.date: "05/02/2018" helpviewer_keywords: - large object heap (LOH)" @@ -7,7 +7,6 @@ helpviewer_keywords: - "garbage collection, large object heap" - "GC [.NET ], large object heap" --- - # The large object heap on Windows systems The .NET Garbage Collector (GC) divides objects up into small and large objects. When an object is large, some of its attributes become more significant than if the object is small. For instance, compacting it -- that is, copying it in memory elsewhere on the heap -- can be expensive. Because of this, the .NET Garbage Collector places large objects on the large object heap (LOH). In this topic, we'll look at the large object heap in depth. We'll discuss what qualifies an object as a large object, how these large objects are collected, and what kind of performance implications large objects impose. @@ -17,7 +16,7 @@ The .NET Garbage Collector (GC) divides objects up into small and large objects. ## How an object ends up on the large object heap and how GC handles them -If an object is greater than or equal to 85,000 bytes, it’s considered a large object. This number was determined by performance tuning. When an object allocation request is for 85,000 or more bytes, the runtime allocates it on the large object heap. +If an object is greater than or equal to 85,000 bytes in size, it’s considered a large object. This number was determined by performance tuning. When an object allocation request is for 85,000 or more bytes, the runtime allocates it on the large object heap. To understand what this means, it's useful to examine some fundamentals about the .NET GC. @@ -149,7 +148,7 @@ These performance counters are usually a good first step in investigating perfor A common way to look at performance counters is with Performance Monitor (perfmon.exe). Use “Add Counters” to add the interesting counter for processes that you care about. You can save the performance counter data to a log file, as Figure 4 shows: -![Screenshow that shows adding performance counters.](media/large-object-heap/add-performance-counter.png) +![Screenshot that shows adding performance counters.](media/large-object-heap/add-performance-counter.png) Figure 4: The LOH after a generation 2 GC Performance counters can also be queried programmatically. Many people collect them this way as part of their routine testing process. When they spot counters with values that are out of the ordinary, they use other means to get more detailed data to help with the investigation. @@ -301,7 +300,7 @@ To verify whether the LOH is causing VM fragmentation, you can set a breakpoint bp kernel32!virtualalloc "j (dwo(@esp+8)>800000) 'kb';'g'" ``` -This command breaks into the debugger and shows the callstack only if [VirtualAlloc](/windows/desktop/api/memoryapi/nf-memoryapi-virtualalloc) is called with an allocation size greater than 8MB (0x800000). +This command breaks into the debugger and shows the call stack only if [VirtualAlloc](/windows/desktop/api/memoryapi/nf-memoryapi-virtualalloc) is called with an allocation size greater than 8MB (0x800000). CLR 2.0 added a feature called *VM Hoarding* that can be useful for scenarios where segments (including on the large and small object heaps) are frequently acquired and released. To specify VM Hoarding, you specify a startup flag called `STARTUP_HOARD_GC_VM` via the hosting API. Instead of releasing empty segments back to the OS, the CLR decommits the memory on these segments and puts them on a standby list. (Note that the CLR doesn't do this for segments that are too large.) The CLR later uses those segments to satisfy new segment requests. The next time that your app needs a new segment, the CLR uses one from this standby list if it can find one that’s big enough. From ee8bf1a00be67ed3034cfb1e92aa4694662aff4f Mon Sep 17 00:00:00 2001 From: Genevieve Warren Date: Mon, 18 Nov 2019 18:11:35 -0800 Subject: [PATCH 10/18] review on staging --- docs/core/run-time-config/garbage-collector.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/run-time-config/garbage-collector.md b/docs/core/run-time-config/garbage-collector.md index 81f312fa3edc7..44666f7acf850 100644 --- a/docs/core/run-time-config/garbage-collector.md +++ b/docs/core/run-time-config/garbage-collector.md @@ -13,11 +13,11 @@ On this page, settings are arranged into groups of settings that you can use in > [!NOTE] > > - These settings can also be changed dynamically by the app as it's running, so any run-time settings you set may be overridden. -> - Some settings, such as [latency level](../../standard/garbage-collection/latency.md)), are typically set only through the API at design time. Such settings are omitted from this page. +> - Some settings, such as [latency level](../../standard/garbage-collection/latency.md), are typically set only through the API at design time. Such settings are omitted from this page. ## Flavors of garbage collection -The main two flavors of garbage collection are workstation and server. For more information about differences between the two, see [Fundamentals of garbage collection](../../standard/garbage-collection/fundamentals.md#workstation-and-server-garbage-collection). The sub-flavors of garbage collection are background and non-concurrent. Use the settings described in this section to select these flavors of garbage collection. +The main two flavors of garbage collection are workstation and server. For more information about differences between the two, see [Fundamentals of garbage collection](../../standard/garbage-collection/fundamentals.md#workstation-and-server-garbage-collection). The subflavors of garbage collection are background and non-concurrent. Use the settings described in this section to select these flavors of garbage collection. ### System.GC.Server/COMPlus_gcServer From d066bec7625ea6c5dec029ed0396d1ab1f920d50 Mon Sep 17 00:00:00 2001 From: Genevieve Warren Date: Mon, 18 Nov 2019 22:17:24 -0800 Subject: [PATCH 11/18] heap count improvements --- .../core/run-time-config/garbage-collector.md | 77 ++++++++++--------- .../runtime/gcheapcount-element.md | 2 +- 2 files changed, 42 insertions(+), 37 deletions(-) diff --git a/docs/core/run-time-config/garbage-collector.md b/docs/core/run-time-config/garbage-collector.md index 44666f7acf850..a584283831c59 100644 --- a/docs/core/run-time-config/garbage-collector.md +++ b/docs/core/run-time-config/garbage-collector.md @@ -17,7 +17,11 @@ On this page, settings are arranged into groups of settings that you can use in ## Flavors of garbage collection -The main two flavors of garbage collection are workstation and server. For more information about differences between the two, see [Fundamentals of garbage collection](../../standard/garbage-collection/fundamentals.md#workstation-and-server-garbage-collection). The subflavors of garbage collection are background and non-concurrent. Use the settings described in this section to select these flavors of garbage collection. +The two main flavors of garbage collection are workstation GC and server GC. For more information about differences between the two, see [Fundamentals of garbage collection](../../standard/garbage-collection/fundamentals.md#workstation-and-server-garbage-collection). + +The subflavors of garbage collection are background and non-concurrent. + +Use the settings described in this section to select flavors of garbage collection. ### System.GC.Server/COMPlus_gcServer @@ -53,48 +57,19 @@ For more information about some of these settings, see the [Middle ground betwee - Limits the number of heaps created by the garbage collector. - Applies to server garbage collection (GC) only. -- If GC thread/processor affinity is disabled, this setting limits the number of GC heaps. If GC thread/processor affinity is enabled, this setting limits the number of GC heaps to the processors 0 to one-less-than its specified value. +- If GC thread/processor affinity is enabled, which is the default, the heap count setting affinitizes *number* GC heaps/threads to the first *number* processors. (Use the affinitize mask or affinitize ranges settings to specify exactly which processors to affinitize.) +- If GC thread/processor affinity is disabled, this setting limits the number of GC heaps. - For more information, see the [GCHeapCount remarks](../../framework/configure-apps/file-schema/runtime/gcheapcount-element.md#remarks). | | Setting name | Values | Version introduced | | - | - | - | - | | **runtimeconfig.json** | `System.GC.HeapCount` | *number* | .NET Core 3.0 | | **Environment variable** | `COMPlus_GCHeapCount` | *number* | .NET Core 3.0 | -| **app.config for .NET Framework** | [GCHeapCount](../../framework/configure-apps/file-schema/runtime/gcheapcount-element.md) | *number* | | - -### System.GC.HeapHardLimit/COMPlus_GCHeapHardLimit - -- Specifies the maximum commit size for the GC heap. -- The value can range from 0 to 18446744073709551615. - -| | Setting name | Values | Version introduced | -| - | - | - | - | -| **runtimeconfig.json** | `System.GC.HeapHardLimit` | *number* | .NET Core 3.0 | -| **Environment variable** | `COMPlus_GCHeapHardLimit` | *number* | .NET Core 3.0 | - -### System.GC.HeapHardLimitPercent/COMPlus_GCHeapHardLimitPercent - -- Specifies the GC heap usage as a percentage of the total memory. -- Example value: 25 - -| | Setting name | Values | Version introduced | -| - | - | - | - | -| **runtimeconfig.json** | `System.GC.HeapHardLimitPercent` | *percentage* | .NET Core 3.0 | -| **Environment variable** | `COMPlus_GCHeapHardLimitPercent` | *percentage* | .NET Core 3.0 | - -### System.GC.RetainVM/COMPlus_GCRetainVM - -- Configures whether segments that should be deleted are put on a standby list for future use or are released back to the operating system (OS). -- Default: Release segments back to the operating system (`false`). - -| | Setting name | Values | Version introduced | -| - | - | - | - | -| **runtimeconfig.json** | `System.GC.RetainVM` | `true` - put on standby
`false` - release to OS | .NET Core 1.0 | -| **Environment variable** | `COMPlus_GCRetainVM` | 0 - release to OS
1 - put on standby | .NET Core 1.0 | +| **app.config for .NET Framework** | [GCHeapCount](../../framework/configure-apps/file-schema/runtime/gcheapcount-element.md) | *number* | 4.6.2 | ### System.GC.HeapAffinitizeMask/COMPlus_GCHeapAffinitizeMask -- Specifies the exact processors that garbage collector threads should use as a bit mask. +- Specifies the exact processors that garbage collector threads should use. - If processor affinity is disabled by setting `System.GC.NoAffinitize` to `true`, this setting is ignored. - Applies to server garbage collection (GC) only. - The decimal value is a bit mask that defines the processors that are available to the process. For example, a decimal value of 1023 is equivalent to 0x3FF in hexadecimal notation and 0011 1111 1111 in binary notation. This specifies that the first 10 processors are to be used. To specify the next 10 processors, that is, processors 10-19, specify a decimal value of 1047552, which is equivalent to 0xFFC00 in hexadecimal and 1111 1111 1100 0000 0000 in binary. @@ -103,7 +78,7 @@ For more information about some of these settings, see the [Middle ground betwee | - | - | - | - | | **runtimeconfig.json** | `System.GC.HeapAffinitizeMask` | *decimal value* | .NET Core 3.0 | | **Environment variable** | `COMPlus_GCHeapAffinitizeMask` | *decimal value* | .NET Core 3.0 | -| **app.config for .NET Framework** | [GCHeapAffinitizeMask](../../framework/configure-apps/file-schema/runtime/gcheapaffinitizemask-element.md) | *decimal value* | | +| **app.config for .NET Framework** | [GCHeapAffinitizeMask](../../framework/configure-apps/file-schema/runtime/gcheapaffinitizemask-element.md) | *decimal value* | 4.6.2 | ### System.GC.GCHeapAffinitizeRanges/COMPlus_GCHeapAffinitizeRanges @@ -146,7 +121,37 @@ For more information about some of these settings, see the [Middle ground betwee | - | - | - | - | | **runtimeconfig.json** | `System.GC.NoAffinitize` | `true` - don't affinitize
`false` - affinitize | .NET Core 3.0 | | **Environment variable** | `COMPlus_GCNoAffinitize` | 0 - affinitize
1 - don't affinitize | .NET Core 3.0 | -| **app.config for .NET Framework** | [GCNoAffinitize](../../framework/configure-apps/file-schema/runtime/gcnoaffinitize-element.md) | `true` - don't affinitize
`false` - affinitize | | +| **app.config for .NET Framework** | [GCNoAffinitize](../../framework/configure-apps/file-schema/runtime/gcnoaffinitize-element.md) | `true` - don't affinitize
`false` - affinitize | 4.6.2 | + +### System.GC.HeapHardLimit/COMPlus_GCHeapHardLimit + +- Specifies the maximum commit size for the GC heap. +- The value can range from 0 to 18446744073709551615. + +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | `System.GC.HeapHardLimit` | *number* | .NET Core 3.0 | +| **Environment variable** | `COMPlus_GCHeapHardLimit` | *number* | .NET Core 3.0 | + +### System.GC.HeapHardLimitPercent/COMPlus_GCHeapHardLimitPercent + +- Specifies the GC heap usage as a percentage of the total memory. +- Example value: 25 + +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | `System.GC.HeapHardLimitPercent` | *percentage* | .NET Core 3.0 | +| **Environment variable** | `COMPlus_GCHeapHardLimitPercent` | *percentage* | .NET Core 3.0 | + +### System.GC.RetainVM/COMPlus_GCRetainVM + +- Configures whether segments that should be deleted are put on a standby list for future use or are released back to the operating system (OS). +- Default: Release segments back to the operating system (`false`). + +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | `System.GC.RetainVM` | `true` - put on standby
`false` - release to OS | .NET Core 1.0 | +| **Environment variable** | `COMPlus_GCRetainVM` | 0 - release to OS
1 - put on standby | .NET Core 1.0 | ## Large pages diff --git a/docs/framework/configure-apps/file-schema/runtime/gcheapcount-element.md b/docs/framework/configure-apps/file-schema/runtime/gcheapcount-element.md index 7487991de5aa3..7ae0faf4cd36f 100644 --- a/docs/framework/configure-apps/file-schema/runtime/gcheapcount-element.md +++ b/docs/framework/configure-apps/file-schema/runtime/gcheapcount-element.md @@ -57,7 +57,7 @@ By default, server GC threads are hard-affinitized with their respective CPU so - [GCHeapAffinitizeMask](gcheapaffinitizemask-element.md), which controls the affinity of GC threads/heaps with CPUs. -If **GCHeapCount** is set and **GCNoAffinitize** is disabled (its default setting), there is an affinity between the *nn* GC threads/heaps and the first *nn* processors. You can use the **GCHeapAffinitizeMask** element to specify which processors are used by the process' server GC heaps. Otherwise, if multiple server processes are running on a system, their processor usage will overlap. +If **GCHeapCount** is set and **GCNoAffinitize** is disabled (its default setting), there is an affinity between the *nn* GC threads/heaps and the first *nn* processors. You can use the **GCHeapAffinitizeMask** element to specify which processors are used by the process's server GC heaps. Otherwise, if multiple server processes are running on a system, their processor usage will overlap. If **GCHeapCount** is set and **GCNoAffinitize** is enabled, the garbage collector limits the number of processors used for server GC but does not affinitize GC heaps and processors. From 499d35eb86c0f0cfbd1c3b21e8e64559fbd77ba4 Mon Sep 17 00:00:00 2001 From: Genevieve Warren Date: Mon, 18 Nov 2019 22:23:58 -0800 Subject: [PATCH 12/18] remove unnecessary whitespace changes for ease of review --- .../cor-prf-high-monitor-enumeration.md | 76 +++++++++---------- 1 file changed, 38 insertions(+), 38 deletions(-) diff --git a/docs/framework/unmanaged-api/profiling/cor-prf-high-monitor-enumeration.md b/docs/framework/unmanaged-api/profiling/cor-prf-high-monitor-enumeration.md index d0200ce8b536d..58b0064952372 100644 --- a/docs/framework/unmanaged-api/profiling/cor-prf-high-monitor-enumeration.md +++ b/docs/framework/unmanaged-api/profiling/cor-prf-high-monitor-enumeration.md @@ -5,66 +5,66 @@ ms.assetid: 3ba543d8-15e5-4322-b6e7-1ebfc92ed7dd --- # COR_PRF_HIGH_MONITOR Enumeration -[Supported in the .NET Framework 4.5.2 and later versions] - -Provides flags in addition to those found in the [COR_PRF_MONITOR](../../../../docs/framework/unmanaged-api/profiling/cor-prf-monitor-enumeration.md) enumeration that the profiler can specify to the [ICorProfilerInfo5::SetEventMask2](../../../../docs/framework/unmanaged-api/profiling/icorprofilerinfo5-seteventmask2-method.md) method when it is loading. - -## Syntax - +[Supported in the .NET Framework 4.5.2 and later versions] + +Provides flags in addition to those found in the [COR_PRF_MONITOR](../../../../docs/framework/unmanaged-api/profiling/cor-prf-monitor-enumeration.md) enumeration that the profiler can specify to the [ICorProfilerInfo5::SetEventMask2](../../../../docs/framework/unmanaged-api/profiling/icorprofilerinfo5-seteventmask2-method.md) method when it is loading. + +## Syntax + ```cpp -typedef enum { - COR_PRF_HIGH_MONITOR_NONE = 0x00000000, - COR_PRF_HIGH_ADD_ASSEMBLY_REFERENCES = 0x00000001, +typedef enum { + COR_PRF_HIGH_MONITOR_NONE = 0x00000000, + COR_PRF_HIGH_ADD_ASSEMBLY_REFERENCES = 0x00000001, COR_PRF_HIGH_IN_MEMORY_SYMBOLS_UPDATED = 0x00000002, COR_PRF_HIGH_MONITOR_DYNAMIC_FUNCTION_UNLOADS = 0x00000004, COR_PRF_HIGH_DISABLE_TIERED_COMPILATION = 0x00000008, COR_PRF_HIGH_BASIC_GC = 0x00000010, COR_PRF_HIGH_MONITOR_GC_MOVED_OBJECTS = 0x00000020, COR_PRF_HIGH_MONITOR_LARGEOBJECT_ALLOCATED = 0x00000040, - COR_PRF_HIGH_REQUIRE_PROFILE_IMAGE = 0, - COR_PRF_HIGH_ALLOWABLE_AFTER_ATTACH = COR_PRF_HIGH_IN_MEMORY_SYMBOLS_UPDATED | + COR_PRF_HIGH_REQUIRE_PROFILE_IMAGE = 0, + COR_PRF_HIGH_ALLOWABLE_AFTER_ATTACH = COR_PRF_HIGH_IN_MEMORY_SYMBOLS_UPDATED | COR_PRF_HIGH_MONITOR_DYNAMIC_FUNCTION_UNLOADS | COR_PRF_HIGH_BASIC_GC | COR_PRF_HIGH_MONITOR_GC_MOVED_OBJECTS | - COR_PRF_HIGH_MONITOR_LARGEOBJECT_ALLOCATED, - COR_PRF_HIGH_MONITOR_IMMUTABLE = COR_PRF_HIGH_DISABLE_TIERED_COMPILATION -} COR_PRF_HIGH_MONITOR; -``` - -## Members - -|Member|Description| -|------------|-----------------| -|`COR_PRF_HIGH_MONITOR_NONE`|No flags are set.| -|`COR_PRF_HIGH_ADD_ASSEMBLY_REFERENCES`|Controls the [ICorProfilerCallback6::GetAssemblyReference](../../../../docs/framework/unmanaged-api/profiling/icorprofilercallback6-getassemblyreferences-method.md) callback for adding assembly references during the CLR assembly reference closure walk.| -|`COR_PRF_HIGH_IN_MEMORY_SYMBOLS_UPDATED`|Controls the [ICorProfilerCallback7::ModuleInMemorySymbolsUpdated](../../../../docs/framework/unmanaged-api/profiling/icorprofilercallback7-moduleinmemorysymbolsupdated-method.md) callback for updates to the symbol stream associated with an in-memory module.| + COR_PRF_HIGH_MONITOR_LARGEOBJECT_ALLOCATED, + COR_PRF_HIGH_MONITOR_IMMUTABLE = COR_PRF_HIGH_DISABLE_TIERED_COMPILATION +} COR_PRF_HIGH_MONITOR; +``` + +## Members + +|Member|Description| +|------------|-----------------| +|`COR_PRF_HIGH_MONITOR_NONE`|No flags are set.| +|`COR_PRF_HIGH_ADD_ASSEMBLY_REFERENCES`|Controls the [ICorProfilerCallback6::GetAssemblyReference](../../../../docs/framework/unmanaged-api/profiling/icorprofilercallback6-getassemblyreferences-method.md) callback for adding assembly references during the CLR assembly reference closure walk.| +|`COR_PRF_HIGH_IN_MEMORY_SYMBOLS_UPDATED`|Controls the [ICorProfilerCallback7::ModuleInMemorySymbolsUpdated](../../../../docs/framework/unmanaged-api/profiling/icorprofilercallback7-moduleinmemorysymbolsupdated-method.md) callback for updates to the symbol stream associated with an in-memory module.| |`COR_PRF_HIGH_MONITOR_DYNAMIC_FUNCTION_UNLOADS`|Controls the [ICorProfilerCallback9::DynamicMethodUnloaded](icorprofilercallback9-dynamicmethodunloaded-method.md) callback for indicating when a dynamic method has been garbage collected and unloaded.
[!INCLUDE[net_current_v472plus](../../../../includes/net-current-v472plus.md)]| |`COR_PRF_HIGH_DISABLE_TIERED_COMPILATION`|.NET Core 3.0 and later versions only: Disables [tiered compilation](../../../core/whats-new/dotnet-core-3-0.md) for profilers.| |`COR_PRF_HIGH_BASIC_GC`|.NET Core 3.0 and later versions only: Provides a lightweight GC profiling option compared to [`COR_PRF_MONITOR_GC`](cor-prf-monitor-enumeration.md). Controls only the [GarbageCollectionStarted](../../../../docs/framework/unmanaged-api/profiling/icorprofilercallback2-garbagecollectionstarted-method.md), [GarbageCollectionFinished](../../../../docs/framework/unmanaged-api/profiling/icorprofilercallback2-garbagecollectionfinished-method.md), and [GetGenerationBounds](icorprofilerinfo2-getgenerationbounds-method.md) callbacks. Unlike the `COR_PRF_MONITOR_GC` flag, `COR_PRF_HIGH_BASIC_GC` does not disable concurrent garbage collection.| |`COR_PRF_HIGH_MONITOR_GC_MOVED_OBJECTS`|.NET Core 3.0 and later versions only: Enables the [MovedReferences](icorprofilercallback-movedreferences-method.md) and [MovedReferences2](icorprofilercallback4-movedreferences2-method.md) callbacks for compacting GCs only.| |`COR_PRF_HIGH_MONITOR_LARGEOBJECT_ALLOCATED`|.NET Core 3.0 and later versions only: Similar to [`COR_PRF_MONITOR_OBJECT_ALLOCATED`](cor-prf-monitor-enumeration.md), but provides information on object allocations for the large object heap (LOH) only.| -|`COR_PRF_HIGH_REQUIRE_PROFILE_IMAGE`|Represents all `COR_PRF_HIGH_MONITOR` flags that require profile-enhanced images. It corresponds to the `COR_PRF_REQUIRE_PROFILE_IMAGE` flag in the [COR_PRF_MONITOR](../../../../docs/framework/unmanaged-api/profiling/cor-prf-monitor-enumeration.md) enumeration.| -|`COR_PRF_HIGH_ALLOWABLE_AFTER_ATTACH`|Represents all `COR_PRF_HIGH_MONITOR` flags that can be set after the profiler is attached to a running app.| -|`COR_PRF_HIGH_MONITOR_IMMUTABLE`|Represents all `COR_PRF_HIGH_MONITOR` flags that can be set only during initialization. Trying to change any of these flags elsewhere results in an `HRESULT` value that indicates failure.| - +|`COR_PRF_HIGH_REQUIRE_PROFILE_IMAGE`|Represents all `COR_PRF_HIGH_MONITOR` flags that require profile-enhanced images. It corresponds to the `COR_PRF_REQUIRE_PROFILE_IMAGE` flag in the [COR_PRF_MONITOR](../../../../docs/framework/unmanaged-api/profiling/cor-prf-monitor-enumeration.md) enumeration.| +|`COR_PRF_HIGH_ALLOWABLE_AFTER_ATTACH`|Represents all `COR_PRF_HIGH_MONITOR` flags that can be set after the profiler is attached to a running app.| +|`COR_PRF_HIGH_MONITOR_IMMUTABLE`|Represents all `COR_PRF_HIGH_MONITOR` flags that can be set only during initialization. Trying to change any of these flags elsewhere results in an `HRESULT` value that indicates failure.| + ## Remarks -The `COR_PRF_HIGH_MONITOR` flags are used with the `pdwEventsHigh` parameter of the [ICorProfilerInfo5::GetEventMask2](../../../../docs/framework/unmanaged-api/profiling/icorprofilerinfo5-geteventmask2-method.md) and [ICorProfilerInfo5::SetEventMask2](../../../../docs/framework/unmanaged-api/profiling/icorprofilerinfo5-seteventmask2-method.md) methods. - -Starting with the .NET Framework 4.6.1, the value of the `COR_PRF_HIGH_ALLOWABLE_AFTER_ATTACH` changed from 0 to `COR_PRF_HIGH_IN_MEMORY_SYMBOLS_UPDATED` (0x00000002). Starting with the .NET Framework 4.7.2, its value changed from `COR_PRF_HIGH_IN_MEMORY_SYMBOLS_UPDATED` to `COR_PRF_HIGH_IN_MEMORY_SYMBOLS_UPDATED | COR_PRF_HIGH_MONITOR_DYNAMIC_FUNCTION_UNLOADS`. +The `COR_PRF_HIGH_MONITOR` flags are used with the `pdwEventsHigh` parameter of the [ICorProfilerInfo5::GetEventMask2](../../../../docs/framework/unmanaged-api/profiling/icorprofilerinfo5-geteventmask2-method.md) and [ICorProfilerInfo5::SetEventMask2](../../../../docs/framework/unmanaged-api/profiling/icorprofilerinfo5-seteventmask2-method.md) methods. + +Starting with the .NET Framework 4.6.1, the value of the `COR_PRF_HIGH_ALLOWABLE_AFTER_ATTACH` changed from 0 to `COR_PRF_HIGH_IN_MEMORY_SYMBOLS_UPDATED` (0x00000002). Starting with the .NET Framework 4.7.2, its value changed from `COR_PRF_HIGH_IN_MEMORY_SYMBOLS_UPDATED` to `COR_PRF_HIGH_IN_MEMORY_SYMBOLS_UPDATED | COR_PRF_HIGH_MONITOR_DYNAMIC_FUNCTION_UNLOADS`. `COR_PRF_HIGH_MONITOR_IMMUTABLE` is intended to be a bitmask that represents all flags that can only be set during initialization. Trying to change any of these flags elsewhere results in a failed `HRESULT`. ## Requirements -**Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). - -**Header:** CorProf.idl, CorProf.h - -**Library:** CorGuids.lib - -**.NET Framework Versions:** [!INCLUDE[net_current_v452plus](../../../../includes/net-current-v452plus-md.md)] - +**Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). + +**Header:** CorProf.idl, CorProf.h + +**Library:** CorGuids.lib + +**.NET Framework Versions:** [!INCLUDE[net_current_v452plus](../../../../includes/net-current-v452plus-md.md)] + ## See also - [Profiling Enumerations](../../../../docs/framework/unmanaged-api/profiling/profiling-enumerations.md) From 85200dc50b7f65191e435157611934267f345dc2 Mon Sep 17 00:00:00 2001 From: Genevieve Warren Date: Mon, 18 Nov 2019 22:29:01 -0800 Subject: [PATCH 13/18] remove trim trailing whitespace changes; remove in-article toc --- .../performance-counters.md | 450 +++++++++--------- 1 file changed, 214 insertions(+), 236 deletions(-) diff --git a/docs/framework/debug-trace-profile/performance-counters.md b/docs/framework/debug-trace-profile/performance-counters.md index 5dc7e4bcf0f1a..bba3ed886c4c5 100644 --- a/docs/framework/debug-trace-profile/performance-counters.md +++ b/docs/framework/debug-trace-profile/performance-counters.md @@ -1,248 +1,226 @@ --- title: "Performance Counters in the .NET Framework" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "performance, .NET Framework applications" - "performance counters" - "performance monitoring, counters" ms.assetid: 06a4ae8c-eeb2-4d5a-817e-b1b95c0653e1 --- -# Performance Counters in the .NET Framework -This topic provides a list of performance counters you can find in the [Windows Performance Monitor](https://docs.microsoft.com/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc749249%28v=ws.11%29). - -- [Exception performance counters](#exception) - -- [Interop performance counters](#interop) - -- [JIT performance counters](#jit) - -- [Loading performance counters](#loading) - -- [Lock and thread performance counters](#lockthread) - -- [Memory performance counters](#memory) - -- [Networking performance counters](#networking) - -- [Security performance counters](#security) - - -## Exception performance counters - The Performance console .NET CLR Exceptions category includes counters that provide information about the exceptions thrown by an application. The following table describes these performance counters. - -|Performance counter|Description| -|-------------------------|-----------------| -|**# of Exceps Thrown**|Displays the total number of exceptions thrown since the application started. This includes both .NET exceptions and unmanaged exceptions that are converted into .NET exceptions. For example, an HRESULT returned from unmanaged code is converted to an exception in managed code.

This counter includes both handled and unhandled exceptions. Exceptions that are rethrown are counted again.| -|**# of Exceps Thrown / Sec**|Displays the number of exceptions thrown per second. This includes both .NET exceptions and unmanaged exceptions that are converted into .NET exceptions. For example, an HRESULT returned from unmanaged code is converted to an exception in managed code.

This counter includes both handled and unhandled exceptions. It is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval. This counter is an indicator of potential performance problems if a large (>100s) number of exceptions are thrown.| -|**# of Filters / Sec**|Displays the number of .NET exception filters executed per second. An exception filter evaluates regardless of whether an exception is handled.

This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| -|**# of Finallys / Sec**|Displays the number of finally blocks executed per second. A finally block is guaranteed to be executed regardless of how the try block was exited. Only the finally blocks executed for an exception are counted; finally blocks on normal code paths are not counted by this counter.

This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| -|**Throw to Catch Depth / Sec**|Displays the number of stack frames traversed, from the frame that threw the exception to the frame that handled the exception, per second. This counter resets to zero when an exception handler is entered, so nested exceptions show the handler-to-handler stack depth.

This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| - - -## Interop performance counters - The Performance console .NET CLR Interop category includes counters that provide information about an application's interaction with COM components, COM+ services, and external type libraries. The following table describes these performance counters. - -|Performance counter|Description| -|-------------------------|-----------------| -|**# of CCWs**|Displays the current number of COM callable wrappers (CCWs). A CCW is a proxy for a managed object being referenced from an unmanaged COM client. This counter indicates the number of managed objects referenced by unmanaged COM code.| -|**# of marshaling**|Displays the total number of times arguments and return values have been marshaled from managed to unmanaged code, and vice versa, since the application started. This counter is not incremented if the stubs are inlined. (Stubs are responsible for marshaling arguments and return values). Stubs are usually inlined if the marshaling overhead is small.| -|**# of Stubs**|Displays the current number of stubs created by the common language runtime. Stubs are responsible for marshaling arguments and return values from managed to unmanaged code, and vice versa, during a COM interop call or a platform invoke call.| -|**# of TLB exports / sec**|Reserved for future use.| -|**# of TLB imports / sec**|Reserved for future use.| - - -## JIT performance counters - The Performance console .NET CLR JIT category includes counters that provide information about code that has been JIT-compiled. The following table describes these performance counters. - -|Performance counter|Description| -|-------------------------|-----------------| -|**# of IL Bytes JITted**|Displays the total number of Microsoft intermediate language (MSIL) bytes compiled by the just-in-time (JIT) compiler since the application started. This counter is equivalent to the **Total # of IL Bytes Jitted** counter.| -|**# of Methods JITted**|Displays the total number of methods JIT-compiled since the application started. This counter does not include pre-JIT-compiled methods.| -|**% Time in Jit**|Displays the percentage of elapsed time spent in JIT compilation since the last JIT compilation phase. This counter is updated at the end of every JIT compilation phase. A JIT compilation phase occurs when a method and its dependencies are compiled.| -|**IL Bytes Jitted / sec**|Displays the number of MSIL bytes that are JIT-compiled per second. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| -|**Standard Jit Failures**|Displays the peak number of methods the JIT compiler has failed to compile since the application started. This failure can occur if the MSIL cannot be verified or if there is an internal error in the JIT compiler.| -|**Total # of IL Bytes Jitted**|Displays the total MSIL bytes JIT-compiled since the application started. This counter is equivalent to the **# of IL Bytes Jitted** counter.| - - -## Loading performance counters - The Performance console .NET CLR Loading category includes counters that provide information about assemblies, classes, and application domains that are loaded. The following table describes these performance counters. - -|Performance counter|Description| -|-------------------------|-----------------| -|**% Time Loading**|Reserved for future use.| -|**Assembly Search Length**|Reserved for future use.| -|**Bytes in Loader Heap**|Displays the current size, in bytes, of the memory committed by the class loader across all application domains. Committed memory is the physical space reserved in the disk paging file.| -|**Current appdomains**|Displays the current number of application domains loaded in this application.| -|**Current Assemblies**|Displays the current number of assemblies loaded across all application domains in the currently running application. If the assembly is loaded as domain-neutral from multiple application domains, this counter is incremented only once.| -|**Current Classes Loaded**|Displays the current number of classes loaded in all assemblies.| -|**Rate of appdomains**|Displays the number of application domains loaded per second. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| -|**Rate of appdomains unloaded**|Displays the number of application domains unloaded per second. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| -|**Rate of Assemblies**|Displays the number of assemblies loaded per second across all application domains. If the assembly is loaded as domain-neutral from multiple application domains, this counter is incremented only once.

This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| -|**Rate of Classes Loaded**|Displays the number of classes loaded per second in all assemblies. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| -|**Rate of Load Failures**|Displays the number of classes that failed to load per second. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.

Load failures can occur for many reasons, such as inadequate security or invalid format. For details, see the profiling services Help.| -|**Total # of Load Failures**|Displays the peak number of classes that have failed to load since the application started.

Load failures can occur for many reasons, such as inadequate security or invalid format. For details, see the profiling services Help.| -|**Total Appdomains**|Displays the peak number of application domains loaded since the application started.| -|**Total appdomains unloaded**|Displays the total number of application domains unloaded since the application started. If an application domain is loaded and unloaded multiple times, this counter increments each time the application domain is unloaded.| -|**Total Assemblies**|Displays the total number of assemblies loaded since the application started. If the assembly is loaded as domain-neutral from multiple application domains, this counter is incremented only once.| -|**Total Classes Loaded**|Displays the cumulative number of classes loaded in all assemblies since the application started.| - - -## Lock and thread performance counters - The Performance console .NET CLR LocksAndThreads category includes counters that provide information about managed locks and threads that an application uses. The following table describes these performance counters. - -|Performance counter|Description| -|-------------------------|-----------------| -|**# of current logical Threads**|Displays the number of current managed thread objects in the application. This counter maintains the count of both running and stopped threads. This counter is not an average over time; it displays only the last observed value.| -|**# of current physical Threads**|Displays the number of native operating system threads created and owned by the common language runtime to act as underlying threads for managed thread objects. This counter's value does not include the threads used by the runtime in its internal operations; it is a subset of the threads in the operating system process.| -|**# of current recognized threads**|Displays the number of threads that are currently recognized by the runtime. These threads are associated with a corresponding managed thread object. The runtime does not create these threads, but they have run inside the runtime at least once.

Only unique threads are tracked; threads with the same thread ID that reenter the runtime or are recreated after the thread exits are not counted twice.| -|**# of total recognized Threads**|Displays the total number of threads that have been recognized by the runtime since the application started. These threads are associated with a corresponding managed thread object. The runtime does not create these threads, but they have run inside the runtime at least once.

Only unique threads are tracked; threads with the same thread ID that reenter the runtime or are recreated after the thread exits are not counted twice.| -|**Contention Rate / Sec**|Displays the rate at which threads in the runtime attempt to acquire a managed lock unsuccessfully.| -|**Current Queue Length**|Displays the total number of threads that are currently waiting to acquire a managed lock in the application. This counter is not an average over time; it displays the last observed value.| -|**Queue Length / sec**|Displays the number of threads per second that are waiting to acquire a lock in the application. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| -|**Queue Length Peak**|Displays the total number of threads that waited to acquire a managed lock since the application started.| -|**rate of recognized threads / sec**|Displays the number of threads per second that have been recognized by the runtime. These threads are associated with a corresponding managed thread object. The runtime does not create these threads, but they have run inside the runtime at least once.

Only unique threads are tracked; threads with the same thread ID that reenter the runtime or are recreated after the thread exits are not counted twice.

This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| -|**Total # of Contentions**|Displays the total number of times that threads in the runtime have attempted to acquire a managed lock unsuccessfully.| - - -## Memory performance counters - The Performance console .NET CLR Memory category includes counters that provide information about the garbage collector. The following table describes these performance counters. - -|Performance counter|Description| -|-------------------------|-----------------| -|**# Bytes in all Heaps**|Displays the sum of the **Gen 1 Heap Size**, **Gen 2 Heap Size**, and **Large Object Heap Size** counters. This counter indicates the current memory allocated in bytes on the garbage collection heaps.| -|**# GC Handles**|Displays the current number of garbage collection handles in use. Garbage collection handles are handles to resources external to the common language runtime and the managed environment.| -|**# Gen 0 Collections**|Displays the number of times the generation 0 objects (that is, the youngest, most recently allocated objects) are garbage collected since the application started.

Generation 0 garbage collection occurs when the available memory in generation 0 is not sufficient to satisfy an allocation request. This counter is incremented at the end of a generation 0 garbage collection. Higher generation garbage collections include all lower generation collections. This counter is explicitly incremented when a higher generation (generation 1 or 2) garbage collection occurs.

This counter displays the last observed value. The **_Global\_** counter value is not accurate and should be ignored.| -|**# Gen 1 Collections**|Displays the number of times the generation 1 objects are garbage collected since the application started.

The counter is incremented at the end of a generation 1 garbage collection. Higher generation garbage collections include all lower generation collections. This counter is explicitly incremented when a higher generation (generation 2) garbage collection occurs.

This counter displays the last observed value. The **_Global\_** counter value is not accurate and should be ignored.| -|**# Gen 2 Collections**|Displays the number of times the generation 2 objects are garbage collected since the application started. The counter is incremented at the end of a generation 2 garbage collection (also called a full garbage collection).

This counter displays the last observed value. The **_Global\_** counter value is not accurate and should be ignored.| -|**# Induced GC**|Displays the peak number of times garbage collection was performed because of an explicit call to . It is good practice to let the garbage collector tune the frequency of its collections.| -|**# of Pinned Objects**|Displays the number of pinned objects encountered in the last garbage collection. A pinned object is an object that the garbage collector cannot move in memory. This counter tracks pinned objects only in the heaps that are garbage collected. For example, a generation 0 garbage collection causes enumeration of pinned objects only in the generation 0 heap.| -|**# of Sink Blocks in use**|Displays the current number of synchronization blocks in use. Synchronization blocks are per-object data structures allocated for storing synchronization information. They hold weak references to managed objects and must be scanned by the garbage collector. Synchronization blocks are not limited to storing synchronization information; they can also store COM interop metadata. This counter indicates performance problems with heavy use of synchronization primitives.| -|**# Total committed Bytes**|Displays the amount of virtual memory, in bytes, currently committed by the garbage collector. Committed memory is the physical memory for which space has been reserved in the disk paging file.| -|**# Total reserved Bytes**|Displays the amount of virtual memory, in bytes, currently reserved by the garbage collector. Reserved memory is the virtual memory space reserved for the application when no disk or main memory pages have been used.| -|**% Time in GC**|Displays the percentage of elapsed time that was spent performing a garbage collection since the last garbage collection cycle. This counter usually indicates the work done by the garbage collector to collect and compact memory on behalf of the application. This counter is updated only at the end of every garbage collection. This counter is not an average; its value reflects the last observed value.| -|**Allocated Bytes/second**|Displays the number of bytes per second allocated on the garbage collection heap. This counter is updated at the end of every garbage collection, not at each allocation. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| -|**Finalization Survivors**|Displays the number of garbage-collected objects that survive a collection because they are waiting to be finalized. If these objects hold references to other objects, those objects also survive but are not counted by this counter. The **Promoted Finalization-Memory from Gen 0** counter represents all the memory that survived due to finalization.

This counter is not cumulative; it is updated at the end of every garbage collection with the count of the survivors during that particular collection only. This counter indicates the extra overhead that the application might incur because of finalization.| -|**Gen 0 heap size**|Displays the maximum bytes that can be allocated in generation 0; it does not indicate the current number of bytes allocated in generation 0.

A generation 0 garbage collection occurs when the allocations since the last collection exceed this size. The generation 0 size is tuned by the garbage collector and can change during the execution of the application. At the end of a generation 0 collection the size of the generation 0 heap is 0 bytes. This counter displays the size, in bytes, of allocations that invokes the next generation 0 garbage collection.

This counter is updated at the end of a garbage collection, not at each allocation.| -|**Gen 0 Promoted Bytes/Sec**|Displays the bytes per second that are promoted from generation 0 to generation 1. Memory is promoted when it survives a garbage collection. This counter is an indicator of relatively long-lived objects being created per second.

This counter displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| -|**Gen 1 heap size**|Displays the current number of bytes in generation 1; this counter does not display the maximum size of generation 1. Objects are not directly allocated in this generation; they are promoted from previous generation 0 garbage collections. This counter is updated at the end of a garbage collection, not at each allocation.| -|**Gen 1 Promoted Bytes/Sec**|Displays the bytes per second that are promoted from generation 1 to generation 2. Objects that are promoted only because they are waiting to be finalized are not included in this counter.

Memory is promoted when it survives a garbage collection. Nothing is promoted from generation 2 because it is the oldest generation. This counter is an indicator of very long-lived objects being created per second.

This counter displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| -|**Gen 2 heap size**|Displays the current number of bytes in generation 2. Objects are not directly allocated in this generation; they are promoted from generation 1 during previous generation 1 garbage collections. This counter is updated at the end of a garbage collection, not at each allocation.| -|**Large Object Heap size**|Displays the current size, in bytes, of the large object heap. Objects that are greater than approximately 85,000 bytes are treated as large objects by the garbage collector and are directly allocated in a special heap. They are not promoted through the generations. This counter is updated at the end of a garbage collection, not at each allocation.| -|**Process ID**|Displays the process ID of the CLR process instance that is being monitored.| -|**Promoted Finalization-Memory from Gen 0**|Displays the bytes of memory that are promoted from generation 0 to generation 1 only because they are waiting to be finalized. This counter is not cumulative; it displays the value observed at the end of the last garbage collection.| -|**Promoted Memory from Gen 0**|Displays the bytes of memory that survive garbage collection and are promoted from generation 0 to generation 1. Objects that are promoted only because they are waiting to be finalized are not included in this counter. This counter is not cumulative; it displays the value observed at the end of the last garbage collection.| -|**Promoted Memory from Gen 1**|Displays the bytes of memory that survive garbage collection and are promoted from generation 1 to generation 2. Objects that are promoted only because they are waiting to be finalized are not included in this counter. This counter is not cumulative; it displays the value observed at the end of the last garbage collection. This counter is reset to 0 if the last garbage collection was a generation 0 collection only.| - - -## Networking performance counters - The Performance console .NET CLR Networking category includes counters that provide information about data that an application sends and receives over the network. The following table describes these performance counters. - -|Performance counter|Description| -|-------------------------|-----------------| -|**Bytes Received**|The cumulative total number of bytes received by all objects within the since the process started. This number includes data and any protocol information that is not defined by TCP/IP.| -|**Bytes Sent**|The cumulative number of bytes sent by all objects within the since the process started. This number includes data and any protocol information that is not defined by TCP/IP.| -|**Connections Established**|The cumulative total number of objects for stream sockets that were ever connected within the since the process started.| -|**Datagrams Received**|The cumulative total number of datagram packets received by all objects within the since the process started.| -|**Datagrams Sent**|The cumulative total number of datagram packets sent by all objects within the since the process started.| -|**HttpWebRequest Average Lifetime**|The average time to completion for all objects that ended in the last interval within the since the process started.| -|**HttpWebRequest Average Queue Time**|The average time-on-queue for all objects that left the queue in the last interval within the since the process started.| -|**HttpWebRequests Created/sec**|The number of objects created per second within the .| -|**HttpWebRequests Queued/sec**|The number of objects that were added to the queue per second within the .| -|**HttpWebRequests Aborted/sec**|The number of objects where the application called the method per second within the .| -|**HttpWebRequests Failed/sec**|The number of objects that received a failed status code from the server per second within the .| - - There are several classes of networking performance counters supported: - -- Event counters that measure the number of times some event occurred. - -- Data counters that measure the quantity of data sent or received. - -- Duration counters that measure how long different processes take. The times are measured on the objects each interval (usually in seconds) after they come out of different states. - -- Per-Interval counters that measure the number of objects that are making a particular transition per interval (normally per second). - - The networking performance counters for events include the following: - -- **Connections Established** - -- **Datagrams Received** - -- **Datagrams Sent** - - These performance counters provide counts since the process started. The counts of connections established includes explicit method calls by an application for a stream socket connection that was established as well as internal calls made by other classes (, , , and , for example) to class - - The counts for **Datagrams Received** and **Datagrams Sent** includes datagram packets sent or received using explicit method calls by an application as well internal calls made by other classes (, for example) to . class. The counts **Datagrams Received** and **Datagrams Sent** may also be used to provide a very crude measure of how many bytes were sent or received using datagrams by assuming an average size for a datagram. - - The networking performance counters for data include the following: - -- **Bytes Received** - -- **Bytes Sent** - - The above counters provide counts of bytes since the process started. - - There are two duration counters that measure how long it took for objects to pass through either their entire life cycle or just part of it: - -- **HttpWebRequest Average Lifetime** - -- **HttpWebRequest Average Queue Time** - - For the **HttpWebRequest Average Lifetime** counter, the lifetime of most objects always starts with the time that the object is created up until the time that the response stream is closed by the application. There are two uncommon cases: - -- If the application never calls the or methods, then the lifetime of the object is ignored. - -- If the object throws a when calling the or methods, the lifetime ends when the exception is thrown. Technically, the underlying response stream is also closed at that point (the response stream returned to the user is really a memory stream containing a copy of the response stream). - - There are four counters that track certain object issues per interval. These performance counters can help application developers, administrators, and support staff better understand what the objects are doing. The counters include the following: - -- **HttpWebRequests Created/sec** - -- **HttpWebRequests Queued/sec** - -- **HttpWebRequests Aborted/sec** - -- **HttpWebRequests Failed/sec** - - For the **HttpWebRequests Aborted/sec** counter, internal calls to are also counted. These internal calls are usually caused by timeouts that an application may want to measure. - - The **HttpWebRequests Failed/sec** counter contains the number of objects that received a failed status code from the server per second. This means that the status code received from the Http server at the end of the request was not in the range between 200 to 299. Status codes that are handled and result in a new request (many of the 401 Unauthorized status codes, for example) will fail or not fail based on the result of the retry. If the application would see an error based on the retry, then this counter is incremented. - - Networking performance counters can be accessed and managed using the and related classes in the namespace. Networking performance counters can also be viewed with the Windows Performance Monitor console. - - Networking performance counters need to be enabled in the configuration file to be used. All networking performance counters are enabled or disabled with a single setting in the configuration file. Individual networking performance counters cannot be enabled or disabled. For more information, see [\ Element (Network Settings)](../configure-apps/file-schema/network/performancecounter-element-network-settings.md). - - If networking counters are enabled, this will create and update both per-AppDomain and global performance counters. If disabled, the application will not provide any networking performance counter data. - - Performance counters are grouped into Categories. An application can list all of the categories with the following example code: - +# Performance counters in the .NET Framework + +This topic provides a list of performance counters you can find in the [Windows Performance Monitor](https://docs.microsoft.com/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc749249%28v=ws.11%29). + +## Exception performance counters + The Performance console .NET CLR Exceptions category includes counters that provide information about the exceptions thrown by an application. The following table describes these performance counters. + +|Performance counter|Description| +|-------------------------|-----------------| +|**# of Exceps Thrown**|Displays the total number of exceptions thrown since the application started. This includes both .NET exceptions and unmanaged exceptions that are converted into .NET exceptions. For example, an HRESULT returned from unmanaged code is converted to an exception in managed code.

This counter includes both handled and unhandled exceptions. Exceptions that are rethrown are counted again.| +|**# of Exceps Thrown / Sec**|Displays the number of exceptions thrown per second. This includes both .NET exceptions and unmanaged exceptions that are converted into .NET exceptions. For example, an HRESULT returned from unmanaged code is converted to an exception in managed code.

This counter includes both handled and unhandled exceptions. It is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval. This counter is an indicator of potential performance problems if a large (>100s) number of exceptions are thrown.| +|**# of Filters / Sec**|Displays the number of .NET exception filters executed per second. An exception filter evaluates regardless of whether an exception is handled.

This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| +|**# of Finallys / Sec**|Displays the number of finally blocks executed per second. A finally block is guaranteed to be executed regardless of how the try block was exited. Only the finally blocks executed for an exception are counted; finally blocks on normal code paths are not counted by this counter.

This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| +|**Throw to Catch Depth / Sec**|Displays the number of stack frames traversed, from the frame that threw the exception to the frame that handled the exception, per second. This counter resets to zero when an exception handler is entered, so nested exceptions show the handler-to-handler stack depth.

This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| + +## Interop performance counters + The Performance console .NET CLR Interop category includes counters that provide information about an application's interaction with COM components, COM+ services, and external type libraries. The following table describes these performance counters. + +|Performance counter|Description| +|-------------------------|-----------------| +|**# of CCWs**|Displays the current number of COM callable wrappers (CCWs). A CCW is a proxy for a managed object being referenced from an unmanaged COM client. This counter indicates the number of managed objects referenced by unmanaged COM code.| +|**# of marshaling**|Displays the total number of times arguments and return values have been marshaled from managed to unmanaged code, and vice versa, since the application started. This counter is not incremented if the stubs are inlined. (Stubs are responsible for marshaling arguments and return values). Stubs are usually inlined if the marshaling overhead is small.| +|**# of Stubs**|Displays the current number of stubs created by the common language runtime. Stubs are responsible for marshaling arguments and return values from managed to unmanaged code, and vice versa, during a COM interop call or a platform invoke call.| +|**# of TLB exports / sec**|Reserved for future use.| +|**# of TLB imports / sec**|Reserved for future use.| + +## JIT performance counters + The Performance console .NET CLR JIT category includes counters that provide information about code that has been JIT-compiled. The following table describes these performance counters. + +|Performance counter|Description| +|-------------------------|-----------------| +|**# of IL Bytes JITted**|Displays the total number of Microsoft intermediate language (MSIL) bytes compiled by the just-in-time (JIT) compiler since the application started. This counter is equivalent to the **Total # of IL Bytes Jitted** counter.| +|**# of Methods JITted**|Displays the total number of methods JIT-compiled since the application started. This counter does not include pre-JIT-compiled methods.| +|**% Time in Jit**|Displays the percentage of elapsed time spent in JIT compilation since the last JIT compilation phase. This counter is updated at the end of every JIT compilation phase. A JIT compilation phase occurs when a method and its dependencies are compiled.| +|**IL Bytes Jitted / sec**|Displays the number of MSIL bytes that are JIT-compiled per second. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| +|**Standard Jit Failures**|Displays the peak number of methods the JIT compiler has failed to compile since the application started. This failure can occur if the MSIL cannot be verified or if there is an internal error in the JIT compiler.| +|**Total # of IL Bytes Jitted**|Displays the total MSIL bytes JIT-compiled since the application started. This counter is equivalent to the **# of IL Bytes Jitted** counter.| + +## Loading performance counters + The Performance console .NET CLR Loading category includes counters that provide information about assemblies, classes, and application domains that are loaded. The following table describes these performance counters. + +|Performance counter|Description| +|-------------------------|-----------------| +|**% Time Loading**|Reserved for future use.| +|**Assembly Search Length**|Reserved for future use.| +|**Bytes in Loader Heap**|Displays the current size, in bytes, of the memory committed by the class loader across all application domains. Committed memory is the physical space reserved in the disk paging file.| +|**Current appdomains**|Displays the current number of application domains loaded in this application.| +|**Current Assemblies**|Displays the current number of assemblies loaded across all application domains in the currently running application. If the assembly is loaded as domain-neutral from multiple application domains, this counter is incremented only once.| +|**Current Classes Loaded**|Displays the current number of classes loaded in all assemblies.| +|**Rate of appdomains**|Displays the number of application domains loaded per second. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| +|**Rate of appdomains unloaded**|Displays the number of application domains unloaded per second. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| +|**Rate of Assemblies**|Displays the number of assemblies loaded per second across all application domains. If the assembly is loaded as domain-neutral from multiple application domains, this counter is incremented only once.

This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| +|**Rate of Classes Loaded**|Displays the number of classes loaded per second in all assemblies. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| +|**Rate of Load Failures**|Displays the number of classes that failed to load per second. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.

Load failures can occur for many reasons, such as inadequate security or invalid format. For details, see the profiling services Help.| +|**Total # of Load Failures**|Displays the peak number of classes that have failed to load since the application started.

Load failures can occur for many reasons, such as inadequate security or invalid format. For details, see the profiling services Help.| +|**Total Appdomains**|Displays the peak number of application domains loaded since the application started.| +|**Total appdomains unloaded**|Displays the total number of application domains unloaded since the application started. If an application domain is loaded and unloaded multiple times, this counter increments each time the application domain is unloaded.| +|**Total Assemblies**|Displays the total number of assemblies loaded since the application started. If the assembly is loaded as domain-neutral from multiple application domains, this counter is incremented only once.| +|**Total Classes Loaded**|Displays the cumulative number of classes loaded in all assemblies since the application started.| + +## Lock and thread performance counters + The Performance console .NET CLR LocksAndThreads category includes counters that provide information about managed locks and threads that an application uses. The following table describes these performance counters. + +|Performance counter|Description| +|-------------------------|-----------------| +|**# of current logical Threads**|Displays the number of current managed thread objects in the application. This counter maintains the count of both running and stopped threads. This counter is not an average over time; it displays only the last observed value.| +|**# of current physical Threads**|Displays the number of native operating system threads created and owned by the common language runtime to act as underlying threads for managed thread objects. This counter's value does not include the threads used by the runtime in its internal operations; it is a subset of the threads in the operating system process.| +|**# of current recognized threads**|Displays the number of threads that are currently recognized by the runtime. These threads are associated with a corresponding managed thread object. The runtime does not create these threads, but they have run inside the runtime at least once.

Only unique threads are tracked; threads with the same thread ID that reenter the runtime or are recreated after the thread exits are not counted twice.| +|**# of total recognized Threads**|Displays the total number of threads that have been recognized by the runtime since the application started. These threads are associated with a corresponding managed thread object. The runtime does not create these threads, but they have run inside the runtime at least once.

Only unique threads are tracked; threads with the same thread ID that reenter the runtime or are recreated after the thread exits are not counted twice.| +|**Contention Rate / Sec**|Displays the rate at which threads in the runtime attempt to acquire a managed lock unsuccessfully.| +|**Current Queue Length**|Displays the total number of threads that are currently waiting to acquire a managed lock in the application. This counter is not an average over time; it displays the last observed value.| +|**Queue Length / sec**|Displays the number of threads per second that are waiting to acquire a lock in the application. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| +|**Queue Length Peak**|Displays the total number of threads that waited to acquire a managed lock since the application started.| +|**rate of recognized threads / sec**|Displays the number of threads per second that have been recognized by the runtime. These threads are associated with a corresponding managed thread object. The runtime does not create these threads, but they have run inside the runtime at least once.

Only unique threads are tracked; threads with the same thread ID that reenter the runtime or are recreated after the thread exits are not counted twice.

This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| +|**Total # of Contentions**|Displays the total number of times that threads in the runtime have attempted to acquire a managed lock unsuccessfully.| + +## Memory performance counters + The Performance console .NET CLR Memory category includes counters that provide information about the garbage collector. The following table describes these performance counters. + +|Performance counter|Description| +|-------------------------|-----------------| +|**# Bytes in all Heaps**|Displays the sum of the **Gen 1 Heap Size**, **Gen 2 Heap Size**, and **Large Object Heap Size** counters. This counter indicates the current memory allocated in bytes on the garbage collection heaps.| +|**# GC Handles**|Displays the current number of garbage collection handles in use. Garbage collection handles are handles to resources external to the common language runtime and the managed environment.| +|**# Gen 0 Collections**|Displays the number of times the generation 0 objects (that is, the youngest, most recently allocated objects) are garbage collected since the application started.

Generation 0 garbage collection occurs when the available memory in generation 0 is not sufficient to satisfy an allocation request. This counter is incremented at the end of a generation 0 garbage collection. Higher generation garbage collections include all lower generation collections. This counter is explicitly incremented when a higher generation (generation 1 or 2) garbage collection occurs.

This counter displays the last observed value. The **_Global\_** counter value is not accurate and should be ignored.| +|**# Gen 1 Collections**|Displays the number of times the generation 1 objects are garbage collected since the application started.

The counter is incremented at the end of a generation 1 garbage collection. Higher generation garbage collections include all lower generation collections. This counter is explicitly incremented when a higher generation (generation 2) garbage collection occurs.

This counter displays the last observed value. The **_Global\_** counter value is not accurate and should be ignored.| +|**# Gen 2 Collections**|Displays the number of times the generation 2 objects are garbage collected since the application started. The counter is incremented at the end of a generation 2 garbage collection (also called a full garbage collection).

This counter displays the last observed value. The **_Global\_** counter value is not accurate and should be ignored.| +|**# Induced GC**|Displays the peak number of times garbage collection was performed because of an explicit call to . It is good practice to let the garbage collector tune the frequency of its collections.| +|**# of Pinned Objects**|Displays the number of pinned objects encountered in the last garbage collection. A pinned object is an object that the garbage collector cannot move in memory. This counter tracks pinned objects only in the heaps that are garbage collected. For example, a generation 0 garbage collection causes enumeration of pinned objects only in the generation 0 heap.| +|**# of Sink Blocks in use**|Displays the current number of synchronization blocks in use. Synchronization blocks are per-object data structures allocated for storing synchronization information. They hold weak references to managed objects and must be scanned by the garbage collector. Synchronization blocks are not limited to storing synchronization information; they can also store COM interop metadata. This counter indicates performance problems with heavy use of synchronization primitives.| +|**# Total committed Bytes**|Displays the amount of virtual memory, in bytes, currently committed by the garbage collector. Committed memory is the physical memory for which space has been reserved in the disk paging file.| +|**# Total reserved Bytes**|Displays the amount of virtual memory, in bytes, currently reserved by the garbage collector. Reserved memory is the virtual memory space reserved for the application when no disk or main memory pages have been used.| +|**% Time in GC**|Displays the percentage of elapsed time that was spent performing a garbage collection since the last garbage collection cycle. This counter usually indicates the work done by the garbage collector to collect and compact memory on behalf of the application. This counter is updated only at the end of every garbage collection. This counter is not an average; its value reflects the last observed value.| +|**Allocated Bytes/second**|Displays the number of bytes per second allocated on the garbage collection heap. This counter is updated at the end of every garbage collection, not at each allocation. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| +|**Finalization Survivors**|Displays the number of garbage-collected objects that survive a collection because they are waiting to be finalized. If these objects hold references to other objects, those objects also survive but are not counted by this counter. The **Promoted Finalization-Memory from Gen 0** counter represents all the memory that survived due to finalization.

This counter is not cumulative; it is updated at the end of every garbage collection with the count of the survivors during that particular collection only. This counter indicates the extra overhead that the application might incur because of finalization.| +|**Gen 0 heap size**|Displays the maximum bytes that can be allocated in generation 0; it does not indicate the current number of bytes allocated in generation 0.

A generation 0 garbage collection occurs when the allocations since the last collection exceed this size. The generation 0 size is tuned by the garbage collector and can change during the execution of the application. At the end of a generation 0 collection the size of the generation 0 heap is 0 bytes. This counter displays the size, in bytes, of allocations that invokes the next generation 0 garbage collection.

This counter is updated at the end of a garbage collection, not at each allocation.| +|**Gen 0 Promoted Bytes/Sec**|Displays the bytes per second that are promoted from generation 0 to generation 1. Memory is promoted when it survives a garbage collection. This counter is an indicator of relatively long-lived objects being created per second.

This counter displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| +|**Gen 1 heap size**|Displays the current number of bytes in generation 1; this counter does not display the maximum size of generation 1. Objects are not directly allocated in this generation; they are promoted from previous generation 0 garbage collections. This counter is updated at the end of a garbage collection, not at each allocation.| +|**Gen 1 Promoted Bytes/Sec**|Displays the bytes per second that are promoted from generation 1 to generation 2. Objects that are promoted only because they are waiting to be finalized are not included in this counter.

Memory is promoted when it survives a garbage collection. Nothing is promoted from generation 2 because it is the oldest generation. This counter is an indicator of very long-lived objects being created per second.

This counter displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| +|**Gen 2 heap size**|Displays the current number of bytes in generation 2. Objects are not directly allocated in this generation; they are promoted from generation 1 during previous generation 1 garbage collections. This counter is updated at the end of a garbage collection, not at each allocation.| +|**Large Object Heap size**|Displays the current size, in bytes, of the large object heap. Objects that are greater than approximately 85,000 bytes are treated as large objects by the garbage collector and are directly allocated in a special heap. They are not promoted through the generations. This counter is updated at the end of a garbage collection, not at each allocation.| +|**Process ID**|Displays the process ID of the CLR process instance that is being monitored.| +|**Promoted Finalization-Memory from Gen 0**|Displays the bytes of memory that are promoted from generation 0 to generation 1 only because they are waiting to be finalized. This counter is not cumulative; it displays the value observed at the end of the last garbage collection.| +|**Promoted Memory from Gen 0**|Displays the bytes of memory that survive garbage collection and are promoted from generation 0 to generation 1. Objects that are promoted only because they are waiting to be finalized are not included in this counter. This counter is not cumulative; it displays the value observed at the end of the last garbage collection.| +|**Promoted Memory from Gen 1**|Displays the bytes of memory that survive garbage collection and are promoted from generation 1 to generation 2. Objects that are promoted only because they are waiting to be finalized are not included in this counter. This counter is not cumulative; it displays the value observed at the end of the last garbage collection. This counter is reset to 0 if the last garbage collection was a generation 0 collection only.| + +## Networking performance counters + +The Performance console .NET CLR Networking category includes counters that provide information about data that an application sends and receives over the network. The following table describes these performance counters. + +|Performance counter|Description| +|-------------------------|-----------------| +|**Bytes Received**|The cumulative total number of bytes received by all objects within the since the process started. This number includes data and any protocol information that is not defined by TCP/IP.| +|**Bytes Sent**|The cumulative number of bytes sent by all objects within the since the process started. This number includes data and any protocol information that is not defined by TCP/IP.| +|**Connections Established**|The cumulative total number of objects for stream sockets that were ever connected within the since the process started.| +|**Datagrams Received**|The cumulative total number of datagram packets received by all objects within the since the process started.| +|**Datagrams Sent**|The cumulative total number of datagram packets sent by all objects within the since the process started.| +|**HttpWebRequest Average Lifetime**|The average time to completion for all objects that ended in the last interval within the since the process started.| +|**HttpWebRequest Average Queue Time**|The average time-on-queue for all objects that left the queue in the last interval within the since the process started.| +|**HttpWebRequests Created/sec**|The number of objects created per second within the .| +|**HttpWebRequests Queued/sec**|The number of objects that were added to the queue per second within the .| +|**HttpWebRequests Aborted/sec**|The number of objects where the application called the method per second within the .| +|**HttpWebRequests Failed/sec**|The number of objects that received a failed status code from the server per second within the .| + + There are several classes of networking performance counters supported: + +- Event counters that measure the number of times some event occurred. + +- Data counters that measure the quantity of data sent or received. + +- Duration counters that measure how long different processes take. The times are measured on the objects each interval (usually in seconds) after they come out of different states. + +- Per-Interval counters that measure the number of objects that are making a particular transition per interval (normally per second). + +The networking performance counters for events include the following: + +- **Connections Established** + +- **Datagrams Received** + +- **Datagrams Sent** + + These performance counters provide counts since the process started. The counts of connections established includes explicit method calls by an application for a stream socket connection that was established as well as internal calls made by other classes (, , , and , for example) to class + + The counts for **Datagrams Received** and **Datagrams Sent** includes datagram packets sent or received using explicit method calls by an application as well internal calls made by other classes (, for example) to . class. The counts **Datagrams Received** and **Datagrams Sent** may also be used to provide a very crude measure of how many bytes were sent or received using datagrams by assuming an average size for a datagram. + + The networking performance counters for data include the following: + +- **Bytes Received** + +- **Bytes Sent** + + The above counters provide counts of bytes since the process started. + + There are two duration counters that measure how long it took for objects to pass through either their entire life cycle or just part of it: + +- **HttpWebRequest Average Lifetime** + +- **HttpWebRequest Average Queue Time** + + For the **HttpWebRequest Average Lifetime** counter, the lifetime of most objects always starts with the time that the object is created up until the time that the response stream is closed by the application. There are two uncommon cases: + +- If the application never calls the or methods, then the lifetime of the object is ignored. + +- If the object throws a when calling the or methods, the lifetime ends when the exception is thrown. Technically, the underlying response stream is also closed at that point (the response stream returned to the user is really a memory stream containing a copy of the response stream). + + There are four counters that track certain object issues per interval. These performance counters can help application developers, administrators, and support staff better understand what the objects are doing. The counters include the following: + +- **HttpWebRequests Created/sec** + +- **HttpWebRequests Queued/sec** + +- **HttpWebRequests Aborted/sec** + +- **HttpWebRequests Failed/sec** + + For the **HttpWebRequests Aborted/sec** counter, internal calls to are also counted. These internal calls are usually caused by timeouts that an application may want to measure. + + The **HttpWebRequests Failed/sec** counter contains the number of objects that received a failed status code from the server per second. This means that the status code received from the Http server at the end of the request was not in the range between 200 to 299. Status codes that are handled and result in a new request (many of the 401 Unauthorized status codes, for example) will fail or not fail based on the result of the retry. If the application would see an error based on the retry, then this counter is incremented. + + Networking performance counters can be accessed and managed using the and related classes in the namespace. Networking performance counters can also be viewed with the Windows Performance Monitor console. + + Networking performance counters need to be enabled in the configuration file to be used. All networking performance counters are enabled or disabled with a single setting in the configuration file. Individual networking performance counters cannot be enabled or disabled. For more information, see [\ Element (Network Settings)](../configure-apps/file-schema/network/performancecounter-element-network-settings.md). + + If networking counters are enabled, this will create and update both per-AppDomain and global performance counters. If disabled, the application will not provide any networking performance counter data. + + Performance counters are grouped into Categories. An application can list all of the categories with the following example code: + ```csharp -PerformanceCounterCategory[] Array = PerformanceCounterCategory.GetCategories(); -for (int i = 0; i < Array.Length; i++) -{ - Console.Out.WriteLine("{0}. Name={1} Help={2}", i, Array[i].CategoryName, Array[i].CategoryHelp); -} -``` - - The networking performance counters are listed in two categories: - -- ".NET CLR Networking" - the original performance counters introduced on .NET Framework Version 2 and supported on .NET Framework Version 2 and later. - -- ".NET CLR Networking 4.0.0.0" - All of the above socket counters plus the new performance counters supported on .NET Framework Version 4 and later. These new counters provide performance information on objects. - - For more information on accessing and managing performance counters in an application, see [Performance Counters](performance-counters.md). - - -## Security performance counters - The Performance console .NET CLR Security category includes counters that provide information about the security checks that the common language runtime performs for an application. The following table describes these performance counters. - -|Performance counter|Description| -|-------------------------|-----------------| -|**# Link Time Checks**|Displays the total number of link-time code access security checks since the application started. Link-time code access security checks are performed when a caller demands a particular permission at just-in-time (JIT) compile time. A link-time check is performed once per caller. This count is not indicative of serious performance issues; it is merely indicative of the security system activity.| -|**% Time in RT checks**|Displays the percentage of elapsed time spent performing runtime code access security checks since the last sample. This counter is updated at the end of a .NET Framework security check. It is not an average; it represents the last observed value.| -|**% Time Sig Authenticating**|Reserved for future use.| -|**Stack Walk Depth**|Displays the depth of the stack during that last runtime code access security check. Runtime code access security checks are performed by walking the stack. This counter is not an average; it displays only the last observed value.| -|**Total Runtime Checks**|Displays the total number of runtime code access security checks performed since the application started. Runtime code access security checks are performed when a caller demands a particular permission. The runtime check is made on every call by the caller and examines the current thread stack of the caller. When used with the **Stack Walk Depth** counter, this counter indicates the performance penalty that occurs for security checks.| - +PerformanceCounterCategory[] Array = PerformanceCounterCategory.GetCategories(); +for (int i = 0; i < Array.Length; i++) +{ + Console.Out.WriteLine("{0}. Name={1} Help={2}", i, Array[i].CategoryName, Array[i].CategoryHelp); +} +``` + + The networking performance counters are listed in two categories: + +- ".NET CLR Networking" - the original performance counters introduced on .NET Framework Version 2 and supported on .NET Framework Version 2 and later. + +- ".NET CLR Networking 4.0.0.0" - All of the above socket counters plus the new performance counters supported on .NET Framework Version 4 and later. These new counters provide performance information on objects. + + For more information on accessing and managing performance counters in an application, see [Performance Counters](performance-counters.md). + +## Security performance counters + The Performance console .NET CLR Security category includes counters that provide information about the security checks that the common language runtime performs for an application. The following table describes these performance counters. + +|Performance counter|Description| +|-------------------------|-----------------| +|**# Link Time Checks**|Displays the total number of link-time code access security checks since the application started. Link-time code access security checks are performed when a caller demands a particular permission at just-in-time (JIT) compile time. A link-time check is performed once per caller. This count is not indicative of serious performance issues; it is merely indicative of the security system activity.| +|**% Time in RT checks**|Displays the percentage of elapsed time spent performing runtime code access security checks since the last sample. This counter is updated at the end of a .NET Framework security check. It is not an average; it represents the last observed value.| +|**% Time Sig Authenticating**|Reserved for future use.| +|**Stack Walk Depth**|Displays the depth of the stack during that last runtime code access security check. Runtime code access security checks are performed by walking the stack. This counter is not an average; it displays only the last observed value.| +|**Total Runtime Checks**|Displays the total number of runtime code access security checks performed since the application started. Runtime code access security checks are performed when a caller demands a particular permission. The runtime check is made on every call by the caller and examines the current thread stack of the caller. When used with the **Stack Walk Depth** counter, this counter indicates the performance penalty that occurs for security checks.| + ## See also - [Performance Counters](performance-counters.md) From ad3385a8fbd787ad2891897938d2c190d7a6857d Mon Sep 17 00:00:00 2001 From: Genevieve Warren Date: Mon, 18 Nov 2019 22:31:35 -0800 Subject: [PATCH 14/18] undo changes to calendar file - will move to another PR --- .../datetime/working-with-calendars.md | 64 +++++++++---------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/docs/standard/datetime/working-with-calendars.md b/docs/standard/datetime/working-with-calendars.md index 11b5bf3ba033b..5d1e2f218df03 100644 --- a/docs/standard/datetime/working-with-calendars.md +++ b/docs/standard/datetime/working-with-calendars.md @@ -14,7 +14,7 @@ helpviewer_keywords: - "culture, calendars" ms.assetid: 0c1534e5-979b-4c8a-a588-1c24301aefb3 --- -# Work with calendars +# Working with calendars Although a date and time value represents a moment in time, its string representation is culture-sensitive and depends both on the conventions used for displaying date and time values by a specific culture and on the calendar used by that culture. This topic explores the support for calendars in .NET and discusses the use of the calendar classes when working with date values. @@ -86,7 +86,7 @@ The following example illustrates this difference between [!code-csharp[Conceptual.Calendars#3](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.calendars/cs/datesandcalendars2.cs#3)] [!code-vb[Conceptual.Calendars#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.calendars/vb/datesandcalendars2.vb#3)] -### Instantiate dates based on a calendar +### Instantiating dates based on a calendar Because and values are based on the Gregorian calendar, you must call an overloaded constructor that includes a parameter of type to instantiate a date value if you want to use the day, month, or year values from a different calendar. You can also call one of the overloads of a specific calendar's method to instantiate a object based on the values of a particular calendar. @@ -95,7 +95,7 @@ The following example instantiates one value by passing a [!code-csharp[Conceptual.Calendars#4](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.calendars/cs/instantiatehcdate1.cs#4)] [!code-vb[Conceptual.Calendars#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.calendars/vb/instantiatehcdate1.vb#4)] -### Represent dates in the current calendar +### Representing dates in the current calendar Date and time formatting methods always use the current calendar when converting dates to strings. This means that the string representation of the year, the month, and the day of the month reflect the current calendar, and do not necessarily reflect the Gregorian calendar. @@ -104,7 +104,7 @@ The following example shows how the current calendar affects the string represen [!code-csharp[Conceptual.Calendars#5](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.calendars/cs/currentcalendar1.cs#5)] [!code-vb[Conceptual.Calendars#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.calendars/vb/currentcalendar1.vb#5)] -### Represent dates in a non-current calendar +### Representing dates in a non-current calendar To represent a date using a calendar that is not the current calendar of a particular culture, you must call methods of that object. For example, the , , and methods convert the year, month, and day to values that reflect a particular calendar. @@ -125,7 +125,7 @@ However, there is one important exception. The default (uninitialized) value of [!code-csharp[Conceptual.Calendars#11](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.calendars/cs/minsupporteddatetime1.cs#11)] [!code-vb[Conceptual.Calendars#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.calendars/vb/minsupporteddatetime1.vb#11)] -## Work with eras +## Working with eras Calendars typically divide dates into eras. However, the classes in .NET do not support every era defined by a calendar, and most of the classes support only a single era. Only the and classes support multiple eras. @@ -163,7 +163,7 @@ The name that corresponds to a particular era number can be retrieved by passing In addition, the "g" custom date and time format string includes a calendar's era name in the string representation of a date and time. For more information, see [Custom date and time format strings](../../../docs/standard/base-types/custom-date-and-time-format-strings.md). -### Instantiatie a date with an era +### Instantiating a date with an era For the two classes that support multiple eras, a date that consists of a particular year, month, and day of the month value can be ambiguous. For example, all eras supported by the have years whose number is 1. Ordinarily, if an era is not specified, both date and time and calendar methods assume that values belong to the current era. This is true of the and constructors that include parameters of type , as well as the [JapaneseCalendar.ToDateTime](xref:System.Globalization.Calendar.ToDateTime(System.Int32,System.Int32,System.Int32,System.Int32,System.Int32,System.Int32,System.Int32)) and [JapaneseLunisolarCalendar.ToDateTime](xref:System.Globalization.Calendar.ToDateTime(System.Int32,System.Int32,System.Int32,System.Int32,System.Int32,System.Int32,System.Int32)) methods. The following example instantiates a date that represents January 1 of the second year of an unspecified era. If you execute the example when the Reiwa era is the current era, the date is interpreted as the second year of the Reiwa era. The era, 令和, precedes the year in the string returned by the method and corresponds to January 1, 2020, in the Gregorian calendar. (The Reiwa era begins in the year 2019 of the Gregorian calendar.) @@ -210,7 +210,7 @@ The following example attempts to instantiate a date in the 65th year of the Sho If relaxed range checks are undesirable, you can restore strict range checks in a number of ways, depending on the version of .NET on which your application is running: -- **.NET Core:** Add the following to the *.netcore.runtime.json* config file: +- **.NET Core:** You can add the following to the *.netcore.runtime.json* config file: ```json "runtimeOptions": { @@ -220,7 +220,7 @@ If relaxed range checks are undesirable, you can restore strict range checks in } ``` -- **.NET Framework 4.6 or later:** Set the following AppContext switch in the *app.config* file: +- **.NET Framework 4.6 or later:** You can set the following AppContext switch: ```xml @@ -231,14 +231,14 @@ If relaxed range checks are undesirable, you can restore strict range checks in ``` -- **.NET Framework 4.5.2 or earlier:** Set the following registry value: +- **.NET Framework 4.5.2 or earlier:** You can set the following registry value: | | | |--|--| - | **Key** | **HKEY_LOCAL_MACHINE\Software\Microsoft\\.NETFramework\AppContext** | - | **Name** | Switch.System.Globalization.EnforceJapaneseEraYearRanges | - | **Type** | REG_SZ | - | **Value** | true | + |Key | HKEY_LOCAL_MACHINE\Software\Microsoft\.NETFramework\AppContext | + |Name | Switch.System.Globalization.EnforceJapaneseEraYearRanges | + |Type | REG_SZ | + |Value | true | With strict range checks enabled, the previous example throws an and displays the following output: @@ -250,7 +250,7 @@ Parameter name: year at Example.Main() ``` -### Represent dates in calendars with multiple eras +### Representing dates in calendars with multiple eras If a object supports eras and is the current calendar of a object, the era is included in the string representation of a date and time value for the full date and time, long date, and short date patterns. The following example displays these date patterns when the current culture is Japan (Japanese) and the current calendar is the Japanese calendar. @@ -278,14 +278,14 @@ In the Japanese calendars, the first year of an era is called Gannen (元年). F - [The year/month pattern](../base-types/standard-date-and-time-format-strings.md#YearMonth), indicated by the Y" or "y" standard date and time format string. - [The "ggy'年'" or "ggy年" [custom date and time format string](../base-types/custom-date-and-time-format-strings.md). -For example, the following example displays a date in the first year of the Heisei era in the . +For example, the following example displays a date in the first year of the Heisei era in the . [!code-csharp[gannen](~/samples/snippets/standard/datetime/calendars/gannen/cs/program.cs)] [!code-vb[gannen](~/samples/snippets/standard/datetime/calendars/gannen/vb/gannen-fmt.vb)] -If this behavior is undesirable in formatting operations, you can restore the previous behavior, which always represents the first year of an era as "1" rather than "Gannen", by doing the following, depending on the version of .NET: +If this behavior is undesirable in formatting operations, you can restore the previous behavior, which always represents the first year of an era as “1” rather than “Gannen”, by doing the following, depending on the version of .NET: -- **.NET Core:** Add the following to the *.netcore.runtime.json* config file: +- **.NET Core:** You can add the following to the *.netcore.runtime.json* config file: ```json "runtimeOptions": { @@ -295,7 +295,7 @@ If this behavior is undesirable in formatting operations, you can restore the pr } ``` -- **.NET Framework 4.6 or later:** Set the following AppContext switch in the *app.config* file: +- **.NET Framework 4.6 or later:** You can set the following AppContext switch: ```xml @@ -306,14 +306,14 @@ If this behavior is undesirable in formatting operations, you can restore the pr ``` -- **.NET Framework 4.5.2 or earlier:** Set the following registry value: +- **.NET Framework 4.5.2 or earlier:** You can set the following registry value: | | | |--|--| - | **Key** | **HKEY_LOCAL_MACHINE\Software\Microsoft\\.NETFramework\AppContext** | - | **Name** | Switch.System.Globalization.FormatJapaneseFirstYearAsANumber | - | **Type** | REG_SZ | - | **Value** | true | + |Key | HKEY_LOCAL_MACHINE\Software\Microsoft\.NETFramework\AppContext | + |Name | Switch.System.Globalization.FormatJapaneseFirstYearAsANumber | + |Type | REG_SZ | + |Value | true | With gannen support in formatting operations disabled, the previous example displays the following output: @@ -321,9 +321,9 @@ With gannen support in formatting operations disabled, the previous example disp Japanese calendar date: 平成1年8月18日 (Gregorian: Friday, August 18, 1989) ``` -.NET has also been updated so that date and time parsing operations support strings that contain the year represented as either "1" or Gannen. Although you should not need to do this, you can restore the previous behavior to recognizes only "1" as the first year of an era. You can do this as follows, depending on the version of .NET: +.NET has also been updated so that date and time parsing operations support strings that contain the year represented as either "1" or Gannen. Although you should not need to do this, you can restore the previous behavior to recognizes only “1” as the first year of an era. You can do this as follows, depending on the version of .NET: -- **.NET Core:** Add the following to the *.netcore.runtime.json* config file: +- **.NET Core:** You can add the following to the *.netcore.runtime.json* config file: ```json "runtimeOptions": { @@ -333,7 +333,7 @@ Japanese calendar date: 平成1年8月18日 (Gregorian: Friday, August 18, 1989) } ``` -- **.NET Framework 4.6 or later:** Set the following AppContext switch in the *app.config* file: +- **.NET Framework 4.6 or later:** You can set the following AppContext switch: ```xml @@ -344,14 +344,14 @@ Japanese calendar date: 平成1年8月18日 (Gregorian: Friday, August 18, 1989) ``` -- **.NET Framework 4.5.2 or earlier:** Set the following registry value: +- **.NET Framework 4.5.2 or earlier:** You can set the following registry value: | | | - |--|--| - | **Key** | **HKEY_LOCAL_MACHINE\Software\Microsoft\\.NETFramework\AppContext** | - | **Name** | Switch.System.Globalization.EnforceLegacyJapaneseDateParsing | - | **Type** | REG_SZ | - | **Value** | true | + |--|--| + |Key | HKEY_LOCAL_MACHINE\Software\Microsoft\.NETFramework\AppContext | + |Name | Switch.System.Globalization.EnforceLegacyJapaneseDateParsing | + |Type | REG_SZ | + |Value | true | ## See also From f0041ccf3cbeccabb3808041892b38d0c74a8461 Mon Sep 17 00:00:00 2001 From: Genevieve Warren Date: Mon, 18 Nov 2019 22:36:35 -0800 Subject: [PATCH 15/18] fix build warnings --- .../network/performancecounter-element-network-settings.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/framework/configure-apps/file-schema/network/performancecounter-element-network-settings.md b/docs/framework/configure-apps/file-schema/network/performancecounter-element-network-settings.md index 64316b1d4a461..a564bc02e80fc 100644 --- a/docs/framework/configure-apps/file-schema/network/performancecounter-element-network-settings.md +++ b/docs/framework/configure-apps/file-schema/network/performancecounter-element-network-settings.md @@ -46,7 +46,7 @@ Enables or disables networking performance counters. ## Remarks This element can be used in the application configuration file or the machine configuration file (Machine.config). - Networking performance counters need to be enabled in the configuration file to be used. All networking performance counters are enabled or disabled with a single setting in the configuration file. Individual networking performance counters cannot be enabled or disabled. For more information on the specific networking performance counters, see [Networking Performance Counters](../../../debug-trace-profile/performance-counters.md#networking). + Networking performance counters need to be enabled in the configuration file to be used. All networking performance counters are enabled or disabled with a single setting in the configuration file. Individual networking performance counters cannot be enabled or disabled. For more information on the specific networking performance counters, see [Networking performance counters](../../../debug-trace-profile/performance-counters.md#networking-performance-counters). The default value is that networking performance counters are disabled. @@ -72,4 +72,4 @@ Enables or disables networking performance counters. - - - [Network Settings Schema](index.md) -- [Networking Performance Counters](../../../debug-trace-profile/performance-counters.md#networking) +- [Networking Performance Counters](../../../debug-trace-profile/performance-counters.md#networking-performance-counters) From 850684dceb74d9f8e1c9fb9d08f8489c3e40424b Mon Sep 17 00:00:00 2001 From: Genevieve Warren Date: Tue, 19 Nov 2019 11:54:40 -0800 Subject: [PATCH 16/18] Apply suggestions from maira and bill Co-Authored-By: Bill Wagner Co-Authored-By: Maira Wenzel --- docs/core/run-time-config/garbage-collector.md | 12 ++++++------ docs/core/run-time-config/index.md | 4 ++-- .../profiling/cor-prf-high-monitor-enumeration.md | 2 +- .../standard/garbage-collection/large-object-heap.md | 2 +- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/core/run-time-config/garbage-collector.md b/docs/core/run-time-config/garbage-collector.md index a584283831c59..5a99af1e734a3 100644 --- a/docs/core/run-time-config/garbage-collector.md +++ b/docs/core/run-time-config/garbage-collector.md @@ -6,7 +6,7 @@ ms.topic: reference --- # Run-time configuration options for garbage collection -This page contains information about garbage collector (GC) settings that can be changed at run time. If you're trying to achieve peak performance of a running app, consider using these settings. However, most users will not need to concern themselves with these settings. +This page contains information about garbage collector (GC) settings that can be changed at run time. If you're trying to achieve peak performance of a running app, consider using these settings. However, the defaults provide optimum performance for most applications in typical situations. On this page, settings are arranged into groups of settings that you can use in conjunction with each other to achieve a specific result. @@ -21,7 +21,7 @@ The two main flavors of garbage collection are workstation GC and server GC. For The subflavors of garbage collection are background and non-concurrent. -Use the settings described in this section to select flavors of garbage collection. +Use the following settings to select flavors of garbage collection: ### System.GC.Server/COMPlus_gcServer @@ -87,7 +87,7 @@ For more information about some of these settings, see the [Middle ground betwee - For Windows operating systems, prefix the processor number or range with the corresponding [CPU group](/windows/win32/procthread/processor-groups), for example, "0:1-10,0:12,1:50-52,1:70". - If processor affinity is disabled by setting `System.GC.NoAffinitize` to `true`, this setting is ignored. - Applies to server garbage collection (GC) only. -- For more information, see [Maoni Stephens' blog entry](https://devblogs.microsoft.com/dotnet/making-cpu-configuration-better-for-gc-on-machines-with-64-cpus/). +- For more information, see [Making CPU configuration better for GC on machines with > 64 CPUs](https://devblogs.microsoft.com/dotnet/making-cpu-configuration-better-for-gc-on-machines-with-64-cpus/) on Maoni Stephens' blog. | | Setting name | Values | Version introduced | | - | - | - | - | @@ -126,7 +126,7 @@ For more information about some of these settings, see the [Middle ground betwee ### System.GC.HeapHardLimit/COMPlus_GCHeapHardLimit - Specifies the maximum commit size for the GC heap. -- The value can range from 0 to 18446744073709551615. +- The value can range from 0 to 18,446,744,073,709,551,615. | | Setting name | Values | Version introduced | | - | - | - | - | @@ -150,7 +150,7 @@ For more information about some of these settings, see the [Middle ground betwee | | Setting name | Values | Version introduced | | - | - | - | - | -| **runtimeconfig.json** | `System.GC.RetainVM` | `true` - put on standby
`false` - release to OS | .NET Core 1.0 | +| **runtimeconfig.json** | `System.GC.RetainVM` | `false` - release to OS
`true` - put on standby| .NET Core 1.0 | | **Environment variable** | `COMPlus_GCRetainVM` | 0 - release to OS
1 - put on standby | .NET Core 1.0 | ## Large pages @@ -178,7 +178,7 @@ For more information about some of these settings, see the [Middle ground betwee | | Setting name | Values | Version introduced | | - | - | - | - | | **runtimeconfig.json** | N/A | N/A | N/A | -| **Environment variable** | `COMPlus_gcAllowVeryLargeObjects` | 0 - disabled
1 - enabled | .NET Core 1.0 | +| **Environment variable** | `COMPlus_gcAllowVeryLargeObjects` | 1 - enabled
0 - disabled | .NET Core 1.0 | ## Large object heap threshold diff --git a/docs/core/run-time-config/index.md b/docs/core/run-time-config/index.md index aa3cb50b420dd..64e67fefc72b0 100644 --- a/docs/core/run-time-config/index.md +++ b/docs/core/run-time-config/index.md @@ -12,7 +12,7 @@ ms.date: 11/13/2019 - Multiple instances of your application run at the same time on a single system, and you want to configure each for optimum performance. > [!NOTE] -> This documentation is a work in progress. If you notice that the information presented here is either incomplete or inaccurate, either [open an issue](https://github.com/dotnet/docs/issues) to let us know about it, or [submit a pull request](https://github.com/dotnet/docs/pulls) to address the issue. For information on submitting pull requests for the dotnet/docs repo, see the [contributor's guide](https://github.com/dotnet/docs/blob/master/CONTRIBUTING.md). +> This documentation is a work in progress. If you notice that the information presented here is either incomplete or inaccurate, either [open an issue](https://github.com/dotnet/docs/issues) to let us know about it, or [submit a pull request](https://github.com/dotnet/docs/pulls) to address the issue. For information on submitting pull requests for the dotnet/docs repository, see the [contributor's guide](https://github.com/dotnet/docs/blob/master/CONTRIBUTING.md). .NET Core provides the following mechanisms for configuring applications at run time: @@ -59,7 +59,7 @@ Some configuration values can also be set programmatically by calling the on both Windows and Unix-based systems. +You can define environment variables from the Windows Control Panel, at the command line, or programmatically by calling the method on both Windows and Unix-based systems. The following examples show how to set an environment variable at the command line: diff --git a/docs/framework/unmanaged-api/profiling/cor-prf-high-monitor-enumeration.md b/docs/framework/unmanaged-api/profiling/cor-prf-high-monitor-enumeration.md index 58b0064952372..74a06e6058547 100644 --- a/docs/framework/unmanaged-api/profiling/cor-prf-high-monitor-enumeration.md +++ b/docs/framework/unmanaged-api/profiling/cor-prf-high-monitor-enumeration.md @@ -49,7 +49,7 @@ typedef enum { ## Remarks -The `COR_PRF_HIGH_MONITOR` flags are used with the `pdwEventsHigh` parameter of the [ICorProfilerInfo5::GetEventMask2](../../../../docs/framework/unmanaged-api/profiling/icorprofilerinfo5-geteventmask2-method.md) and [ICorProfilerInfo5::SetEventMask2](../../../../docs/framework/unmanaged-api/profiling/icorprofilerinfo5-seteventmask2-method.md) methods. +The `COR_PRF_HIGH_MONITOR` flags are used with the `pdwEventsHigh` parameter of the [ICorProfilerInfo5::GetEventMask2](icorprofilerinfo5-geteventmask2-method.md) and [ICorProfilerInfo5::SetEventMask2](icorprofilerinfo5-seteventmask2-method.md) methods. Starting with the .NET Framework 4.6.1, the value of the `COR_PRF_HIGH_ALLOWABLE_AFTER_ATTACH` changed from 0 to `COR_PRF_HIGH_IN_MEMORY_SYMBOLS_UPDATED` (0x00000002). Starting with the .NET Framework 4.7.2, its value changed from `COR_PRF_HIGH_IN_MEMORY_SYMBOLS_UPDATED` to `COR_PRF_HIGH_IN_MEMORY_SYMBOLS_UPDATED | COR_PRF_HIGH_MONITOR_DYNAMIC_FUNCTION_UNLOADS`. diff --git a/docs/standard/garbage-collection/large-object-heap.md b/docs/standard/garbage-collection/large-object-heap.md index 1d5f4459edfbd..ef138836977de 100644 --- a/docs/standard/garbage-collection/large-object-heap.md +++ b/docs/standard/garbage-collection/large-object-heap.md @@ -1,5 +1,5 @@ --- -title: LOH on Windows +title: LOH on Windows - .NET ms.date: "05/02/2018" helpviewer_keywords: - large object heap (LOH)" From 47bfc9892e72dc5f098eaf12b2f311c38af62158 Mon Sep 17 00:00:00 2001 From: Genevieve Warren Date: Tue, 19 Nov 2019 12:04:40 -0800 Subject: [PATCH 17/18] add byte size --- docs/core/run-time-config/garbage-collector.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/run-time-config/garbage-collector.md b/docs/core/run-time-config/garbage-collector.md index a584283831c59..e389f93076e8c 100644 --- a/docs/core/run-time-config/garbage-collector.md +++ b/docs/core/run-time-config/garbage-collector.md @@ -125,7 +125,7 @@ For more information about some of these settings, see the [Middle ground betwee ### System.GC.HeapHardLimit/COMPlus_GCHeapHardLimit -- Specifies the maximum commit size for the GC heap. +- Specifies the maximum commit size, in bytes, for the GC heap. - The value can range from 0 to 18446744073709551615. | | Setting name | Values | Version introduced | From 5c67d6b32900e3bbd7aac7b25065b484bc04eefd Mon Sep 17 00:00:00 2001 From: Genevieve Warren Date: Tue, 19 Nov 2019 12:49:20 -0800 Subject: [PATCH 18/18] review feedback --- docs/breadcrumb/toc.yml | 9 ++++++--- docs/core/run-time-config/garbage-collector.md | 16 ++++++++-------- docs/core/run-time-config/index.md | 1 + 3 files changed, 15 insertions(+), 11 deletions(-) diff --git a/docs/breadcrumb/toc.yml b/docs/breadcrumb/toc.yml index 31f62bc4824a7..e4b1b762c4599 100644 --- a/docs/breadcrumb/toc.yml +++ b/docs/breadcrumb/toc.yml @@ -115,12 +115,15 @@ tocHref: /dotnet/core/ topicHref: /dotnet/core/index items: - - name: Tools - tocHref: /dotnet/core/tools/ - topicHref: /dotnet/core/tools/index - name: Compatibility tocHref: /dotnet/core/compatibility/ topicHref: /dotnet/core/compatibility/index + - name: Run-time configuration + tocHref: /dotnet/core/run-time-config/ + topicHref: /dotnet/core/run-time-config/index + - name: Tools + tocHref: /dotnet/core/tools/ + topicHref: /dotnet/core/tools/index - name: .NET Framework tocHref: /dotnet/framework/ topicHref: /dotnet/framework/index diff --git a/docs/core/run-time-config/garbage-collector.md b/docs/core/run-time-config/garbage-collector.md index eb21464e56435..0b7f0db75eff7 100644 --- a/docs/core/run-time-config/garbage-collector.md +++ b/docs/core/run-time-config/garbage-collector.md @@ -8,7 +8,7 @@ ms.topic: reference This page contains information about garbage collector (GC) settings that can be changed at run time. If you're trying to achieve peak performance of a running app, consider using these settings. However, the defaults provide optimum performance for most applications in typical situations. -On this page, settings are arranged into groups of settings that you can use in conjunction with each other to achieve a specific result. +Settings are arranged into groups on this page. The settings within each group are commonly used in conjunction with each other to achieve a specific result. > [!NOTE] > @@ -31,9 +31,9 @@ Use the following settings to select flavors of garbage collection: | | Setting name | Values | Version introduced | | - | - | - | - | -| **runtimeconfig.json** | `System.GC.Server` | `true` - server
`false` - workstation | .NET Core 1.0 | +| **runtimeconfig.json** | `System.GC.Server` | `false` - workstation
`true` - server | .NET Core 1.0 | | **Environment variable** | `COMPlus_gcServer` | 0 - workstation
1 - server | .NET Core 1.0 | -| **app.config for .NET Framework** | [GCServer](../../framework/configure-apps/file-schema/runtime/gcserver-element.md) | `true` - server
`false` - workstation | | +| **app.config for .NET Framework** | [GCServer](../../framework/configure-apps/file-schema/runtime/gcserver-element.md) | `false` - workstation
`true` - server | | ### System.GC.Concurrent/COMPlus_gcConcurrent @@ -109,7 +109,7 @@ For more information about some of these settings, see the [Middle ground betwee | - | - | - | - | | **runtimeconfig.json** | N/A | N/A | N/A | | **Environment variable** | `COMPlus_GCCpuGroup` | 0 - disabled
1 - enabled | .NET Core 1.0 | -| **app.config for .NET Framework** | [GCCpuGroup](../../framework/configure-apps/file-schema/runtime/gccpugroup-element.md) | `true` - enabled
`false` - disabled | | +| **app.config for .NET Framework** | [GCCpuGroup](../../framework/configure-apps/file-schema/runtime/gccpugroup-element.md) | `false` - disabled
`true` - enabled | | ### System.GC.NoAffinitize/COMPlus_GCNoAffinitize @@ -119,9 +119,9 @@ For more information about some of these settings, see the [Middle ground betwee | | Setting name | Values | Version introduced | | - | - | - | - | -| **runtimeconfig.json** | `System.GC.NoAffinitize` | `true` - don't affinitize
`false` - affinitize | .NET Core 3.0 | +| **runtimeconfig.json** | `System.GC.NoAffinitize` | `false` - affinitize
`true` - don't affinitize | .NET Core 3.0 | | **Environment variable** | `COMPlus_GCNoAffinitize` | 0 - affinitize
1 - don't affinitize | .NET Core 3.0 | -| **app.config for .NET Framework** | [GCNoAffinitize](../../framework/configure-apps/file-schema/runtime/gcnoaffinitize-element.md) | `true` - don't affinitize
`false` - affinitize | 4.6.2 | +| **app.config for .NET Framework** | [GCNoAffinitize](../../framework/configure-apps/file-schema/runtime/gcnoaffinitize-element.md) | `false` - affinitize
`true` - don't affinitize | 4.6.2 | ### System.GC.HeapHardLimit/COMPlus_GCHeapHardLimit @@ -130,8 +130,8 @@ For more information about some of these settings, see the [Middle ground betwee | | Setting name | Values | Version introduced | | - | - | - | - | -| **runtimeconfig.json** | `System.GC.HeapHardLimit` | *number* | .NET Core 3.0 | -| **Environment variable** | `COMPlus_GCHeapHardLimit` | *number* | .NET Core 3.0 | +| **runtimeconfig.json** | `System.GC.HeapHardLimit` | *decimal value* | .NET Core 3.0 | +| **Environment variable** | `COMPlus_GCHeapHardLimit` | *decimal value* | .NET Core 3.0 | ### System.GC.HeapHardLimitPercent/COMPlus_GCHeapHardLimitPercent diff --git a/docs/core/run-time-config/index.md b/docs/core/run-time-config/index.md index 64e67fefc72b0..e531ed7cd6586 100644 --- a/docs/core/run-time-config/index.md +++ b/docs/core/run-time-config/index.md @@ -47,6 +47,7 @@ Here is an example file: "System.GC.RetainVM": true, "System.Threading.ThreadPool.MinThreads": "4", "System.Threading.ThreadPool.MaxThreads": "25" + } } } ```