diff --git a/xml/Microsoft.CSharp/CSharpCodeProvider.xml b/xml/Microsoft.CSharp/CSharpCodeProvider.xml index 0019fcfb8b2..30977d9c42f 100644 --- a/xml/Microsoft.CSharp/CSharpCodeProvider.xml +++ b/xml/Microsoft.CSharp/CSharpCodeProvider.xml @@ -114,18 +114,14 @@ - A object that contains the provider options from the configuration file. + A object that contains the provider options. Initializes a new instance of the class by using the specified provider options. ](/dotnet/framework/configure-apps/file-schema/compiler/provideroption-element) element in the configuration file. You can identify the version of the you want to use by specifying the `` element, supplying "CompilerVersion" as the option name, and supplying the version number (for example, "v3.5") as the option value. You must precede the version number with a lower case "v". - - - -## Examples - The following configuration file example demonstrates how to specify that version 3.5 of the C# code provider should be used. + +In .NET Framework apps, you can obtain the value for `providerOptions` from the [\](/dotnet/framework/configure-apps/file-schema/compiler/provideroption-element) element in the configuration file. You can identify the version of the you want to use by specifying the `` element, supplying "CompilerVersion" as the option name, and supplying the version number (for example, "v3.5") as the option value. You must precede the version number with a lower case "v". The following configuration file example demonstrates how to specify that version 3.5 of the C# code provider should be used. ```xml @@ -148,7 +144,9 @@ ``` - + +## Examples + The following example shows how to specify the compiler version when you create a new instance of the class. :::code language="csharp" source="~/snippets/csharp/Microsoft.CSharp/CSharpCodeProvider/.ctor/program.cs" id="Snippet1"::: diff --git a/xml/Microsoft.VisualBasic.Logging/FileLogTraceListener.xml b/xml/Microsoft.VisualBasic.Logging/FileLogTraceListener.xml index ac765b68f24..d874d5bbf47 100644 --- a/xml/Microsoft.VisualBasic.Logging/FileLogTraceListener.xml +++ b/xml/Microsoft.VisualBasic.Logging/FileLogTraceListener.xml @@ -34,7 +34,7 @@ ## Remarks The class provides automated maintenance capabilities to archive log files as needed, on a daily or per-application basis. This automatic archival functionality helps reduce the maintenance responsibilities of developers and administrators. - An instance of can be added to the or collections to redirect output from logging to a text file. Instances of this class can also be added to `My.Application.Log` or `My.Log` (for Web applications) in Visual Basic applications. For more information, see [Walkthrough: Changing Where My.Application.Log Writes Information](/dotnet/visual-basic/developing-apps/programming/log-info/walkthrough-changing-where-my-application-log-writes-information)`.` + An instance of can be added to the or collections to redirect output from logging to a text file. Instances of this class can also be added to `My.Application.Log` or `My.Log` (for Web applications) in Visual Basic applications. For more information, see [Walkthrough: Changing Where My.Application.Log Writes Information](/dotnet/visual-basic/developing-apps/programming/log-info/walkthrough-changing-where-my-application-log-writes-information). The main features of this class are: @@ -102,9 +102,7 @@ - To enable tracing in C#, add the `/d:TRACE` flag to the compiler command line when you compile your code, or add `#define TRACE` to the top of your file. In Visual Basic, add the `/d:TRACE=True` flag to the compiler command line. - To set the level of your listener, edit the configuration file for your application. Within this file, you can add a listener, set its type and set its parameters, remove a listener, or clear all the listeners previously set by the application. The configuration file should be formatted like the following example. - - For this example to run, you must provide the fully qualified assembly name. For information about how to obtain the fully qualified assembly name, see [Assembly Names](/dotnet/standard/assembly/names). +In .NET Framework apps, you can set the level of your listener by editing the configuration file for your application. Within this file, you can add a listener, set its type and set its parameters, remove a listener, or clear all the listeners previously set by the application. The configuration file should be formatted like the following example. ```xml @@ -119,7 +117,9 @@ -``` +``` + +For this example to run, you must provide the fully qualified assembly name. For information about how to obtain the fully qualified assembly name, see [Assembly Names](/dotnet/standard/assembly/names). ]]> diff --git a/xml/Microsoft.VisualBasic/VBCodeProvider.xml b/xml/Microsoft.VisualBasic/VBCodeProvider.xml index 4386a0638b5..189e738bbb2 100644 --- a/xml/Microsoft.VisualBasic/VBCodeProvider.xml +++ b/xml/Microsoft.VisualBasic/VBCodeProvider.xml @@ -114,18 +114,14 @@ - A object that contains the provider options from the configuration file. + A object that contains the provider options. Initializes a new instance of the class by using the specified provider options. you want to use by specifying the `` element, supplying "CompilerVersion" as the option name, and supplying the version number (for example, "v3.5") as the option value. You must precede the version number with a lower case "v". - - - -## Examples - The following configuration file example demonstrates how to specify that version 3.5 of the Visual Basic code provider should be used. +## Remarks + +In .NET Framework apps, you can obtain the value for `providerOptions` from the [\](/dotnet/framework/configure-apps/file-schema/compiler/provideroption-element) element in the configuration file. You can identify the version of the you want to use by specifying the `` element, supplying "CompilerVersion" as the option name, and supplying the version number (for example, "v3.5") as the option value. You must precede the version number with a lower case "v". The following configuration file example demonstrates how to specify that version 3.5 of the Visual Basic code provider should be used. ```xml @@ -148,7 +144,9 @@ ``` - + +## Examples + The following example shows how to specify the compiler version when creating a new instance of the class. :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/vbprovider.provideroptions/vb/program.vb" id="Snippet1"::: diff --git a/xml/System.ComponentModel.DataAnnotations/ValidationContext.xml b/xml/System.ComponentModel.DataAnnotations/ValidationContext.xml index 2d6925230c2..ede0eefb9a0 100644 --- a/xml/System.ComponentModel.DataAnnotations/ValidationContext.xml +++ b/xml/System.ComponentModel.DataAnnotations/ValidationContext.xml @@ -436,7 +436,7 @@ In .NET Framework 4.7.2 and earlier versions, when using a custom diff --git a/xml/System.ComponentModel/TypeConverter.xml b/xml/System.ComponentModel/TypeConverter.xml index 1365a2a7ed9..e2684b93f3c 100644 --- a/xml/System.ComponentModel/TypeConverter.xml +++ b/xml/System.ComponentModel/TypeConverter.xml @@ -2401,7 +2401,7 @@ Note: Your derived type might be marked as or method catches exceptions from the and methods. If the input value type causes to return `false`, or if the input value causes to raise an exception, the method returns `false`. - To enable the legacy behavior, insert the following lines into the configuration file of the application, for example, application1.exe.config. + To enable the legacy behavior, insert the following lines into the configuration file of your .NET Framework application. ```xml @@ -2475,7 +2475,7 @@ Note: Your derived type might be marked as or method catches exceptions from the and methods. If the input value type causes to return `false`, or if the input value causes to raise an exception, the method returns `false`. - To enable the legacy behavior, insert the following lines into the configuration file of the application, for example, application1.exe.config. + To enable the legacy behavior, insert the following lines into the configuration file of your .NET Framework application. ```xml @@ -2483,9 +2483,7 @@ Note: Your derived type might be marked as or -``` - - +``` ## Examples For an example of this function, see the class. diff --git a/xml/System.Configuration/ConfigurationCollectionAttribute.xml b/xml/System.Configuration/ConfigurationCollectionAttribute.xml index 1ae5bc01ae7..5c405c1a56a 100644 --- a/xml/System.Configuration/ConfigurationCollectionAttribute.xml +++ b/xml/System.Configuration/ConfigurationCollectionAttribute.xml @@ -63,7 +63,7 @@ ## Examples The following example shows how to use the . - This example consists of three classes: `UrlsSection`, `UrlsCollection` and `UrlConfigElement`. The `UrlsSection` class uses the to define a custom configuration section. This section contains a URL collection (defined by the `UrlsCollection` class) of URL elements (defined by the `UrlConfigElement` class). When you run the example, an instance of the `UrlsSection` class is created and the following configuration elements are generated in the application configuration file: + This example consists of three classes: `UrlsSection`, `UrlsCollection`, and `UrlConfigElement`. The `UrlsSection` class uses the to define a custom configuration section. This section contains a URL collection (defined by the `UrlsCollection` class) of URL elements (defined by the `UrlConfigElement` class). When you run the example, an instance of the `UrlsSection` class is created and the following configuration elements are generated in the application configuration file: ```xml diff --git a/xml/System.Resources/ResourceManager.xml b/xml/System.Resources/ResourceManager.xml index 421995f208d..bc69f977a86 100644 --- a/xml/System.Resources/ResourceManager.xml +++ b/xml/System.Resources/ResourceManager.xml @@ -69,7 +69,7 @@ The class retrieves resources from a binary .resources file that is embedded in an assembly or from a standalone .resources file. If an app has been localized and localized resources have been deployed in [satellite assemblies](/dotnet/framework/resources/creating-satellite-assemblies-for-desktop-apps), it looks up culture-specific resources, provides resource fallback when a localized resource does not exist, and supports resource serialization. - For more information about creating and managing resources in desktop apps and Windows 8.x Store apps, see the following sections: + For more information about creating and managing resources in desktop apps and Windows 8.x apps, see the following sections: - [Desktop Apps](#desktop) @@ -279,6 +279,10 @@ al /out:ru-RU\Showdate.resources.dll /culture:ru-RU /embed:DateStrings.ru-RU.res ### \ Configuration File Node + +> [!NOTE] +> This section is specific to .NET Framework apps. + For executables that are deployed and run from a website (HREF .exe files), the object may probe for satellite assemblies over the web, which can hurt your app's performance. To eliminate the performance problem, you can limit this probing to the satellite assemblies that you have deployed with your app. To do this, you create a `` node in your app's configuration file to specify that you have deployed a specific set of cultures for your app, and that the object should not try to probe for any culture that is not listed in that node. > [!NOTE] @@ -286,16 +290,16 @@ al /out:ru-RU\Showdate.resources.dll /culture:ru-RU /embed:DateStrings.ru-RU.res In your app's configuration file, create a section similar to the following: -``` +```xml -    -        -            cultureName1 -            cultureName2 -            cultureName3 -        -    + + + cultureName1 + cultureName2 + cultureName3 + + ``` @@ -316,19 +320,17 @@ al /out:ru-RU\Showdate.resources.dll /culture:ru-RU /embed:DateStrings.ru-RU.res If resources are needed for any assembly not listed under the `` node, the class probes for cultures using standard probing rules. -## Windows 8.x Store Apps +## Windows 8.x Apps > [!IMPORTANT] -> Although the class is supported in Windows 8.x Store apps, we do not recommend its use. Use this class only when you develop Portable Class Library projects that can be used with Windows 8.x Store apps. To retrieve resources from Windows 8.x Store apps, use the [Windows.ApplicationModel.Resources.ResourceLoader](https://go.microsoft.com/fwlink/p/?LinkId=238182) class instead. +> Although the class is supported in Windows 8.x apps, we do not recommend its use. Use this class only when you develop Portable Class Library projects that can be used with Windows 8.x apps. To retrieve resources from Windows 8.x apps, use the [Windows.ApplicationModel.Resources.ResourceLoader](/uwp/api/Windows.ApplicationModel.Resources.ResourceLoader) class instead. - For Windows 8.x Store apps, the class retrieves resources from package resource index (PRI) files. A single PRI file (the application package PRI file) contains the resources for both the default culture and any localized cultures. You use the MakePRI utility to create a PRI file from one or more resource files that are in XML resource (.resw) format. For resources that are included in a Visual Studio project, Visual Studio handles the process of creating and packaging the PRI file automatically. You can then use the .NET Framework class to access the app's or library's resources. + For Windows 8.x apps, the class retrieves resources from package resource index (PRI) files. A single PRI file (the application package PRI file) contains the resources for both the default culture and any localized cultures. You use the MakePRI utility to create a PRI file from one or more resource files that are in XML resource (.resw) format. For resources that are included in a Visual Studio project, Visual Studio handles the process of creating and packaging the PRI file automatically. You can then use the .NET Framework class to access the app's or library's resources. - You can instantiate a object for a Windows 8.x Store app in the same way that you do for a desktop app. + You can instantiate a object for a Windows 8.x app in the same way that you do for a desktop app. You can then access the resources for a particular culture by passing the name of the resource to be retrieved to the method. By default, this method returns the resource for the culture determined by the current UI culture of the thread that made the call. You can also retrieve the resources for a specific culture by passing the name of the resource and a object that represents the culture whose resource is to be retrieved to the method. If the resource for the current UI culture or the specified culture cannot be found, the resource manager uses a UI language fallback list to locate a suitable resource. - - ## Examples The following example demonstrates how to use an explicit culture and the implicit current UI culture to obtain string resources from a main assembly and a satellite assembly. For more information, see the "Directory Locations for Satellite Assemblies Not Installed in the Global Assembly Cache" section of the [Creating Satellite Assemblies](/dotnet/framework/resources/creating-satellite-assemblies-for-desktop-apps) topic. @@ -337,11 +339,9 @@ al /out:ru-RU\Showdate.resources.dll /culture:ru-RU /embed:DateStrings.ru-RU.res 1. In the app directory, create a file named rmc.txt that contains the following resource strings: ``` - day=Friday year=2006 holiday="Cinco de Mayo" - ``` 2. Use the [Resource File Generator](/dotnet/framework/tools/resgen-exe-resource-file-generator) to generate the rmc.resources resource file from the rmc.txt input file as follows: @@ -355,11 +355,9 @@ al /out:ru-RU\Showdate.resources.dll /culture:ru-RU /embed:DateStrings.ru-RU.res 4. Create a file named rmc.es-MX.txt in the es-MX directory that contains the following resource strings: ``` - day=Viernes year=2006 holiday="Cinco de Mayo" - ``` 5. Use the [Resource File Generator](/dotnet/framework/tools/resgen-exe-resource-file-generator) to generate the rmc.es-MX.resources resource file from the rmc.es-MX.txt input file as follows: @@ -521,12 +519,12 @@ al /out:ru-RU\Showdate.resources.dll /culture:ru-RU /embed:DateStrings.ru-RU.res If you're not using Visual Studio, you can create a class with no members whose namespace and name are the same as that of the default .resources file. The example provides an illustration. -## Windows 8.x Store Apps +## Windows 8.x Apps > [!IMPORTANT] -> Although the class is supported in Windows 8.x Store apps, we do not recommend its use. Use this class only when you develop Portable Class Library projects that can be used with Windows 8.x Store apps. To retrieve resources from Windows 8.x Store apps, use the [Windows.ApplicationModel.Resources.ResourceLoader](https://go.microsoft.com/fwlink/p/?LinkId=238182) class instead. +> Although the class is supported in Windows 8.x apps, we do not recommend its use. Use this class only when you develop Portable Class Library projects that can be used with Windows 8.x apps. To retrieve resources from Windows 8.x apps, use the [Windows.ApplicationModel.Resources.ResourceLoader](https://go.microsoft.com/fwlink/p/?LinkId=238182) class instead. - In Windows 8.x Store apps, uses the `resourceSource` parameter to infer the assembly, base name, and the namespace where the resource items can be located within the app's package resource index (PRI) file. For example, given a type named MyCompany.MyProduct.MyType that is defined in `MyAssembly`, the resource manager looks for a resource set identifier named MyAssembly and looks for a scope MyCompany.MyProduct.MyType within that resource set. The resource manager searches for resource items under the default context (current culture, current high contrast setting, and so on) within this scope. + In Windows 8.x apps, uses the `resourceSource` parameter to infer the assembly, base name, and the namespace where the resource items can be located within the app's package resource index (PRI) file. For example, given a type named MyCompany.MyProduct.MyType that is defined in `MyAssembly`, the resource manager looks for a resource set identifier named MyAssembly and looks for a scope MyCompany.MyProduct.MyType within that resource set. The resource manager searches for resource items under the default context (current culture, current high contrast setting, and so on) within this scope. @@ -638,12 +636,12 @@ al /out:ru-RU\Greet.resources.dll /culture:ru-RU /embed: GreetingResources.ru-RU If the resource file identified by `baseName` cannot be found in `assembly`, the method instantiates a object, but the attempt to retrieve a specific resource throws an exception, typically . For information about diagnosing the cause of the exception, see the "Handling the MissingManifestResourceException Exception" section of the class topic. -## Windows 8.x Store Apps +## Windows 8.x Apps > [!IMPORTANT] -> Although the class is supported in Windows 8.x Store apps, we do not recommend its use. Use this class only when you develop Portable Class Library projects that can be used with Windows 8.x Store apps. To retrieve resources from Windows 8.x Store apps, use the [Windows.ApplicationModel.Resources.ResourceLoader](https://go.microsoft.com/fwlink/p/?LinkId=238182) class instead. +> Although the class is supported in Windows 8.x apps, we do not recommend its use. Use this class only when you develop Portable Class Library projects that can be used with Windows 8.x apps. To retrieve resources from Windows 8.x apps, use the [Windows.ApplicationModel.Resources.ResourceLoader](https://go.microsoft.com/fwlink/p/?LinkId=238182) class instead. - In Windows 8.x Store apps, the resource manager uses the simple name of the `assembly` parameter to look up a matching resource set in the app's package resource index (PRI) file. The `baseName` parameter is used to look up a resource item within the resource set. For example, the root name for PortableLibrary1.Resource1.de-DE.resources is PortableLibrary1.Resource1. + In Windows 8.x apps, the resource manager uses the simple name of the `assembly` parameter to look up a matching resource set in the app's package resource index (PRI) file. The `baseName` parameter is used to look up a resource item within the resource set. For example, the root name for PortableLibrary1.Resource1.de-DE.resources is PortableLibrary1.Resource1. @@ -1774,12 +1772,12 @@ csc GetStream.cs /resource:AppResources.resources > [!CAUTION] > This method can throw more exceptions than are listed. One reason this might occur is if a method that this method calls throws an exception. For example, a exception might be thrown if an error was made deploying or installing a satellite assembly, or a exception might be thrown if a user-defined type throws a user-defined exception when the type is deserialized. -## Windows 8.x Store Apps +## Windows 8.x Apps > [!IMPORTANT] -> Although the class is supported in Windows 8.x Store apps, we do not recommend its use. Use this class only when you develop Portable Class Library projects that can be used with Windows 8.x Store apps. To retrieve resources from Windows 8.x Store apps, use the [Windows.ApplicationModel.Resources.ResourceLoader](https://go.microsoft.com/fwlink/p/?LinkId=238182) class instead. +> Although the class is supported in Windows 8.x apps, we do not recommend its use. Use this class only when you develop Portable Class Library projects that can be used with Windows 8.x apps. To retrieve resources from Windows 8.x apps, use the [Windows.ApplicationModel.Resources.ResourceLoader](https://go.microsoft.com/fwlink/p/?LinkId=238182) class instead. - In Windows 8.x Store apps, the method returns the value of the `name` string resource, localized for the caller's current UI culture settings. The list of cultures is derived from the operating system's preferred UI language list. If the resource manager cannot match `name`, the method returns `null`. + In Windows 8.x apps, the method returns the value of the `name` string resource, localized for the caller's current UI culture settings. The list of cultures is derived from the operating system's preferred UI language list. If the resource manager cannot match `name`, the method returns `null`. @@ -1891,12 +1889,12 @@ al /out:ru-RU\Showdate.resources.dll /culture:ru-RU /embed:DateStrings.ru-RU.res > [!CAUTION] > This method can throw more exceptions than are listed. One reason this might occur is if a method that this method calls throws an exception. For example, a exception might be thrown if an error was made deploying or installing a satellite assembly, or a exception might be thrown if a user-defined type throws a user-defined exception when the type is deserialized. -## Windows 8.x Store Apps +## Windows 8.x Apps > [!IMPORTANT] -> Although the class is supported in Windows 8.x Store apps, we do not recommend its use. Use this class only when you develop Portable Class Library projects that can be used with Windows 8.x Store apps. To retrieve resources from Windows 8.x Store apps, use the [Windows.ApplicationModel.Resources.ResourceLoader](https://go.microsoft.com/fwlink/p/?LinkId=238182) class instead. +> Although the class is supported in Windows 8.x apps, we do not recommend its use. Use this class only when you develop Portable Class Library projects that can be used with Windows 8.x apps. To retrieve resources from Windows 8.x apps, use the [Windows.ApplicationModel.Resources.ResourceLoader](https://go.microsoft.com/fwlink/p/?LinkId=238182) class instead. - In Windows 8.x Store apps, the method returns the value of the `name` string resource, localized for the culture specified by the `culture` parameter. If the resource is not localized for the `culture` culture, the lookup uses the entire Windows 8 language fallback list, and stops after looking in the default culture. If the resource manager cannot match `name`, the method returns `null`. + In Windows 8.x apps, the method returns the value of the `name` string resource, localized for the culture specified by the `culture` parameter. If the resource is not localized for the `culture` culture, the lookup uses the entire Windows 8 language fallback list, and stops after looking in the default culture. If the resource manager cannot match `name`, the method returns `null`. diff --git a/xml/System.Runtime/GCSettings.xml b/xml/System.Runtime/GCSettings.xml index feabf0594fc..cf4311114d9 100644 --- a/xml/System.Runtime/GCSettings.xml +++ b/xml/System.Runtime/GCSettings.xml @@ -99,22 +99,13 @@ - - - - -``` - - + An unmanaged host can request server garbage collection, and the host request overrides configuration file settings. If the host does not specify the type of garbage collection, you can use a configuration setting to specify server garbage collection. For more information, see [Configure workstation vs. server](/dotnet/core/runtime-config/garbage-collector#workstation-vs-server). ## Examples The following example indicates whether the host computer is using server or workstation garbage collection. diff --git a/xml/System.Threading/Thread.xml b/xml/System.Threading/Thread.xml index 8360982639f..58954d2042d 100644 --- a/xml/System.Threading/Thread.xml +++ b/xml/System.Threading/Thread.xml @@ -446,7 +446,7 @@ Main thread: ThreadProc.Join has returned. Press Enter to end program. > [!NOTE] > If you are developing a fully trusted library that will be used by partially trusted code, and you need to start a thread that requires a large stack, you must assert full trust before creating the thread, or the default stack size will be used. Do not do this unless you fully control the code that runs on the thread. - If `maxStackSize` is less than the minimum stack size, the minimum stack size is used. If `maxStackSize` is not a multiple of the page size, it is rounded to the next larger multiple of the page size. For example, if you are using the .NET Framework version 2.0 on Windows Vista, 256KB (262,144 bytes) is the minimum stack size, and the page size is 64KB (65,536 bytes). + If `maxStackSize` is less than the minimum stack size, the minimum stack size is used. If `maxStackSize` is not a multiple of the page size, it is rounded to the next larger multiple of the page size. > [!NOTE] > On versions of Microsoft Windows prior to Windows XP and Windows Server 2003, `maxStackSize` is ignored, and the stack size specified in the executable header is used. diff --git a/xml/System/AppContext.xml b/xml/System/AppContext.xml index cf99937ba3a..0b30f74dfd4 100644 --- a/xml/System/AppContext.xml +++ b/xml/System/AppContext.xml @@ -51,29 +51,30 @@ class enables library writers to provide a uniform opt-out mechanism for new functionality for their users. It establishes a loosely-coupled contract between components in order to communicate an opt-out request. This capability is typically important when a change is made to existing functionality. Conversely, there is already an implicit opt-in for new functionality. + The class enables library writers to provide a uniform opt-out mechanism for new functionality for their users. It establishes a loosely coupled contract between components in order to communicate an opt-out request. This capability is typically important when a change is made to existing functionality. Conversely, there is already an implicit opt-in for new functionality. ## AppContext for library developers - Libraries use the class to define and expose compatibility switches, while library users can set those switches to affect the library behavior. By default, libraries provide the new functionality, and they only alter it (that is, they provide the previous functionality) if the switch is set. This allows libraries to provide new behavior for an existing API while continuing to support callers who depend on the previous behavior. + Libraries use the class to define and expose compatibility switches, while library users can set those switches to affect the library behavior. By default, libraries provide the new functionality, and they only alter it (that is, they provide the previous functionality) if the switch is set. This allows libraries to provide new behavior for an existing API while continuing to support callers who depend on the previous behavior. ### Define the switch name - The most common way to allow consumers of your library to opt out of a change of behavior is to define a named switch. Its `value` element is a name/value pair that consists of the name of a switch and its value. By default, the switch is always implicitly `false`, which provides the new behavior (and makes the new behavior opt-in by default). Setting the switch to `true` enables it, which provides the legacy behavior. Explicitly setting the switch to `false` also provides the new behavior. + The most common way to allow consumers of your library to opt out of a change of behavior is to define a named switch. Its `value` element is a name/value pair that consists of the name of a switch and its value. By default, the switch is always implicitly `false`, which provides the new behavior (and makes the new behavior opt-in by default). Setting the switch to `true` enables it, which provides the legacy behavior. Explicitly setting the switch to `false` also provides the new behavior. - It's beneficial to use a consistent format for switch names, since they are a formal contract exposed by a library. The following are two obvious formats. + It's beneficial to use a consistent format for switch names, since they are a formal contract exposed by a library. The following are two obvious formats: - *Switch*.*namespace*.*switchname* - *Switch*.*library*.*switchname* - Once you define and document the switch, callers can use it by using the registry, by adding an [\](/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element) element to their application configuration file, or by calling the method programmatically. See the [AppContext for library consumers](#ForConsumers) section for more information about how callers use and set the value of configuration switches. + Once you define and document the switch, callers can use it by calling the method programmatically. .NET Framework apps can also use the switch by adding an [\](/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element) element to their application configuration file or by using the registry. For more information about how callers use and set the value of configuration switches, see the [AppContext for library consumers](#ForConsumers) section. - When the common language runtime runs an application, it automatically reads the registry's compatibility settings and loads the application configuration file in order to populate the application's instance. Because the instance is populated either programmatically by the caller or by the runtime, you do not have to take any action, such as calling the method, to configure the instance. + When the .NET Framework common language runtime runs an application, it automatically reads the registry's compatibility settings and loads the application configuration file to populate the application's instance. Because the instance is populated either programmatically by the caller or by the .NET Framework runtime, .NET Framework apps don't have to take any action, such as calling the method, to configure the instance. ### Check the setting - You can then check if a consumer has declared the value of the switch and act appropriately by calling the method. The method returns `true` if the `switchName` argument is found, and when the method returns, its `isEnabled` argument indicates the value of the switch. Otherwise, the method returns `false`. + +You can check if a consumer has declared the value of the switch and act appropriately by calling the method. The method returns `true` if the `switchName` argument is found, and when the method returns, its `isEnabled` argument indicates the value of the switch. Otherwise, the method returns `false`. ### An example - The following example illustrates the use of the class to allow the customer to choose the original behavior of a library method. The following is version 1.0 of a library named `StringLibrary`. It defines a `SubstringStartsAt` method that performs an ordinal comparison to determine the starting index of a substring within a larger string. + The following example illustrates the use of the class to allow the customer to choose the original behavior of a library method. The following is version 1.0 of a library named `StringLibrary`. It defines a `SubstringStartsAt` method that performs an ordinal comparison to determine the starting index of a substring within a larger string. :::code language="csharp" source="~/snippets/csharp/System/AppContext/Overview/Example4.cs" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/System.AppContext.Class/fs/Example4.fs" id="Snippet4"::: @@ -85,7 +86,7 @@ :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/System.AppContext.Class/fs/Example4.fs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.AppContext.Class/vb/Example4.vb" id="Snippet5"::: - Version 2 of the library, however, changes the `SubstringStartsAt` method to use culture-sensitive comparison. + Version 2.0 of the library, however, changes the `SubstringStartsAt` method to use culture-sensitive comparison. :::code language="csharp" source="~/snippets/csharp/System/AppContext/Overview/Example6.cs" id="Snippet6"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/System.AppContext.Class/fs/Example6.fs" id="Snippet6"::: @@ -97,25 +98,23 @@ :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/System.AppContext.Class/fs/Example6.fs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.AppContext.Class/vb/Example6.vb" id="Snippet7"::: - This change can be prevented from breaking the applications that depend on the original behavior by defining an [\](/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element) switch. In this case, the switch is named `StringLibrary.DoNotUseCultureSensitiveComparison`. Its default value, `false`, indicates that the library should perform its version 2.0 culture-sensitive comparison. `true` indicates that the library should perform its version 1.0 ordinal comparison. A slight modification of the previous code allows the library consumer to set the switch to determine the kind of comparison the method performs. + This change can be prevented from breaking the applications that depend on the original behavior by defining a switch. In this case, the switch is named `StringLibrary.DoNotUseCultureSensitiveComparison`. Its default value, `false`, indicates that the library should perform its version 2.0 culture-sensitive comparison. `true` indicates that the library should perform its version 1.0 ordinal comparison. A slight modification of the previous code allows the library consumer to set the switch to determine the kind of comparison the method performs. :::code language="csharp" source="~/snippets/csharp/System/AppContext/Overview/Example8.cs" id="Snippet8"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/System.AppContext.Class/fs/Example8.fs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.AppContext.Class/vb/Example8.vb" id="Snippet8"::: - If application can then use the following configuration file to restore the version 1.0 behavior. +A .NET Framework application can then use the following configuration file to restore the version 1.0 behavior. ```xml - - ``` - When the application is run with the configuration file present, it produces the following output: +When the application is run with the configuration file present, it produces the following output: ``` 'archæ' not found in 'The archaeologist' @@ -123,26 +122,24 @@ ## AppContext for library consumers - If you are the consumer of a library, the class allows you to take advantage of a library or library method's opt-out mechanism for new functionality. Individual methods of the class library that you are calling define particular switches that enable or disable a new behavior. The value of the switch is a Boolean. If it is `false`, which is typically the default value, the new behavior is enabled; if it is `true`, the new behavior is disabled, and the member behaves as it did previously. - - You can set the value of a switch in one of four ways: + If you're the consumer of a library, the class allows you to take advantage of a library or library method's opt-out mechanism for new functionality. Individual methods of the class library that you are calling define particular switches that enable or disable a new behavior. The value of the switch is a Boolean. If it is `false`, which is typically the default value, the new behavior is enabled; if it is `true`, the new behavior is disabled, and the member behaves as it did previously. -- By calling the method in your code. The `switchName` argument defines the switch name, and the `isEnabled` property defines the value of the switch. Because is a static class, it is available on a per-application domain basis. + You can set the value of a switch by calling the method in your code. The `switchName` argument defines the switch name, and the `isEnabled` property defines the value of the switch. Because is a static class, it is available on a per-application domain basis. Calling the has application scope; that is, it affects only the application. - Calling the has application scope; that is, it affects only the application. +.NET Framework apps have additional ways to set the value of a switch: -- By adding an `` element to the [\](/dotnet/framework/configure-apps/file-schema/runtime/runtime-element) section of your app.config file. The switch has a single attribute, `value`, whose value is a string that represents a key/value pair containing both the switch name and its value. +- By adding an `` element to the [\](/dotnet/framework/configure-apps/file-schema/runtime/runtime-element) section of the app.config file. The switch has a single attribute, `value`, whose value is a string that represents a key/value pair containing both the switch name and its value. - To define multiple switches, separate each switch's key/value pair in the [\](/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element) element's `value` attribute with a semicolon. In that case, the `` element has the following format: + To define multiple switches, separate each switch's key/value pair in the [\](/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element) element's `value` attribute with a semicolon. In that case, the `` element has the following format: ```xml ``` - Using the `` element to define a configuration setting has application scope; that is, it affects only the application. + Using the `` element to define a configuration setting has application scope; that is, it affects only the application. > [!NOTE] - > For information on the switches defined by the .NET Framework, see the [\ element](/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element). + > For information on the switches defined by .NET Framework, see [\ element](/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element). - By adding an entry to the registry. Add a new string value to the **HKLM\SOFTWARE\Microsoft\\.NETFramework\AppContext** subkey. Set the name of the entry to the name of the switch. Set its value to one of the following options: `True`, `true`, `False`, or `false`. If the runtime encounters any other value, it ignores the switch. @@ -150,7 +147,7 @@ Using the registry to define an switch has machine scope; that is, it affects every application running on the machine. -- For ASP.NET applications, you add an [\](/dotnet/framework/configure-apps/file-schema/appsettings/add-element-for-appsettings) element to the [\](/dotnet/framework/configure-apps/file-schema/appsettings/) section of the web.config file. For example: +For ASP.NET and ASP.NET Core applications, you set a switch by adding an [\](/dotnet/framework/configure-apps/file-schema/appsettings/add-element-for-appsettings) element to the [\](/dotnet/framework/configure-apps/file-schema/appsettings/) section of the web.config file. For example: ```xml @@ -161,13 +158,13 @@ If you set the same switch in more than one way, the order of precedence for determining which setting overrides the others is: -1. The programmatic setting. +1. The programmatic setting. -2. The setting in the app config file or the web.config file. +2. The setting in the app.config file (for .NET Framework apps) or the web.config file (for ASP.NET Core apps). -3. The registry setting. +3. The registry setting (for .NET Framework apps only). - The following is a simple application that passes a file URI to the method. When run under the .NET Framework 4.6, it throws an because `file://` is no longer a valid part of a file path. + The following is a simple application that passes a file URI to the method. When run under .NET Framework 4.6, it throws an because `file://` is no longer a valid part of a file path. :::code language="csharp" source="~/snippets/csharp/System/AppContext/Overview/ForConsumers1.cs" id="Snippet10"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/System.AppContext.Class/fs/ForConsumers1.fs" id="Snippet10"::: @@ -184,7 +181,7 @@ If you set the same switch in more than one way, the order of precedence for det ``` ## See also -[AppContext switch](/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element) +- [AppContext switch](/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element) ]]> @@ -390,28 +387,17 @@ In .NET 5 and later versions, for bundled assemblies, the value returned is the - By adding the switch name and value to the [\](/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element) element in the [\](/dotnet/framework/configure-apps/file-schema/runtime/runtime-element) section of an application configuration file. For example, the following defines a switch named `Libraries.FPLibrary.UseExactFloatingPointComparison` whose value is `False`. ```xml - - ``` - By adding a string value whose name is the name of the switch to the **HKLM\SOFTWARE\Microsoft\\.NETFramework\AppContext** (and **HKLM\SOFTWARE\Wow6432Node\Microsoft\\.NETFramework\AppContext**) subkeys in the registry. Its value must be the string representation of a that can be parsed by the method; that is, it must be "True", "true", "False", or "false". If the registry entry exists, its value is overwritten by the `isEnabled` argument when is called. That is, the most recent call to the method overrides the value defined in the registry, in an app configuration file, or by previous calls to the method. - ### AppContext.SetSwitch and .NET Core - -.NET Core supports programmatic calls with the method only. The following switches are supported: - -|Switch|Values|Description| -|--|--|--| -|`System.Net.Http.SocketsHttpHandler.Http2Support`|`true` or `false`|Indicates whether support for the HTTP/2 protocol is enabled (`true`) or disabled (`false`). The default is disabled. The switch must be set before the first use of . Available starting with .NET Core 3.0 Preview 4.| -|`System.Net.Http.UseSocketsHttpHandler` |`true` or `false`|Determines whether high-level networking APIs such as use (`true`) or (`false`).| - ## Examples The following line of code sets a switch named `Switch.AmazingLib.ThrowOnException` to `true`, which enables a legacy behavior. The library can then check whether a library consumer has set the value of the switch by calling the method. diff --git a/xml/System/String.xml b/xml/System/String.xml index 20d05a3362d..57f1b14a008 100644 --- a/xml/System/String.xml +++ b/xml/System/String.xml @@ -6785,7 +6785,7 @@ This method uses the [composite formatting feature](/dotnet/standard/base-types/ > > For more information about hash codes, see . - In desktop apps, you can use the [\ element](/dotnet/framework/configure-apps/file-schema/runtime/userandomizedstringhashalgorithm-element) to generate unique hash codes on a per application domain basis. This can reduce the number of collisions and improve the overall performance of insertions and lookups that use hash tables. The following example shows how to use the [\ element](/dotnet/framework/configure-apps/file-schema/runtime/userandomizedstringhashalgorithm-element). It defines a `DisplayString` class that includes a private string constant, `s`, whose value is "This is a string." It also includes a `ShowStringHashCode` method that displays the string value and its hash code along with the name of the application domain in which the method is executing. + In .NET Framework desktop apps, you can use the [\ element](/dotnet/framework/configure-apps/file-schema/runtime/userandomizedstringhashalgorithm-element) to generate unique hash codes on a per-application domain basis. This can reduce the number of collisions and improve the overall performance of insertions and lookups that use hash tables. The following example shows how to use the [\ element](/dotnet/framework/configure-apps/file-schema/runtime/userandomizedstringhashalgorithm-element). It defines a `DisplayString` class that includes a private string constant, `s`, whose value is "This is a string." It also includes a `ShowStringHashCode` method that displays the string value and its hash code along with the name of the application domain in which the method is executing. :::code language="csharp" source="~/snippets/csharp/System/String/GetHashCode/perdomain.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System/String/GetHashCode/perdomain.fs" id="Snippet2"::: diff --git a/xml/System/Uri.xml b/xml/System/Uri.xml index 35e94211e72..0bb0353f3fd 100644 --- a/xml/System/Uri.xml +++ b/xml/System/Uri.xml @@ -143,15 +143,15 @@ Web addresses are typically expressed using uniform resource identifiers that co With the growth of the Internet, there is a growing need to identify resources using languages other than English. Identifiers which facilitate this need and allow non-ASCII characters (characters in the Unicode/ISO 10646 character set) are known as International Resource Identifiers (IRIs). The specifications for IRIs are documented in RFC 3987 published by IETF. Using IRIs allows a URL to contain Unicode characters. - The existing class has been extended in .NET Framework v3.5, 3.0 SP1, and 2.0 SP1 to provide IRI support based on RFC 3987. Users of .NET Framework versions before version 4.5 will not see any change from the .NET Framework 2.0 behavior unless they specifically enable IRI. This ensures application compatibility with prior versions of .NET Framework. + The existing class was extended in .NET Framework v3.5, 3.0 SP1, and 2.0 SP1 to provide IRI support based on RFC 3987. Users of .NET Framework versions before version 4.5 will not see any change from the .NET Framework 2.0 behavior unless they specifically enable IRI. This ensures application compatibility with prior versions of .NET Framework. In .NET Framework 4.5 and later versions, IRI is always enabled and can't be changed using a configuration option. To enable support for IRI in .NET Framework versions prior to .NET Framework 4.5, set a configuration option in the *machine.config* or in the *app.config* file. Specify whether you want Internationalized Domain Name (IDN) parsing applied to the domain name and whether IRI parsing rules should be applied. For example: ```xml - - + + ``` @@ -172,7 +172,7 @@ There are three possible values for IDN depending on the DNS servers that are us - idn enabled = None - This value will not convert any Unicode domain names to use Punycode. This is the default value which is consistent with the .NET Framework 2.0 behaviour. + This value will not convert any Unicode domain names to use Punycode. This is the default value which is consistent with the .NET Framework 2.0 behavior. When IRI parsing is enabled (iriParsing enabled = `true`), normalization and character checking are done according to the latest IRI rules in RFC 3986 and RFC 3987. When IRI parsing is disabled, normalization and character checking are performed according to RFC 2396 and RFC 2732 (for IPv6 literals). In versions of .NET Framework before version 4.5, the default value is `false`. In .NET Framework 4.5+, .NET Core, and .NET 5+, the default value is `true`, and the enabled state of IRI parsing cannot be modified by settings in a *.config* file. @@ -1672,26 +1672,26 @@ The URI formed by combining and property is dependent on configuration settings, as discussed later in this topic. Configuration settings cannot be changed by Windows Store applications, which can lead to inconsistent results when using . The property is provided as the preferred alternative to using , because is guaranteed to always be DNS safe, no matter what the current *app.config* settings might be. + The property is dependent on configuration settings in .NET Framework apps, as discussed later in this topic. The property is provided as the preferred alternative to using , because is guaranteed to always be DNS safe. - The property has been extended in .NET Framework v3.5, 3.0 SP1, and 2.0 SP1 to provide International Resource Identifier (IRI) support based on RFC 3987. Current users will not see any change from the .NET Framework 2.0 behavior unless they specifically enable IRI. This ensures application compatibility with prior versions of the .NET Framework. + The property was extended in .NET Framework v3.5, 3.0 SP1, and 2.0 SP1 to provide International Resource Identifier (IRI) support based on RFC 3987. However, to ensure application compatibility with prior versions, you must specifically enable it in .NET Framework apps. To enable support for IRI, the following two changes are required: - To enable support for IRI, the following two changes are required: +1. Add the following line to the *machine.config* file under the .NET Framework 2.0 directory: -1. Add the following line to the *machine.config* file under the .NET Framework 2.0 directory \
+ `\
` -2. Specify whether you want Internationalized Domain Name (IDN) parsing applied to the domain name and whether IRI parsing rules should be applied. This can be done in the *machine.config* or in the *app.config* file. For example, add the following: +2. Specify whether you want Internationalized Domain Name (IDN) parsing applied to the domain name and whether IRI parsing rules should be applied. This can be done in the *machine.config* or in the *app.config* file. For example, add the following: ```xml - - + + ``` - Enabling IDN will convert all Unicode labels in a domain name to their Punycode equivalents. Punycode names contain only ASCII characters and always start with the xn-- prefix. The reason for this is to support existing DNS servers on the Internet, since most DNS servers only support ASCII characters (see RFC 3940). + Enabling IDN converts all Unicode labels in a domain name to their Punycode equivalents. Punycode names contain only ASCII characters and always start with the xn-- prefix. The reason for this is to support existing DNS servers on the Internet, since most DNS servers only support ASCII characters (see RFC 3940). Enabling IDN only affects the value of the property. @@ -1707,9 +1707,9 @@ If you used an escaped string to construct this instance (for example, `"http:// - idn enabled = None - This value will not convert any Unicode domain names to use Punycode. This is the default value which is consistent with the .NET Framework 2.0 behaviour. + This value will not convert any Unicode domain names to use Punycode. This is the default value, which is consistent with the .NET Framework 2.0 behavior. - Enabling IRI parsing (iriParsing enabled = `true`) will do normalization and character checking according to the latest IRI rules in RFC 3987. The default value is `false` and will do normalization and character checking according to RFC 2396 and RFC 2732 (for IPv6 literals). + Enabling IRI parsing (iriParsing enabled = `true`) normalizes and checks characters according to the IRI rules in RFC 3987. The default value is `false` and normalizes and checks characters according to RFC 2396 and RFC 2732 (for IPv6 literals). For more information on IRI support, see the Remarks section for the class. diff --git a/xml/ns-System.Transactions.Configuration.xml b/xml/ns-System.Transactions.Configuration.xml index 674c2f070a5..a247f973a80 100644 --- a/xml/ns-System.Transactions.Configuration.xml +++ b/xml/ns-System.Transactions.Configuration.xml @@ -5,19 +5,16 @@ ` - - `` - - `` - - `` - - `` - - `` + An example configuration file used by a .NET Framework transaction application is as follows: + +```xml + + + + + + +``` This example specifies the default values of a transaction. Specifically, it sets the computer name of the Distributed Transaction Coordinator (MSDTC) that is responsible for coordinating all distributed transactions started locally, and the default time after which a transaction times out. In addition, it specifies a setting that can only be modified at the machine level, which is the maximum amount of time allowed before a transaction times out.