diff --git a/xml/System.Configuration/AppSettingsReader.xml b/xml/System.Configuration/AppSettingsReader.xml index 7382aa67174..abf3a0c1ce4 100644 --- a/xml/System.Configuration/AppSettingsReader.xml +++ b/xml/System.Configuration/AppSettingsReader.xml @@ -33,57 +33,7 @@ Provides a method for reading values of a particular type from the configuration. - - ` section, and then uses the to read the settings just generated. - -```csharp -using System; -using System.Configuration; - -class Program -{ - static void Main(string[] args) - { - var reader = new AppSettingsReader(); - - var stringSetting = reader.GetValue("String setting", typeof(string)); - Console.WriteLine("String setting: " + stringSetting); - - var dateTimeSetting = reader.GetValue("DateTime setting", typeof(DateTime)); - Console.WriteLine("DateTime setting: " + dateTimeSetting); - - try - { - var missingSetting = reader.GetValue("Int setting", typeof(Int32)); - } - catch (InvalidOperationException e) - { - Console.WriteLine("Missing key error: " + e.Message); - } - - Console.WriteLine("Press any key to continue"); - Console.ReadKey(); - } -} -``` - - The following example demonstrates a configuration file used by the previous example. - -```xml - - - - - - - -``` - - ]]> - + To be added. @@ -115,57 +65,7 @@ class Program Initializes a new instance of the class. - - ` section, and then uses the to read the settings just generated. - -```csharp -using System; -using System.Configuration; - -class Program -{ - static void Main(string[] args) - { - var reader = new AppSettingsReader(); - - var stringSetting = reader.GetValue("String setting", typeof(string)); - Console.WriteLine("String setting: " + stringSetting); - - var dateTimeSetting = reader.GetValue("DateTime setting", typeof(DateTime)); - Console.WriteLine("DateTime setting: " + dateTimeSetting); - - try - { - var missingSetting = reader.GetValue("Int setting", typeof(Int32)); - } - catch (InvalidOperationException e) - { - Console.WriteLine("Missing key error: " + e.Message); - } - - Console.WriteLine("Press any key to continue"); - Console.ReadKey(); - } -} -``` - - The following example demonstrates a configuration file used by the previous example. - -```xml - - - - - - - -``` - - ]]> - + To be added. diff --git a/xml/System.Configuration/AppSettingsSection.xml b/xml/System.Configuration/AppSettingsSection.xml index ac1a01ae7df..38dd71fc3c3 100644 --- a/xml/System.Configuration/AppSettingsSection.xml +++ b/xml/System.Configuration/AppSettingsSection.xml @@ -32,26 +32,7 @@ Provides configuration system support for the configuration section. This class cannot be inherited. - - object, you should use the property of the class or the property of the class. - - - -## Examples - The following example shows how to use the class in a console application. It reads and writes the key/value pairs that are contained by the `appSettings` section. It also shows how to access the property of the class. - -> [!NOTE] -> Before you compile this code, add a reference in your project to System.Configuration.dll. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.AppSettingsSection/CS/UsingAppSettingsSection.cs" id="Snippet21"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.AppSettingsSection/VB/AppSettingsSection.vb" id="Snippet21"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.AppSettingsSection/VB/UsingAppSettingsSection.vb" id="Snippet21"::: - - ]]> - + To be added. diff --git a/xml/System.Configuration/ApplicationSettingsBase.xml b/xml/System.Configuration/ApplicationSettingsBase.xml index 71d025cffcb..858efb2bbd9 100644 --- a/xml/System.Configuration/ApplicationSettingsBase.xml +++ b/xml/System.Configuration/ApplicationSettingsBase.xml @@ -246,7 +246,7 @@ property to the value of the `settingsKey` parameter. This property is useful in disambiguating different instances of the settings wrapper class in the same application domain. + This constructor initializes the property to the value of the `settingsKey` parameter. This property is useful in disambiguating different instances of the settings wrapper class. For information about how reflection is used during the instantiation of a wrapper class, see the default constructor. @@ -294,7 +294,7 @@ ## Remarks The object specified by the `owner` parameter acts as the owner of the current instance of this applications settings class. During the initialization of the settings wrapper class derived from , the owner's site is queried for a . If one exists, it is used in preference to native settings provider for all the properties of the wrapper class, as specified by the . - This constructor initializes the property to the value of the `settingsKey` parameter. This property is useful in disambiguating different instances of the wrapper class in the same application domain. + This constructor initializes the property to the value of the `settingsKey` parameter. This property is useful in disambiguating different instances of the wrapper class. For information about how reflection is used during the instantiation of a wrapper class, see the default constructor. diff --git a/xml/System.Configuration/ClientSettingsSection.xml b/xml/System.Configuration/ClientSettingsSection.xml index f9bdd51f346..72f25a9d14d 100644 --- a/xml/System.Configuration/ClientSettingsSection.xml +++ b/xml/System.Configuration/ClientSettingsSection.xml @@ -36,11 +36,10 @@ , which stores configuration data to the local file system in files with the extension `.config`. The contents of configuration files are structured as XML documents. User-scoped settings are persisted in a file with the name `username.config`. Within this file, data is stored as elements within a `` section. Each of these sections is represented by a corresponding . Each section object is owned and administered by a configuration section handler, which is an . - The class represents a simple extension of the class, which is used in the .NET Framework support for general configuration files. +.NET contains a single default settings provider, , which stores configuration data to the local file system in files with the extension `.config`. The contents of configuration files are structured as XML documents. User-scoped settings are persisted in a file with the name `username.config`. Within this file, data is stored as elements within a `` section. Each of these sections is represented by a corresponding . Each section object is owned and administered by a configuration section handler, which is an . - For more information about application settings, see the topic [Application Settings for Windows Forms](/dotnet/desktop/winforms/advanced/application-settings-for-windows-forms). + The class represents a simple extension of the class, which is used in the .NET support for general configuration files. ]]> diff --git a/xml/System.Configuration/Configuration.xml b/xml/System.Configuration/Configuration.xml index 2b790e075d8..bb41eb1bdcf 100644 --- a/xml/System.Configuration/Configuration.xml +++ b/xml/System.Configuration/Configuration.xml @@ -43,7 +43,6 @@ You can get a object by using the following classes: - The class, if your entity is a client application. - - The class, if your entity is a Web application. The names of the methods that return a object begin with "Open". @@ -51,15 +50,12 @@ You can also generate a configuration file that represents the configuration settings in a object. To do this, use one of the following methods: - Call the method to create a new configuration file. - - Call the method to generate a new configuration file at another location. The names of the methods that create configuration files begin with "Save". > [!NOTE] -> To enable access to configuration settings on a remote computer, use the Aspnet_regiis command-line tool. For information about creating and accessing custom configuration settings other than the intrinsic sections included in the .NET Framework, refer to . - - +> To enable access to configuration settings on a remote computer, use the Aspnet_regiis command-line tool. For information about creating and accessing custom configuration settings other than the intrinsic sections included in .NET, see . ## Examples The following code example demonstrates how to use the class to access configuration file elements. @@ -92,7 +88,6 @@ Note: If you use a static method that takes a path - Configuration Files @@ -178,7 +173,7 @@ Note: If you use a static method that takes a path @@ -466,17 +461,9 @@ Note: If you use a static method that takes a path property also returns `true` when the resource represented by this object inherits settings from a Web.config file. - The property returns `false` when this object represents a location-specific configuration. - - - -## Examples - The following code example demonstrates how to use the property. +The property returns `false` when this object represents a location-specific configuration. - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.Configuration/CS/Configuration.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.Configuration/VB/Configuration.vb" id="Snippet9"::: ]]> @@ -1138,7 +1125,7 @@ Note: If you use a static method that takes a path diff --git a/xml/System.Configuration/ConfigurationCollectionAttribute.xml b/xml/System.Configuration/ConfigurationCollectionAttribute.xml index ed516ef1090..2a8b3e2cd10 100644 --- a/xml/System.Configuration/ConfigurationCollectionAttribute.xml +++ b/xml/System.Configuration/ConfigurationCollectionAttribute.xml @@ -138,9 +138,8 @@ . diff --git a/xml/System.Configuration/ConfigurationElement.xml b/xml/System.Configuration/ConfigurationElement.xml index 29b15915036..e0079e66b66 100644 --- a/xml/System.Configuration/ConfigurationElement.xml +++ b/xml/System.Configuration/ConfigurationElement.xml @@ -36,52 +36,10 @@ is an abstract class that is used to represent an XML element in a configuration file (such as Web.config). An element in a configuration file can contain zero, one, or more child elements. - Because the class is defined as abstract, you cannot create an instance of it. You can only derive classes from it. The .NET Framework includes classes that derive from the class in order to represent standard XML configuration elements, such as . You can also extend the class to access custom configuration elements and sections. The example included later in this topic shows how to access custom configuration elements and sections by using custom classes that derive from . +Because the class is defined as abstract, you cannot create an instance of it. You can only derive classes from it. .NET includes classes that derive from the class to represent standard XML configuration elements, such as . You can also extend the class to access custom configuration elements and sections. The example included later in this topic shows how to access custom configuration elements and sections by using custom classes that derive from . - You can also extend the standard configuration types such as , , , and . For more information, see the documentation for those classes. - - For more information about how to access information in configuration files, see the class and the class. - - - -## Examples - The following code example shows how to implement a custom both as an individual element in a custom section and as a collection of elements in a custom section. The example consists of the following files: - -- An app.config file that contains a custom section that is named `MyUrls`. This section contains a simple element (it does not contain any other elements) and a collection of elements. The simple element is named `simple` and the collection is named `urls`. - -- A console application. The application reads the contents of the app.config file and writes the information to the console. It uses classes that derive from , , and . - -- A class named `UrlsSection` that derives from the class. This class is used to access the `MyUrls` section in the configuration file. - -- A class named `UrlsCollection` that derives from the class. This class is used to access the `urls` collection in the configuration file. - -- A class named `UrlConfigElement` that derives from the class. This class is used to access the `simple` element and the members of the `urls` collection in the configuration file. - - To run the example, perform the following steps: - -1. Create a solution that has a console application project and a class library project that is named `ConfigurationElement`. - -2. Put the three class files in the class library project and put the other files in the console library project. - -3. In both projects set a reference to `System.Configuration`. - -4. In the console application project set a project reference to the class library project. - - - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/CS/ConfigurationElement.cs" id="Snippet151"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/ConfigurationElement.vb" id="Snippet151"::: - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/CS/CustomSection.cs" id="Snippet71"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/CustomSection.vb" id="Snippet71"::: - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/CS/CustomElementCollection.cs" id="Snippet51"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/CustomElementCollection.vb" id="Snippet51"::: - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/CS/CustomElement.cs" id="Snippet31"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/CustomElement.vb" id="Snippet31"::: +You can also extend the standard configuration types such as , , , and . ]]> @@ -492,7 +450,7 @@ method and the method call this method in order to transform an assembly name when an earlier version of the .NET Framework is targeted. + The method and the method call this method in order to transform an assembly name when an earlier version of .NET is targeted. ]]> @@ -536,7 +494,7 @@ method and the method call this method in order to transform a type name when an earlier version of the .NET Framework is targeted. + The method and the method call this method in order to transform a type name when an earlier version of .NET is targeted. ]]> diff --git a/xml/System.Configuration/ConfigurationManager.xml b/xml/System.Configuration/ConfigurationManager.xml index 5deedbe4785..57b1f0547da 100644 --- a/xml/System.Configuration/ConfigurationManager.xml +++ b/xml/System.Configuration/ConfigurationManager.xml @@ -36,12 +36,7 @@ class enables you to access machine, application, and user configuration information. This class replaces the class, which is deprecated. For web applications, use the class. - - To use the class, your project must reference the `System.Configuration` assembly. By default, some project templates, like Console Application, do not reference this assembly so you must manually reference it. - -> [!NOTE] -> The name and location of the application configuration file depend on the application's host. For more information, see [Configuring Apps by using Configuration Files](/dotnet/framework/configure-apps/). + The class enables you to access machine, application, and user configuration information. You can use the built-in types or derive from them to handle configuration information. By using these types, you can work directly with configuration information and you can extend configuration files to include custom information. @@ -53,21 +48,15 @@ - Support configuration tasks. The following types are used to support various configuration tasks: - - - - - - - - - - - - - - + - + - + - + - + - + - + - - - - - - - - In addition to working with existing configuration information, you can create and work with custom configuration elements by extending the built-in configuration types such as the , , , and classes. For an example of how to extend a built-in configuration type programmatically, see . For an example of how to extend a built-in configuration type that uses the attribute-based model, see . + In addition to working with existing configuration information, you can create and work with custom configuration elements by extending the built-in configuration types such as the , , , and classes. For an example of how to extend a built-in configuration type programmatically, see . For an example of how to extend a built-in configuration type that uses the attribute-based model, see . ## Examples The first example shows a simple console application that reads application settings, adds a new setting, and updates an existing setting. @@ -282,24 +271,13 @@ End Module ]]> - The class enables programmatic access for editing configuration files. You use one of the Open methods provided by . These methods return a object, which in turn provides the required methods and properties to handle the underlying configuration files. You can access these files for reading or writing. - - To read the configuration files, use or . The user or process that reads must have the following permissions: - -- Read permission on the configuration file at the current configuration hierarchy level. - -- Read permissions on all the parent configuration files. - - If your application needs read-only access to its own configuration, we recommend that you use the method. This method provides access to the cached configuration values for the current application, which has better performance than the class. - - To write to the configuration files, use one of the methods. The user or process that writes must have the following permissions: + The class enables programmatic access for editing configuration files. You use one of the Open methods provided by . These methods return a object, which in turn provides the required methods and properties to handle the underlying configuration files. You can access these files for reading or writing. -- Write permission on the configuration file and directory at the current configuration hierarchy level. + To read the configuration files, use or . -- Read permissions on all the configuration files. + To write to the configuration files, use one of the methods. - Configuration Files @@ -644,11 +622,11 @@ End Module The method accesses run-time configuration information that it cannot change. To change the configuration, you use the method on the configuration file that you obtain by using one of the following methods: -- +- -- +- -- +- ## Examples The following example shows how to use the method. The example is part of a larger example that is provided for the class. @@ -830,12 +808,12 @@ Calling this method overload is equivalent to calling the [!NOTE] -> To obtain the object for a resource, your code must have read permissions on all the configuration files from which it inherits settings. To update a configuration file, your code must additionally have write permissions for both the configuration file and the directory in which it exists. It is not possible to access the Machine.config file for other versions of the .NET Framework that might be installed on the computer. +> To obtain the object for a resource, your code must have read permissions on all the configuration files from which it inherits settings. To update a configuration file, your code must additionally have write permissions for both the configuration file and the directory in which it exists. It's not possible to access the Machine.config file for other versions of .NET that might be installed on the computer. ## Examples The following code example shows how to use the method to obtain all sections that are contained in the configuration file. @@ -1011,12 +989,12 @@ Calling this method overload is equivalent to calling the [!NOTE] -> To obtain the object for a resource, your code must have read permissions on all the configuration files from which it inherits settings. To update a configuration file, your code must additionally have write permissions for both the configuration file and the directory in which it exists. It is not possible to access the Machine.config file for other versions of the .NET Framework that might be installed on the computer. +> To obtain the object for a resource, your code must have read permissions on all the configuration files from which it inherits settings. To update a configuration file, your code must additionally have write permissions for both the configuration file and the directory in which it exists. It's not possible to access the Machine.config file for other versions of .NET that might be installed on the computer. ## Examples The following code example shows how to use the method to obtain all sections in the configuration file. diff --git a/xml/System.Configuration/ConfigurationPermission.xml b/xml/System.Configuration/ConfigurationPermission.xml index 2a18a43e238..92e1b943c2c 100644 --- a/xml/System.Configuration/ConfigurationPermission.xml +++ b/xml/System.Configuration/ConfigurationPermission.xml @@ -48,8 +48,6 @@ [!INCLUDE[cas-deprecated](~/includes/cas-deprecated.md)] - The class provides a permission structure that allows methods or classes to access configuration files. Also, provides ways to resolve multiple permissions values through such methods as and . - ]]> @@ -214,14 +212,7 @@ The attribute for the given The object containing the permissions to perform the intersection with. Returns the logical intersection between the object and a given object that implements the interface. The logical intersection between the and a given object that implements . - - interface, an exception will be thrown if calling the method on the object referenced by the `target` parameter does not return . - - ]]> - + To be added. is not typed as . @@ -262,16 +253,7 @@ The attribute for the given object with an object implementing the interface. if the permission state is equal; otherwise, . - - interface, an exception will be thrown if calling the method on the object referenced by the `target` parameter does not return . - - If the object referenced by the `target` parameter is `null`, the comparison is done between the permission state of the object and the value of the enumeration. - - ]]> - + To be added. is not typed as . diff --git a/xml/System.Configuration/ConfigurationPermissionAttribute.xml b/xml/System.Configuration/ConfigurationPermissionAttribute.xml index 9c8142fa9d8..9f022f187ac 100644 --- a/xml/System.Configuration/ConfigurationPermissionAttribute.xml +++ b/xml/System.Configuration/ConfigurationPermissionAttribute.xml @@ -121,14 +121,7 @@ Creates and returns an object that implements the interface. An object that implements . - - object. - - ]]> - + To be added. diff --git a/xml/System.Configuration/ConfigurationProperty.xml b/xml/System.Configuration/ConfigurationProperty.xml index 695eb867522..018c1d832a4 100644 --- a/xml/System.Configuration/ConfigurationProperty.xml +++ b/xml/System.Configuration/ConfigurationProperty.xml @@ -568,7 +568,7 @@ System.Boolean - Indicates whether the assembly name for the configuration property requires transformation when it is serialized for an earlier version of the .NET Framework. + Indicates whether the assembly name for the configuration property requires transformation when it is serialized for an earlier version of .NET. if the property requires assembly name transformation; otherwise, . @@ -762,7 +762,7 @@ System.Boolean - Indicates whether the type name for the configuration property requires transformation when it is serialized for an earlier version of the .NET Framework. + Indicates whether the type name for the configuration property requires transformation when it is serialized for an earlier version of .NET. if the property requires type-name transformation; otherwise, . @@ -811,9 +811,10 @@ to set this property when you call a constructor that includes a parameter. +If you're creating a configuration property and the property value should not be serialized to XML when an earlier version of the framework is targeted, set this property to `true`. + +Use to set this property when you call a constructor that includes a parameter. ]]> diff --git a/xml/System.Configuration/ConfigurationSection.xml b/xml/System.Configuration/ConfigurationSection.xml index f6c6fb3b2ef..7e413864c15 100644 --- a/xml/System.Configuration/ConfigurationSection.xml +++ b/xml/System.Configuration/ConfigurationSection.xml @@ -40,9 +40,6 @@ A section registers its handling type with an entry in the `configSections` element. For an example, see the configuration file excerpt shown in the Example section. -> [!NOTE] -> In previous versions of the .NET Framework, configuration section handlers were used to make changes to configuration settings programmatically. Now, all the default configuration sections are represented by classes that extend the class. - ## Examples The following example shows how to implement a custom section programmatically. @@ -472,15 +469,15 @@ Note: If you use a static method that takes a The object that is a candidate for serialization. The name of the object as it occurs in XML. - The target version of the .NET Framework. - Indicates whether the specified element should be serialized when the configuration object hierarchy is serialized for the specified target version of the .NET Framework. + The target version of .NET. + Indicates whether the specified element should be serialized when the configuration object hierarchy is serialized for the specified target version of .NET. if the should be serialized; otherwise, . method that takes a The object that is a candidate for serialization. The name of the object as it occurs in XML. - The target version of the .NET Framework. + The target version of .NET. The parent element of the property. - Indicates whether the specified property should be serialized when the configuration object hierarchy is serialized for the specified target version of the .NET Framework. + Indicates whether the specified property should be serialized when the configuration object hierarchy is serialized for the specified target version of .NET. if the should be serialized; otherwise, . method that takes a - The target version of the .NET Framework. - Indicates whether the current instance should be serialized when the configuration object hierarchy is serialized for the specified target version of the .NET Framework. + The target version of .NET. + Indicates whether the current instance should be serialized when the configuration object hierarchy is serialized for the specified target version of .NET. if the current section should be serialized; otherwise, . Represents a group of related sections within a configuration file. - - class represents the `sectionGroup` XML element that is used to group sections when they are defined in the `configSections` element of a configuration file. Section groups can be nested (a section group can contain other section groups as well as sections). The following example shows a `configSections` element that defines three nested section groups: - -```xml - - - -
- -
-
-
- - - - -``` - - The configuration system loads settings from configuration files into objects. You can use the and properties to access the sections and section groups that are contained in a object. - - For more information about how to access information from configuration files, see the class. - - - -## Examples - The following example shows how to use the class to retrieve configuration settings. The example is a console application that reads configuration settings and writes information about each configuration section group and the sections in it to the console. - - The `Main` method loads the configuration settings into a object, retrieves the collection from the object, and then calls the `ShowSectionGroupCollectionInfo` method to display the section property values. - - The `ShowSectionGroupCollectionInfo` method iterates through the section groups and calls the `ShowSectionGroupInfo` method for each one. - - The `ShowSectionGroupInfo` method displays the name of the section group, some property values, and the names of the sections that it contains. If the section group contains section groups, this method calls `ShowSectionGroupCollectionInfo` recursively to display those section groups. - - The `indentLevel` field is used to add spaces to the left side of displayed lines to show logical groupings. All lines are limited to 79 characters of text to avoid line wrapping, which would make it harder to distinguish the logical groupings. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroup/CS/ConfigurationSectionGroup.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroup/VB/ConfigurationSectionGroup.vb" id="Snippet1"::: - - ]]> - + To be added. @@ -572,15 +530,15 @@ - The target version of the .NET Framework. - Indicates whether the current instance should be serialized when the configuration object hierarchy is serialized for the specified target version of the .NET Framework. + The target version of .NET. + Indicates whether the current instance should be serialized when the configuration object hierarchy is serialized for the specified target version of .NET. if the current section group should be serialized; otherwise, . - Provides runtime versions 1.0 and 1.1 support for reading configuration sections and common configuration settings. - - type to read configuration information at run time for version 1.0 and 1.1 applications. - -> [!NOTE] -> The class provides backward compatibility only. For new applications, use the class or class instead. To use these two classes, add a reference in your project to the `System.Configuration` namespace. - - ]]> - + Provides legacy support for reading configuration sections and common configuration settings. + To be added. diff --git a/xml/System.Configuration/ExeConfigurationFileMap.xml b/xml/System.Configuration/ExeConfigurationFileMap.xml index bfc22005f7a..1e62a5a4707 100644 --- a/xml/System.Configuration/ExeConfigurationFileMap.xml +++ b/xml/System.Configuration/ExeConfigurationFileMap.xml @@ -46,7 +46,6 @@ ]]> - Configuration Files @@ -122,11 +121,10 @@ - Configuration Files diff --git a/xml/System.Configuration/IApplicationSettingsProvider.xml b/xml/System.Configuration/IApplicationSettingsProvider.xml index 7cbeaa3d869..5dea9349eac 100644 --- a/xml/System.Configuration/IApplicationSettingsProvider.xml +++ b/xml/System.Configuration/IApplicationSettingsProvider.xml @@ -192,7 +192,8 @@ method, implemented in a class derived from . + +.NET enables side-by-side installation and execution of different versions of the same application. The application settings provider stores the application settings for each version of an application separately to ensure isolation. However, you may want to migrate settings from the previous version of an application to the current one. To provide this migration functionality, use the method, implemented in a class derived from . You can use the method in conjunction with the method to migrate application settings during or after the installation of a new version of an application. diff --git a/xml/System.Configuration/IConfigurationSectionHandler.xml b/xml/System.Configuration/IConfigurationSectionHandler.xml index 9c19027ff73..f68b41b72ce 100644 --- a/xml/System.Configuration/IConfigurationSectionHandler.xml +++ b/xml/System.Configuration/IConfigurationSectionHandler.xml @@ -37,7 +37,7 @@ ## Remarks > [!IMPORTANT] - > is deprecated starting in .NET Framework 2.0. In .NET Framework version 2.0 and later, you must instead derive from the class to implement the related configuration section handler. + > is deprecated. Instead, derive from the class to implement the related configuration section handler. Instances of the class must be thread safe and stateless. The method must be callable from multiple threads simultaneously. diff --git a/xml/System.Configuration/IdnElement.xml b/xml/System.Configuration/IdnElement.xml index 3096c7d438d..27693573a55 100644 --- a/xml/System.Configuration/IdnElement.xml +++ b/xml/System.Configuration/IdnElement.xml @@ -36,9 +36,8 @@ class has been extended to provide support for International Resource Identifiers (IRI) based on RFC 3987. Users upgrading from .NET Framework 2.0 won't see any change in behavior unless they specifically enable IRI. This ensures application compatibility with prior versions of .NET Framework. - The configuration setting for the is indirectly controlled by the configuration setting that controls IRI processing in the class. IRI processing must be enabled for IDN processing to be possible. If IRI processing is disabled, then IDN processing will be set to the default setting where the .NET Framework 2.0 behavior is used for compatibility and IDN names are not used. + The configuration setting for the is indirectly controlled by the configuration setting that controls IRI processing in the class. IRI processing must be enabled for IDN processing to be possible. If IRI processing is disabled, then IDN processing will be set to the default setting where IDN names are not used. The Internationalized Domain Name (IDN) attribute only controls IDN processing. All other IRI processing (character normalization, for example) is performed by default. @@ -133,7 +132,7 @@ ## Remarks The International Domain Name (IDN) attribute only controls IDN processing. All other International Resource Identifiers (IRI) processing (character normalization, for example) is performed by default. - The configuration setting for the is indirectly controlled by the configuration setting that controls IRI processing in the class. IRI processing must be enabled for IDN processing to be possible. If IRI processing is disabled, then IDN processing will be set to the default setting where the .NET Framework 2.0 behavior is used for compatibility and IDN names are not used. + The configuration setting for the is indirectly controlled by the configuration setting that controls IRI processing in the class. IRI processing must be enabled for IDN processing to be possible. If IRI processing is disabled, then IDN processing will be set to the default setting where IDN names are not used. The configuration setting for the will be read once when the first class is constructed. Changes to configuration settings after that time are ignored. diff --git a/xml/System.Configuration/IriParsingElement.xml b/xml/System.Configuration/IriParsingElement.xml index e2c211445d4..0ebef16101e 100644 --- a/xml/System.Configuration/IriParsingElement.xml +++ b/xml/System.Configuration/IriParsingElement.xml @@ -36,7 +36,6 @@ class has been extended to provide support for International Resource Identifiers (IRI) based on RFC 3987. Users upgrading from .NET Framework 2.0 won't see any change in behavior unless they specifically enable IRI. This ensures application compatibility with prior versions of the .NET Framework. The configuration setting for the will be read once when the first class is constructed. Changes to configuration settings after that time are ignored. @@ -127,7 +126,7 @@ configuration setting controls IRI processing in the class. This setting also indirectly controls International Domain Name (IDN) processing set with the class. IRI processing must be enabled for IDN processing to be possible. If IRI processing is disabled, then IDN processing will be set to the default setting where the .NET Framework 2.0 behavior is used for compatibility and IDN names are not used. + The configuration setting controls IRI processing in the class. This setting also indirectly controls International Domain Name (IDN) processing set with the class. IRI processing must be enabled for IDN processing to be possible. If IRI processing is disabled, then IDN processing will be set to the default setting where IDN names are not used. The configuration setting for the will be read once when the first class is constructed. Changes to configuration settings after that time are ignored. diff --git a/xml/System.Configuration/LocalFileSettingsProvider.xml b/xml/System.Configuration/LocalFileSettingsProvider.xml index c8680571eea..85750e7079b 100644 --- a/xml/System.Configuration/LocalFileSettingsProvider.xml +++ b/xml/System.Configuration/LocalFileSettingsProvider.xml @@ -40,7 +40,7 @@ , which stores configuration data to the local file system. An application settings property or group of properties are associated to a specific settings provider through the use of the . + Setting providers define a mechanism for storing configuration data used in the application settings architecture. .NET contains a single default settings provider, , which stores configuration data to the local file system. An application settings property or group of properties are associated to a specific settings provider through the use of the . Typically, the client program does not explicitly access this class; rather, the application settings architecture automatically invokes the appropriate settings provider when its services are required. For example, many of the members of delegate their work to the associated settings provider. diff --git a/xml/System.Configuration/ProtectedConfigurationProviderCollection.xml b/xml/System.Configuration/ProtectedConfigurationProviderCollection.xml index d8153a23acd..013e7c2403b 100644 --- a/xml/System.Configuration/ProtectedConfigurationProviderCollection.xml +++ b/xml/System.Configuration/ProtectedConfigurationProviderCollection.xml @@ -40,7 +40,7 @@ You can encrypt sections of a configuration file to protect sensitive information used by your application. This improves security by making unauthorized access difficult, even if an attacker gains access to your configuration file. - The .NET Framework includes two protected configuration providers that can be used to encrypt sections of a configuration file: the class, which uses the class to encrypt configuration sections, and the class, which uses the Windows Data Protection API (DPAPI) to encrypt configuration sections. +.NET includes two protected configuration providers that can be used to encrypt sections of a configuration file: the class, which uses the class to encrypt configuration sections, and the class, which uses the Windows Data Protection API (DPAPI) to encrypt configuration sections. You might have a requirement to encrypt sensitive information using an algorithm other than the RSA or DPAPI providers. In this case, you can build your own custom protected-configuration provider. The class is an abstract base class that you must inherit from to create your own protected-configuration provider. diff --git a/xml/System.Configuration/RsaProtectedConfigurationProvider.xml b/xml/System.Configuration/RsaProtectedConfigurationProvider.xml index 10bfcaa9d66..48222589316 100644 --- a/xml/System.Configuration/RsaProtectedConfigurationProvider.xml +++ b/xml/System.Configuration/RsaProtectedConfigurationProvider.xml @@ -35,58 +35,11 @@ class gives you a way to encrypt sensitive information stored in a configuration file, which helps protect it from unauthorized access. You use the built-in instance by declaring the provider and making appropriate settings in the configuration file instead of creating an instance of this class, as shown in the Examples section. - - The object uses the cryptography functions provided by class to encrypt and decrypt configuration sections. - -> [!NOTE] -> Before ASP.NET can decrypt encrypted information in your configuration file, the identity of your ASP.NET application must have read access to the encryption key used to encrypt and decrypt the configuration data. - > [!NOTE] -> On .NET Core and .NET 5+, the type is not supported. All APIs throw a at run time. - -## Examples - -The following example shows how to use the standard to protect or unprotect a configuration section. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.RsaProtectedConfigurationProvider/CS/RsaProtectedConfigurationProvider.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.RsaProtectedConfigurationProvider/VB/RsaProtectedConfigurationProvider.vb" id="Snippet1"::: - - The following example shows an excerpt from a configuration file after encryption. - -```xml - - - - - - - - - - Rsa Key - - - B702tRDVHJjC3CYXt7I0ucCDjdht/Vyk/DdUhwQyt7vepSD85dwCP8ox9Y1BUdjajFeTFfFBsGypbli5HPGRYamQdrVkPo07bBBXNT5H02qxREguGUU4iDtV1Xp8BLVZjQMV4ZgP6Wbctw2xRvPC7GvKHLI4fUN/Je5LmutsijA= - - - - - ME+XJA2TAj3QN3yT4pJq3sRArC0i7Cz3Da71BkaRe9QNfuVuUjcv0jeGUN4wDdOAZ7LPq6UpVrpirY3kQcALDvPJ5nKxk++Mw75rjtIO8eh2goTY9rCK6zanfzaDshFy7IqItpvs/y2kmij25nM3ury6uO0hCf0UbEL1mbT2jXDqvcrHZUobO1Ef6bygBZ/8HpU+VfF9CTCob/BBE9zUkK37EQhcduwsnzBvDblYbF/Rd+F4lxAkZnecGLfCZjOzJB4xH1a0vvWtPR7zNwL/7I0uHzQjyMdWrkBnotMjoR70R7NELBotCogWO0MBimncKigdR3dTTdrCd72a7UJ4LMlEQaZXGIJp4PIg6qVDHII= - - - - -``` +> The type is not supported. All APIs throw a at run time. ]]> - - - - Cryptographic Services @@ -116,14 +69,7 @@ The following example shows how to use the standard Initializes a new instance of the class. - - constructor is not intended to be used directly from your code. It is called by the ASP.NET configuration system. - - ]]> - + To be added. diff --git a/xml/System.Configuration/SchemeSettingElement.xml b/xml/System.Configuration/SchemeSettingElement.xml index 29263d686d0..5bb2614a389 100644 --- a/xml/System.Configuration/SchemeSettingElement.xml +++ b/xml/System.Configuration/SchemeSettingElement.xml @@ -46,7 +46,6 @@ - Network Settings Schema @@ -132,7 +131,6 @@ - Network Settings Schema @@ -186,7 +184,6 @@ - Network Settings Schema diff --git a/xml/System.Configuration/SchemeSettingElementCollection.xml b/xml/System.Configuration/SchemeSettingElementCollection.xml index 2e35ddce74f..27e05b2f9ef 100644 --- a/xml/System.Configuration/SchemeSettingElementCollection.xml +++ b/xml/System.Configuration/SchemeSettingElementCollection.xml @@ -66,7 +66,6 @@ - Network Settings Schema diff --git a/xml/System.Configuration/SectionInformation.xml b/xml/System.Configuration/SectionInformation.xml index 987a1eaf29e..0a5a87d30b3 100644 --- a/xml/System.Configuration/SectionInformation.xml +++ b/xml/System.Configuration/SectionInformation.xml @@ -337,19 +337,13 @@ A implementation can optionally specify a separate file in which the configuration settings for that section are defined. This can be useful in multiple ways: - Using include files can result in a more logical and modular structure for configuration files. - - File-access security and permissions can be used to restrict access to sections of configuration settings. - - Settings in an include file that are not used during application initialization can be modified and reloaded without requiring an application restart. The following example shows how this attribute is used in a configuration file to specify that the `pages` section is defined in an external include file: `` - If any of the settings in a configuration include file require the application to restart when they are modified, set the property to `true`. - - In ASP.NET applications, at run time you can assign to the property the name of an alternative configuration file. In that case, the contents of the file are overwritten by the default connection string information that is contained in the Web.config file. This occurs also when the alternative file does not exist and it is created at run time. If the Web.config file does not contain any connection string information, an empty section is added to the alternative file. - ]]> @@ -1223,53 +1217,9 @@ The following example shows how to get the is set to `true`, the `GetSection` methods are restricted by the trust level setting of the application. This means that methods or properties that allow access to configuration section handlers are restricted by the trust level set for the Web application. > [!NOTE] -> Because high and full trust are the only levels that allow access to files outside the current application domain, an application can use configuration section handlers only at these trust levels. - - When is set to `false`, the access to the configuration data is not restricted by the application's trust level settings. - -> [!NOTE] -> The appropriate file ACL (Access Control List) permissions are still required, regardless of the setting. ACL permissions determine who can access the configuration file. - - - -## Examples - The following example shows two possible trust levels for a Web application when the property of the `appSettings` section is `true`. - -```xml - - // With the following trust value - // the code below works. - - - - - // With the following trust value - // the code below does not work. - - -``` - - The following example shows code that runs without errors when the trust level is set to full. Otherwise, the code results in an error. - -```csharp -AppSettingsSection apSection = - ConfigurationManager.GetSection("appSettings") as AppSettingsSection; - -NameValueCollection apSectionCollection = - ConfigurationManager.AppSettings; -``` - -```vb -Dim apSection As AppSettingsSection = _ - TryCast(ConfigurationManager.GetSection("appSettings"), - AppSettingsSection) - - Dim apSectionCollection As NameValueCollection = _ - ConfigurationManager.AppSettings -``` +> The appropriate file ACL (Access Control List) permissions are still required, regardless of the setting. ACL permissions determine who can access the configuration file. ]]> diff --git a/xml/System.Configuration/SettingsProvider.xml b/xml/System.Configuration/SettingsProvider.xml index 6fbbe8d6b5b..57178ebb688 100644 --- a/xml/System.Configuration/SettingsProvider.xml +++ b/xml/System.Configuration/SettingsProvider.xml @@ -36,21 +36,19 @@ , which stores configuration data to the local file system. However, you can create alternate storage mechanisms by deriving from the abstract class. The provider that a wrapper class uses is determined by decorating the wrapper class with the . If this attribute is not provided, the default, , is used. + A settings provider defines the mechanism for storing configuration data used in the application settings architecture. .NET contains a single default settings provider, , which stores configuration data to the local file system. However, you can create alternate storage mechanisms by deriving from the abstract class. The provider that a wrapper class uses is determined by decorating the wrapper class with the . If this attribute is not provided, the default, , is used. When you create a custom settings provider, at minimum, you must provide implementations for the three methods of this class: , and . For client applications, you can add more standardized functionality to a custom provider by also implementing the interface. This interface mirrors methods found in the class, which mainly enables versioning support. - Typically, you should design settings providers to be single-instanced to avoid storage resource contention. Providers should also be thread-safe because they can be called simultaneously from multiple wrapper instances in a single application domain or from multiple applications in different domains. + Typically, you should design settings providers to be single-instanced to avoid storage resource contention. Providers should also be thread-safe because they can be called simultaneously from multiple wrapper instances or from multiple applications. At minimum, a settings provider must recognize three attributes - , , and . For a full listing of attributes that can be applied to application settings, see [Application Settings Attributes](/dotnet/desktop/winforms/advanced/application-settings-attributes). A custom setting provider should resolve attributes applied to settings properties in the following manner: -1. If the provider can fulfill the request implied by the attribute, obviously it should do so. - -2. If the provider cannot fulfill the request, it should ignore it silently. - -3. If two or more properties conflict; for example, a property being decorated with both and ; the provider should throw a . +1. If the provider can fulfill the request implied by the attribute, obviously it should do so. +2. If the provider cannot fulfill the request, it should ignore it silently. +3. If two or more properties conflict; for example, a property being decorated with both and ; the provider should throw a . ]]> @@ -98,9 +96,9 @@ Client code typically does not directly instantiate a settings provider; instead, you use the following procedure to find a settings provider for a particular settings property: -1. Call the method on the current or to return a reference to the current . +1. Call the method on the current or to return a reference to the current . -2. Call the method of the retrieved in the first step to return the settings provider. +2. Call the method of the retrieved in the first step to return the settings provider. ]]> @@ -242,12 +240,6 @@ ## Remarks contains the method, which is called to persist the values of all of its settings properties. This method enumerates through all the settings providers associated with its settings properties, and calls the method for each to perform the actual serialization operation. - The method should be implemented with security in mind: - -- Only fully trusted code should be allowed to update application settings. Partially trusted code should be allowed to update only user application settings. Untrusted code is not typically allowed to update application settings. - -- Usage quotas should be considered to guard against resource attacks by partially trusted applications. - ]]> diff --git a/xml/System.Configuration/SettingsSerializeAsAttribute.xml b/xml/System.Configuration/SettingsSerializeAsAttribute.xml index 49f5baad2ab..221734bd45a 100644 --- a/xml/System.Configuration/SettingsSerializeAsAttribute.xml +++ b/xml/System.Configuration/SettingsSerializeAsAttribute.xml @@ -42,7 +42,7 @@ enumeration, and include plain text, XML, and binary serialization. In addition, a provider may optionally support a custom serialization scheme. + A settings provider often supports more than one of the standard .NET serialization schemes. These schemes are outlined by the enumeration, and include plain text, XML, and binary serialization. In addition, a provider may optionally support a custom serialization scheme. With the , you can specify which serialization mechanism should be used for a given application settings class or property. This attribute is considered a request to the settings provider. It may be ignored or cause an error if the provider or the individual property type does not support the specified serialization scheme. If this attribute is not present, the provider will usually provide a default serialization mechanism, most commonly plain text. diff --git a/xml/System.Configuration/UriSection.xml b/xml/System.Configuration/UriSection.xml index a35db088c77..0beb82652e1 100644 --- a/xml/System.Configuration/UriSection.xml +++ b/xml/System.Configuration/UriSection.xml @@ -37,13 +37,11 @@ class has been extended to provide support for International Resource Identifiers (IRI) and Internationalized Domain Names. Users upgrading from .NET Framework 2.0 won't see any change in behavior unless they specifically enable IRI and IDN. This ensures application compatibility with prior versions of the .NET Framework. - The configuration settings for IRI and IDN can be retrieved using the class. +The configuration settings for IRI and IDN can be retrieved using the class. ]]> - Network Settings Schema @@ -77,7 +75,6 @@ class has been extended to provide support for International Resource Identifiers (IRI) and Internationalized Domain Names. Users upgrading from .NET Framework 2.0 won't see any change in behavior unless they specifically enable IRI and IDN. This ensures application compatibility with prior versions of the .NET Framework. The configuration settings for IRI and IDN can be retrieved using the class. @@ -128,11 +125,10 @@ class has been extended to provide support for International Resource Identifiers (IRI) and Internationalized Domain Names. Users upgrading from .NET Framework 2.0 won't see any change in behavior unless they specifically enable IRI and IDN. This ensures application compatibility with prior versions of the .NET Framework. The configuration settings for IRI and IDN can be retrieved using the class. The property returns the configuration setting for IDN processing in the class. - IRI processing must be enabled for IDN processing to be possible. If IRI processing is disabled, then IDN processing will be set to the default setting where the .NET Framework 2.0 behavior is used for compatibility and IDN names are not used. + IRI processing must be enabled for IDN processing to be possible. If IRI processing is disabled, then IDN processing will be set to the default setting where IDN names are not used. The Internationalized Domain Name (IDN) attribute only controls IDN processing. All other IRI processing (character normalization, for example) is performed by default. @@ -145,7 +141,6 @@ - Network Settings Schema @@ -189,11 +184,10 @@ class has been extended to provide support for International Resource Identifiers (IRI) and Internationalized Domain Names. Users upgrading from .NET Framework 2.0 won't see any change in behavior unless they specifically enable IRI and IDN. This ensures application compatibility with prior versions of the .NET Framework. The configuration settings for IRI and IDN can be retrieved using the class. The property returns the configuration setting for IRI parsing in the class. - IRI processing must be enabled for IDN processing to be possible. If IRI processing is disabled, then IDN processing will be set to the default setting where the .NET Framework 2.0 behavior is used for compatibility and IDN names are not used. + IRI processing must be enabled for IDN processing to be possible. If IRI processing is disabled, then IDN processing will be set to the default setting where IDN names are not used. The Internationalized Domain Name (IDN) attribute only controls IDN processing. All other IRI processing (character normalization, for example) is performed by default. @@ -206,7 +200,6 @@ - Network Settings Schema @@ -293,7 +286,6 @@ - Network Settings Schema diff --git a/xml/System.Diagnostics.Contracts/Contract.xml b/xml/System.Diagnostics.Contracts/Contract.xml index 0a14e7c567a..f9167cef0c9 100644 --- a/xml/System.Diagnostics.Contracts/Contract.xml +++ b/xml/System.Diagnostics.Contracts/Contract.xml @@ -409,7 +409,7 @@ ## Remarks The event information for this event is supplied by the object that is passed to the event handler. This event notifies a managed application environment such as an interactive interpreter or a Web browser host that a contract has failed. Before doing so, it will raise an event that an application can handle as it sees fit. For example, if code is being run in a testing framework, you can log a test failure and then end the test. - The default implementation of the method in the .NET Framework class library is to call each handler that is registered with the event. Exceptions thrown by handlers are ignored, but each handler can indicate whether the failure is handled by calling the method for the event arguments. If any handler sets the failure as handled, the method returns `null` and no further action is taken. Alternatively, handlers can call the method to instruct the code to unwind. In that case, an exception is thrown after all handlers have executed. + The default implementation of the method is to call each handler that is registered with the event. Exceptions thrown by handlers are ignored, but each handler can indicate whether the failure is handled by calling the method for the event arguments. If any handler sets the failure as handled, the method returns `null` and no further action is taken. Alternatively, handlers can call the method to instruct the code to unwind. In that case, an exception is thrown after all handlers have executed. ]]> diff --git a/xml/System.Diagnostics.Contracts/ContractFailedEventArgs.xml b/xml/System.Diagnostics.Contracts/ContractFailedEventArgs.xml index 6909de5d01e..e2ae606fa9e 100644 --- a/xml/System.Diagnostics.Contracts/ContractFailedEventArgs.xml +++ b/xml/System.Diagnostics.Contracts/ContractFailedEventArgs.xml @@ -53,7 +53,7 @@ object is passed to the event when a contract fails. The event enables a managed application environment such as an interactive interpreter, a Web browser host, a test harness, or a logging infrastructure to be notified of contract failures. The event requires full trust. + A object is passed to the event when a contract fails. The event enables a managed application environment such as an interactive interpreter, a Web browser host, a test harness, or a logging infrastructure to be notified of contract failures. ]]> diff --git a/xml/System.Diagnostics.PerformanceData/CounterData.xml b/xml/System.Diagnostics.PerformanceData/CounterData.xml index 11eb3056db1..5b2bae231fa 100644 --- a/xml/System.Diagnostics.PerformanceData/CounterData.xml +++ b/xml/System.Diagnostics.PerformanceData/CounterData.xml @@ -255,14 +255,9 @@ ## Remarks This property provides safe access to the counter data for multi-threaded applications. If performance is of primary concern, use the property; however, the property is not thread safe. - Note that the property is not thread safe in .NET Framework 3.5. - To increment the counter value, consider using the or method. - - -## Examples - For an example, see . +For an example, see . ]]> diff --git a/xml/System.Diagnostics.Tracing/EventListener.xml b/xml/System.Diagnostics.Tracing/EventListener.xml index f44784e07ca..8b4329fab5a 100644 --- a/xml/System.Diagnostics.Tracing/EventListener.xml +++ b/xml/System.Diagnostics.Tracing/EventListener.xml @@ -61,16 +61,16 @@ object) implementations in the current application domain. When a new event listener is created, it is logically attached to all event sources in that application domain. + An event listener represents the target for all events generated by event source ( object) implementations. When a new event listener is created, it is logically attached to all event sources. > [!NOTE] -> This type implements the interface. When you have finished using the type, you must dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you have finished using the type, you must dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` in C#. An event listener can enable or disable on a per-current event source basis by using event levels () and event keywords () to further restrict the set of events to be sent to the listener. The listener can also send arbitrary commands to a specific current event source by using the method. The meanings of the commands are specific to the implementation of the event source. - Multiple event listeners can be defined in a single application domain. Each listener is logically independent of the other listeners so that events that are enabled or disabled by one listener affect only that listener. It is possible for commands sent with the method to do a semantic operation (such as a garbage collection or flushing data) that affects the other listeners, but this is the exception rather than the rule. + Multiple event listeners can be defined. Each listener is logically independent of the other listeners so that events that are enabled or disabled by one listener affect only that listener. It is possible for commands sent with the method to do a semantic operation (such as a garbage collection or flushing data) that affects the other listeners, but this is the exception rather than the rule. - Each event source keeps a list of event listeners that it sends events to. A set of filtering criteria is associated with each event source-listener pair. These criteria determine the events that listener will receive for the current event source. Listeners receive the events on their method. Therefore, subclasses of must override this method to do something useful with the data. + Each event source keeps a list of event listeners that it sends events to. A set of filtering criteria is associated with each event source-listener pair. These criteria determine the events that listener will receive for the current event source. Listeners receive the events on their method. Therefore, subclasses of must override this method to do something useful with the data. When a new event source is created, the method is called. Every current event listener gets exactly one call for every current event source that can send it log messages. When an event listener is created, a series of calls are made to notify the new listener of all the event sources that existed before the listener was created. @@ -489,7 +489,7 @@ identifies an event source that is suitable for indexing an array. This integer is unique within the application domain. An event listener might find it useful to store additional information about each event source that is connected to it. The value returned by allows this extra information to be efficiently stored in an expandable array such as `List`. + The value returned by identifies an event source that is suitable for indexing an array. An event listener might find it useful to store additional information about each event source that is connected to it. The value returned by allows this extra information to be efficiently stored in an expandable array such as `List`. ]]> diff --git a/xml/System.Diagnostics.Tracing/EventWrittenEventArgs.xml b/xml/System.Diagnostics.Tracing/EventWrittenEventArgs.xml index e42588c70e8..818b48b7dce 100644 --- a/xml/System.Diagnostics.Tracing/EventWrittenEventArgs.xml +++ b/xml/System.Diagnostics.Tracing/EventWrittenEventArgs.xml @@ -469,7 +469,7 @@ System.Int64 - Gets the thread identifier for the OS thread that wrote the event. (.NET Core 2.2 and later only.) + Gets the thread identifier for the OS thread that wrote the event. The thread identifier for the OS thread that wrote the event. To be added. @@ -723,7 +723,7 @@ System.DateTime - Gets the time that the event was originally generated as a timestamp. (.NET Core 2.2 and later only.) + Gets the time that the event was originally generated as a timestamp. The date and time when the event was logged. The system tries to be as precise as possible. To be added. diff --git a/xml/System.Diagnostics/BooleanSwitch.xml b/xml/System.Diagnostics/BooleanSwitch.xml index e79a9d83eaf..dcea3c2b319 100644 --- a/xml/System.Diagnostics/BooleanSwitch.xml +++ b/xml/System.Diagnostics/BooleanSwitch.xml @@ -64,40 +64,17 @@ You can create a in your code and set the property directly to instrument a specific section of code. -For .NET Framework apps only, you can also enable or disable a through the application configuration file and then use the configured value in your application. To configure a , edit the configuration file that corresponds to the name of your application. Within this file, you can add or remove a switch, set a switch's value, or clear all the switches previously set by the application. The configuration file should be formatted like the following example. +The property of the new switch is set to `false` by default. -```xml - - - - - - - -``` - - This example configuration section defines a with the property set to `mySwitch` and the value set to `true`. Within your .NET Framework application, you can use the configured switch value by creating a with the same name, as shown in the following code example. - - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/BooleanSwitch/Overview/remarks.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/BooleanSwitch/Overview/remarks.vb" id="Snippet2"::: - -For .NET Core and .NET 5+ apps, the property of the new switch is set to `false` by default. - -For .NET Framework apps, the property is set using the value specified in the configuration file. Configure the switch with a value of 0 to set the property to `false`; configure the switch with a nonzero value to set the property to `true`. If the constructor cannot find initial switch settings in the configuration file, the property of the new switch is set to `false`. - - You must enable tracing or debugging to use a switch. The following syntax is compiler specific. If you use compilers other than C# or Visual Basic, refer to the documentation for your compiler. - -- To enable debugging in C#, add the `/d:DEBUG` flag to the compiler command line when you compile your code, or you can add `#define DEBUG` to the top of your file. In Visual Basic, add the `/d:DEBUG=True` flag to the compiler command line. - -- 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. + You must enable tracing or debugging to use a switch. > [!NOTE] -> These debug and trace compiler switches are not required when using the class in isolation. They are only required in conjunction with or methods that are conditionally compiled. +> These debug and trace compiler switches are not required when using the class in isolation. They are only required in conjunction with or methods that are conditionally compiled. - For more information on instrumenting your application, see and . For more information about configuring and using trace switches, see [Trace Switches](/dotnet/framework/debug-trace-profile/trace-switches). + For more information on instrumenting your application, see and > [!NOTE] -> To improve performance, you can make members `static` in your class. +> To improve performance, you can make members `static` in your class. ## Examples The following example creates a and uses the switch to determine whether to print an error message. You create the switch at the class level. The `Main` method passes its location to `MyMethod`, which prints an error message and where the error occurred. @@ -177,25 +154,7 @@ For .NET Framework apps, the pro , the `displayName` parameter is used to find the initial switch settings for .NET Framework apps in the application configuration file. If the constructor cannot find initial settings, or for .NET Core and .NET 5+ apps, the property is set to `false` (disabled). - - To set the level of your in a .NET Framework app, edit the configuration file corresponding to the name of your application. Within this file, you can add a switch and set its value, remove a switch, or clear all switches previously set by the application. The configuration file should be formatted like the following example: - -```xml - - - - - - - - - - -``` - -> [!NOTE] -> The switches you created should be `static`. + When you create a , the property is set to `false` (disabled). ## Examples The following example creates a and uses the switch to determine whether to print an error message. The switch is created at the class level. The `Main` method passes its location to `MyMethod`, which prints an error message and where the error occurred. diff --git a/xml/System.Diagnostics/ConsoleTraceListener.xml b/xml/System.Diagnostics/ConsoleTraceListener.xml index 4a880da2ff9..a539d5b9ac0 100644 --- a/xml/System.Diagnostics/ConsoleTraceListener.xml +++ b/xml/System.Diagnostics/ConsoleTraceListener.xml @@ -35,7 +35,7 @@ Use the class to write trace and debugging messages to the console. You can initialize a object to write trace messages to the stream or to the stream. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a`try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a`try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` in C#. When trace and debugging output is enabled, the messages are written to the specified stream, which is similar to the way messages are written with the or methods. In a console application, the output and error streams write messages to the existing console window, or you can redirect the streams to write to a instance. @@ -47,32 +47,10 @@ > [!NOTE] > The and classes share the same collection, accessed through their respective `Listeners` properties. If you add a object to the collection using one of these classes, the other class automatically uses the same listener. - Most compilers enable trace and debug output through conditional compilation flags. If you do not enable tracing or debugging, the messages written through the and classes are effectively ignored. The syntax to enable trace and debug output is compiler specific; if you use compilers other than C# or Visual Basic, refer to the documentation for your compiler. - -- To enable debugging in C#, add the **/d:DEBUG**flag to the compiler command line when you compile your code, or you can add **#define DEBUG** to the top of your file. In Visual Basic, add the **/d:DEBUG=True** flag to the compiler command line. - -- 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. - - You can add a object to the collection in your code. Or, for .NET Framework apps, you can add a object to the collection through the application configuration file. Add the object in your code to write messages for a specific code section or execution path. Add the object in your application configuration file to direct all trace and debug messages to the console while the application executes. + Most compilers enable trace and debug output through conditional compilation flags. If you do not enable tracing or debugging, the messages written through the and classes are effectively ignored. To write trace and debug messages to the console for a specific section of code, initialize a object and add it to the collection. Instrument the section of code that contains messages using the or classes. At the end of the code section, remove the object from the collection, and call the method on the . -For .NET Framework apps, to direct all trace and debug messages to the console while the application executes, add a object to the application configuration file. The following example adds a object named `configConsoleListener` to the collection. - -```xml - - - - - - - - - -``` - - For details about adding trace listeners in the application configuration file, see [\](/dotnet/framework/configure-apps/file-schema/trace-debug/listeners-element-for-trace). - ## Examples The following code example implements a console application consisting of a class with two public methods. diff --git a/xml/System.Diagnostics/Debug.xml b/xml/System.Diagnostics/Debug.xml index 145341facbe..a08d66a28fb 100644 --- a/xml/System.Diagnostics/Debug.xml +++ b/xml/System.Diagnostics/Debug.xml @@ -77,7 +77,7 @@ To make your code more robust without impacting the performance and code size of - - - The and classes provide means to dynamically control the tracing output. For .NET Framework apps, you can modify the values of these switches without recompiling your application. For information on using the configuration file to set a switch in .NET Framework apps, see the class and the [Trace Switches](/dotnet/framework/debug-trace-profile/trace-switches) article. + The and classes provide means to dynamically control the tracing output. You can customize the tracing output's target by adding instances to or removing instances from the collection. The collection is shared by both the and the classes; adding a trace listener to either class adds the listener to both. By default, the class emits trace output. @@ -86,16 +86,6 @@ To make your code more robust without impacting the performance and code size of You can modify the level of indentation using the method or the property. To modify the indent spacing, use the property. You can specify whether to automatically flush the output buffer after each write by setting the property to `true`. -For .NET Framework apps, you can set the and for by editing your app's configuration file. The configuration file should be formatted as shown in the following example. - -```xml - - - - - -``` - The attribute is applied to the methods of . Compilers that support ignore calls to these methods unless `DEBUG` is defined as a conditional compilation symbol. Refer to a compiler's documentation to determine whether is supported and the syntax for defining a conditional compilation symbol. > [!NOTE] @@ -211,20 +201,7 @@ The following example uses to indicate the begin When the application runs in user interface mode, it displays a message box that shows the call stack with file and line numbers. The message box contains three buttons: **Abort**, **Retry**, and **Ignore**. Clicking the **Abort** button terminates the application. Clicking **Retry** sends you to the code in the debugger if your application is running in a debugger, or offers to open a debugger if it is not. Clicking **Ignore** continues with the next instruction in the code. > [!NOTE] -> Windows 8.x apps do not support modal dialog boxes, so they behave the same in user interface mode and non-user interface mode. The message is written to the active trace listeners in debugging mode, or no message is written in release mode. - -> [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. - -For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: - -```xml - - - - - -``` +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). ## Examples @@ -313,17 +290,8 @@ This overload was introduced in .NET 6 to improve performance. In comparison to When the application runs in user interface mode, it displays a message box that shows the call stack with file and line numbers. The message box contains three buttons: **Abort**, **Retry**, and **Ignore**. Clicking the **Abort** button terminates the application. Clicking **Retry** sends you to the code in the debugger if your application is running in a debugger, or offers to open a debugger if it is not. Clicking **Ignore** continues with the next instruction in the code. > [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). -For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: - -```xml - - - - - -``` ]]> @@ -419,17 +387,7 @@ For .NET Framework apps, you can change the behavior of the [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. - -For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: - -```xml - - - - - -``` +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). ## Examples @@ -527,17 +485,8 @@ This overload was introduced in .NET 6 to improve performance. In comparison to When the application runs in user interface mode, it displays a message box that shows the call stack with file and line numbers. The message box contains three buttons: **Abort**, **Retry**, and **Ignore**. Clicking the **Abort** button terminates the application. Clicking **Retry** sends you to the code in the debugger if your application is running in a debugger, or offers to open a debugger if it is not. Clicking **Ignore** continues with the next instruction in the code. > [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. - -For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). -```xml - - - - - -``` ]]> @@ -625,17 +574,7 @@ For .NET Framework apps, you can change the behavior of the [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. - -For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: - -```xml - - - - - -``` +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). ## Examples @@ -758,17 +697,7 @@ The following example checks whether the `type` parameter is valid. If `type` is When the application runs in user interface mode, it displays a message box that shows the call stack with file and line numbers. The message box contains three buttons: **Abort**, **Retry**, and **Ignore**. Clicking the **Abort** button terminates the application. Clicking **Retry** sends you to the code in the debugger if your application is running in a debugger, or offers to open a debugger if it is not. Clicking **Ignore** continues with the next instruction in the code. > [!NOTE] -> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. - -For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: - -```xml - - - - - -``` +> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). ]]> @@ -825,16 +754,6 @@ For .NET Framework apps, you can change the behavior of the or . Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. -For .NET Framework apps, you can also set the and properties for by editing the configuration file corresponding to the name of your application. The configuration file should be formatted as shown in the following example. - -```xml - - - - - -``` - ]]> @@ -996,12 +915,10 @@ The following example creates a outputs the message to a message box when the application is running in user interface mode and to the instances in the collection. > [!NOTE] -> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace), the [<remove>](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). +> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). You can customize this behavior by adding a to, or removing one from, the collection. - - ## Examples The following example uses the method to print a message during exception handling. @@ -1092,12 +1009,10 @@ The following example uses the method to p The default behavior is that the outputs the message to a message box when the application is running in user interface mode and to the instances in the collection. > [!NOTE] -> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace), the [<remove>](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). +> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). You can customize this behavior by adding a to, or removing one from, the collection. - - ## Examples The following example uses the method to print a message during exception handling. @@ -1397,16 +1312,6 @@ End of list of errors ## Remarks A interprets this number as spaces. An ignores this value. -For .NET Framework apps, you can also set the and properties for by editing the configuration file corresponding to the name of your application. The configuration file should be formatted as shown in the following example. - -```xml - - - - - -``` - ]]> diff --git a/xml/System.Diagnostics/DebuggableAttribute+DebuggingModes.xml b/xml/System.Diagnostics/DebuggableAttribute+DebuggingModes.xml index 082c2a6af74..24308f1a122 100644 --- a/xml/System.Diagnostics/DebuggableAttribute+DebuggingModes.xml +++ b/xml/System.Diagnostics/DebuggableAttribute+DebuggingModes.xml @@ -54,23 +54,23 @@ Specifies the debugging mode for the just-in-time (JIT) compiler. - enumeration specifies how the runtime is to track information important to the debugger during code generation. This information helps the debugger provide a rich debugging experience. Unlike the .NET Framework version 1.1, versions 2.0 or later do not allow you to turn off tracking by the just-in-time (JIT) compiler. JIT tracking is always enabled for debuggable files. In version 2.0 and later, the enumeration values have the following effect. - -|Debugging mode|Result| -|--------------------|------------| -|None|Tracking on, JIT optimizations enabled| -|Default|Tracking on, JIT optimizations enabled| -|DisableOptimizations|Tracking on, JIT optimizations enabled| -|Default | DisableOptimizations|Tracking on, JIT optimizations disabled| - - Sequence points are used to indicate locations in the Microsoft intermediate language (MSIL) code that a debugger user expects to be able to refer to uniquely, such as for setting a breakpoint. The JIT compiler ensures it does not compile the MSIL at two different sequence points into a single native instruction. By default, the JIT compiler examines the symbol store in the program database (PDB) file for a list of additional sequence points. However, loading the PDB file requires that the file be available and has a negative performance impact. Starting with version 2.0, compilers can emit "implicit sequence points" in the MSIL code stream through the use of MSIL "`nop"` instructions. Such compilers should set the `IgnoreSymbolStoreSequencePoints` flag to notify the common language runtime to not load the PDB file. - + enumeration specifies how the runtime is to track information important to the debugger during code generation. This information helps the debugger provide a rich debugging experience. You can't turn off tracking by the just-in-time (JIT) compiler. JIT tracking is always enabled for debuggable files. The enumeration values have the following effects: + +| Debugging mode | Result | +|---------------------------------------|-----------------------------------------| +| `None` | Tracking on, JIT optimizations enabled | +| `Default` | Tracking on, JIT optimizations enabled | +| `DisableOptimizations` | Tracking on, JIT optimizations enabled | +| `Default | DisableOptimizations` | Tracking on, JIT optimizations disabled | + + Sequence points are used to indicate locations in the Microsoft intermediate language (MSIL) code that a debugger user expects to be able to refer to uniquely, such as for setting a breakpoint. The JIT compiler ensures it does not compile the MSIL at two different sequence points into a single native instruction. By default, the JIT compiler examines the symbol store in the program database (PDB) file for a list of additional sequence points. However, loading the PDB file requires that the file be available and has a negative performance impact. Starting with version 2.0, compilers can emit "implicit sequence points" in the MSIL code stream through the use of MSIL "`nop"` instructions. Such compilers should set the `IgnoreSymbolStoreSequencePoints` flag to notify the common language runtime to not load the PDB file. + > [!NOTE] -> This enumeration is primarily used by language developers. It is generally not used in application development. Development environments use based on compiler parameters such as **/debug** and **/optimize**. - +> This enumeration is primarily used by language developers. It is generally not used in application development. Development environments use based on compiler parameters such as **/debug** and **/optimize**. + ]]> @@ -113,7 +113,7 @@ 1 - Instructs the just-in-time (JIT) compiler to use its default behavior, which includes enabling optimizations, disabling Edit and Continue support, and using symbol store sequence points if present. Starting with the .NET Framework version 2.0, JIT tracking information, the Microsoft intermediate language (MSIL) offset to the native-code offset within a method, is always generated. + Instructs the just-in-time (JIT) compiler to use its default behavior, which includes enabling optimizations, disabling Edit and Continue support, and using symbol store sequence points if present. JIT tracking information is always generated. @@ -277,9 +277,9 @@ 0 - Starting with the .NET Framework version 2.0, JIT tracking information is always generated, and this flag has the same effect as , except that it sets the property to . However, because JIT tracking is always enabled, the property value is ignored in version 2.0 or later. - - Note that, unlike the flag, the flag cannot be used to disable JIT optimizations. + JIT tracking information is always generated, so this flag has the same effect as , except that it sets the property to . However, because JIT tracking is always enabled, the property value is ignored. + +Unlike the flag, the flag cannot be used to disable JIT optimizations. diff --git a/xml/System.Diagnostics/DebuggableAttribute.xml b/xml/System.Diagnostics/DebuggableAttribute.xml index 66c93f8928c..551c4d454dd 100644 --- a/xml/System.Diagnostics/DebuggableAttribute.xml +++ b/xml/System.Diagnostics/DebuggableAttribute.xml @@ -182,7 +182,7 @@ ## Remarks This constructor sets the properties and . - An `isJITTrackingEnabled` parameter value of `true` causes the runtime to track information important to the debugger during code generation; a value of `false` results in no tracking, but does not prevent debugging. This parameter has no effect in the .NET Framework version 2.0. In version 2.0, JIT tracking information, the Microsoft intermediate language (MSIL) offset to the native-code offset within a method, is always generated. +The `isJITTrackingEnabled` parameter has no effect. JIT tracking information, that is, the Microsoft intermediate language (MSIL) offset to the native-code offset within a method, is always generated. An `isJITOptimizerDisabled` parameter value of `true` optimizes for debugging; a value of `false` optimizes for execution. @@ -328,19 +328,7 @@ Gets a value that indicates whether the runtime will track information during code generation for the debugger. if the runtime will track information during code generation for the debugger; otherwise, . - - controls whether the runtime tracks information important to the debugger during code generation. This information helps the debugger provide a rich debugging experience. - - Starting in .NET Framework 2.0, JIT tracking information is always enabled during debugging, and this property value is ignored. - -> [!NOTE] -> This property does not control the ability to debug, but tells the just-in-time (JIT) compiler to generate tracking information. Specifically, the compiler tracks the Microsoft Intermediate Language (MSIL)-offset to the native-code offset within a method. - - ]]> - + JIT tracking information is always enabled during debugging, and this property value is ignored. diff --git a/xml/System.Diagnostics/Debugger.xml b/xml/System.Diagnostics/Debugger.xml index 6f29a31d91e..26c1c4e28d5 100644 --- a/xml/System.Diagnostics/Debugger.xml +++ b/xml/System.Diagnostics/Debugger.xml @@ -114,15 +114,14 @@ [!WARNING] -> Starting with .NET Framework 4, the runtime no longer exercises tight control of launching the debugger for the method, but instead reports an error to the Windows Error Reporting (WER) subsystem. WER provides many settings to customize the problem reporting experience, so a lot of factors will influence the way WER responds to an error such as operating system version, process, session, user, machine and domain. If you're having unexpected results when calling the method, check the WER settings on your machine. For more information on how to customize WER, see [WER Settings](/windows/win32/wer/wer-settings). If you want to ensure the debugger is launched regardless of the WER settings, be sure to call the method instead. - + If no debugger is attached, users are asked if they want to attach a debugger. If they choose yes, the debugger is started. If a debugger is attached, the debugger is signaled with a user breakpoint event, and the debugger suspends execution of the process just as if a debugger breakpoint had been hit. +> [!TIP] +> On Windows, the runtime reports an error to the Windows Error Reporting (WER) subsystem when this method is called. WER provides many settings to customize the problem reporting experience, so a lot of factors will influence the way WER responds to an error, such as operating system version, process, session, user, machine, and domain. If you're having unexpected results when calling the method, check the [WER settings](/windows/win32/wer/wer-settings). If you want to ensure the debugger is launched regardless of the WER settings, call the method instead. ## Examples - The following code example demonstrates how to stop the debugger at the call to . + +The following code example demonstrates how to stop the debugger at the call to . ```vb Debugger.Break() diff --git a/xml/System.Diagnostics/DebuggerBrowsableAttribute.xml b/xml/System.Diagnostics/DebuggerBrowsableAttribute.xml index 2d60201de80..82f867a348b 100644 --- a/xml/System.Diagnostics/DebuggerBrowsableAttribute.xml +++ b/xml/System.Diagnostics/DebuggerBrowsableAttribute.xml @@ -67,18 +67,13 @@ ## Remarks -> [!NOTE] -> In .NET Framework version 2.0, the class is not supported by Visual Basic. Using C#, you can add expansions for custom data using the , , and . Visual Basic supports the attribute but not the attribute. +This attribute can be applied only as a single instance to properties and fields. It cannot be applied to assemblies. - This attribute can be applied only as a single instance to properties and fields. It cannot be applied to assemblies. +The constructor for this attribute takes one of the enumeration values, which specifies one of the following states: - The constructor for this attribute takes one of the enumeration values, which specifies one of the following states: - -- indicates that the member is not displayed in the data window. For example, using this value for the on a field removes the field from the hierarchy; the field is not displayed when you expand the enclosing type by clicking the plus sign (+) for the type instance. - -- indicates that the member is displayed but not expanded by default. This is the default behavior. - -- indicates that the member itself is not shown, but its constituent objects are displayed if it is an array or collection. +- indicates that the member is not displayed in the data window. For example, using this value for the on a field removes the field from the hierarchy; the field is not displayed when you expand the enclosing type by clicking the plus sign (+) for the type instance. +- indicates that the member is displayed but not expanded by default. This is the default behavior. +- indicates that the member itself is not shown, but its constituent objects are displayed if it is an array or collection. For an example of the use of this attribute and the and attributes, see the example provided for the class. diff --git a/xml/System.Diagnostics/DefaultTraceListener.xml b/xml/System.Diagnostics/DefaultTraceListener.xml index cfc4ddbbb4a..ae7c1f60484 100644 --- a/xml/System.Diagnostics/DefaultTraceListener.xml +++ b/xml/System.Diagnostics/DefaultTraceListener.xml @@ -63,28 +63,9 @@ The method, by default, displays a message box when the application is running in a user interface mode; it also emits the message using . > [!NOTE] -> The display of the message box for and method calls depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. +> The display of the message box for and method calls depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). - You must enable tracing or debugging to use a trace listener. The following syntax is compiler specific. If you use compilers other than C# or Visual Basic, refer to the documentation for your compiler. - -- To enable debugging in C#, add the `/d:DEBUG` flag to the compiler command line when you compile your code, or add `#define DEBUG` to the top of your file. In Visual Basic, add the `/d:DEBUG=True` flag to the compiler command line. - -- 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. - -For .NET Framework apps, you can add a trace listener by editing the configuration file that corresponds to the name of 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 similar to the following example: - -```xml - - - - - - - - - - -``` + You must enable tracing or debugging to use a trace listener. ## Examples The following code example calculates binomial coefficients, which are values used in probability and statistics. This example uses a to trace results and log errors. It creates a new , adds it to the collection, and sets the property to the log file specified in the command-line arguments. diff --git a/xml/System.Diagnostics/DelimitedListTraceListener.xml b/xml/System.Diagnostics/DelimitedListTraceListener.xml index 2baa3af3ec1..2f76a8b3e15 100644 --- a/xml/System.Diagnostics/DelimitedListTraceListener.xml +++ b/xml/System.Diagnostics/DelimitedListTraceListener.xml @@ -58,31 +58,11 @@ The trace output is in a delimited text format that uses the delimiter specified by the property. The delimiter is used to terminate each field in a line of output. For example, to display the trace output in a Microsoft Excel spreadsheet, you might specify a comma (",") as a delimiter and create a comma-separated value (CSV) file. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a`try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - -You can create a in your code. Alternatively, in .NET Framework apps only, you can enable or disable a through the application configuration file and then use the configured in your application. +> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface docs. > [!NOTE] > The delimits only text that is emitted by using the methods that have names starting with the word `Trace`, such as or . Trace data that is emitted by using the and methods is not delimited. -To configure a in a .NET Framework app, edit the configuration file that corresponds to the name of your application. In this file, you can add a listener, set the properties for a listener, or remove a listener. The configuration file should be formatted as shown in the following example: - -```xml - - - - - - - - - -``` - > [!NOTE] > If you try to write to a file that is in use or unavailable, the file name is automatically prefixed by a GUID. @@ -487,35 +467,7 @@ To configure a in a .NET Fr Gets or sets the delimiter for the delimited list. The delimiter for the delimited list. - - property using the `delimiter` attribute in a configuration file for a .NET Framework app: - -```xml - - - - - - - - - - - -``` - - ]]> - + The default delimiter is ";" (semicolon). is set to . @@ -564,27 +516,7 @@ The following configuration file example shows how to set the is used to set the property. - -The following .NET Framework application configuration file example shows the use of the `delimiter` attribute to set the property: - -```xml - - - - - - - - - - -``` +A custom attribute is an attribute that is not inherited from the base class that can be used to set a property for the class. The custom attribute for is used to set the property. ]]> diff --git a/xml/System.Diagnostics/EventLog.xml b/xml/System.Diagnostics/EventLog.xml index de57ab20c38..4d77ccefa9d 100644 --- a/xml/System.Diagnostics/EventLog.xml +++ b/xml/System.Diagnostics/EventLog.xml @@ -54,15 +54,13 @@ lets you access or customize Windows event logs, which record information about important software or hardware events. Using , you can read from existing logs, write entries to logs, create or delete event sources, delete logs, and respond to log entries. You can also create new logs when creating an event source. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. In addition to providing access to individual event logs and their entries, the class lets you access the collection of all event logs. You can use the `static` members of to delete logs, get log lists, create or delete a source, or determine if a computer already contains a particular source. There are three default event logs: Application, System, and Security. A Security log is read-only. Other applications and services you install, such as Active Directory, might have additional event logs. - There are security considerations when using the class. requires permissions for specific actions. We recommend that not be granted to partially trusted code. You should never pass any event log object, including and objects, to less trusted code. For example, creating an object, writing an entry, and then passing the object to partially trusted code can create a security issue, because the ability to read and write to the event log allows code to perform actions such as issuing event log messages in the name of another application. - - Starting with Windows Vista, User Account Control (UAC) determines the credentials of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To run the code that accesses the Security log, you must first elevate your credentials from standard user to administrator. You can do this when you start an application by opening the shortcut menu for the application (if you're using a mouse, right-click the application icon) and indicating that you want to run as an administrator. +On Windows, User Account Control (UAC) determines the credentials of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To run the code that accesses the Security log, you must first elevate your credentials from standard user to administrator. You can do this when you start an application by opening the shortcut menu for the application (if you're using a mouse, right-click the application icon) and indicating that you want to run as an administrator. You can use to create custom event logs that you can view through the server's Event Viewer. Use the method to display a localized name for your event log in the Event Viewer. Use the method to configure the behavior of your event log when it reaches its maximum log size. @@ -72,15 +70,15 @@ If the event source for the event log associated with the instance doesn't exist, a new event source is created. To create an event source in Windows Vista and later or Windows Server 2003, you must have administrative credentials. - This requirement is because all event logs, including Security logs, must be searched to determine whether the event source is unique. Starting with Windows Vista, users do not have permission to access the Security log; therefore, a is thrown. + This requirement is because all event logs, including Security logs, must be searched to determine whether the event source is unique. Users don't have permission to access the Security log; therefore, a is thrown. > [!IMPORTANT] -> Creating or deleting an event source requires synchronization of the underlying code by using a named mutex. If a highly privileged application locks the named mutex, trying to create or delete an event source causes the application to stop responding until the lock is released. To help prevent this problem, never grant permission to untrusted code. In addition, permission potentially allows other permissions to be bypassed and should only be granted to highly trusted code. +> Creating or deleting an event source requires synchronization of the underlying code by using a named mutex. If a highly privileged application locks the named mutex, trying to create or delete an event source causes the application to stop responding until the lock is released. To help prevent this problem, never grant permission to untrusted code. In addition, permission potentially allows other permissions to be bypassed and should only be granted to highly trusted code. Applications and services should write to the Application log or to a custom log. Device drivers should write to the System log. If you do not explicitly set the property, the event log defaults to the Application log. > [!NOTE] -> There is nothing to protect an application from writing as any registered source. If an application is granted permission, it can write events for any valid source registered on the computer. +> There is nothing to protect an application from writing as any registered source. If an application is granted permission, it can write events for any valid source registered on the computer. Use the and methods to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. @@ -95,18 +93,14 @@ When writing events, you must at least specify either a message string or the resource identifier for a message string. Other event properties are optional. Examples of optional event settings include the following: - You can set the to specify the icon that the Event Viewer displays for the entry. - - You can specify a category identifier for the event, if your application uses categories for filtering the events. - - You can attach binary data to your event entry if you want to associate additional information with a given event. > [!IMPORTANT] -> Event logging consumes disk space, processor time, and other system resources. It is important to log only essential information. We recommend that you place event log calls in an error path, rather than in the main code path, so they don't adversely affect performance. +> Event logging consumes disk space, processor time, and other system resources. It is important to log only essential information. We recommend that you place event log calls in an error path, rather than in the main code path, so they don't adversely affect performance. For a list of initial property values for an instance of , see the constructor. - - ## Examples The following example creates the event source `MySource` if it doesn't already exist, and writes an entry to the event log `MyNewLog`. @@ -167,7 +161,7 @@ Before calling , specify the property of the instance. If you are only reading from the log, you can alternatively specify only the and properties. > [!NOTE] -> If you do not specify a , the local computer (".") is assumed. +> If you do not specify a , the local computer (".") is assumed. The following table shows initial property values for an instance of . @@ -235,7 +229,7 @@ This overload sets the property to the `logName` parameter. Before calling , specify the property of the instance. If you are only reading from the log, you can alternatively specify only the and properties. > [!NOTE] -> If you do not specify a , the local computer (".") is assumed. This overload of the constructor specifies the property, but you can change this before reading the property. +> If you do not specify a , the local computer (".") is assumed. This overload of the constructor specifies the property, but you can change this before reading the property. If the source you specify in the property is unique from other sources on the computer, a subsequent call to creates a log with the specified name, if it does not already exist. @@ -309,7 +303,7 @@ This overload sets the property to the `logName` parameter and the property to the `machineName` parameter. Before calling , specify the property of the . If you are only reading from the log, you can alternatively specify only the and properties. > [!NOTE] -> This overload of the constructor specifies the and properties, but you can change either before reading the property. +> This overload of the constructor specifies the and properties, but you can change either before reading the property. The following table shows initial property values for an instance of . @@ -513,7 +507,7 @@ The following example clears an event log. > [!CAUTION] -> Because Application, System, Security, and other non-custom logs can contain crucial information; be sure to specify a custom log before executing this example code. This example deletes the custom log `myNewLog`. +> Because Application, System, Security, and other non-custom logs can contain crucial information; be sure to specify a custom log before executing this example code. This example deletes the custom log `myNewLog`. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/Clear/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventLog/Clear/source.vb" id="Snippet1"::: @@ -628,11 +622,11 @@ The method uses the input `sourceData` , and properties to create registry values on the target computer for the new source and its associated event log. A new source name cannot match an existing source name or an existing event log name on the target computer. If the property is not set, the source is registered for the Application event log. If the is not set, the source is registered on the local computer. > [!NOTE] -> To create an event source in Windows Vista and later or Windows Server 2003, you must have administrative privileges. +> To create an event source in Windows Vista and later or Windows Server 2003, you must have administrative privileges. > -> The reason for this requirement is that all event logs, including security, must be searched to determine whether the event source is unique. Starting with Windows Vista, users do not have permission to access the security log; therefore, a is thrown. +> The reason for this requirement is that all event logs, including security, must be searched to determine whether the event source is unique. Starting with Windows Vista, users do not have permission to access the security log; therefore, a is thrown. > -> Starting with Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses the security log, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. +> Starting with Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses the security log, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. Use and to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. @@ -651,7 +645,7 @@ To change the configuration details of an existing source, you must delete the source and then create it with the new configuration. If other applications or components use the existing source, create a new source with the updated configuration rather than deleting the existing source. > [!NOTE] -> If a source is configured for an event log, and you reconfigure it for another event log, you must restart the computer for the changes to take effect. +> If a source is configured for an event log, and you reconfigure it for another event log, you must restart the computer for the changes to take effect. @@ -864,16 +858,16 @@ SVC_UPDATE.EXE If `logName` is `null` or an empty string ("") when you call , the log defaults to the Application log. If the log does not exist on the local computer, the system creates a custom log and registers your application as a for that log. > [!NOTE] -> To create an event source in Windows Vista and later or Windows Server 2003, you must have administrative privileges. +> To create an event source in Windows Vista and later or Windows Server 2003, you must have administrative privileges. > -> The reason for this requirement is that all event logs, including security, must be searched to determine whether the event source is unique. Starting with Windows Vista, users do not have permission to access the security log; therefore, a is thrown. +> The reason for this requirement is that all event logs, including security, must be searched to determine whether the event source is unique. Starting with Windows Vista, users do not have permission to access the security log; therefore, a is thrown. > -> In Windows Vista and later, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses the security log, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. +> In Windows Vista and later, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses the security log, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. You only need to create an event source if you are writing to the event log. Before writing an entry to an event log, you must register the event source with the event log as a valid source of events. When you write a log entry, the system uses the to find the appropriate log in which to place your entry. If you are reading the event log, you can either specify the , or a and . > [!NOTE] -> You are not required to specify the if you are connecting to a log on the local computer. If you do not specify the when reading from a log, the local computer (".") is assumed. +> You are not required to specify the if you are connecting to a log on the local computer. If you do not specify the when reading from a log, the local computer (".") is assumed. Use and to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. @@ -890,7 +884,7 @@ SVC_UPDATE.EXE To change the configuration details of an existing source, you must delete the source and then create it with the new configuration. If other applications or components use the existing source, create a new source with the updated configuration rather than deleting the existing source. > [!NOTE] -> If a source has already been mapped to a log and you remap it to a new log, you must restart the computer for the changes to take effect. +> If a source has already been mapped to a log and you remap it to a new log, you must restart the computer for the changes to take effect. @@ -972,8 +966,8 @@ SVC_UPDATE.EXE [<System.Obsolete("EventLog.CreateEventSource has been deprecated. Use System.Diagnostics.EventLog.CreateEventSource(EventSourceCreationData sourceData) instead.")>] - [System.Obsolete("This method has been deprecated. Please use System.Diagnostics.EventLog.CreateEventSource(EventSourceCreationData sourceData) instead. https://go.microsoft.com/fwlink/?linkid=14202")] - [<System.Obsolete("This method has been deprecated. Please use System.Diagnostics.EventLog.CreateEventSource(EventSourceCreationData sourceData) instead. https://go.microsoft.com/fwlink/?linkid=14202")>] + [System.Obsolete("This method has been deprecated. Please use System.Diagnostics.EventLog.CreateEventSource(EventSourceCreationData sourceData) instead. https://go.microsoft.com/fwlink/?linkid=14202")] + [<System.Obsolete("This method has been deprecated. Please use System.Diagnostics.EventLog.CreateEventSource(EventSourceCreationData sourceData) instead. https://go.microsoft.com/fwlink/?linkid=14202")>] @@ -1000,11 +994,11 @@ SVC_UPDATE.EXE You only need to create an event source if you are writing to the event log. Before writing an entry to an event log, you must register the event source with the event log as a valid source of events. When you write a log entry, the system uses the to find the appropriate log in which to place your entry. If you are reading the event log, you can either specify the , or a and . > [!NOTE] -> To create an event source in Windows Vista and later or Windows Server 2003, you must have administrative privileges. +> To create an event source in Windows Vista and later or Windows Server 2003, you must have administrative privileges. > -> The reason for this requirement is that all event logs, including security, must be searched to determine whether the event source is unique. In Windows Vista and later, users do not have permission to access the security log; therefore, a is thrown. +> The reason for this requirement is that all event logs, including security, must be searched to determine whether the event source is unique. In Windows Vista and later, users do not have permission to access the security log; therefore, a is thrown. > -> In Windows Vista and later, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses the security log, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. +> In Windows Vista and later, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses the security log, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. Use and to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. @@ -1122,7 +1116,7 @@ SVC_UPDATE.EXE The method first deletes the file that holds the contents of the log. It then accesses the registry and removes all the event sources registered for that log. If you recreate the log at a later point, you should register the event sources again, if they are to be reused. If you do not register the event sources and other users write to an event source without specifying a log name, the event source will be created in the Application event log. Therefore, applications that previously were able to write entries to the log you deleted and recreated will write to the Application log instead, because it now contains the event source. > [!NOTE] -> Recreating an event log can be a difficult process. Avoid deleting any of the system-created event logs, such as the Application log. +> Recreating an event log can be a difficult process. Avoid deleting any of the system-created event logs, such as the Application log. Deleting a log through a call to automatically deletes the sources registered to that log. This can make other applications using that log inoperative. @@ -1132,7 +1126,7 @@ SVC_UPDATE.EXE The following example deletes a log from the local computer. The example determines the log from its source. > [!NOTE] -> More than one source might write to an event log. Before deleting a custom log, make sure there are no other sources writing to that log. +> More than one source might write to an event log. Before deleting a custom log, make sure there are no other sources writing to that log. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/Delete/source1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventLog/Delete/source1.vb" id="Snippet1"::: @@ -1205,7 +1199,7 @@ SVC_UPDATE.EXE This method first deletes the file that holds the contents of the log. It then accesses the registry and removes all the event sources registered for that log. If you recreate the log at a later point, you should register the event sources again, if they are to be reused. If you do not register the event sources and other users write to an event source without specifying a log name, the event source will be created in the Application event log. Therefore, applications that previously were able to write entries to the log you deleted and recreated will write to the Application log instead, because it now contains the event source. > [!NOTE] -> Recreating an event log can be a difficult process. Avoid deleting any of the system-created event logs, such as the Application log. +> Recreating an event log can be a difficult process. Avoid deleting any of the system-created event logs, such as the Application log. Deleting a log through a call to automatically deletes the sources registered to that log. This can make other applications using that log inoperative. @@ -1215,7 +1209,7 @@ SVC_UPDATE.EXE The following example deletes a log from the specified computer. The example determines the log from its source. > [!NOTE] -> More than one source might write to an event log. Before deleting a custom log, make sure there are no other sources writing to that log. +> More than one source might write to an event log. Before deleting a custom log, make sure there are no other sources writing to that log. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/Delete/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventLog/Delete/source.vb" id="Snippet1"::: @@ -1302,7 +1296,7 @@ SVC_UPDATE.EXE Deleting a log through a call to automatically deletes the sources registered to that log. This can make other applications using that log inoperative. > [!NOTE] -> If a source has already been mapped to a log and you remap it to a new log, you must restart the computer for the changes to take effect. +> If a source has already been mapped to a log and you remap it to a new log, you must restart the computer for the changes to take effect. @@ -1310,7 +1304,7 @@ SVC_UPDATE.EXE The following example deletes a source from the local computer. The example determines the log from its source, and then deletes the log. > [!NOTE] -> More than one source might write to an event log. Before deleting a custom log, make sure there are no other sources writing to that log. +> More than one source might write to an event log. Before deleting a custom log, make sure there are no other sources writing to that log. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/Delete/source1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventLog/Delete/source1.vb" id="Snippet1"::: @@ -1379,7 +1373,7 @@ SVC_UPDATE.EXE Deleting a log through a call to automatically deletes the sources registered to that log. This can make other applications using that log inoperative. > [!NOTE] -> If a source has already been mapped to a log and you remap it to a new log, you must restart the computer for the changes to take effect. +> If a source has already been mapped to a log and you remap it to a new log, you must restart the computer for the changes to take effect. @@ -1387,7 +1381,7 @@ SVC_UPDATE.EXE The following example deletes a source from the specified computer. The example determines the log from its source, and then deletes the log. > [!NOTE] -> More than one source might write to an event log. Before deleting a custom log, make sure there are no other sources writing to that log. +> More than one source might write to an event log. Before deleting a custom log, make sure there are no other sources writing to that log. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/Delete/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventLog/Delete/source.vb" id="Snippet1"::: @@ -1517,7 +1511,7 @@ SVC_UPDATE.EXE The property determines whether the raises events when entries are written to the log. When the property is `true`, components that receive the event will receive notification any time an entry is written to the log that is specified in the property. If is `false`, no events are raised. > [!NOTE] -> You can receive event notifications only when entries are written on the local computer. You cannot receive notifications for entries written on remote computers. +> You can receive event notifications only when entries are written on the local computer. You cannot receive notifications for entries written on remote computers. @@ -1634,7 +1628,7 @@ SVC_UPDATE.EXE An important distinction between reading and writing log entries is that it is not necessary to explicitly call a read method. After the and are specified, the property is automatically populated. If you change the value of the or property, the property is repopulated the next time you read it. > [!NOTE] -> You are not required to specify the if you are connecting to a log. If you do not specify the , the local computer, ".", is assumed. +> You are not required to specify the if you are connecting to a log. If you do not specify the , the local computer, ".", is assumed. @@ -2060,12 +2054,12 @@ SVC_UPDATE.EXE Three log files exist by default on the server: Application, System, and Security. Applications and services use the Application log file. Device drivers use the System log file. The system generates success and failure audit events in the Security log when auditing is turned on. If you have other applications installed, like Active Directory on Windows servers, there might be other default log files. In addition, you can create custom log files on a local or remote computer. Custom logs help organize your entries in a more detailed way than is allowed when your components write events to the default Application log. > [!NOTE] -> Log names are limited to eight characters. According to the system, MyLogSample1 and MyLogSample2 are the same log. +> Log names are limited to eight characters. According to the system, MyLogSample1 and MyLogSample2 are the same log. If you write to an event log, it is not enough to specify the property. You must associate a property with your event log resource to connect it to a particular log. It is not necessary to specify a when only reading from a log, but an event source must be associated with the event log resource in the server's registry. You can specify only the name and (server computer name) to read from it. > [!NOTE] -> You are not required to specify the if you are connecting to a log. If you do not specify the , the local computer (".") is assumed. +> You are not required to specify the if you are connecting to a log. If you do not specify the , the local computer (".") is assumed. If the property has not been specified, a call to returns an empty string if has not been explicitly set (by setting the property, or through the constructor). If the has been specified, returns the name of the log to which that source was registered. @@ -2078,7 +2072,7 @@ SVC_UPDATE.EXE If the value changes, the event log is closed and all event handles are released. > [!CAUTION] -> If you set the property to the name of a log that does not exist, the system attaches the to the Application log, but does not warn you that it is using a log other than the one you specified. +> If you set the property to the name of a log that does not exist, the system attaches the to the Application log, but does not warn you that it is using a log other than the one you specified. @@ -2148,9 +2142,9 @@ SVC_UPDATE.EXE ## Remarks > [!NOTE] -> In Windows Vista and later, users do not have permission to access the security log. If you are running Windows Vista or later as a user, you will get a when you attempt to access the display name for an event in the security log. +> In Windows Vista and later, users do not have permission to access the security log. If you are running Windows Vista or later as a user, you will get a when you attempt to access the display name for an event in the security log. > -> In Windows Vista and later, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses the security log, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. +> In Windows Vista and later, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses the security log, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. @@ -2218,7 +2212,7 @@ SVC_UPDATE.EXE The following example deletes a source from the local computer. The example determines the log from its source, and then deletes the log. > [!NOTE] -> More than one source might write to an event log. Before deleting a custom log, make sure there are no other sources writing to that log. +> More than one source might write to an event log. Before deleting a custom log, make sure there are no other sources writing to that log. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/Delete/source1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventLog/Delete/source1.vb" id="Snippet1"::: @@ -2284,7 +2278,7 @@ SVC_UPDATE.EXE If you write to an event log, you must associate a with your event log object to connect it to a particular log. It is not necessary to specify the property when only reading from a log. You can specify only the name and (server computer name). > [!NOTE] -> You need not specify the if you are connecting to a log. If you do not specify the , the local computer (".") is assumed. +> You need not specify the if you are connecting to a log. If you do not specify the , the local computer (".") is assumed. A source can only be registered to one log at a time. If the property was set for an instance of , you cannot change the property for that without changing the value of or calling first. If you change the property, the closes all handles and reattaches to the log and source on the new computer. @@ -2359,7 +2353,7 @@ SVC_UPDATE.EXE The property represents the size limit of the event log file. When the event log reaches the size limit, the configured value determines whether new entries are discarded, or whether new entries overwrite older entries. > [!NOTE] -> This property represents a configuration setting for the event log represented by this instance. When the event log reaches its maximum size, this property specifies how the operating system handles new entries written by all event sources registered for the event log. +> This property represents a configuration setting for the event log represented by this instance. When the event log reaches its maximum size, this property specifies how the operating system handles new entries written by all event sources registered for the event log. @@ -2568,7 +2562,7 @@ SVC_UPDATE.EXE Use the property value to examine the configured overflow behavior for an event log at its maximum size. Use the method to change the overflow behavior for an event log. > [!NOTE] -> The overflow behavior takes effect only when an event log reaches its maximum file size. The overflow behavior does not affect writing a new entry to a log that can accommodate additional event log entries. +> The overflow behavior takes effect only when an event log reaches its maximum file size. The overflow behavior does not affect writing a new entry to a log that can accommodate additional event log entries. @@ -2633,7 +2627,7 @@ SVC_UPDATE.EXE If the Event Viewer cannot load the localized string from the resource file, or if no display name was registered for the event log, then the Event Viewer displays the event log name defined in . > [!NOTE] -> You do not need to register a display name for the pre-defined event logs. The operating system registers the localized display names for the Application, System, and Security event logs. +> You do not need to register a display name for the pre-defined event logs. The operating system registers the localized display names for the Application, System, and Security event logs. @@ -2823,7 +2817,7 @@ SVC_UPDATE.EXE You only need to specify an event source if you are writing to an event log. Before writing an entry to an event log, you must register the event source with the event log as a valid source of events. When you write a log entry, the system uses the property to find the appropriate log in which to place your entry. If you are reading the event log, you can either specify the , or a and . > [!NOTE] -> You are not required to specify the if you are connecting to a log on the local computer. If you do not specify the , the local computer (".") is assumed. +> You are not required to specify the if you are connecting to a log on the local computer. If you do not specify the , the local computer (".") is assumed. Use and to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. @@ -2840,7 +2834,7 @@ SVC_UPDATE.EXE To change the configuration details of an existing source, you must delete the source and then create it with the new configuration. If other applications or components use the existing source, create a new source with the updated configuration rather than deleting the existing source. > [!NOTE] -> If a source has already been mapped to a log and you remap it to a new log, you must restart the computer for the changes to take effect. +> If a source has already been mapped to a log and you remap it to a new log, you must restart the computer for the changes to take effect. @@ -2923,14 +2917,14 @@ SVC_UPDATE.EXE Because this method accesses the registry, you must have the appropriate registry permissions on the local computer; otherwise, a will be thrown. > [!NOTE] -> To search for an event source in Windows Vista and later or Windows Server 2003, you must have administrative privileges. +> To search for an event source in Windows Vista and later or Windows Server 2003, you must have administrative privileges. > -> The reason for this requirement is that all event logs, including security, must be searched to determine whether the event source is unique. Starting with Windows Vista, users do not have permission to access the security log; therefore, a is thrown. +> The reason for this requirement is that all event logs, including security, must be searched to determine whether the event source is unique. Starting with Windows Vista, users do not have permission to access the security log; therefore, a is thrown. > -> Starting with Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses performance counters, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. +> Starting with Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses performance counters, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. > [!NOTE] -> A service that is executing under the account does not have the privileges required to execute this method. The solution is to check whether the event source exists in the , and if it does not exist, to create the source in the installer. +> A service that is executing under the account does not have the privileges required to execute this method. The solution is to check whether the event source exists in the , and if it does not exist, to create the source in the installer. Because you cannot give a new source the name of an existing source on the same computer, use this method before attempting to call to ensure that a source with the name specified by `source` does not already exist on the local computer. The `source` parameter is not case-sensitive. @@ -3012,14 +3006,14 @@ SVC_UPDATE.EXE Because this method accesses the registry, you must have the appropriate registry permissions on the given server; otherwise, a will be thrown. > [!NOTE] -> To search for an event source in Windows Vista and later or Windows Server 2003, you must have administrative privileges. +> To search for an event source in Windows Vista and later or Windows Server 2003, you must have administrative privileges. > -> The reason for this requirement is that all event logs, including security, must be searched to determine whether the event source is unique. Starting with Windows Vista, users do not have permission to access the security log; therefore, a is thrown. +> The reason for this requirement is that all event logs, including security, must be searched to determine whether the event source is unique. Starting with Windows Vista, users do not have permission to access the security log; therefore, a is thrown. > -> Starting with Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses performance counters, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. +> Starting with Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses performance counters, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. > [!NOTE] -> A service that is executing under the account does not have the privileges required to execute this method. The solution is to check whether the event source exists in the , and if it does not exist, to create the source in the installer. +> A service that is executing under the account does not have the privileges required to execute this method. The solution is to check whether the event source exists in the , and if it does not exist, to create the source in the installer. Because you cannot give a new source the name of an existing source on the same computer, use this method before attempting to call to ensure that a source with the name specified by `source` does not already exist on the computer. The `source` and `machineName` parameters are not case sensitive. @@ -3161,7 +3155,7 @@ SVC_UPDATE.EXE Use this method to write an information entry to the event log associated with this instance. If you want to specify any other , use a different overload of . > [!NOTE] -> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. +> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. You must set the property on your component before you can write entries to the log. You must create and configure the event source before writing the first entry with the source. @@ -3170,24 +3164,19 @@ SVC_UPDATE.EXE If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. > [!NOTE] -> If you do not specify a for your instance before you call or , the local computer (".") is assumed. +> If you do not specify a for your instance before you call or , the local computer (".") is assumed. If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. > [!NOTE] -> Many of the exceptions listed above are generated by errors raised during the process of registering the . +> Many of the exceptions listed above are generated by errors raised during the process of registering the . The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. > [!NOTE] -> If you write an entry to a remote computer, the value of the message (the text string) might not be what you expect if the remote computer is not running the .NET Framework. - -> [!NOTE] -> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. - - +> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. ## Examples The following example creates the source `MySource` if it does not already exist, and writes an entry to the event log `MyNewLog`. @@ -3277,20 +3266,17 @@ SVC_UPDATE.EXE If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. > [!NOTE] -> If you do not specify a for your instance before you call or , the local computer (".") is assumed. +> If you do not specify a for your instance before you call or , the local computer (".") is assumed. If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. > [!NOTE] -> Many exceptions listed above are generated by errors raised during the process of registering the . +> Many exceptions listed above are generated by errors raised during the process of registering the . The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. -> [!NOTE] -> If you write an entry to a remote computer, the value of the message (the text string) might not be what you expect if the remote computer is not running the .NET Framework. - > [!NOTE] > If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. @@ -3471,7 +3457,7 @@ SVC_UPDATE.EXE Use this method to write an entry with an application-defined `eventID` to the event log. The `eventID` together with the source uniquely identify an event. Each application can define its own numbered events and the description strings to which they map. Event viewers display these string values to help the user understand what went wrong and suggest what actions to take. > [!NOTE] -> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. +> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. In addition to the event identifier, you can specify an for the event being written to the event log. The `type` is indicated by an icon and text in the Type column in the Event Viewer for a log. This parameter indicates whether the event type is error, warning, information, success audit, or failure audit. @@ -3482,24 +3468,19 @@ SVC_UPDATE.EXE If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. > [!NOTE] -> If you do not specify a for your instance before you call or , the local computer (".") is assumed. +> If you do not specify a for your instance before you call or , the local computer (".") is assumed. If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. > [!NOTE] -> Many exceptions listed above are generated by errors raised during the process of registering the . +> Many exceptions listed above are generated by errors raised during the process of registering the . The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. > [!NOTE] -> If you write an entry to a remote computer, the value of the message (the text string) might not be what you expect if the remote computer is not running the .NET Framework. - -> [!NOTE] -> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. - - +> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. ## Examples :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLog/WriteEntry/eventlog_writeentry_1_3.cs" id="Snippet3"::: @@ -3594,7 +3575,7 @@ SVC_UPDATE.EXE Use this method to write an entry of a specified to the event log, using a source already registered as an event source for the appropriate log. The `type` is indicated by an icon and text in the Type column in the Event Viewer for a log. > [!NOTE] -> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. +> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. @@ -3603,7 +3584,7 @@ SVC_UPDATE.EXE If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. > [!NOTE] -> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. +> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. @@ -3689,10 +3670,10 @@ SVC_UPDATE.EXE Use this method to write an entry with an application-defined `category` to the event log. The Event Viewer uses the category to filter events written by an event source. The Event Viewer can display the category as a numeric value, or it can use the category as a resource identifier to display a localized category string. > [!NOTE] -> The `category` parameter should be a positive value. Negative category values appear as a complementary positive number in the Event Viewer. For example, a -10 appears as 65,526, a -1 as 65,535. +> The `category` parameter should be a positive value. Negative category values appear as a complementary positive number in the Event Viewer. For example, a -10 appears as 65,526, a -1 as 65,535. > [!NOTE] -> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. +> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. To display localized category strings in the Event Viewer, you must use an event source configured with a category resource file, and set the `category` to a resource identifier in the category resource file. If the event source does not have a configured category resource file, or the specified `category` does not index a string in the category resource file, then the Event Viewer displays the numeric category value for that entry. Configure the category resource file, along with the number of category strings in the resource file, using the or the class. @@ -3707,22 +3688,19 @@ SVC_UPDATE.EXE If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. > [!NOTE] -> If you do not specify a for your instance before you call or , the local computer (".") is assumed. +> If you do not specify a for your instance before you call or , the local computer (".") is assumed. If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. > [!NOTE] -> Many exceptions listed above are generated by errors raised during the process of registering the . +> Many exceptions listed above are generated by errors raised during the process of registering the . The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. > [!NOTE] -> If you write an entry to a remote computer, the value of the message (the text string) might not be what you expect if the remote computer is not running the .NET Framework. - -> [!NOTE] -> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. +> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. @@ -3821,7 +3799,7 @@ SVC_UPDATE.EXE Use this method to write an entry with an application-defined `eventID` to the event log, using a source already registered as an event source for the appropriate log. The `eventID`, along with the source, uniquely identify an event. Each application can define its own numbered events and the description strings to which they map. Event viewers present these strings to the user to help the user understand what went wrong and suggest what actions to take. > [!NOTE] -> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. +> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. In addition to the event identifier, this overload of lets you specify an for the event being written to the event log. The `type` is indicated by an icon and text in the Type column in the Event Viewer for a log. This parameter indicates whether the event type is error, warning, information, success audit, or failure audit. @@ -3832,7 +3810,7 @@ SVC_UPDATE.EXE If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. > [!NOTE] -> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. +> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. @@ -3924,10 +3902,10 @@ SVC_UPDATE.EXE In addition to the binary data, you can specify an application-defined category and an application-defined event identifier. The Event Viewer uses the category to filter events written by an event source. The Event Viewer can display the category as a numeric value, or it can use the category as a resource identifier to display a localized category string. > [!NOTE] -> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. +> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. > [!NOTE] -> The `category` parameter should be a positive value. Negative category values appear as a complementary positive number in the Event Viewer. For example, a -10 appears as 65,526, a -1 as 65,535. +> The `category` parameter should be a positive value. Negative category values appear as a complementary positive number in the Event Viewer. For example, a -10 appears as 65,526, a -1 as 65,535. To display localized category strings in the Event Viewer, you must use an event source configured with a category resource file, and set the `category` to a resource identifier in the category resource file. If the event source does not have a configured category resource file, or the specified `category` does not index a string in the category resource file, then the Event Viewer displays the numeric category value for that entry. Configure the category resource file, along with the number of category strings in the resource file, using the or the class. @@ -3942,22 +3920,19 @@ SVC_UPDATE.EXE If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. > [!NOTE] -> If you do not specify a for your instance before you call or , the local computer (".") is assumed. +> If you do not specify a for your instance before you call or , the local computer (".") is assumed. If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. > [!NOTE] -> Many exceptions listed above are generated by errors raised during the process of registering the . +> Many exceptions listed above are generated by errors raised during the process of registering the . The source must be configured either for writing localized entries or for writing direct strings. The method writes the given string directly to the event log; it does not use a localizable message resource file. Use the method to write events using a localized message resource file. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. > [!NOTE] -> If you write an entry to a remote computer, the value of the message (the text string) might not be what you expect if the remote computer is not running the .NET Framework. - -> [!NOTE] -> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. +> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. @@ -4058,7 +4033,7 @@ SVC_UPDATE.EXE Use this method to write an entry with an application-defined `category` to the event log, using a source that is already registered as an event source for the appropriate log. The Event Viewer uses the category to filter events written by an event source. The Event Viewer can display the category as a numeric value, or it can use the category as a resource identifier to display a localized category string. > [!NOTE] -> The `category` parameter should be a positive value. Negative category values appear as a complementary positive number in the Event Viewer. For example, a -10 appears as 65,526, a -1 as 65,535. +> The `category` parameter should be a positive value. Negative category values appear as a complementary positive number in the Event Viewer. For example, a -10 appears as 65,526, a -1 as 65,535. To display localized category strings in the Event Viewer, you must use an event source configured with a category resource file, and set the `category` to a resource identifier in the category resource file. If the event source does not have a configured category resource file, or the specified `category` does not index a string in the category resource file, then the Event Viewer displays the numeric category value for that entry. Configure the category resource file, along with the number of category strings in the resource file, using the or the class. @@ -4073,9 +4048,9 @@ SVC_UPDATE.EXE If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. > [!NOTE] -> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. +> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. > -> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. +> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. @@ -4180,7 +4155,7 @@ SVC_UPDATE.EXE In addition to the binary data, you can specify an application-defined category and an application-defined event identifier. The Event Viewer uses the category to filter events written by an event source. The Event Viewer can display the category as a numeric value, or it can use the category as a resource identifier to display a localized category string. > [!NOTE] -> The `category` parameter should be a positive value. Negative category values appear as a complementary positive number in the Event Viewer. For example, a -10 will appear as 65,526, a -1 as 65,535. +> The `category` parameter should be a positive value. Negative category values appear as a complementary positive number in the Event Viewer. For example, a -10 will appear as 65,526, a -1 as 65,535. To display localized category strings in the Event Viewer, you must use an event source configured with a category resource file, and set the `category` to a resource identifier in the category resource file. If the event source does not have a configured category resource file, or the specified `category` does not index a string in the category resource file, then the Event Viewer displays the numeric category value for that entry. Configure the category resource file, along with the number of category strings in the resource file, using the or the class. @@ -4195,9 +4170,9 @@ SVC_UPDATE.EXE If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. > [!NOTE] -> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. +> If the `message` parameter contains a NUL character, the message in the event log is terminated at the NUL character. > -> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. +> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. @@ -4541,16 +4516,14 @@ SVC_UPDATE.EXE You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. > [!NOTE] -> If you do not specify a for your instance before you call , the local computer (".") is assumed. +> If you do not specify a for your instance before you call , the local computer (".") is assumed. The source must be configured either for writing localized entries or for writing direct strings. Use the method if your application writes string values directly to the event log. If your application writes entries using both resource identifiers and string values, you must register two separate sources. For example, configure one source with resource files, and then use that source in the method to write entries using resource identifiers to the event log. Then create a different source without resource files, and use that source in the method to write strings directly to the event log using that source. > [!NOTE] -> If you write an entry to a remote computer, the value of the `message` string might not be what you expect if the remote computer is not running the .NET Framework. Also, the `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. - - +> The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. ## Examples The following example writes two audit entries to the event log `myNewLog`. The example creates a new event source and a new event log if they do not exist on the local computer. The event message text is specified using a resource identifier in a resource file. diff --git a/xml/System.Diagnostics/EventLogPermission.xml b/xml/System.Diagnostics/EventLogPermission.xml index 351d737cd55..de949763e43 100644 --- a/xml/System.Diagnostics/EventLogPermission.xml +++ b/xml/System.Diagnostics/EventLogPermission.xml @@ -46,15 +46,6 @@ [!INCLUDE[cas-deprecated](~/includes/cas-deprecated.md)] - Do not grant to partially trusted code. The ability to read and write the event log enables code to perform actions such as issuing event log messages in the name of another application. - -> [!NOTE] -> If the event source that is specified by the property for the event log does not exist, a new event source is created. To create an event source in Windows Vista and later versions of Windows, or Windows Server 2003, you must have administrative privileges. -> -> The reason for this requirement is that all event logs, including security, must be searched to determine whether the event source is unique. Starting with Windows Vista, users do not have permission to access the security log; therefore, a is thrown. -> -> Starting with Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses the security log, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. - ]]> diff --git a/xml/System.Diagnostics/EventLogPermissionAttribute.xml b/xml/System.Diagnostics/EventLogPermissionAttribute.xml index 56c7ff28fb1..f0e5c575b32 100644 --- a/xml/System.Diagnostics/EventLogPermissionAttribute.xml +++ b/xml/System.Diagnostics/EventLogPermissionAttribute.xml @@ -44,14 +44,12 @@ Allows declarative permission checks for event logging. - diff --git a/xml/System.Diagnostics/EventLogPermissionEntry.xml b/xml/System.Diagnostics/EventLogPermissionEntry.xml index baffd877868..23541521d1a 100644 --- a/xml/System.Diagnostics/EventLogPermissionEntry.xml +++ b/xml/System.Diagnostics/EventLogPermissionEntry.xml @@ -33,19 +33,8 @@ Defines the smallest unit of a code access security permission that is set for an . - - - + To be added. - - - - @@ -83,11 +72,11 @@ The name of the computer on which to read or write events. The property is set to this value. Initializes a new instance of the class. - The computer name is invalid. @@ -126,11 +115,11 @@ Gets the name of the computer on which to read or write events. The name of the computer on which to read or write events. - diff --git a/xml/System.Diagnostics/EventLogTraceListener.xml b/xml/System.Diagnostics/EventLogTraceListener.xml index 4a69a2e0776..610c99f1ccc 100644 --- a/xml/System.Diagnostics/EventLogTraceListener.xml +++ b/xml/System.Diagnostics/EventLogTraceListener.xml @@ -42,37 +42,17 @@ can be added to the , , or collections to send output from tracing or debugging to an . You can add the instance in your code or, for a .NET Framework app, specify it in the application configuration file. - -To add an using a .NET Framework application configuration file, edit the file that corresponds to the name of your application. In this file, insert an element for a type. The following example adds a object named `myListener` to the collection. The `initializeData` parameter specifies the name of the event log source that is to be passed to the constructor. - -```xml - - - - - - - - - -``` + An instance of this can be added to the , , or collections to send output from tracing or debugging to an . > [!NOTE] -> If the for the event log that is associated with the instance does not exist, a new event source is created. To create an event source in Windows Vista, Windows XP Professional, or Windows Server 2003, you must have administrative privileges. -> -> The reason for this requirement is that all event logs, including security, must be searched to determine whether the event source is unique. In Windows Vista, users do not have permission to access the security log; therefore, a is thrown. -> -> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses the security log, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. +> If the for the event log that's associated with the instance does not exist, a new event source is created. To create an event source in Windows, you must have administrative privileges. You can elevate your privileges when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. The class provides the property to get or set the event log that receives the tracing or debugging output, and the property to hold the name of the . The method closes the event log so it no longer receives tracing or debugging output. The and methods write a message to the event log. > [!NOTE] -> To avoid the possibility of writing large amounts of data to the event log, the does not output the optional trace data specified by the property. +> To avoid the possibility of writing large amounts of data to the event log, the does not output the optional trace data specified by the property. ## Examples The following example creates a trace listener that sends output to an event log. First, the code creates a new that uses the source `myEventLogSource`. Next, `myTraceListener` is added to the collection. Finally, the example sends a line of output to the object. diff --git a/xml/System.Diagnostics/EventTypeFilter.xml b/xml/System.Diagnostics/EventTypeFilter.xml index 9e11a5a2168..f594c80cb41 100644 --- a/xml/System.Diagnostics/EventTypeFilter.xml +++ b/xml/System.Diagnostics/EventTypeFilter.xml @@ -51,24 +51,7 @@ ## Remarks One of several different types of filters can be assigned to a trace listener through the property to provide a layer of screening beyond that provided by the . The filter can be used to control the event types that are produced by the listener. - This class filters events based on the value of the property. This property can be set by code or, for .NET Framework apps, in a configuration file to specify the event type of messages that should be traced by the listener. The value of the property indicates the threshold at which to begin tracing. Event types at and above the specified level are traced. The method, called by listeners to determine if an event should be traced, uses the value of the property. - -To set the event type at which to begin tracing in a .NET Framework app, edit the configuration file that corresponds to the name of your application. Within this file, you can add a listener, set its filter type, and specify the event type to trace. The configuration file should be formatted as follows. - -```xml - - - - - - - - - -``` - - For more information about how to initialize data for an , see [\](/dotnet/framework/configure-apps/file-schema/trace-debug/filter-element-for-add-for-sharedlisteners). + This class filters events based on the value of the property. The value of the property indicates the threshold at which to begin tracing. Event types at and above the specified level are traced. The method, called by listeners to determine if an event should be traced, uses the value of the property. ]]> diff --git a/xml/System.Diagnostics/FileVersionInfo.xml b/xml/System.Diagnostics/FileVersionInfo.xml index b0399738e09..4d80a2b2ab0 100644 --- a/xml/System.Diagnostics/FileVersionInfo.xml +++ b/xml/System.Diagnostics/FileVersionInfo.xml @@ -72,9 +72,6 @@ Version resources are typically specified in a Win32 resource file, or in assembly attributes. For example the property reflects the `VS_FF_DEBUG` flag value in the file's `VS_FIXEDFILEINFO` block, which is built from the `VERSIONINFO` resource in a Win32 resource file. For more information about specifying version resources in a Win32 resource file, see "About Resource Files" and "VERSIONINFO Resource" in the Platform SDK. For more information about specifying version resources in a .NET module, see the [Setting Assembly Attributes](/dotnet/standard/assembly/set-attributes) topic. -> [!NOTE] -> This class makes a link demand at the class level that applies to all members. A is thrown when the immediate caller does not have full trust permission. - ## Examples The following example calls to get the for the Notepad. Then it prints the file description and version number to the console. diff --git a/xml/System.Diagnostics/PerformanceCounter.xml b/xml/System.Diagnostics/PerformanceCounter.xml index 32327c97e3f..7d0e3eee83a 100644 --- a/xml/System.Diagnostics/PerformanceCounter.xml +++ b/xml/System.Diagnostics/PerformanceCounter.xml @@ -43,14 +43,7 @@ ## Remarks The component can be used for both reading existing predefined or custom counters and publishing (writing) performance data to custom counters. - There are numerous predefined counters listed in the Windows Performance Monitor's **Add Counters** dialog box. To learn about the .NET Framework performance counters, see [Performance Counters](/dotnet/framework/debug-trace-profile/performance-counters). - - This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - -> [!IMPORTANT] -> In versions 1.0 and 1.1 of .NET Framework, this class requires immediate callers to be fully trusted. Starting with .NET Framework version 2.0, this class requires for specific actions. It is strongly recommended that not be granted to semi-trusted code. The ability to read and write performance counters allows code to perform actions such as enumerating executing processes and obtaining information about them. -> -> In addition, passing a object to less-trusted code can create a security issue. Never pass performance counter objects, such as a or , to less trusted code. + There are numerous predefined counters listed in the Windows Performance Monitor's **Add Counters** dialog box. To learn about the .NET performance counters, see [Performance Counters](/dotnet/framework/debug-trace-profile/performance-counters). To read from a performance counter, create an instance of the class, set the , , and, optionally, the or properties, and then call the method to take a performance counter reading. @@ -70,7 +63,7 @@ To obtain performance data for counters that required an initial or previous value for performing the necessary calculation, call the method twice and use the information returned as your application requires. > [!NOTE] -> Performance counter categories installed with .NET use separate shared memory, with each performance counter category having its own memory. You can specify the size of separate shared memory by creating a DWORD named FileMappingSize in the registry key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\\*\*\Performance. The FileMappingSize value is set to the shared memory size of the category. The default size is 131072 decimal. If the FileMappingSize value is not present, the `fileMappingSize` attribute value for the `performanceCounters` element specified in the Machine.config file is used, causing additional overhead for configuration file processing. You can realize a performance improvement for application startup by setting the file mapping size in the registry. For more information about the file mapping size, see [<performanceCounters>](/dotnet/framework/configure-apps/file-schema/trace-debug/performancecounters-element). +> Performance counter categories installed with .NET use separate shared memory, with each performance counter category having its own memory. You can specify the size of separate shared memory by creating a DWORD named FileMappingSize in the registry key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\\*\*\Performance. The FileMappingSize value is set to the shared memory size of the category. The default size is 131072 decimal. ## Examples The following code example demonstrates the use of the class to create and use an counter type. The example creates categories, sets up counters, collects data from the counters, and calls the class to interpret the performance counter data. The intermediate and final results are displayed in the console window. For additional examples of other performance counter types, see the enumeration. @@ -193,10 +186,6 @@ > [!NOTE] > To read performance counters from a non-interactive logon session in Windows Vista and later, Windows XP Professional x64 Edition, or Windows Server 2003, you must either be a member of the Performance Monitor Users group or have administrative privileges. -> -> To avoid having to elevate your privileges to access performance counters in Windows Vista, add yourself to the Performance Monitor Users group. -> -> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses performance counters, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. ]]> @@ -278,10 +267,6 @@ > [!NOTE] > To read performance counters from a non-interactive logon session in Windows Vista and later, Windows XP Professional x64 Edition, or Windows Server 2003, you must either be a member of the Performance Monitor Users group or have administrative privileges. -> -> To avoid having to elevate your privileges to access performance counters in Windows Vista, add yourself to the Performance Monitor Users group. -> -> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses performance counters, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. ## Examples The following code example creates an instance of the class. The example passes in category names, counter names, and a flag value indicating that the counter is not read-only. This code example is part of a larger example for the class. @@ -303,7 +288,7 @@ -or- - The category specified is not a .NET Framework custom category (if is ). + The category specified is not a .NET custom category (if is ). -or- @@ -369,11 +354,7 @@ To create a performance category instance, specify an `instanceName` on the constructor. If the category instance specified by `instanceName` already exists the new object will reference the existing category instance. > [!NOTE] -> To read performance counters in Windows Vista, Windows XP Professional x64 Edition, or Windows Server 2003, you must either be a member of the Performance Monitor Users group or have administrative privileges. -> -> To avoid having to elevate your privileges to access performance counters in Windows Vista, add yourself to the Performance Monitor Users group. -> -> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses performance counters, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. +> To read performance counters in Windows, you must either be a member of the Performance Monitor Users group or have administrative privileges. ]]> @@ -462,11 +443,7 @@ To create a performance category instance, specify an `instanceName` on the constructor. If the category instance specified by `instanceName` already exists the new object will reference the existing category instance. > [!NOTE] -> To read performance counters in Windows Vista, Windows XP Professional x64 Edition, or Windows Server 2003, you must either be a member of the Performance Monitor Users group or have administrative privileges. -> -> To avoid having to elevate your privileges to access performance counters in Windows Vista, add yourself to the Performance Monitor Users group. -> -> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses performance counters, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. +> To read performance counters in Windows, you must either be a member of the Performance Monitor Users group or have administrative privileges. ]]> @@ -487,7 +464,7 @@ -or- - The category specified is not a .NET Framework custom category (if is ). + The category specified is not a .NET custom category (if is ). -or- @@ -560,11 +537,7 @@ To create a performance category instance, specify an `instanceName` on the constructor. If the category instance specified by `instanceName` already exists the new object will reference the existing category instance. > [!NOTE] -> To read performance counters in Windows Vista, Windows XP Professional x64 Edition, or Windows Server 2003, you must either be a member of the Performance Monitor Users group or have administrative privileges. -> -> To avoid having to elevate your privileges to access performance counters in Windows Vista, add yourself to the Performance Monitor Users group. -> -> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses performance counters, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. +> To read performance counters in Windows, you must either be a member of the Performance Monitor Users group or have administrative privileges. > [!NOTE] > In Windows Vista, when the remote computer is a member of a workgroup, you may need to disable UAC so that the local user account is not filtered and can be elevated to an administrator account. For security reasons, disabling UAC should be a last resort. For information on disabling UAC, see [User Account Control and WMI](/windows/win32/wmisdk/user-account-control-and-wmi). @@ -823,14 +796,7 @@ When you create a new counter, use the text to describe what the counter monitors do so the user can determine whether to add the counter to the System Monitor's display. > [!NOTE] -> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. - -> [!NOTE] -> To read performance counters in Windows Vista, Windows XP Professional x64 Edition, or Windows Server 2003, you must either be a member of the Performance Monitor Users group or have administrative privileges. -> -> To avoid having to elevate your privileges to access performance counters in Windows Vista, add yourself to the Performance Monitor Users group. -> -> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses performance counters, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. +> To read performance counters in Windows, you must either be a member of the Performance Monitor Users group or have administrative privileges. ]]> @@ -940,14 +906,7 @@ When you create a counter whose type requires the use of a corresponding base counter, you must declare the counter and the base in the you pass into the method. > [!NOTE] -> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. - -> [!NOTE] -> To read performance counters in Windows Vista, Windows XP Professional x64 Edition, or Windows Server 2003, you must either be a member of the Performance Monitor Users group or have administrative privileges. -> -> To avoid having to elevate your privileges to access performance counters in Windows Vista, add yourself to the Performance Monitor Users group. -> -> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses performance counters, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. +> To read performance counters in Windows, you must either be a member of the Performance Monitor Users group or have administrative privileges. ]]> @@ -1002,9 +961,6 @@ > [!NOTE] > The , , and methods use interlocks to update the counter value. This helps keep the counter value accurate in multithreaded or multiprocess scenarios, but also results in a performance penalty. If you do not need the accuracy that interlocked operations provide, you can update the property directly for up to a 5 times performance improvement. However, in multithreaded scenarios, some updates to the counter value might be ignored, resulting in inaccurate data. -> [!NOTE] -> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. - ]]> The counter is read-only, so the application cannot decrement it. @@ -1193,9 +1149,6 @@ > [!NOTE] > The , , and methods use interlocks to update the counter value. This helps keep the counter value accurate in multithreaded or multiprocess scenarios, but also results in a performance penalty. If you do not need the accuracy that interlocked operations provide, you can update the property directly for up to a 5 times performance improvement. However, in multithreaded scenarios, some updates to the counter value might be ignored, resulting in inaccurate data. -> [!NOTE] -> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. - ]]> The counter is read-only, so the application cannot increment it. @@ -1256,9 +1209,6 @@ > [!NOTE] > The , , and methods use interlocks to update the counter value. This helps keep the counter value accurate in multithreaded or multiprocess scenarios, but also results in a performance penalty. If you do not need the accuracy that interlocked operations provide, you can update the property directly for up to a 5 times performance improvement. However, in multithreaded scenarios, some updates to the counter value might be ignored, resulting in inaccurate data. -> [!NOTE] -> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. - ## Examples @@ -1317,10 +1267,9 @@ must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. > [!NOTE] -> If the value of the property is , the value for the performance counter must be . +> If the value of the property is , the value for the performance counter must be . ]]> @@ -1489,14 +1438,7 @@ This method is generally used for counters that contain uncalculated values. > [!NOTE] -> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. - -> [!NOTE] -> To read performance counters in Windows Vista, Windows XP Professional x64 Edition, or Windows Server 2003, you must either be a member of the Performance Monitor Users group or have administrative privileges. -> -> To avoid having to elevate your privileges to access performance counters in Windows Vista, add yourself to the Performance Monitor Users group. -> -> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses performance counters, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. +> To read performance counters in Windows, you must either be a member of the Performance Monitor Users group or have administrative privileges. @@ -1622,14 +1564,7 @@ > The , , and methods use interlocks to update the counter value. This helps keep the counter value accurate in multithreaded or multiprocess scenarios, but also results in a performance penalty. If you do not need the accuracy that interlocked operations provide, you can update the property directly for up to a 5 times performance improvement. However, in multithreaded scenarios, some updates to the counter value might be ignored, resulting in inaccurate data. > [!NOTE] -> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. - -> [!NOTE] -> To read performance counters in Windows Vista, Windows XP Professional x64 Edition, or Windows Server 2003, you must either be a member of the Performance Monitor Users group or have administrative privileges. -> -> To avoid having to elevate your privileges to access performance counters in Windows Vista, add yourself to the Performance Monitor Users group. -> -> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses performance counters, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. +> To read performance counters in Windows, you must either be a member of the Performance Monitor Users group or have administrative privileges. @@ -1686,7 +1621,7 @@ Gets or sets a value indicating whether this instance is in read-only mode. - , if the instance is in read-only mode (even if the counter itself is a custom .NET Framework counter); if it is in read/write mode. The default is the value set by the constructor. + , if the instance is in read-only mode (even if the counter itself is a custom .NET counter); if it is in read/write mode. The default is the value set by the constructor. constructor. If the category instance specified by `instanceName` already exists the new object will reference the existing category instance. -> [!NOTE] -> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. - ]]> This counter is read-only, so any instance that is associated with the category cannot be removed. diff --git a/xml/System.Diagnostics/PerformanceCounterCategory.xml b/xml/System.Diagnostics/PerformanceCounterCategory.xml index 8f031dff90c..1639c0dd918 100644 --- a/xml/System.Diagnostics/PerformanceCounterCategory.xml +++ b/xml/System.Diagnostics/PerformanceCounterCategory.xml @@ -58,9 +58,7 @@ > It is strongly recommended that new performance counter categories be created during the installation of the application, not during the execution of the application. This allows time for the operating system to refresh its list of registered performance counter categories. If the list has not been refreshed, the attempt to use the category will fail. > [!NOTE] -> Performance counter categories installed with .NET use separate shared memory, with each performance counter category having its own memory. You can specify the size of separate shared memory by creating a DWORD named FileMappingSize in the registry key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\\*\*\Performance. The FileMappingSize value is set to the shared memory size of the category. The default size is 131072 decimal. If the FileMappingSize value is not present, the `fileMappingSize` attribute value for the `performanceCounters` element specified in the Machine.config file is used, causing additional overhead for configuration file processing. You can realize a performance improvement for application startup by setting the file mapping size in the registry. For more information about the file mapping size, see [<performanceCounters>](/dotnet/framework/configure-apps/file-schema/trace-debug/performancecounters-element). - - +> Performance counter categories installed with .NET use separate shared memory, with each performance counter category having its own memory. You can specify the size of separate shared memory by creating a DWORD named FileMappingSize in the registry key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\\*\*\Performance. The FileMappingSize value is set to the shared memory size of the category. The default size is 131072 decimal. ## Examples The following code example determines whether a and its exist on the local computer or on another computer. If these objects do not exist on the local computer, the example optionally creates them. It uses the method to determine whether the exists. If the does not exist and no counter name is specified, or if the computer is a remote machine, the example exits. @@ -759,14 +757,12 @@ Performance counter categories installed with .NET use separate shared memory, with each performance counter category having its own memory. You can specify the size of separate shared memory by creating a DWORD named FileMappingSize in the registry key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\\*\*\Performance. The FileMappingSize value is set to the shared memory size of the category. The default size is 131072 decimal. If the FileMappingSize value is not present, the `fileMappingSize` attribute value for the `performanceCounters` element specified in the Machine.config file is used, causing additional overhead for configuration file processing. You can realize a performance improvement for application startup by setting the file mapping size in the registry. > [!NOTE] -> It is strongly recommended that new performance counter categories be created during the installation of the application, not during the execution of the application. This allows time for the operating system to refresh its list of registered performance counter categories. If the list has not been refreshed, the attempt to use the category will fail. +> It is strongly recommended that new performance counter categories be created during the installation of the application, not during the execution of the application. This allows time for the operating system to refresh its list of registered performance counter categories. If the list has not been refreshed, the attempt to use the category will fail. > [!NOTE] -> To read performance counters from a non-interactive logon session in Windows Vista and later, Windows XP Professional x64 Edition, or Windows Server 2003, you must either be a member of the Performance Monitor Users group or have administrative privileges. +> To read performance counters from a non-interactive logon session on Windows, you must either be a member of the Performance Monitor Users group or have administrative privileges. > -> To avoid having to elevate your privileges to access performance counters in Windows Vista and later, add yourself to the Performance Monitor Users group. -> -> In Windows Vista and later, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses performance counters, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. +> On Windows, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses performance counters, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. ## Examples The following code example shows the use of the method. The example shows how to create a custom, multi-instance performance counter category for the number of orders per second. diff --git a/xml/System.Diagnostics/PerformanceCounterCategoryType.xml b/xml/System.Diagnostics/PerformanceCounterCategoryType.xml index 3d209935b12..05866654641 100644 --- a/xml/System.Diagnostics/PerformanceCounterCategoryType.xml +++ b/xml/System.Diagnostics/PerformanceCounterCategoryType.xml @@ -32,11 +32,11 @@ Indicates whether the performance counter category can have multiple instances. - enumeration is used to indicate whether a performance counter can have multiple instances. - + enumeration to indicate whether a performance counter can have multiple instances. + ]]> diff --git a/xml/System.Diagnostics/PerformanceCounterPermissionAttribute.xml b/xml/System.Diagnostics/PerformanceCounterPermissionAttribute.xml index a104bb50c0e..55cffef4d30 100644 --- a/xml/System.Diagnostics/PerformanceCounterPermissionAttribute.xml +++ b/xml/System.Diagnostics/PerformanceCounterPermissionAttribute.xml @@ -44,14 +44,12 @@ Allows declarative performance counter permission checks. - diff --git a/xml/System.Diagnostics/PerformanceCounterPermissionEntry.xml b/xml/System.Diagnostics/PerformanceCounterPermissionEntry.xml index 69929fbcffb..a1746f16b5d 100644 --- a/xml/System.Diagnostics/PerformanceCounterPermissionEntry.xml +++ b/xml/System.Diagnostics/PerformanceCounterPermissionEntry.xml @@ -33,19 +33,8 @@ Defines the smallest unit of a code access security permission that is set for a . - - - + To be added. - - - - @@ -86,16 +75,16 @@ Initializes a new instance of the class. To be added. - is . - - -or- - + is . + + -or- + is . - is not a valid value. - - -or- - + is not a valid value. + + -or- + is not a valid computer name. diff --git a/xml/System.Diagnostics/PresentationTraceLevel.xml b/xml/System.Diagnostics/PresentationTraceLevel.xml index aeda0b1767f..96eb6a87de0 100644 --- a/xml/System.Diagnostics/PresentationTraceLevel.xml +++ b/xml/System.Diagnostics/PresentationTraceLevel.xml @@ -23,20 +23,16 @@ Describes the level of detail to trace about a particular object. - is introduced in the .NET Framework version 3.5. For more information, see [Versions and Dependencies](/dotnet/framework/migration-guide/versions-and-dependencies). - - - -## Examples - If you run the application that contains the following XAML under a debugger, the output window provides lines of information describing the status and evaluation of the binding: - - :::code language="xaml" source="~/snippets/csharp/System.Diagnostics/PresentationTraceLevel/Overview/Page1.xaml" id="Snippet1"::: -:::code language="xaml" source="~/snippets/csharp/System.Diagnostics/PresentationTraceLevel/Overview/Page1.xaml" id="Snippet2"::: -:::code language="xaml" source="~/snippets/csharp/System.Diagnostics/PresentationTraceLevel/Overview/Page1.xaml" id="Snippet3"::: - + diff --git a/xml/System.Diagnostics/PresentationTraceSources.xml b/xml/System.Diagnostics/PresentationTraceSources.xml index 90a95e95de9..919883a6ba1 100644 --- a/xml/System.Diagnostics/PresentationTraceSources.xml +++ b/xml/System.Diagnostics/PresentationTraceSources.xml @@ -28,43 +28,10 @@ ## Remarks -Debug tracing is only available when a WPF application is running in full trust mode. - -To enable tracing, you first must set a registry key, then you must configure trace sources. - -- To create the registry key, set a `ManagedTracing` reg_dword value to 1 under "HKeyCurrentUser\Software\Microsoft\Tracing\WPF". - -- To configure trace sources in a .NET Framework app, create an application config file. This file has a .config extension, for example, XamlPad.exe.config. +To enable tracing, you must first set a registry key, and then configure trace sources. To create the registry key, set a `ManagedTracing` reg_dword value to 1 under `HKeyCurrentUser\Software\Microsoft\Tracing\WPF`. Achieving optimal application performance requires forethought in application design and an understanding of best practices for Windows Presentation Foundation (WPF) application development. For more information, see [Optimizing WPF Application Performance](/dotnet/desktop/wpf/advanced/optimizing-wpf-application-performance). -## Examples - The following sample configuration file enables tracing of animations, writing the output to a text file called "debug.txt". This configuration file can only be used with .NET Framework apps. - -```xml - - - - - - - - - - - - - - - - - - -``` - ]]> @@ -240,14 +207,7 @@ switchName="SourceSwitch" > The element from which the property value is read. Gets the value of the attached property for a specified element. The property value for the element. - - is introduced in the .NET Framework version 3.5. For more information, see [Versions and Dependencies](/dotnet/framework/migration-guide/versions-and-dependencies). - - ]]> - + To be added. @@ -276,14 +236,7 @@ switchName="SourceSwitch" > Gets an hwnd host trace source. An hwnd host trace source. - - is introduced in the .NET Framework version 3.5. For more information, see [Versions and Dependencies](/dotnet/framework/migration-guide/versions-and-dependencies). - - ]]> - + To be added. @@ -456,14 +409,7 @@ switchName="SourceSwitch" > The element to which the attached property is written. The needed value. Sets the value of the attached property to a specified element. - - is introduced in the .NET Framework version 3.5. For more information, see [Versions and Dependencies](/dotnet/framework/migration-guide/versions-and-dependencies). - - ]]> - + To be added. @@ -544,14 +490,7 @@ switchName="SourceSwitch" > Identifies the attached property. - - is introduced in the .NET Framework version 3.5. For more information, see [Versions and Dependencies](/dotnet/framework/migration-guide/versions-and-dependencies). - - ]]> - + To be added. diff --git a/xml/System.Diagnostics/Process.xml b/xml/System.Diagnostics/Process.xml index f7ad583d344..947837ef0f4 100644 --- a/xml/System.Diagnostics/Process.xml +++ b/xml/System.Diagnostics/Process.xml @@ -98,16 +98,9 @@ On macOS, the following properties return 0: - - -> [!NOTE] -> This class contains a link demand and an inheritance demand at the class level that applies to all members. A is thrown when either the immediate caller or the derived class does not have full-trust permission. - -## .NET Core Notes - In .NET Framework, the class by default uses encodings, which are typically code-page encodings, for the input, output, and error streams. For example code, on systems whose culture is English (United States), code page 437 is the default encoding for the class. However, .NET Core may make only a limited subset of these encodings available. If this is the case, it uses as the default encoding. - - If a object depends on specific code page encodings, you can still make them available by doing the following *before* you call any methods: +.NET might make only a limited subset of encodings available. If this is the case, the class uses as the default encoding. If a object depends on specific code-page encodings, you can make them available by doing the following *before* you call any methods: 1. Retrieve the object from the property. - 2. Pass the object to the method to make the additional encodings supported by the encoding provider available. The class will then automatically use the default system encoding rather than UTF8, provided that you have registered the encoding provider before calling any methods. @@ -2315,11 +2308,7 @@ You cannot cause processes on remote computers to exit. You can only view inform The process is terminating. You are attempting to call for a process that is running on a remote computer. The method is available only for processes running on the local computer. - .NET Framework only: The process has already exited. - --or- - -There is no process associated with this object. + There is no process associated with this object. -or- @@ -5421,7 +5410,7 @@ There is a similar issue when you read all text from both the standard output an The member of the property is while , , or is . There was an error in opening the associated file. The process object has already been disposed. - Method not supported on operating systems without shell support such as Nano Server (.NET Core only). + Method not supported on operating systems without shell support, such as Nano Server. @@ -5557,7 +5546,7 @@ The member -or- The sum of the length of the arguments and the length of the full path to the process exceeds 2080. The error message associated with this exception can be one of the following: "The data area passed to a system call is too small." or "Access is denied." - Method not supported on operating systems without shell support such as Nano Server (.NET Core only). + Method not supported on operating systems without shell support, such as Nano Server. @@ -5966,7 +5955,7 @@ The file specified in the could not be found. The file specified in the could not be found. The process object has already been disposed. - This member is not supported on Linux or macOS (.NET Core only). + This member is not supported on Linux or macOS. @@ -6072,7 +6061,7 @@ The file specified in the could not be found. The sum of the length of the arguments and the length of the full path to the associated file exceeds 2080. The error message associated with this exception can be one of the following: "The data area passed to a system call is too small." or "Access is denied." The process object has already been disposed. - This member is not supported on Linux or macOS (.NET Core only). + This member is not supported on Linux or macOS. @@ -6219,7 +6208,7 @@ The file specified in the could not be found. You can change the parameters specified in the property up to the time that you call the method on the process. After you start the process, changing the values does not affect or restart the associated process. If you call the method with the and properties set, the unmanaged `CreateProcessWithLogonW` function is called, which starts the process in a new window even if the property value is `true` or the property value is . - You should only access the property on a object returned by the method. For example, you should not access the property on a object returned by . Otherwise, on .NET Core the property will throw an and on .NET Framework it will return a dummy object. + You should only access the property on a object returned by the method. For example, you should not access the property on a object returned by . Otherwise, the property will throw an . When the process is started, the file name is the file that populates the (read-only) property. If you want to retrieve the executable file that is associated with the process after the process has started, use the property. If you want to set the executable file of a instance for which an associated process has not been started, use the property's member. Because the members of the property are arguments that are passed to the method of a process, changing the property after the associated process has started will not reset the property. These properties are used only to initialize the associated process. @@ -6233,7 +6222,7 @@ The file specified in the could not be found. ]]> The value that specifies the is . - .NET Core and .NET 5+ only: The method was not used to start the process. + The method was not used to start the process. @@ -6813,9 +6802,6 @@ The file specified in the could not be found. This method instructs the component to wait an infinite amount of time for the process and event handlers to exit. This can cause an application to stop responding. For example, if you call for a process that has a user interface, the request to the operating system to terminate the associated process might not be handled if the process is written to never enter its message loop. -> [!NOTE] -> In the .NET Framework 3.5 and earlier versions, the overload waited for milliseconds (approximately 24 days), not indefinitely. Also, previous versions did not wait for the event handlers to exit if the full time was reached. - This overload ensures that all processing has been completed, including the handling of asynchronous events for redirected standard output. You should use this overload after a call to the overload when standard output has been redirected to asynchronous event handlers. When an associated process exits (that is, when it is shut down by the operation system through a normal or abnormal termination), the system stores administrative information about the process and returns to the component that had called . The component can then access the information, which includes the , by using the to the exited process. @@ -6901,17 +6887,12 @@ The file specified in the could not be found. This method instructs the component to wait a finite amount of time for the process to exit. If the associated process does not exit by the end of the interval because the request to terminate is denied, `false` is returned to the calling procedure. You can specify for `milliseconds`, and will behave the same as the overload. If you pass 0 (zero) to the method, it returns `true` only if the process has already exited; otherwise, it immediately returns `false`. -> [!NOTE] -> In the .NET Framework 3.5 and earlier versions, if `milliseconds` was -1, the overload waited for milliseconds (approximately 24 days), not indefinitely. - When standard output has been redirected to asynchronous event handlers, it is possible that output processing will not have completed when this method returns. To ensure that asynchronous event handling has been completed, call the overload that takes no parameter after receiving a `true` from this overload. To help ensure that the event is handled correctly in Windows Forms applications, set the property. When an associated process exits (is shut down by the operating system through a normal or abnormal termination), the system stores administrative information about the process and returns to the component that had called . The component can then access the information, which includes the , by using the to the exited process. Because the associated process has exited, the property of the component no longer points to an existing process resource. Instead, the handle can be used only to access the operating system's information about the process resource. The system is aware of handles to exited processes that have not been released by components, so it keeps the and information in memory until the component specifically frees the resources. For this reason, any time you call for a instance, call when the associated process has terminated and you no longer need any administrative information about it. frees the memory allocated to the exited process. - - ## Examples See the code example for the property. diff --git a/xml/System.Diagnostics/ProcessStartInfo.xml b/xml/System.Diagnostics/ProcessStartInfo.xml index 71f3e064f2f..b2e64d946c8 100644 --- a/xml/System.Diagnostics/ProcessStartInfo.xml +++ b/xml/System.Diagnostics/ProcessStartInfo.xml @@ -70,9 +70,6 @@ [!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)] -> [!NOTE] -> This class contains a link demand at the class level that applies to all members. A is thrown when the immediate caller does not have full-trust permission. - ## Examples The following code example demonstrates how to use the class to start Internet Explorer. The destination URLs are provided as arguments. @@ -514,9 +511,7 @@ If you use this property to set command-line arguments, property is `true` or the and properties are not `null`, the property value is ignored and a new window is created. - .NET Core does not support creating windows directly on Unix-like platforms, including macOS and Linux. This property is ignored on such platforms. - - +.NET does not support creating windows directly on Unix-like platforms, including macOS and Linux. This property is ignored on such platforms. ## Examples :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/Overview/processstart.cs" id="Snippet1"::: @@ -629,8 +624,6 @@ If you use this property to set command-line arguments, property, you can modify the generic dictionary returned by the property. For example, the following code adds a TempPath environment variable: `myProcess.StartInfo.Environment.Add("TempPath", "C:\\Temp")`. You must set the property to `false` to start the process after changing the property. If is `true`, an is thrown when the method is called. - On .NET Framework applications, using the property is the same as using the property. - ]]> @@ -1046,7 +1039,7 @@ If you use this property to set command-line arguments, [!NOTE] > Setting the , , and the properties in a object is the recommended practice for starting a process with user credentials. - A object is like a object in that it has a text value. However, the value of a object is automatically encrypted, it can be modified until your application marks it as read-only, and it can be deleted from computer memory by either your application or the .NET Framework garbage collector. + A object is like a object in that it has a text value. However, the value of a object is automatically encrypted, it can be modified until your application marks it as read-only, and it can be deleted from computer memory by either your application or the .NET garbage collector. For more information about secure strings and an example of how to obtain a password to set this property, see the class. @@ -1756,7 +1749,7 @@ You can use asynchronous read operations to avoid these dependencies and their d Gets or sets a value indicating whether to use the operating system shell to start the process. - if the shell should be used when starting the process; if the process should be created directly from the executable file. The default is on .NET Framework apps and on .NET Core apps. + if the shell should be used when starting the process; if the process should be created directly from the executable file. The default is (or on .NET Framework apps). For more information about this API, see Supplemental API remarks for ProcessStartInfo.UseShellExecute. [!NOTE] -> Starting with the .NET Framework version 2.0, the ability to reference performance counter data on other computers has been eliminated for many of the .NET Framework methods and properties. This change was made to improve performance and to enable non-administrators to use the class. As a result, some applications that did not get exceptions in earlier versions of the .NET Framework may now get a . The methods and properties affected are too numerous to list here, but the exception information has been added to the affected member topics. - The threads of a process execute individually and are unaware of each other unless you make them visible to each other. Threads that share common resources, however, must coordinate their work by using semaphores or another method of interprocess communication. To get a collection of all the objects associated with the current process, get the property of the instance. diff --git a/xml/System.Diagnostics/SourceSwitch.xml b/xml/System.Diagnostics/SourceSwitch.xml index 23193bc5870..901c082347e 100644 --- a/xml/System.Diagnostics/SourceSwitch.xml +++ b/xml/System.Diagnostics/SourceSwitch.xml @@ -125,20 +125,7 @@ property. - - To set the level of your in a .NET Framework app, edit the configuration file that corresponds to the name of your application. Within this file, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. To add a source switch, the configuration file should be formatted as shown in the following example. - -```xml - - - - - - - -``` +The `name` parameter is used to set the value of the property. ]]> @@ -191,21 +178,6 @@ ## Remarks The `displayName` parameter is used to set the value of the property; the `defaultSwitchValue` parameter is saved as a field and used to initialize the property on first reference. -> [!NOTE] -> For .NET Framework apps, if the switch is defined in a configuration file and the `value` attribute is specified, the configuration file value takes precedence and the `defaultSwitchValue` is ignored. - -To set the level of your in a .NET Framework app, edit the configuration file that corresponds to the name of your application. Within this file, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. To add a source switch, the configuration file should be formatted as shown in the following example. - -```xml - - - - - - - -``` - ## Examples The following code example creates a with the name "SourceSwitch" and a default value of . This code example is part of a larger example provided for the class. diff --git a/xml/System.Diagnostics/StackFrameExtensions.xml b/xml/System.Diagnostics/StackFrameExtensions.xml index ec6699ee096..857341f6176 100644 --- a/xml/System.Diagnostics/StackFrameExtensions.xml +++ b/xml/System.Diagnostics/StackFrameExtensions.xml @@ -93,7 +93,7 @@ A stack frame. Returns a pointer to the base address of the native image that this stack frame is executing. - A pointer to the base address of the native image or if you're targeting the .NET Framework. + A pointer to the base address of the native image (or if you're targeting .NET Framework). To be added. @@ -138,7 +138,7 @@ A stack frame. Gets an interface pointer to the start of the native code for the method that is being executed. - An interface pointer to the start of the native code for the method that is being executed or if you're targeting the .NET Framework. + An interface pointer to the start of the native code for the method that is being executed (or if you're targeting .NET Framework). To be added. diff --git a/xml/System.Diagnostics/Switch.xml b/xml/System.Diagnostics/Switch.xml index 45696e7b6c0..6f1f8bba682 100644 --- a/xml/System.Diagnostics/Switch.xml +++ b/xml/System.Diagnostics/Switch.xml @@ -60,27 +60,7 @@ This class is the base class for the , , and classes. These switches meet most debugging and tracing needs. For more information about trace switches, see [Trace Switches](/dotnet/framework/debug-trace-profile/trace-switches). - You must enable tracing or debugging to use a switch. The following syntax is compiler specific. If you use compilers other than C# or Visual Basic, refer to the documentation for your compiler. - -- To enable debugging in C#, add the `/d:DEBUG` flag to the compiler command line when you compile your code, or you can add `#define DEBUG` to the top of your file. In Visual Basic, add the `/d:DEBUG=True` flag to the compiler command line. - -- To enable tracing using 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 switch in a .NET Framework app, edit the configuration file that corresponds to the name of your application. Within this file, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. The configuration file should be formatted like the following example: - -```xml - - - - - - - -``` - - This example configuration section defines a with the property set to `mySwitch` and the value set to `true`. Within your application, you can use the configured switch value by creating a with the same name, as shown in the following code example. - - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Switch/Overview/remarks.cs" id="Snippet4"::: + You must enable tracing or debugging to use a switch. ## Examples The following example shows how to define a new class with four levels of tracing that can be used to trace a call stack. You can use the switch to instrument your application to log each time the method is entered or exited. @@ -178,21 +158,6 @@ ## Remarks When you create a new object, the value of the `displayName` parameter is used to find initial switch settings. The default value is an empty string (""). - Within the XML configuration file of a .NET Framework app, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. Dynamic changes to the configuration file are not detected while the application is executing. You must stop and restart an application before changes to the configuration file take effect. The configuration file should be formatted like the following example: - -```xml - - - - - - - - - - -``` - ]]> diff --git a/xml/System.Diagnostics/TextWriterTraceListener.xml b/xml/System.Diagnostics/TextWriterTraceListener.xml index 3f070eddce3..8a2ee48c3a8 100644 --- a/xml/System.Diagnostics/TextWriterTraceListener.xml +++ b/xml/System.Diagnostics/TextWriterTraceListener.xml @@ -63,28 +63,7 @@ This class also provides methods to the so that it no longer receives tracing or debugging output, to the output buffer for the , and to a message to the . - You must enable tracing or debugging to use a trace listener. The following syntax is compiler specific. If you use compilers other than C# or Visual Basic, refer to the documentation for your compiler. - -- To enable debugging in C#, add the `/d:DEBUG` flag to the compiler command line when you compile your code, or you can add `#define DEBUG` to the top of your file. In Visual Basic, add the `/d:DEBUG=True` flag to the compiler command line. - -- 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 add a trace listener in a .NET Framework app, edit the configuration file that corresponds to the name of your application. Within this file, you can add a listener, set its type and set its parameter, remove a listener, or clear all the listeners previously set by the application. The configuration file should be formatted like the following example. - -```xml - - - - - - - - - - -``` + You must enable tracing or debugging to use a trace listener. > [!NOTE] > If an attempt is made to write to a file that is in use or unavailable, the file name is automatically prefixed by a GUID. diff --git a/xml/System.Diagnostics/Trace.xml b/xml/System.Diagnostics/Trace.xml index 71ffc23b6e7..832cb189ce7 100644 --- a/xml/System.Diagnostics/Trace.xml +++ b/xml/System.Diagnostics/Trace.xml @@ -65,28 +65,15 @@ - - - The and classes provide means to dynamically control the tracing output. In .NET Framework apps, you can modify the values of these switches without recompiling your application. For information on using the configuration file to set a switch in a .NET Framework app, see the class and [How to: Create, Initialize, and Configure Trace Switches](/dotnet/framework/debug-trace-profile/how-to-create-initialize-and-configure-trace-switches). + The and classes provide means to dynamically control the tracing output. You can customize the tracing output's target by adding instances to or removing instances from the collection. The collection is shared by both the and the classes; adding a trace listener to either class adds the listener to both. By default, trace output is emitted using the class. > [!NOTE] -> Adding a trace listener to the collection can cause an exception to be thrown while tracing, if a resource used by the trace listener is not available. The conditions and the exception thrown depend on the trace listener and cannot be enumerated in this topic. It may be useful to place calls to the methods in `try`/`catch` blocks to detect and handle any exceptions from trace listeners. - -> [!NOTE] -> If you add trace listeners to partially trusted code, you will get a exception, because adding trace listeners requires permission. To trace partially trusted code that is running in a sandbox in Visual Studio, do not add trace listeners. Instead, view the and messages in the **Output** window. +> Adding a trace listener to the collection can cause an exception to be thrown while tracing, if a resource used by the trace listener is not available. The conditions and the exception thrown depend on the trace listener. It might be useful to place calls to the methods in `try`/`catch` blocks to detect and handle any exceptions from trace listeners. The class provides properties to get or set the level of and the , and whether to after each write. -In .NET Framework apps, you can set the and for by editing the configuration file that corresponds to the name of your application. The configuration file should be formatted like the following example: - -```xml - - - - - -``` - The attribute is applied to the methods of . Compilers that support ignore calls to these methods unless `TRACE` is defined as a conditional compilation symbol. Refer to a compiler's documentation to determine whether is supported and the syntax for defining a conditional compilation symbol. > [!NOTE] @@ -197,21 +184,7 @@ In .NET Framework apps, you can set the [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. - -For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: - -```xml - - - - - - - - - -``` +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). ## Examples The following example creates an index for an array. Then some action is performed that sets the value of the index. Next the code calls to verify the index value is valid. If it is not valid, the outputs the call stack. @@ -309,21 +282,7 @@ For .NET Framework apps, you can change the behavior of the [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. - -For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: - -```xml - - - - - - - - - -``` +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). ## Examples The following example checks to see that the `type` parameter is valid. If the `type` passed in is `null`, the outputs a message. @@ -414,21 +373,7 @@ For .NET Framework apps, you can change the behavior of the [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. - -For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: - -```xml - - - - - - - - - -``` +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). ## Examples The following example checks to see that the `type` parameter is valid. If the `type` passed in is `null`, the outputs a message. @@ -487,24 +432,13 @@ For .NET Framework apps, you can change the behavior of the Gets or sets whether should be called on the after every write. - if is called on the after every write; otherwise, . + if is called on the after every write; otherwise, . The default is . or . Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. - - To set the and for in .NET Framework apps, you can also edit the configuration file that corresponds to the name of your application. The configuration file should be formatted like the following example: -```xml - - - - - -``` +Flushing the stream doesn't flush its underlying encoder unless you explicitly call or . Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. ]]> @@ -720,12 +654,10 @@ For .NET Framework apps, you can change the behavior of the instances in the collection. > [!NOTE] -> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace), the [<remove>](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). +> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). You can customize this behavior by adding a to, or by removing one from, the collection. - - ## Examples The following example uses the method to print a message during exception handling. @@ -811,12 +743,10 @@ For .NET Framework apps, you can change the behavior of the instances in the collection. > [!NOTE] -> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace), the [<remove>](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). +> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). You can customize this behavior by adding a to, or by removing one from, the collection. - - ## Examples The following example uses the method to print a message during exception handling. @@ -1106,16 +1036,6 @@ End of list of errors This property is stored on per-thread/per-request basis. - To set the and for in .NET Framework apps, you can also edit the configuration file that corresponds to the name of your application. The configuration file should be formatted like the following example: - -```xml - - - - - -``` - ]]> @@ -1883,16 +1803,6 @@ End of list of errors ## Remarks The global lock is always used if the trace listener is not thread safe, regardless of the value of . The property is used to determine if the listener is thread safe. The global lock is not used only if the value of is `false` and the value of is `true`. The default behavior is to use the global lock. - To set the for in .NET Framework apps, you can also edit the configuration file that corresponds to the name of your application. The configuration file should be formatted like the following example: - -```xml - - - - - -``` - ]]> diff --git a/xml/System.Diagnostics/TraceLevel.xml b/xml/System.Diagnostics/TraceLevel.xml index 34401bdecc6..d55a77a574c 100644 --- a/xml/System.Diagnostics/TraceLevel.xml +++ b/xml/System.Diagnostics/TraceLevel.xml @@ -51,24 +51,10 @@ ## Remarks This enumeration is used by the class. - You must enable tracing or debugging to use a switch. The following syntax is compiler specific. If you use compilers other than C# or Visual Basic, refer to the documentation for your compiler. - -- To enable debugging in C#, add the `/d:DEBUG` flag to the compiler command line when you compile your code, or you can add `#define DEBUG` to the top of your file. In Visual Basic, add the `/d:DEBUG=True` flag to the compiler command line. - -- 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. + You must enable tracing or debugging to use a switch. For more information on instrumenting your application, see and . -In .NET Framework app configuration files, you can use text to specify the value for a switch. For example, `true` for a , or the text representing an enumeration value such as `Error` for a . The line `` is equivalent to ``. You can also set trace levels using the integer value of the enumeration. The following table shows the relationship between the enumeration members and their corresponding configuration file entries. - -|Trace Level|Configuration File Value| -|-----------------|------------------------------| -|Off|0| -|Error|1| -|Warning|2| -|Info|3| -|Verbose|4| - ]]> diff --git a/xml/System.Diagnostics/TraceListener.xml b/xml/System.Diagnostics/TraceListener.xml index 86374b29d1a..0f5fdd469c0 100644 --- a/xml/System.Diagnostics/TraceListener.xml +++ b/xml/System.Diagnostics/TraceListener.xml @@ -68,28 +68,7 @@ ## Remarks For examples of how to implement a , see the , and the classes. - You must enable tracing or debugging to use a trace listener. The following syntax is compiler specific. If you use compilers other than C# or Visual Basic, refer to the documentation for your compiler. - -- To enable debugging in C#, add the `/d:DEBUG` flag to the compiler command line when you compile your code, or you can add `#define DEBUG` to the top of your file. In Visual Basic, add the `/d:DEBUG=True` flag to the compiler command line. - -- 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 add a trace listener, edit the configuration file that corresponds to the name of your application. Within this file, you can add a listener, set its type and set its parameter, remove a listener, or clear all the listeners previously set by the application. The configuration file should be formatted similar to the following example. - -```xml - - - - - - - - - - -``` - - For more information on using configuration files for tracing, see [<system.diagnostics>](/dotnet/framework/configure-apps/file-schema/trace-debug/system-diagnostics-element). + You must enable tracing or debugging to use a trace listener. ]]> @@ -103,7 +82,6 @@ - <system.diagnostics> Element diff --git a/xml/System.Diagnostics/TraceOptions.xml b/xml/System.Diagnostics/TraceOptions.xml index 3fc5d9c8382..f41d641e9e2 100644 --- a/xml/System.Diagnostics/TraceOptions.xml +++ b/xml/System.Diagnostics/TraceOptions.xml @@ -56,30 +56,10 @@ ## Remarks This enumeration is used by trace listeners to determine which options, or elements, should be included in the trace output. Trace listeners store the trace options in the property. - The following example shows the use of the `traceOutputOptions` attribute to specify the trace output options for a . Using a configuration file like this is only possible in .NET Framework apps. - -```xml - - - - - - - - - -``` - - For details about adding trace listeners to the application configuration file, see [\](/dotnet/framework/configure-apps/file-schema/trace-debug/listeners-element-for-trace). - The enumeration is not used by the following classes and methods: - The class, because it can cause a large volume of data to be written to the log. - - The `Write` and `WriteLine` methods of the , , and classes. - - The and methods of the class when they are not overridden in a derived class. ## Examples diff --git a/xml/System.Diagnostics/TraceSource.xml b/xml/System.Diagnostics/TraceSource.xml index 1effc2b2c90..5378ae58b88 100644 --- a/xml/System.Diagnostics/TraceSource.xml +++ b/xml/System.Diagnostics/TraceSource.xml @@ -57,40 +57,6 @@ ## Remarks The class is used by applications to produce traces that can be associated with the application. provides tracing methods that allow you to easily trace events, trace data, and issue informational traces. -In .NET Framework apps, trace output from can be controlled by configuration file settings. The configuration file is located in the folder with the application executable and has the name of the application with the .config extension added. For example, the name of the configuration file for TraceSourceSample.exe is TraceSourceSample.exe.config. The configuration file can be used to specify where the trace information is to be sent and what levels of activity are to be traced. The following example shows the contents of a sample .NET Framework application configuration file. - -```xml - - - - - - - - - - - - - - - - - - - - - - - - - - -``` - The class is identified by the name of a source, typically the name of the application. The trace messages coming from a particular component can be initiated by a particular trace source, allowing all messages coming from that component to be easily identified. defines tracing methods but does not actually provide any specific mechanism for generating and storing tracing data. The tracing data is produced by trace listeners, which are plug-ins that can be loaded by trace sources. @@ -100,29 +66,16 @@ In .NET Framework apps, trace output from You can customize the tracing output's target by adding or removing instances to or from the collection stored in the property. By default, trace output is produced using an instance of the class. -The preceding .NET Framework app configuration file example demonstrates removing the and adding a to produce the trace output for the trace source. For more information, see [\](/dotnet/framework/configure-apps/file-schema/trace-debug/listeners-element-for-source) and [\](/dotnet/framework/configure-apps/file-schema/trace-debug/sharedlisteners-element). - > [!NOTE] -> Adding a trace listener to the collection can cause an exception to be thrown while tracing, if a resource used by the trace listener is not available. The conditions and the exception thrown depend on the trace listener and cannot be enumerated in this topic. It may be useful to place calls to the methods in `try`/`catch` blocks to detect and handle any exceptions from trace listeners. - - The class provides the means to dynamically control the tracing output. For .NET Framework apps, the preceding configuration file example shows how you can turn off tracing from a trace source and control the level at which tracing occurs. You can modify the value of the source switch without recompiling your application. For information on using the configuration file to set a switch, see and [How to: Create, Initialize and Configure Trace Switches](/dotnet/framework/debug-trace-profile/how-to-create-initialize-and-configure-trace-switches). +> Adding a trace listener to the collection can cause an exception to be thrown while tracing, if a resource used by the trace listener is not available. The conditions and the exception thrown depend on the trace listener. It might be useful to place calls to the methods in `try`/`catch` blocks to detect and handle any exceptions from trace listeners. -> [!NOTE] -> If you modify a configuration file while an application is executing, the application must be stopped and restarted or the method must be called before the new settings take effect. + The class provides the means to dynamically control the tracing output. The enumeration is used to define the event type of the trace message. Trace filters use the to determine if a trace listener should produce the trace message. The trace listeners can optionally have an additional layer of filtering through a trace filter. If a trace listener has an associated filter, the listener calls the method on that filter to determine whether or not to produce the trace information. - The trace listeners use the values of the class properties , , and to format trace output. In .NET Framework apps, you can use configuration file attributes to set the , , and properties. The following example sets the property to `false` and the property to 3. - -```xml - - - - - -``` + The trace listeners use the values of the , , and properties to format trace output. ## Examples The following code example shows the use of the class to forward traces to listeners. The example also demonstrates switch and filter usage. @@ -133,7 +86,6 @@ The preceding .NET Framework app configuration file example demonstrates removin ]]> This type is thread safe. - Trace and Debug Settings Schema @@ -672,19 +624,6 @@ The preceding .NET Framework app configuration file example demonstrates removin ## Remarks The name is set by the `name` parameter passed to the constructor. -You can refer to the trace source by using the `name` attribute in the configuration file of a .NET Framework app. The following XML element shows how to refer to a trace source in the configuration file of a .NET Framework app. - -```xml - - - - - - - - -``` - ## Examples The following code sample shows how to name a trace source in the constructor call. This code example is part of a larger example provided for the class. diff --git a/xml/System.Diagnostics/TraceSwitch.xml b/xml/System.Diagnostics/TraceSwitch.xml index bfc518ebb25..31fa148300b 100644 --- a/xml/System.Diagnostics/TraceSwitch.xml +++ b/xml/System.Diagnostics/TraceSwitch.xml @@ -64,42 +64,12 @@ You can create a in your code and set the level directly to instrument a specific section of code. -In .NET Framework apps only, you can also set the level of a through the application configuration file and then use the configured level in your application. In the application configuration file, you can add or remove a switch, set a switch's value, or clear all the switches previously set by the application. The configuration file should be formatted like the following example: - -```xml - - - - - - - -``` - - This configuration section defines a with the set to `mySwitch`, and the set to 1, which corresponds to the enumeration value . - -> [!NOTE] -> You can also use text to specify the value for a switch. For example, `true` for a , or the text representing an enumeration value, such as `Error` for a . The line `` is equivalent to ``. - - In your application, you can use the configured switch level by creating a with the same name, as shown in the following example: - - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TraceSwitch/Overview/remarks.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/TraceSwitch/Overview/remarks.vb" id="Snippet3"::: - -In .NET Core and .NET 5+ apps, the of the new switch defaults to . - -In .NET Framework apps, the switch property defaults to the value specified in the configuration file. If the constructor cannot find initial switch settings in the configuration file, of the new switch defaults to . - - You must enable tracing or debugging to use a switch. The following syntax is compiler specific. If you use compilers other than C# or Visual Basic, refer to the documentation for your compiler. - -- To enable debugging in C#, add the `/d:DEBUG` flag to the compiler command line when you compile your code, or add `#define DEBUG` to the top of your file. In Visual Basic, add the `/d:DEBUG=True` flag to the compiler command line. - -- 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. + You must enable tracing or debugging to use a switch. > [!NOTE] > These debug and trace compiler switches are not required when using the class in isolation. They are only required in conjunction with or methods that are conditionally compiled. - For more information on instrumenting your application, see and . For more information about configuring and using trace switches, see [Trace Switches](/dotnet/framework/debug-trace-profile/trace-switches). + For more information on instrumenting your application, see and . > [!NOTE] > To improve performance, you can make members `static` in your class. @@ -184,28 +154,7 @@ In .NET Framework apps, the switch p ## Remarks -For .NET Framework apps, to set the level of your , edit the configuration file that corresponds to the name of your application. In this file, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. The configuration file should be formatted like the following example: - -```xml - - - - - - - -``` - -You can also use text to specify the value for a switch. For example, `true` for a or the text representing an enumeration value, such as `Error` for a . The line `` is equivalent to ``. - - In your application, you can use the configured switch level by creating a with the same name, as shown in the following example: - - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TraceSwitch/Overview/remarks.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/TraceSwitch/Overview/remarks.vb" id="Snippet3"::: - -This constructor sets the property of the new switch to . Or, for .NET Framework apps, the switch settings are obtained from the configuration file, if available. - - The class provides the , , , and properties to test the of the switch. The property gets or sets the switch's . +The class provides the , , , and properties to test the of the switch. The property gets or sets the switch's . > [!NOTE] > To improve performance, you can make members `static` in your class. @@ -331,26 +280,7 @@ This constructor sets the property o ## Remarks -For .NET Framework apps, to set the level of your , edit the configuration file that corresponds to the name of your application. In this file, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. The configuration file should be formatted like the following example: - -```xml - - - - - - - - - - -``` - -You can also use text to specify the value for a switch. For example, `true` for a or the text representing an enumeration value, such as `Error` for a . The line `` is equivalent to ``. - -The default value of the property is . Or, for .NET Framework apps, the level is obtained from the configuration file, if available. - - Setting this property updates the , , , and properties to reflect the new value. +Setting this property updates the , , , and properties to reflect the new value. ## Examples The following code example creates a new and uses the switch to determine whether to print error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . @@ -413,9 +343,9 @@ The default value of the property is method is used by the .NET framework to validate and correct the value of a switch initialized via a configuration file. A message is written to all trace listeners if the switch value specified in the configuration file is not defined by the enumeration and the switch is set to a defined value. + The method is used by .NET Framework to validate and correct the value of a switch initialized via a configuration file. A message is written to all trace listeners if the switch value specified in the configuration file is not defined by the enumeration and the switch is set to a defined value. - If you attempt in your code to set the property to a value that is not defined by the enumeration, an exception is thrown. + If you attempt in your code to set the property to a value that is not defined by the enumeration, an is thrown. ]]> diff --git a/xml/System.Diagnostics/XmlWriterTraceListener.xml b/xml/System.Diagnostics/XmlWriterTraceListener.xml index abe519de883..acc7ec9c999 100644 --- a/xml/System.Diagnostics/XmlWriterTraceListener.xml +++ b/xml/System.Diagnostics/XmlWriterTraceListener.xml @@ -39,29 +39,8 @@ ## Remarks -> [!NOTE] -> You must have unmanaged code permission to create an instance of the class. - The class converts tracing and debugging information into an XML-encoded text stream. The description of the XML output is shown in the tables that follow. You can use the [Service Trace Viewer Tool (SvcTraceViewer.exe)](https://learn.microsoft.com/dotnet/framework/wcf/service-trace-viewer-tool-svctraceviewer-exe) to display the XML output. -You can create an in your code. Alternatively, for .NET Framework apps, you can enable or disable an through the application configuration file and then use the configured in your application. To configure an , edit the configuration file that corresponds to the name of your application. In this file, you can add or remove a listener, set the properties for a listener, or remove listeners. The configuration file should be formatted like the following example. - -```xml - - - - - - - - - - -``` - The class inherits the property from the base class . The property allows an additional level of trace output filtering at the listener. If there is a filter present, the `Trace` methods of the trace listener call the method of the filter to determine whether to emit the trace. > [!NOTE] @@ -72,8 +51,8 @@ You can create an in your code. The following table describes the elements and attributes of the XML output. -|Element|Attributes|Output|Notes| -|-------------|----------------|------------|-----------| +| Element | Attributes | Output | Notes | +|---------|------------|--------|-------| |`CallStack`|None|Depends on the presence of the flag in the property.|Special characters such as > or < are replaced with escape sequences. See the escaped character translation table that follows.| |`Computer`|None|Always present.|The value of the property.| |`Correlation`|`ActivityID`|Always present|If not specified, the default is an empty GUID.| @@ -94,15 +73,15 @@ You can create an in your code. The following table shows the characters that are escaped in the XML output. Escaping occurs in all the elements and attributes with the exception of the `DataItem` element, which is not escaped if the object passed to the `data` parameter of the method is an object. If an is used for the data object, the method is called and the entire root node is traced as unescaped data. -|Escaped character|Value| -|-----------------------|-----------| -|&|&| -|\<|<| -|>|>| -|"|"| -|\|'| -|0xD|&\#xD;| -|0xA|&\#xA;| +| Escaped character | Value | +|-------------------|--------| +| & | & | +| \< | < | +| > | > | +| " | " | +| \ | ' | +| 0xD | &\#xD; | +| 0xA | &\#xA; | ## Examples The following code example shows the use of the class to write both escaped and non-escaped data to file logs. diff --git a/xml/System.Globalization/Calendar.xml b/xml/System.Globalization/Calendar.xml index c82e6267941..9c2736f0695 100644 --- a/xml/System.Globalization/Calendar.xml +++ b/xml/System.Globalization/Calendar.xml @@ -2528,7 +2528,7 @@ Only the and the property contains the default calendar week rule that can be used for the `rule` parameter. > [!NOTE] -> This does not map exactly to ISO 8601. The differences are discussed in the blog entry [ISO 8601 Week of Year format in Microsoft .NET](https://learn.microsoft.com/archive/blogs/shawnste/iso-8601-week-of-year-format-in-microsoft-net). Starting with .NET Core 3.0, and solve this problem. +> This does not map exactly to ISO 8601. The differences are discussed in the blog entry [ISO 8601 Week of Year format in Microsoft .NET](https://learn.microsoft.com/archive/blogs/shawnste/iso-8601-week-of-year-format-in-microsoft-net). and solve this problem. The following example uses the current culture's object to determine that January 1, 2011 is in the first week of the year in the Gregorian calendar. diff --git a/xml/System.Globalization/CalendarWeekRule.xml b/xml/System.Globalization/CalendarWeekRule.xml index 240bad5c951..9d28492738b 100644 --- a/xml/System.Globalization/CalendarWeekRule.xml +++ b/xml/System.Globalization/CalendarWeekRule.xml @@ -108,7 +108,7 @@ :::code language="vb" source="~/snippets/visualbasic/System.Globalization/CalendarWeekRule/Overview/calendarweekruleex.vb" id="Snippet1"::: > [!NOTE] -> This does not map exactly to ISO 8601. The differences are discussed in the blog entry [ISO 8601 Week of Year format in Microsoft .NET](https://learn.microsoft.com/archive/blogs/shawnste/iso-8601-week-of-year-format-in-microsoft-net). Starting with .NET Core 3.0, and solve this problem. +> This does not map exactly to ISO 8601. The differences are discussed in the blog entry [ISO 8601 Week of Year format in Microsoft .NET](https://learn.microsoft.com/archive/blogs/shawnste/iso-8601-week-of-year-format-in-microsoft-net). and solve this problem. Each object supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , set the property of to a new . diff --git a/xml/System.Globalization/CharUnicodeInfo.xml b/xml/System.Globalization/CharUnicodeInfo.xml index b57682399d1..dc59aaf54ab 100644 --- a/xml/System.Globalization/CharUnicodeInfo.xml +++ b/xml/System.Globalization/CharUnicodeInfo.xml @@ -75,25 +75,19 @@ Use the class to obtain the value for a specific character. The class defines methods that return the following Unicode character values: - The specific category to which a character or surrogate pair belongs. The value returned is a member of the enumeration. - - Numeric value. Applies only to numeric characters, including fractions, subscripts, superscripts, Roman numerals, currency numerators, encircled numbers, and script-specific digits. - - Digit value. Applies to numeric characters that can be combined with other numeric characters to represent a whole number in a numbering system. - - Decimal digit value. Applies only to characters that represent decimal digits in the decimal (base 10) system. A decimal digit can be one of ten digits, from zero through nine. These characters are members of the category. In addition, the class is used internally by a number of other .NET types and methods that rely on character classification. These include: - The class, which works with textual elements instead of single characters in a string. - - The overloads of the method, which determine the category to which a character or surrogate pair belongs. - - The [character classes](/dotnet/standard/base-types/character-classes-in-regular-expressions) recognized by , .NET's regular expression engine. When using this class in your applications, keep in mind the following programming considerations for using the type. The type can be difficult to use, and strings are generally preferable for representing linguistic content. - A object does not always correspond to a single character. Although the type represents a single 16-bit value, some characters (such as grapheme clusters and surrogate pairs) consist of two or more UTF-16 code units. For more information, see "Char Objects and Unicode Characters" in the class. - - The notion of a "character" is also flexible. A character is often thought of as a glyph, but many glyphs require multiple code points. For example, ä can be represented either by two code points ("a" plus U+0308, which is the combining diaeresis), or by a single code point ("ä" or U+00A4). Some languages have many letters, characters, and glyphs that require multiple code points, which can cause confusion in linguistic content representation. For example, there is a ΰ (U+03B0, Greek small letter upsilon with dialytika and tonos), but there is no equivalent capital letter. Uppercasing such a value simply retrieves the original value. ## Examples @@ -105,19 +99,7 @@ When using this class in your applications, keep in mind the following programmi ]]> - Recognized characters and the specific categories to which they belong are defined by the Unicode standard and can change from one version of the Unicode Standard to another. Categorization of characters in a particular version of .NET Framework is based on a single version of the Unicode Standard, regardless of the underlying operating system on which .NET Framework is running. The following table lists versions of .NET Framework since .NET Framework 4 and the versions of the Unicode Standard used to classify characters. - -| .NET Framework version | Unicode Standard version | -| - | - | -| .NET Framework 4 | 5.0.0 | -| .NET Framework 4.5 | 5.0.0 | -| .NET Framework 4.5.1 | 5.0.0 | -| .NET Framework 4.5.2 | 5.0.0 | -| .NET Framework 4.6 | 6.3.0 | -| .NET Framework 4.6.1 | 6.3.0 | -| .NET Framework 4.6.2 | 8.0.0 | - -Each version of the Unicode standard includes information on changes to the Unicode character database since the previous version. The Unicode character database is used by the class for categorizing characters. + Recognized characters and the specific categories to which they belong are defined by the Unicode standard and can change from one version of the Unicode Standard to another. Categorization of characters in a particular version of .NET is based on a single version of the Unicode Standard, regardless of the underlying operating system on which .NET is running. Each version of the Unicode standard includes information on changes to the Unicode character database since the previous version. The Unicode character database is used by the class for categorizing characters. diff --git a/xml/System.Globalization/ChineseLunisolarCalendar.xml b/xml/System.Globalization/ChineseLunisolarCalendar.xml index 474010b7c0f..1145302cdf2 100644 --- a/xml/System.Globalization/ChineseLunisolarCalendar.xml +++ b/xml/System.Globalization/ChineseLunisolarCalendar.xml @@ -72,7 +72,7 @@ The class is derived from the class, which represents the lunisolar calendar. The class supports the sexagenary year cycle (which repeats every 60 years) in addition to solar years and lunar months. Each solar year in the calendar is associated with a Sexagenary Year, a Celestial Stem, and a Terrestrial Branch, and these calendars can have leap months after any month of the year. The class calculates years based on solar calculations, and months and days based on lunar calculations. > [!NOTE] -> For information about using the class and the other calendar classes in the .NET Framework, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). +> For information about using the class and the other calendar classes in .NET, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). A leap month can occur after any month in a year. For example, the method returns a number between 1 and 13 that indicates the month associated with a specified date. If there is a leap month between the eighth and ninth months of the year, the method returns 8 for the eighth month, 9 for the leap eighth month, and 10 for the ninth month. diff --git a/xml/System.Globalization/CompareInfo.xml b/xml/System.Globalization/CompareInfo.xml index 859f8f0c1d9..2a45163860c 100644 --- a/xml/System.Globalization/CompareInfo.xml +++ b/xml/System.Globalization/CompareInfo.xml @@ -1337,11 +1337,11 @@ The behavior of this overload is dependent on its implementation, which might change from one version of the common language runtime to another, or from one .NET implementation to another. > [!IMPORTANT] -> If two character spans are equal, this overload returns identical values. However, there is not a unique hash code value for each unique character span value. Different character spans can return the same hash code. +> If two character spans are equal, this overload returns identical values. However, there is not a unique hash code value for each unique character span value. Different character spans can return the same hash code. > -> The hash code itself is not guaranteed to be stable. Hash codes for identical character spans can differ across versions of the .NET implementations and across platforms (such as 32-bit and 64-bit) for a single version of .NET. +> The hash code itself is not guaranteed to be stable. Hash codes for identical character spans can differ across versions of the .NET implementations and across platforms (such as 32-bit and 64-bit) for a single version of .NET. > -> As a result, hash codes should never be used outside of the application domain in which they were created, they should never be used as key fields in a collection, and they should never be persisted. +> As a result, hash codes should not be treated as unique identifiers, they should not be persisted, and they should not be used outside the current process. ]]> @@ -1402,14 +1402,12 @@ is dependent on its implementation, which might change from one version of the common language runtime to another, or from one .NET Framework platform to another. + The behavior of is dependent on its implementation, which might change from one version of the common language runtime to another, or from one platform to another. > [!IMPORTANT] -> If two string objects are equal, the method returns identical values. However, there is not a unique hash code value for each unique string value. Different strings can return the same hash code. +> If two string objects are equal, the method returns identical values. However, there is not a unique hash code value for each unique string value. Different strings can return the same hash code. > -> The hash code itself is not guaranteed to be stable. Hash codes for identical strings can differ across versions of the .NET Framework and across platforms (such as 32-bit and 64-bit) for a single version of the .NET Framework. In some cases, they can even differ by application domain. -> -> As a result, hash codes should never be used outside of the application domain in which they were created, they should never be used as key fields in a collection, and they should never be persisted. +> The hash code itself is not guaranteed to be stable. Hash codes for identical strings can differ across versions of .NET and across platforms (such as 32-bit and 64-bit) for a single version of .NET. Hash codes shouldn't be treated as unique identifiers, persisted, or used outside the current process. ]]> @@ -5306,14 +5304,10 @@ This method has greater overhead than other method. It returns a string that consists of the class name and the value of the instance property, separated by a hyphen. +This method overrides the method. It returns a string that consists of the class name followed by a space, a hyphen, a space, and the value of the property. ]]> - - Staring with the .NET Framework 4, the method returns the class name followed by a space, a hyphen, a space, and the value of the property. For example, for a object that represents the en-US culture, the method returns "CompareInfo - en-US". In previous versions of the .NET Framework, it returns the class name followed by a space, a hyphen, a space, and the value of the property. For example, for a object that represents the en-US culture, the method returns "CompareInfo - 1033". - @@ -5361,13 +5355,7 @@ This method has greater overhead than other object returned by the property doesn't identify the precise Unicode version used to compare strings. It is useful only when comparing two objects to determine whether they use the same Unicode version and culture to compare strings. For more information and an example, see the reference page. diff --git a/xml/System.Globalization/CultureInfo.xml b/xml/System.Globalization/CultureInfo.xml index 0637afc6402..4c11f4c43c7 100644 --- a/xml/System.Globalization/CultureInfo.xml +++ b/xml/System.Globalization/CultureInfo.xml @@ -169,13 +169,10 @@ Predefined culture identifiers for cultures available on Windows system are list For example, suppose that Arabic (Saudi Arabia) is the current Windows culture and the user has changed the calendar from Hijri to Gregorian. - With `CultureInfo("0x0401")` (culture name ar-SA), is set to (which is the user setting) and is set to `true`. - - With `CultureInfo("0x041E")` (culture name th-TH), is set to (which is the default calendar for th-TH) and is set to `true`. - For cultures that use the euro, .NET Framework and Windows XP set the default currency as euro. However, older versions of Windows do not. Therefore, if the user of an older version of Windows has not changed the currency setting through the regional and language options portion of Control Panel, the currency might be incorrect. To use the .NET Framework default setting for the currency, the application should use a constructor overload that accepts a `useUserOverride` parameter and set it to `false`. - > [!NOTE] -> For backwards compatibility, a culture constructed using a `culture` parameter of 0x0004 or 0x7c04 will have a property of `zh-CHS` or `zh-CHT`, respectively. You should instead prefer to construct the culture using the current standard culture names of `zh-Hans` or `zh-Hant`, unless you have a reason for using the older names. +> For backwards compatibility, a culture constructed using a `culture` parameter of 0x0004 or 0x7c04 has a property of `zh-CHS` or `zh-CHT`, respectively. You should instead prefer to construct the culture using the current standard culture names of `zh-Hans` or `zh-Hant`, unless you have a reason for using the older names. > [!NOTE] > LCIDs are being deprecated, and implementers are strongly encouraged to use newer versions of APIs that support BCP 47 locale names instead. Each LCID can be represented by a BCP 47 locale name, but the reverse is not true. The LCID range is restricted and unable to uniquely identify all the possible combinations of language and region. @@ -187,8 +184,8 @@ Predefined culture identifiers for cultures available on Windows system are list is not a valid culture identifier. See the Notes to Callers section for more information. - .NET Framework 3.5 and earlier versions throw an if is not a valid culture identifier. Starting with .NET Framework 4, this constructor throws a . Starting with apps that run under .NET Framework 4 or later on Windows 7 or later, the method attempts to retrieve a object whose identifier is from the operating system; if the operating system does not support that culture, the method throws a exception. - On .NET 6 and later versions, a is thrown if the app is running in an environment where globalization-invariant mode is enabled, for example, some Docker containers, and a culture other than the invariant culture is specified. + This method attempts to retrieve a object whose identifier is from the operating system; if the operating system does not support that culture, the method throws a exception. + A is also thrown if the app is running in an environment where globalization-invariant mode is enabled, for example, some Docker containers, and a culture other than the invariant culture is specified. @@ -273,8 +270,8 @@ The property of the new is not a valid culture name. For more information, see the Notes to Callers section. - .NET Framework 3.5 and earlier versions throw an if is not a valid culture name. Starting with .NET Framework 4, this constructor throws a . Starting with apps that run under .NET Framework 4 or later on Windows 7 or later, the method attempts to retrieve a object whose identifier is from the operating system; if the operating system does not support that culture, and if is not the name of a supplementary or replacement culture, the method throws a exception. - On .NET 6 and later versions, a is thrown if the app is running in an environment where globalization-invariant mode is enabled, for example, some Docker containers, and a culture other than the invariant culture is specified. + This method attempts to retrieve a object whose identifier is from the operating system; if the operating system does not support that culture, and if is not the name of a supplementary or replacement culture, the method throws a exception. + A is also thrown if the app is running in an environment where globalization-invariant mode is enabled, for example, some Docker containers, and a culture other than the invariant culture is specified. @@ -347,18 +344,13 @@ Predefined culture identifiers available on Windows systems are listed in the ** The value of the `useUserOverride` parameter becomes the value of the property. - For example, suppose that Arabic (Saudi Arabia) is the current culture of Windows and the user has changed the calendar from Hijri to Gregorian. +For example, suppose that Arabic (Saudi Arabia) is the current culture of Windows and the user has changed the calendar from Hijri to Gregorian. - With `CultureInfo("0x0401", true)` (culture name ar-SA), is set to (which is the user setting) and is set to `true`. - - With `CultureInfo("0x0401", false)` (culture name ar-SA), is set to (which is the default calendar for ar-SA) and is set to `false`. - - With `CultureInfo("0x041E", true)` (culture name th-TH), is set to (which is the default calendar for th-TH) and is set to `true`. - - With `CultureInfo("0x041E", false)` (culture name th-TH), is set to (which is the default calendar for th-TH) and is set to `false`. - For cultures that use the euro, the .NET Framework and Windows XP set the default currency as euro. However, older versions of Windows do not. Therefore, if the user of an older version of Windows has not changed the currency setting through the regional and language options portion of Control Panel, the currency might be incorrect. To use the .NET Framework default setting for the currency, the application should set the `useUserOverride` parameter to `false`. - > [!NOTE] > For backwards compatibility, a culture constructed using a `culture` parameter of 0x0004 or 0x7c04 will have a property of zh-CHS or zh-CHT, respectively. You should instead prefer to construct the culture using the current standard culture names of `zh-Hans` or zh-Hant, unless you have a reason for using the older names. @@ -372,8 +364,8 @@ Predefined culture identifiers available on Windows systems are listed in the ** is not a valid culture identifier. See the Notes to Callers section for more information. - .NET Framework 3.5 and earlier versions throw an if is not a valid culture identifier. Starting with .NET Framework 4, this constructor throws a . Starting with apps that run under .NET Framework 4 or later on Windows 7 or later, the method attempts to retrieve a object whose identifier is from the operating system; if the operating system does not support that culture, the method throws a exception. - On .NET 6 and later versions, a is thrown if the app is running in an environment where globalization-invariant mode is enabled, for example, some Docker containers, and a culture other than the invariant culture is specified. + This method attempts to retrieve a object whose identifier is from the operating system; if the operating system does not support that culture, the method throws a exception. + A is also thrown if the app is running in an environment where globalization-invariant mode is enabled, for example, some Docker containers, and a culture other than the invariant culture is specified. @@ -455,8 +447,6 @@ If `name` is , the constr The property of the new is set to the culture identifier associated with the specified name. - For cultures that use the euro, the .NET Framework and Windows XP set the default currency as euro. However, older versions of Windows do not do this. Therefore, if the user of an older version of Windows has not changed the currency setting through the regional and language options portion of Control Panel, the currency might be incorrect. To use the .NET Framework default setting for the currency, the application should set the `useUserOverride` parameter to `false`. - ]]> @@ -464,8 +454,8 @@ If `name` is , the constr is not a valid culture name. See the Notes to Callers section for more information. - .NET Framework 3.5 and earlier versions throw an if is not a valid culture name. Starting with .NET Framework 4, this constructor throws a . Starting with apps that run under .NET Framework 4 or later on Windows 7 or later, the method attempts to retrieve a object whose identifier is from the operating system; if the operating system does not support that culture, and if is not the name of a supplementary or replacement culture, the method throws a exception. - On .NET 6 and later versions, a is thrown if the app is running in an environment where globalization-invariant mode is enabled, for example, some Docker containers, and a culture other than the invariant culture is specified. + This method attempts to retrieve a object whose identifier is from the operating system; if the operating system does not support that culture, and if is not the name of a supplementary or replacement culture, the method throws a exception. + A is also thrown if the app is running in an environment where globalization-invariant mode is enabled, for example, some Docker containers, and a culture other than the invariant culture is specified. @@ -814,13 +804,14 @@ If `name` is , the constr -or- - The culture specified by does not have a specific culture associated with it. + The culture specified by does not have a specific culture associated with it. + + -or- + + The app is running in an environment where globalization-invariant mode is enabled, for example, some Docker containers, and a culture other than the invariant culture is specified. + is null. - - .NET Framework 3.5 and earlier versions throw an if is not a valid culture name. Starting with .NET Framework 4, this method throws a . - On .NET 6 and later versions, a is thrown if the app is running in an environment where globalization-invariant mode is enabled, for example, some Docker containers, and a culture other than the invariant culture is specified. - @@ -1126,32 +1117,31 @@ You might choose to override some of the values associated with the current cult System.Globalization.CultureInfo - Gets or sets the default culture for threads in the current application domain. - The default culture for threads in the current application domain, or if the current system culture is the default thread culture in the application domain. + Gets or sets the default culture for threads. + The default culture for threads, or if the current system culture is the default thread culture. property enables an application to define the default culture of all threads in an application domain. - -> [!IMPORTANT] -> If you have not explicitly set the culture of any existing threads executing in an application domain, setting the property also changes the culture of these threads. However, if these threads execute in another application domain, their culture is defined by the property in that application domain or, if no default value is defined, by the default system culture. Because of this, we recommend that you always explicitly set the culture of your main application thread, and not rely on the property to define the culture of the main application thread. - Unless it is set explicitly, the value of the property is `null`, and the culture of threads in an application domain that have not been assigned an explicit culture is defined by the default Windows system culture. +The property enables an application to define the default culture of all threads. - For more information about cultures, threads, and application domains, see the "Culture and threads" and "Culture and application domains" sections in the reference page. +> [!IMPORTANT] +> If you have not explicitly set the culture of any existing threads, setting the property also changes the culture of these threads. You should always explicitly set the culture of your main application thread, and not rely on the property to define the culture of the main application thread. + Unless it is set explicitly, the value of the property is `null`, and the culture of threads that have not been assigned an explicit culture is defined by the default Windows system culture. + For more information about cultures and threads, see the "Culture and threads" section in the reference page. ## Examples - The following example illustrates the default behavior of the .NET Framework in defining the current culture of a new thread. At startup, the example sets the current culture and the current UI culture to French (France) on all systems except those on which the default system culture is already French (France). If the default system culture is already French (France), the code sets the current culture and the current UI culture to English (United States). It then calls the `DisplayRandomNumbers` routine, which generates three random numbers and displays them as currency values. Next, it creates a new thread, which also executes the `DisplayRandomNumbers` routine. + The following example illustrates the default behavior of .NET in defining the current culture of a new thread. At startup, the example sets the current culture and the current UI culture to French (France) on all systems except those on which the default system culture is already French (France). If the default system culture is already French (France), the code sets the current culture and the current UI culture to English (United States). It then calls the `DisplayRandomNumbers` routine, which generates three random numbers and displays them as currency values. Next, it creates a new thread, which also executes the `DisplayRandomNumbers` routine. :::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureInfo/DefaultThreadCurrentCulture/defaultculture1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/CultureInfo/DefaultThreadCurrentCulture/defaultculture1.vb" id="Snippet1"::: As the output from the example shows, when the example is run on a computer whose system culture is English (United States), the main thread displays its currency values using the formatting conventions of the French (France) culture. However, because the worker thread's culture is derived from the current Windows system culture rather than the application's current culture, the work thread displays its currency values using the formatting conventions of the English (United States) culture. - The following example uses the and properties to define the current culture and current UI culture of a new application thread. At startup, the example sets the current culture and the current UI culture to French (France) on all systems except those on which the default system culture is already French (France). If the default system culture is already French (France), it sets the current culture and the current UI culture to English (United States). It then calls the `DisplayRandomNumbers` routine, which generates three random numbers and displays them as currency values. Next, it creates a new thread, which also executes the `DisplayRandomNumbers` routine. + The following example uses the and properties to define the current culture and current UI culture of a new application thread. At startup, the example sets the current culture and the current UI culture to French (France) on all systems except those on which the default system culture is already French (France). If the default system culture is already French (France), it sets the current culture and the current UI culture to English (United States). It then calls the `DisplayRandomNumbers` routine, which generates three random numbers and displays them as currency values. Next, it creates a new thread, which also executes the `DisplayRandomNumbers` routine. :::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureInfo/DefaultThreadCurrentCulture/defaultculture2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/CultureInfo/DefaultThreadCurrentCulture/defaultculture2.vb" id="Snippet2"::: @@ -1211,20 +1201,21 @@ You might choose to override some of the values associated with the current cult System.Globalization.CultureInfo - Gets or sets the default UI culture for threads in the current application domain. - The default UI culture for threads in the current application domain, or if the current system UI culture is the default thread UI culture in the application domain. + Gets or sets the default UI culture for threads. + The default UI culture for threads, or if the current system UI culture is the default thread UI culture. property lets you define the default UI culture of all threads in an application domain. + +The property lets you define the default UI culture of all threads. > [!IMPORTANT] -> If you have not explicitly set the UI culture of any existing threads executing in an application domain, setting the property also changes the culture of these threads. However, if these threads execute in another application domain, their culture is defined by the property in that application domain or, if no default value is defined, by the default system culture. Because of this, we recommend that you always explicitly set the culture of your main application thread and do not rely on the property to define the culture of the main application thread. +> If you have not explicitly set the UI culture of any existing threads, setting the property also changes the culture of these threads. You should always explicitly set the culture of your main application thread, and not rely on the property to define the culture of the main application thread. - Unless it is set explicitly, the value of the property is `null`, and the current culture of all threads in an application domain that have not been assigned an explicit culture is defined by the default Windows system culture. + Unless it is set explicitly, the value of the property is `null`, and the current culture of all threads that have not been assigned an explicit culture is defined by the default Windows system culture. - For more information about cultures, threads, and application domains, see the "Culture and threads" and "Culture and application domains" sections of . + For more information about cultures and threads, see the "Culture and threads" section of . ## Examples The following example illustrates the default behavior of .NET in defining the current culture of a new thread. It uses English and Russian language resources. The following text file named GreetingStrings.txt contains the English language resources: @@ -1421,10 +1412,6 @@ csc /resource:GreetingStrings.resources Example1.cs ## Remarks For example, the for the specific culture name en-US is "English (United States)". - The value of this property is the same, regardless of the language version of the .NET Framework. - - - ## Examples The following code example displays several properties of the neutral cultures. @@ -1739,8 +1726,8 @@ csc /resource:GreetingStrings.resources Example1.cs specifies a culture that is not supported. See the Notes to Caller section for more information. - .NET Framework 3.5 and earlier versions throw an if is not a valid culture identifier. Starting with .NET Framework 4, this method throws a . Starting with apps that run under .NET Framework 4 or later on Windows 7 or later, the method attempts to retrieve a object whose identifier is from the operating system; if the operating system does not support that culture, the method throws a . - On .NET 6 and later versions, a is thrown if the app is running in an environment where globalization-invariant mode is enabled, for example, some Docker containers, and a culture other than the invariant culture is specified. + This method attempts to retrieve a object whose identifier is from the operating system; if the operating system does not support that culture, the method throws a . + A is also thrown if the app is running in an environment where globalization-invariant mode is enabled, for example, some Docker containers, and a culture other than the invariant culture is specified. @@ -1811,8 +1798,8 @@ For a list of predefined culture names on Windows systems, see the **Language ta specifies a culture that is not supported. See the Notes to Callers section for more information. - .NET Framework 3.5 and earlier versions throw an if is not a valid culture name. Starting with .NET Framework 4, this method throws a . Starting with apps that run under .NET Framework 4 or later on Windows 7 or later, the method attempts to retrieve a object whose identifier is from the operating system; if the operating system does not support that culture, and if is not the name of a supplementary or replacement culture, the method throws a . - On .NET 6 and later versions, a is thrown if the app is running in an environment where globalization-invariant mode is enabled, for example, some Docker containers, and a culture other than the invariant culture is specified. + This method attempts to retrieve a object whose identifier is from the operating system; if the operating system does not support that culture, and if is not the name of a supplementary or replacement culture, the method throws a . + A is also thrown if the app is running in an environment where globalization-invariant mode is enabled, for example, some Docker containers, and a culture other than the invariant culture is specified. @@ -1931,8 +1918,8 @@ Setting `predefinedOnly` to `true` will ensure a culture is created only if the or specifies a culture that is not supported. See the Notes to Callers section for more information. - .NET Framework 3.5 and earlier versions throw an if or is not a valid culture name. Starting with .NET Framework 4, this method throws a . Starting with apps that run under .NET Framework 4 or later on Windows 7 or later, the method attempts to retrieve a object whose identifier is from the operating system; if the operating system does not support that culture, and if is not the name of a supplementary or replacement culture, the method throws a exception. - On .NET 6 and later versions, a is thrown if the app is running in an environment where globalization-invariant mode is enabled, for example, some Docker containers, and a culture other than the invariant culture is specified. + This method attempts to retrieve a object whose identifier is from the operating system; if the operating system does not support that culture, and if is not the name of a supplementary or replacement culture, the method throws a exception. + A is also thrown if the app is running in an environment where globalization-invariant mode is enabled, for example, some Docker containers, and a culture other than the invariant culture is specified. @@ -2005,9 +1992,6 @@ Setting `predefinedOnly` to `true` will ensure a culture is created only if the is null. does not correspond to a supported culture. - - .NET Framework 3.5 and earlier versions throw an if does not correspond to the name of a supported culture. Starting with .NET Framework 4, this method throws a . - @@ -2764,14 +2748,7 @@ For a list of predefined culture names and identifiers that the Gets the culture name, consisting of the language, the country/region, and the optional script, that the culture is set to display. The culture name, consisting of the full name of the language, the full name of the country/region, and the optional script. The format is discussed in the description of the class. - - - + To be added. diff --git a/xml/System.Globalization/CultureNotFoundException.xml b/xml/System.Globalization/CultureNotFoundException.xml index 410f3799278..18b1c302524 100644 --- a/xml/System.Globalization/CultureNotFoundException.xml +++ b/xml/System.Globalization/CultureNotFoundException.xml @@ -76,14 +76,12 @@ ## Remarks A exception is thrown whenever the construction of an invalid culture is eventually attempted within a method. Most commonly, this exception is thrown when a call to one of the following methods fails to create or return a culture: -- constructors. - +- constructors. - The method. - - The method. > [!WARNING] -> On Windows 7 and later operating systems, the .NET Framework retrieves culture data from the operating system. The exception is thrown if the operating system is unable to find the culture, and the culture is not a custom culture or a replacement culture. +> .NET retrieves culture data from the operating system. The exception is thrown if the operating system is unable to find the culture, and the culture is not a custom culture or a replacement culture. If the calling code attempted to instantiate a object by using a culture name, the property contains the invalid name, and the property of the object returned by the property is `false`. If the calling code attempted to instantiate a object by using a culture identifier, the property of the object returned by the property contains the invalid identifier, and the value of the property is `null`. diff --git a/xml/System.Globalization/CultureTypes.xml b/xml/System.Globalization/CultureTypes.xml index e49bcc3b2e1..e1f053584dd 100644 --- a/xml/System.Globalization/CultureTypes.xml +++ b/xml/System.Globalization/CultureTypes.xml @@ -131,7 +131,7 @@ The following example demonstrates the `CultureTypes.AllCultures` enumeration me All cultures that are recognized by .NET, including neutral and specific cultures and custom cultures created by the user. -On .NET Framework 4 and later versions and .NET Core running on Windows, it includes the culture data available from the Windows operating system. On .NET Core running on Linux and macOS, it includes culture data defined in the ICU libraries. +On Windows, it includes the culture data available from the Windows operating system. On Linux and macOS, it includes culture data defined in the ICU libraries. is a composite field that includes the , , and values. @@ -183,7 +183,7 @@ On .NET Framework 4 and later versions and .NET Core running on Windows, it incl 64 - **This member is deprecated**; using this value with returns neutral and specific cultures shipped with .NET Framework 2.0. + **This member is deprecated.** Specifies neutral and specific cultures shipped with .NET Framework 2.0. @@ -305,7 +305,7 @@ On .NET Framework 4 and later versions and .NET Core running on Windows, it incl 16 - **This member is deprecated.** Custom cultures created by the user that replace cultures shipped with the .NET Framework. + **This member is deprecated.** Specifies custom cultures created by the user that replace cultures shipped with .NET Framework. @@ -436,12 +436,10 @@ On .NET Framework 4 and later versions and .NET Core running on Windows, it incl 32 - **This member is deprecated** and is ignored. + **This member is deprecated and ignored.** method on .NET Framework 4 and later versions, the method returns an empty array. +If used as an argument to the method, the method returns an empty array. ]]> diff --git a/xml/System.Globalization/EastAsianLunisolarCalendar.xml b/xml/System.Globalization/EastAsianLunisolarCalendar.xml index 870eddde7bb..14102d33830 100644 --- a/xml/System.Globalization/EastAsianLunisolarCalendar.xml +++ b/xml/System.Globalization/EastAsianLunisolarCalendar.xml @@ -66,7 +66,7 @@ The class supports the sexagenary cycle of years (which repeats every 60 years) in addition to solar years and lunar months. Each solar year in the calendar is associated with a Sexagenary Year (see ), a Celestial Stem (see ), and a Terrestrial Branch (see ). > [!NOTE] -> For information about using the class and the other calendar classes in the .NET Framework, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). +> For information about using the class and the other calendar classes in .NET, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). A year can have a leap month after any month of the year, and a month can have a leap day. For example, the method returns a positive integer that indicates the month associated with a specified date. If there is a leap month between the eighth and ninth months of the year, the method returns 8 for the eighth month, 9 for the leap eighth month, and 10 for the ninth month. diff --git a/xml/System.Globalization/GregorianCalendar.xml b/xml/System.Globalization/GregorianCalendar.xml index 6b6f38cc51a..b464ebdb238 100644 --- a/xml/System.Globalization/GregorianCalendar.xml +++ b/xml/System.Globalization/GregorianCalendar.xml @@ -73,7 +73,7 @@ The Gregorian calendar recognizes two eras: B.C. or B.C.E., and A.D. or C.E. This implementation of the class recognizes only the current era (A.D. or C.E.). > [!NOTE] -> For information about using the class and the other calendar classes in the .NET Framework, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). +> For information about using the class and the other calendar classes in .NET, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). A leap year in the Gregorian calendar is defined as a year that is evenly divisible by 4, unless it is divisible by 100. However, years that are divisible by 400 are leap years. For example, the year 1900 was not a leap year, but the year 2000 was. A common year has 365 days and a leap year has 366 days. @@ -82,7 +82,7 @@ > [!IMPORTANT] > By default, all and values express dates and times in the Gregorian calendar. - The Gregorian calendar was developed as a replacement for the Julian calendar (which is represented by the class) and was first introduced in a small number of cultures on October 15, 1582. When working with historic dates that precede a culture's adoption of the Gregorian calendar, you should use the original calendar if it is available in the .NET Framework. For example, Denmark changed from the Julian calendar to the Gregorian calendar on February 19 (in the Julian calendar) or March 1 (in the Gregorian calendar) of 1700. In this case, for dates before the adoption of the Gregorian calendar, you should use the Julian calendar. However, note that no culture offers intrinsic support for the class. You must use the class as a standalone calendar. For more information, see [Working with calendars](/dotnet/standard/datetime/working-with-calendars). + The Gregorian calendar was developed as a replacement for the Julian calendar (which is represented by the class) and was first introduced in a small number of cultures on October 15, 1582. When working with historic dates that precede a culture's adoption of the Gregorian calendar, you should use the original calendar if it is available in .NET. For example, Denmark changed from the Julian calendar to the Gregorian calendar on February 19 (in the Julian calendar) or March 1 (in the Gregorian calendar) of 1700. In this case, for dates before the adoption of the Gregorian calendar, you should use the Julian calendar. However, no culture offers intrinsic support for the class. You must use the class as a standalone calendar. For more information, see [Working with calendars](/dotnet/standard/datetime/working-with-calendars). The following example illustrates that February 18, 1700 in the Julian calendar, which is the last day the Julian calendar was officially used in Denmark, is one day earlier than March 1, 1700 in the Gregorian calendar. @@ -502,7 +502,7 @@ type found in the .NET Framework and displays the value of its property. + The following example uses reflection to instantiate each type in .NET and displays the value of its property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AlgorithmType/algorithmtype1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AlgorithmType/algorithmtype1.vb" id="Snippet1"::: diff --git a/xml/System.Globalization/HebrewCalendar.xml b/xml/System.Globalization/HebrewCalendar.xml index 100038f2794..0e350accf06 100644 --- a/xml/System.Globalization/HebrewCalendar.xml +++ b/xml/System.Globalization/HebrewCalendar.xml @@ -73,7 +73,7 @@ The Hebrew calendar recognizes two eras: B.C.E. (before the common era) and A.M. (Latin "Anno Mundi", which means "the year of the world"). This implementation of the class recognizes only the current era (A.M.) and the Hebrew years 5343 to 5999 (1583 to 2239 in the Gregorian calendar). > [!NOTE] -> For information about using the class and the other calendar classes in the .NET Framework, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). +> For information about using the class and the other calendar classes in .NET, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). In every 19-year cycle that ends with a year that is evenly divisible by 19, the 3rd, 6th, 8th, 11th, 14th, 17th, and 19th years are leap years. A common year can have from 353 to 355 days, depending on the placement of Jewish holidays. A leap year can have from 383 to 385 days. @@ -390,7 +390,7 @@ type found in the .NET Framework and displays the value of its property. + The following example uses reflection to instantiate each type in .NET and displays the value of its property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AlgorithmType/algorithmtype1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AlgorithmType/algorithmtype1.vb" id="Snippet1"::: diff --git a/xml/System.Globalization/HijriCalendar.xml b/xml/System.Globalization/HijriCalendar.xml index 04c93a2aec3..dc5c5d9d142 100644 --- a/xml/System.Globalization/HijriCalendar.xml +++ b/xml/System.Globalization/HijriCalendar.xml @@ -73,7 +73,7 @@ The Hijri calendar recognizes one era: A.H. (Latin "Anno Hegirae", which means "the year of the migration," in reference to the migration of Muhammad (PBUH) from Mecca). > [!NOTE] -> For information about using the class and the other calendar classes in the .NET Framework, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). +> For information about using the class and the other calendar classes in .NET, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). In every 30-year cycle that ends with a year that is evenly divisible by 30, the 2nd, 5th, 7th, 10th, 13th, 16th, 18th, 21st, 24th, 26th, and 29th years are leap years. A common year has 354 days and a leap year has 355 days. @@ -377,7 +377,7 @@ type found in the .NET Framework and displays the value of its property. + The following example uses reflection to instantiate each type in .NET and displays the value of its property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AlgorithmType/algorithmtype1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AlgorithmType/algorithmtype1.vb" id="Snippet1"::: diff --git a/xml/System.Globalization/IdnMapping.xml b/xml/System.Globalization/IdnMapping.xml index bcb48aa37ed..194547904e9 100644 --- a/xml/System.Globalization/IdnMapping.xml +++ b/xml/System.Globalization/IdnMapping.xml @@ -73,20 +73,10 @@ The IDNA mechanism uses Punycode to map an internationalized domain name that contains Unicode characters outside the US-ASCII character range to the US-ASCII character range supported by the domain name system. The IDNA mechanism is used to convert only domain names, not data transmitted over the Internet. -> [!IMPORTANT] -> In the .NET Framework 4.5, the class supports different versions of the IDNA standard, depending on the operating system in use: -> -> - When run on Windows 8, it supports the 2008 version of the IDNA standard outlined by [RFC 5891: Internationalized Domain Names in Applications (IDNA): Protocol](https://datatracker.ietf.org/doc/html/rfc5891). -> - When run on earlier versions of the Windows operating system, it supports the 2003 version of the standard outlined by [RFC 3490: Internationalizing Domain Names in Applications (IDNA)](https://www.rfc-editor.org/rfc/rfc3490.txt). -> -> See [Unicode Technical Standard #46: IDNA Compatibility Processing](https://www.unicode.org/reports/tr46/) for the differences in the way these standards handle particular sets of characters. - The method normalizes a domain name, converts the normalized name to a representation that consists of displayable Unicode characters in the US-ASCII code point range (U+0020 to U+007E), and prepends an ASCII-compatible encoding (ACE) prefix ("xn--") to each label. The method restores the domain name labels converted by the method. If the string to be converted includes the label separator characters IDEOGRAPHIC FULL STOP (U+3002), FULLWIDTH FULL STOP (U+FF0E), and HALFWIDTH IDEOGRAPHIC FULL STOP (U+FF61), the method converts them to the label separator FULL STOP (period, U+002E). The method, however, does not restore the original label separator character. - - ## Examples The following example uses the method to convert an array of internationalized domain names to Punycode. The method then converts the Punycode domain name back to the original domain name, but replaces the original label separators with the standard label separator. @@ -354,15 +344,6 @@ is . is invalid based on the and properties, and the IDNA standard. - - In the .NET Framework 4.5, the class supports different versions of the IDNA standard, depending on the operating system in use: - -- When run on Windows 8, it supports the 2008 version of the IDNA standard outlined by RFC 5891: Internationalized Domain Names in Applications (IDNA): Protocol. - -- When run on earlier versions of the Windows operating system, it supports the 2003 version of the standard outlined by RFC 3490: Internationalizing Domain Names in Applications (IDNA). - - See Unicode Technical Standard #46: IDNA Compatibility Processing for the differences in the way these standards handle particular sets of characters. - @@ -448,15 +429,6 @@ is greater than the length of . is invalid based on the and properties, and the IDNA standard. - - In the .NET Framework 4.5, the class supports different versions of the IDNA standard, depending on the operating system in use: - -- When run on Windows 8, it supports the 2008 version of the IDNA standard outlined by RFC 5891: Internationalized Domain Names in Applications (IDNA): Protocol. - -- When run on earlier versions of the Windows operating system, it supports the 2003 version of the standard outlined by RFC 3490: Internationalizing Domain Names in Applications (IDNA). - - See Unicode Technical Standard #46: IDNA Compatibility Processing for the differences in the way these standards handle particular sets of characters. - @@ -552,15 +524,6 @@ is greater than the length of minus . is invalid based on the and properties, and the IDNA standard. - - In the .NET Framework 4.5, the class supports different versions of the IDNA standard, depending on the operating system in use: - -- When run on Windows 8, it supports the 2008 version of the IDNA standard outlined by RFC 5891: Internationalized Domain Names in Applications (IDNA): Protocol. - -- When run on earlier versions of the Windows operating system, it supports the 2003 version of the standard outlined by RFC 3490: Internationalizing Domain Names in Applications (IDNA). - - See Unicode Technical Standard #46: IDNA Compatibility Processing for the differences in the way these standards handle particular sets of characters. - diff --git a/xml/System.Globalization/JapaneseCalendar.xml b/xml/System.Globalization/JapaneseCalendar.xml index 0ef6df274d7..18183f931a4 100644 --- a/xml/System.Globalization/JapaneseCalendar.xml +++ b/xml/System.Globalization/JapaneseCalendar.xml @@ -1677,7 +1677,7 @@ The following code example gets the minimum value and the maximum value of the c The earliest date supported by the class is October 23, 1868 C.E., in the first year of the Meiji era. Ordinarily, date and time operations that use the class throw an exception for dates before this date. However, some members, such as the method, support dates from January 1, 1868 through October 22 in the year Meiji 1. > [!NOTE] -> In .NET Framework versions and in .NET Core 1.0 through .NET 10, this property returns a date and time representing the first moment of September 8, 1868 C.E. in the Gregorian calendar. +> In .NET 10 and earlier versions, this property returns a date and time representing the first moment of September 8, 1868 C.E. in the Gregorian calendar. ## Examples diff --git a/xml/System.Globalization/JulianCalendar.xml b/xml/System.Globalization/JulianCalendar.xml index 80b884c161f..f6979e0cb92 100644 --- a/xml/System.Globalization/JulianCalendar.xml +++ b/xml/System.Globalization/JulianCalendar.xml @@ -73,7 +73,7 @@ In 45 B.C., Julius Caesar ordered a calendar reform, which resulted in the calendar called the Julian calendar. The Julian calendar is the predecessor of the Gregorian calendar. > [!NOTE] -> For information about using the class and the other calendar classes in the .NET Framework, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). +> For information about using the class and the other calendar classes in .NET, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). The class recognizes only the current era. @@ -362,7 +362,7 @@ type found in the .NET Framework and displays the value of its property. + The following example uses reflection to instantiate each type in .NET and displays the value of its property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AlgorithmType/algorithmtype1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AlgorithmType/algorithmtype1.vb" id="Snippet1"::: diff --git a/xml/System.Globalization/KoreanCalendar.xml b/xml/System.Globalization/KoreanCalendar.xml index f572b80ec66..d845d6b71bf 100644 --- a/xml/System.Globalization/KoreanCalendar.xml +++ b/xml/System.Globalization/KoreanCalendar.xml @@ -73,7 +73,7 @@ The Korean calendar is exactly like the Gregorian calendar, except that the year and era are different. > [!NOTE] -> For information about using the class and the other calendar classes in the .NET Framework, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). +> For information about using the class and the other calendar classes in .NET, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). The class recognizes only the current era. @@ -378,7 +378,7 @@ type found in the .NET Framework and displays the value of its property. + The following example uses reflection to instantiate each type in .NET and displays the value of its property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AlgorithmType/algorithmtype1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AlgorithmType/algorithmtype1.vb" id="Snippet1"::: diff --git a/xml/System.Globalization/KoreanLunisolarCalendar.xml b/xml/System.Globalization/KoreanLunisolarCalendar.xml index 2fd831d3630..94b67d4d71b 100644 --- a/xml/System.Globalization/KoreanLunisolarCalendar.xml +++ b/xml/System.Globalization/KoreanLunisolarCalendar.xml @@ -72,7 +72,7 @@ The class is derived from the class, which represents the lunisolar calendar. The class supports the sexagenary year cycle (which repeats every 60 years) in addition to solar years and lunar months. Each solar year in the calendar is associated with a Sexagenary Year, a Celestial Stem, and a Terrestrial Branch, and these calendars can have leap months after any month of the year. > [!NOTE] -> For information about using the class and the other calendar classes in the .NET Framework, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). +> For information about using the class and the other calendar classes in .NET, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). The class calculates years using the Gregorian calendar, and days and months using the class. @@ -423,7 +423,7 @@ diff --git a/xml/System.Globalization/NumberFormatInfo.xml b/xml/System.Globalization/NumberFormatInfo.xml index 93e44a0d701..5b131b5a0b1 100644 --- a/xml/System.Globalization/NumberFormatInfo.xml +++ b/xml/System.Globalization/NumberFormatInfo.xml @@ -590,7 +590,7 @@ On Windows, the initial value of this property is derived from the settings in t ]]> - The property is set to a value that's less than 0 or greater than 16. On .NET Framework, this exception is thrown if the value is greater than 15. + The property is set to a value that's less than 0 or greater than 16. The property is being set and the object is read-only. diff --git a/xml/System.Globalization/PersianCalendar.xml b/xml/System.Globalization/PersianCalendar.xml index 294432bb77b..37009761b88 100644 --- a/xml/System.Globalization/PersianCalendar.xml +++ b/xml/System.Globalization/PersianCalendar.xml @@ -334,10 +334,8 @@ ## Remarks A date calculation for a particular calendar depends on whether the calendar is solar-based, lunar-based, or lunisolar-based. - - ## Examples - The following example uses reflection to instantiate each type found in the .NET Framework and displays the value of its property. + The following example uses reflection to instantiate each type in .NET and displays the value of its property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AlgorithmType/algorithmtype1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AlgorithmType/algorithmtype1.vb" id="Snippet1"::: @@ -1252,12 +1250,8 @@ class has changed from an observational algorithm to the Hijri solar algorithm. As a result, the method may return different values when run on .NET Framework 4.6 than when run on previous versions of the .NET Framework. - - - ## Examples + The following code example demonstrates the use of the method. :::code language="csharp" source="~/snippets/csharp/System.Globalization/PersianCalendar/Overview/pcal.cs" id="Snippet1"::: @@ -1320,11 +1314,7 @@ property is the last moment of December 31, 9999 C.E. in the Gregorian calendar. In the .NET Framework 4.6, this value is equivalent to the 13th day of the 10th month of the year 9378 in the Persian calendar. In previous versions of the .NET Framework, it is equivalent to the 10th day of the 10th month of the year 9378 in the Persian calendar. For more information, see "The PersianCalendar class and .NET Framework versions" in the topic. - - 9999 C.E. is equivalent to the year 9378 in the Persian calendar. - - + The value of the property is the last moment of December 31, 9999 C.E. in the Gregorian calendar. This value is equivalent to the 13th day of the 10th month of the year 9378 in the Persian calendar. ## Examples The following code example demonstrates the use of the property. @@ -1384,11 +1374,10 @@ property is equivalent to the first moment of March 22, 622 C.E. in the Gregorian calendar. In previous versions of the .NET Framework, it is equivalent to the first moment of March 21, 622 C.E. in the Gregorian calendar. For more information, see "The PersianCalendar class and .NET Framework versions" in the topic. - - 622 C.E. is equivalent to the year 0001 in the Persian calendar. +The value of the property is equivalent to the first moment of March 22, 622 C.E. in the Gregorian calendar. +622 C.E. is equivalent to the year 0001 in the Persian calendar. ## Examples The following code example demonstrates the use of the property. diff --git a/xml/System.Globalization/RegionInfo.xml b/xml/System.Globalization/RegionInfo.xml index 2452182d51c..cd14546f38a 100644 --- a/xml/System.Globalization/RegionInfo.xml +++ b/xml/System.Globalization/RegionInfo.xml @@ -144,7 +144,7 @@ The culture identifier is mapped to the corresponding National Language Support (NLS) locale identifier. For more information, see [Windows LCID reference](/openspecs/windows_protocols/ms-lcid/a9eac961-e77d-41a6-90a5-ce1a8b0cdb9c). -The value of the property of the new object instantiated by calling this constructor is the ISO 3166 2-letter code for the country/region, not the combined language and country/region code. For example, if a object is instantiated with the culture identifier 0x0409 for the English (United States) culture, the value of the property is "US". In contrast, if a object is instantiated with the combined language and country/region code `en-US` for the English (United States) culture, the value of the property is "en-US" in .NET Framework and just "US" in .NET Core and .NET 5+. +The value of the property of the new object instantiated by calling this constructor is the ISO 3166 2-letter code for the country/region, not the combined language and country/region code. For example, if a object is instantiated with the culture identifier 0x0409 for the English (United States) culture, the value of the property is "US". In contrast, if a object is instantiated with the combined language and country/region code `en-US` for the English (United States) culture, the value of the property is "en-US" in .NET Framework and just "US" in modern .NET. ## Examples @@ -1094,7 +1094,7 @@ The following code example displays the properties of the object is created with the constructor that takes a culture identifier parameter, the property value is one of the two-letter codes defined in ISO 3166 for the country/region and is formatted in uppercase. For example, the two-letter code for the United States is "US". -If the current object is created with the constructor and is passed a full culture name such as "en-US", the property value is a full culture name in .NET Framework and just the region name in .NET Core and .NET 5+. +If the current object is created with the constructor and is passed a full culture name such as "en-US", the property value is a full culture name in .NET Framework and just the region name in modern .NET. ## Examples diff --git a/xml/System.Globalization/StringInfo.xml b/xml/System.Globalization/StringInfo.xml index 0e84ac29e5a..974bf762511 100644 --- a/xml/System.Globalization/StringInfo.xml +++ b/xml/System.Globalization/StringInfo.xml @@ -108,7 +108,7 @@ This example uses the - Internally, the methods of the class call the methods of the class to determine character categories. Starting with the .NET Framework 4.6.2, character classification is based on The Unicode Standard, Version 8.0.0. For the .NET Framework 4 through the .NET Framework 4.6.1, it is based on The Unicode Standard, Version 6.3.0. In .NET Core, it is based on The Unicode Standard, Version 8.0.0. + Internally, the methods of the class call the methods of the class to determine character categories. In modern .NET, character classification is based on The Unicode Standard, Version 8.0.0. Sorting Weight Tables for Windows operating systems Default Unicode Collation Element Table, for Linux and macOS @@ -903,10 +903,9 @@ A grapheme cluster is a sequence of one or more Unicode code points that should The length of each element is easily computed as the difference between successive indexes. The length of the array will always be less than or equal to the length of the string. For example, given the string "\u4f00\u302a\ud800\udc00\u4f01", this method returns the indexes 0, 2, and 4. -## Equivalent Members - Starting in version 2.0 of the .NET Framework, the method and property provide an easy to use implementation of the functionality offered by the method. - +## Equivalent members +The method and property provide an easy to use implementation of the functionality offered by the method. ## Examples The following example demonstrates calling the method. This code example is part of a larger example provided for the class. diff --git a/xml/System.Globalization/TaiwanCalendar.xml b/xml/System.Globalization/TaiwanCalendar.xml index 914c5837c32..3268ebf481e 100644 --- a/xml/System.Globalization/TaiwanCalendar.xml +++ b/xml/System.Globalization/TaiwanCalendar.xml @@ -73,7 +73,7 @@ The Taiwan calendar works exactly like the Gregorian calendar, except that the year and era are different. The class recognizes only the current era. > [!NOTE] -> For information about using the class and the other calendar classes in the .NET Framework, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). +> For information about using the class and the other calendar classes in .NET, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). Leap years in the Taiwan calendar correspond to the same leap years in the Gregorian calendar. A leap year in the Gregorian calendar is defined as a Gregorian year that is evenly divisible by four, except if it is divisible by 100. However, Gregorian years that are divisible by 400 are leap years. A common year has 365 days and a leap year has 366 days. @@ -368,7 +368,7 @@ type found in the .NET Framework and displays the value of its property. + The following example uses reflection to instantiate each type in .NET and displays the value of its property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AlgorithmType/algorithmtype1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AlgorithmType/algorithmtype1.vb" id="Snippet1"::: diff --git a/xml/System.Globalization/TaiwanLunisolarCalendar.xml b/xml/System.Globalization/TaiwanLunisolarCalendar.xml index 73a345cfe53..28bf2ca7aae 100644 --- a/xml/System.Globalization/TaiwanLunisolarCalendar.xml +++ b/xml/System.Globalization/TaiwanLunisolarCalendar.xml @@ -72,7 +72,7 @@ The Taiwan lunisolar calendar works exactly like the Gregorian calendar, except that the year and era are different. The class calculates years using the Gregorian calendar, days and months using the class, and recognizes only the current era. > [!NOTE] -> For information about using the class and the other calendar classes in the .NET Framework, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). +> For information about using the class and the other calendar classes in .NET, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). The class is derived from the class, which represents the lunisolar calendar. The class supports the sexagenary year cycle (which repeats every 60 years) in addition to solar years and lunar months. Each solar year in the calendar is associated with a Sexagenary Year, a Celestial Stem, and a Terrestrial Branch, and these calendars can have leap months after any month of the year. diff --git a/xml/System.Globalization/TextElementEnumerator.xml b/xml/System.Globalization/TextElementEnumerator.xml index 81df14be720..aaa26e34611 100644 --- a/xml/System.Globalization/TextElementEnumerator.xml +++ b/xml/System.Globalization/TextElementEnumerator.xml @@ -74,12 +74,11 @@ value. For example, LATIN CAPITAL LETTER A (U+0041) and LATIN SMALL LETTER AE (U+00E6) are base characters. - -- A combining character sequence, which consists of a base character and one or more combining characters. For example, example, LATIN CAPITAL LETTER A (U+0041) followed by COMBINING MACRON (U+0304) is a combining character sequence. +.NET defines a text element as a unit of text that's displayed as a single character, that is, a grapheme. A text element can be any of the following: +- A base character, which is represented as a single value. For example, LATIN CAPITAL LETTER A (U+0041) and LATIN SMALL LETTER AE (U+00E6) are base characters. +- A combining character sequence, which consists of a base character and one or more combining characters. For example, LATIN CAPITAL LETTER A (U+0041) followed by COMBINING MACRON (U+0304) is a combining character sequence. - Surrogate pairs, which the [Unicode Standard](https://www.unicode.org/) defines as a coded character representation for a single abstract character that consists of a sequence of two code units: a high surrogate, and a low surrogate. Surrogate pairs are used to represent characters outside of the Unicode Basic Multilingual Plane as UTF-16 encoded characters. For example, GOTHIC LETTER SAUIL (U+10343) is represented in UTF-16 encoding as a high surrogate whose value is 0xD800 and a low surrogate whose value is 0xDF43. A surrogate pair can represent a base character or a combining character. The class allows you to work with the text elements in a string rather than with single objects. @@ -91,15 +90,10 @@ The object represents a snapshot of the current state of a string variable or string literal at the moment that the object is instantiated. Note that: - Text element enumerators can only be used to read data in a string. They cannot modify the underlying string. - - An enumerator does not have exclusive access to the string that it represents. A string variable can be modified after the enumerator is created. - - A object enumerates the text elements present in the string at the time that the object was instantiated. It does not reflect any subsequent changes to the string variable if that variable is modified afterward. - - Because the class does not override , two objects that represent the same string will be considered unequal. - - ## Examples The following example uses the class to enumerate the text elements of a string. diff --git a/xml/System.Globalization/ThaiBuddhistCalendar.xml b/xml/System.Globalization/ThaiBuddhistCalendar.xml index 45ab221d6f5..fc3bbd2c429 100644 --- a/xml/System.Globalization/ThaiBuddhistCalendar.xml +++ b/xml/System.Globalization/ThaiBuddhistCalendar.xml @@ -73,7 +73,7 @@ The Thai Buddhist calendar works exactly like the Gregorian calendar, except that the year and era are different. > [!NOTE] -> For information about using the class and the other calendar classes in the .NET Framework, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). +> For information about using the class and the other calendar classes in .NET, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). The class recognizes only the current era. @@ -365,7 +365,7 @@ type found in the .NET Framework and displays the value of its property. + The following example uses reflection to instantiate each type in .NET and displays the value of its property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AlgorithmType/algorithmtype1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AlgorithmType/algorithmtype1.vb" id="Snippet1"::: diff --git a/xml/System.Globalization/UmAlQuraCalendar.xml b/xml/System.Globalization/UmAlQuraCalendar.xml index f856b39b35d..546247f4d8c 100644 --- a/xml/System.Globalization/UmAlQuraCalendar.xml +++ b/xml/System.Globalization/UmAlQuraCalendar.xml @@ -72,7 +72,7 @@ The class is nearly identical to the class, except the Um Al Qura calendar uses a table-based algorithm licensed from the Saudi government to calculate dates, can express dates to the year 1500 A.H., and does not support the property. > [!NOTE] -> For information about using the class and the other calendar classes in the .NET Framework, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). +> For information about using the class and the other calendar classes in .NET, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). For the class, each month has either 29 or 30 days, but usually in no discernible order. Whereas the documentation for the Hijri Calendar gives a table that shows the corresponding days in each month, no such general table can be produced for the Um Al Qura calendar. @@ -342,7 +342,7 @@ type found in the .NET Framework and displays the value of its property. + The following example uses reflection to instantiate each type in .NET and displays the value of its property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AlgorithmType/algorithmtype1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AlgorithmType/algorithmtype1.vb" id="Snippet1"::: @@ -1376,13 +1376,6 @@ [!NOTE] -> Starting with the .NET Framework 4.5, the value of the property is 11/16/2077. In previous versions of the .NET Framework, its value is the last moment of May 13, 2029 C.E. in the Gregorian calendar. - - - ## Examples The following example displays the date ranges supported by the class in both the Gregorian and Um Al Qura calendars. diff --git a/xml/System.Net/AuthenticationManager.xml b/xml/System.Net/AuthenticationManager.xml index b147319374f..f95df311e33 100644 --- a/xml/System.Net/AuthenticationManager.xml +++ b/xml/System.Net/AuthenticationManager.xml @@ -134,29 +134,8 @@ The credentials associated with this request. Calls each registered authentication module to find the first module that can respond to the authentication request. An instance of the class containing the result of the authorization attempt. If there is no authentication module to respond to the challenge, this method returns . - - method calls the method on each registered authentication module until one of the module responds with an instance. - - The first instance returned is used to authenticate the request. If no authentication module can authenticate the request, the method returns `null`. - - Authentication modules are called in the order in which they are registered with the . - - ]]> - - .NET Core and .NET 5+ only: In all cases. - - is . - - -or- - - is . - - -or- - - is . + To be added. + In all cases. @@ -349,19 +328,8 @@ The credentials associated with the request. Preauthenticates a request. An instance of the class if the request can be preauthenticated; otherwise, . If is , this method returns . - - method returns an Authentication instance and sends the authorization information to the server preemptively instead of waiting for the resource to issue a challenge. This behavior is outlined in section 3.3 of RFC 2617 (HTTP Authentication: Basic and Digest Access Authentication). Authentication modules that support preauthentication allow clients to improve server efficiency by avoiding extra round trips caused by authentication challenges. - - Authorization modules that can preauthenticate requests set the property to `true`. - - ]]> - - .NET Core and .NET 5+ only: In all cases. - - is . + To be added. + In all cases. diff --git a/xml/System.Net/BindIPEndPoint.xml b/xml/System.Net/BindIPEndPoint.xml index 439d16d7365..54bae821b42 100644 --- a/xml/System.Net/BindIPEndPoint.xml +++ b/xml/System.Net/BindIPEndPoint.xml @@ -67,7 +67,7 @@ ## Remarks Specify that the delegate is used by a by setting the property with the delegate as an argument. This delegate should specify a local IP address and port number in the returned . - If the .NET Framework cannot bind the returned to the after attempts, an is thrown. + If .NET cannot bind the returned to the after attempts, an is thrown. If you want the delegate to give the service point control of the connection binding, the delegate should return `null`. If you want to abort the connection, the delegate must throw an exception. diff --git a/xml/System.Net/Dns.xml b/xml/System.Net/Dns.xml index dd729a60c5c..5d2a7ff11c3 100644 --- a/xml/System.Net/Dns.xml +++ b/xml/System.Net/Dns.xml @@ -140,7 +140,7 @@ The method asynchronously queries a DNS server for the IP addresses that are associated with a host name. If `hostNameOrAddress` is an IP address, this address is returned without querying the DNS server. > [!NOTE] -> This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). +> This member emits trace information when you enable network tracing in your application. If an empty string is passed as the `hostNameOrAddress` argument, then this method returns the IPv4 and IPv6 addresses of the local host. @@ -247,7 +247,7 @@ For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). > [!NOTE] -> This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). +> This member emits trace information when you enable network tracing in your application. ]]> @@ -334,7 +334,7 @@ ## Remarks The method asynchronously queries a DNS server for the IP addresses and aliases associated with an IP address. - **Note** This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). + **Note** This member emits trace information when you enable network tracing in your application. The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the `requestCallback` delegate. @@ -426,7 +426,7 @@ ## Remarks The method queries a DNS server for the IP address that is associated with a host name or IP address. - **Note** This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). + **Note** This member emits trace information when you enable network tracing in your application. The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the `requestCallback` delegate. @@ -539,7 +539,7 @@ For more information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). > [!NOTE] -> This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). +> This member emits trace information when you enable network tracing in your application. ]]> @@ -600,7 +600,7 @@ If an empty string is passed as the `hostNameOrAddress` argument, then this method returns the IPv4 and IPv6 addresses of the local host. > [!NOTE] -> This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). +> This member emits trace information when you enable network tracing in your application. ]]> @@ -674,7 +674,7 @@ If the property is set to `true`, the property of the instance returned is not populated by this method and will always be empty. > [!NOTE] -> This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). +> This member emits trace information when you enable network tracing in your application. ]]> @@ -736,7 +736,7 @@ To perform this operation synchronously, use a method. > [!NOTE] -> This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). +> This member emits trace information when you enable network tracing in your application. ]]> @@ -812,7 +812,7 @@ To perform this operation synchronously, use the method. > [!NOTE] -> This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). +> This member emits trace information when you enable network tracing in your application. ]]> @@ -876,7 +876,7 @@ This method is implemented using the underlying operating system's name resolution APIs (such as the Win32 API getaddrinfo on Windows, and equivalent APIs on other platforms). If a host is described in the `hosts` file, the IP address or addresses there will be returned without querying the DNS server. > [!NOTE] -> This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). +> This member emits trace information when you enable network tracing in your application. @@ -1139,7 +1139,7 @@ ## Remarks > [!NOTE] -> This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). +> This member emits trace information when you enable network tracing in your application. ]]> @@ -1211,7 +1211,7 @@ ## Remarks > [!NOTE] -> This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). +> This member emits trace information when you enable network tracing in your application. ]]> @@ -1290,7 +1290,7 @@ If the property is set to `true`, the property of the instance returned is not populated by this method and will always be empty. > [!NOTE] -> This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). +> This member emits trace information when you enable network tracing in your application. ]]> @@ -1363,7 +1363,7 @@ The property of the instance returned is not populated by this method and will always be empty. > [!NOTE] -> This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). +> This member emits trace information when you enable network tracing in your application. ## Examples The following code example uses the method to resolve an IP address to an instance. @@ -1453,7 +1453,7 @@ The property of the instance returned is not populated by this method and will always be empty. > [!NOTE] -> This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). +> This member emits trace information when you enable network tracing in your application. @@ -1571,7 +1571,7 @@ The property of the instance returned is not populated by this method and will always be empty. > [!NOTE] -> This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). +> This member emits trace information when you enable network tracing in your application. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -1661,7 +1661,7 @@ This method is implemented using the underlying operating system's name resolution APIs (such as the Win32 API getaddrinfo on Windows, and equivalent APIs on other platforms). If a host is described in the `hosts` file, the IP address or addresses there will be returned without querying the DNS server. > [!NOTE] -> This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). +> This member emits trace information when you enable network tracing in your application. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -1869,7 +1869,7 @@ If the property is set to `true`, the property of the instance returned is not populated by this method and will always be empty. > [!NOTE] -> This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). +> This member emits trace information when you enable network tracing in your application. ]]> diff --git a/xml/System.Net/DnsPermission.xml b/xml/System.Net/DnsPermission.xml index 5524b261fa0..56c176b0dee 100644 --- a/xml/System.Net/DnsPermission.xml +++ b/xml/System.Net/DnsPermission.xml @@ -50,8 +50,6 @@ [!INCLUDE[cas-deprecated](~/includes/cas-deprecated.md)] - The default permissions allow all local and Intranet zone applications to access DNS services, and no DNS permission for Internet zone applications. - ]]> @@ -89,14 +87,7 @@ One of the values. Creates a new instance of the class that either allows unrestricted DNS access or disallows DNS access. - - , the instance passes all demands. If `state` contains any other value, the instance fails all demands. - - ]]> - + To be added. is not a valid value. @@ -134,14 +125,7 @@ Creates an identical copy of the current permission instance. A new instance of the class that is an identical copy of the current instance. - - instance provides the same access to DNS servers as the original permission instance. - - ]]> - + To be added. @@ -179,16 +163,7 @@ The XML encoding to use to reconstruct the instance. Reconstructs a instance from an XML encoding. - - method reconstructs a instance from an XML encoding defined by the class. - - Use the method to XML-encode the instance, including state information. - - ]]> - + To be added. is . @@ -232,14 +207,7 @@ The instance to intersect with the current instance. Creates a permission instance that is the intersection of the current permission instance and the specified permission instance. A instance that represents the intersection of the current instance with the specified instance, or if the intersection is empty. If both the current instance and are unrestricted, this method returns a new instance that is unrestricted; otherwise, it returns . - - method returns a instance that allows the access defined by both the current instance and the specified instance. Any demand must pass both permissions to pass their intersection. - - ]]> - + To be added. is neither a nor . @@ -281,16 +249,7 @@ Determines whether the current permission instance is a subset of the specified permission instance. if the current instance is unrestricted and is either or unrestricted; otherwise, . - - instance is a subset of the specified instance if the current instance specifies a set of operations that is wholly contained by the specified instance. - - If the method returns `true`, the current instance allows no more access to DNS servers than does the specified instance. - - ]]> - + To be added. is neither a nor . @@ -368,16 +327,7 @@ Creates an XML encoding of a instance and its current state. A instance that contains an XML-encoded representation of the security object, including state information. - - method creates a instance to XML-encode a representation of the instance, including state information. - - Use the method to restore the state information from a instance. - - ]]> - + To be added. @@ -416,14 +366,7 @@ The instance to combine with the current instance. Creates a permission instance that is the union of the current permission instance and the specified permission instance. A instance that represents the union of the current instance with the specified instance. If is , this method returns a copy of the current instance. If the current instance or is unrestricted, this method returns a instance that is unrestricted; otherwise, it returns a instance that is restricted. - - method returns a instance that allows the access defined by either the current instance or the specified instance. Any demand that passes either permission passes their union. - - ]]> - + To be added. is neither a nor . diff --git a/xml/System.Net/DnsPermissionAttribute.xml b/xml/System.Net/DnsPermissionAttribute.xml index 35cdee6c979..0c774d419e6 100644 --- a/xml/System.Net/DnsPermissionAttribute.xml +++ b/xml/System.Net/DnsPermissionAttribute.xml @@ -50,17 +50,8 @@ [!INCLUDE[cas-deprecated](~/includes/cas-deprecated.md)] - The security information declared by is stored in the metadata of the attribute target, which is the class to which the is applied. The system then accesses this information at run time. The that is passed to the constructor determines the allowable DNS targets. - - These security attributes are used only for Declarative Security. For Imperative Security, use the corresponding class. - - Security access is either fully restricted or fully unrestricted. Set the property to `true` to grant access, or `false` for no access. Set this property as a named parameter. - - For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). - ]]> - @@ -95,14 +86,7 @@ One of the values. Initializes a new instance of the class with the specified value. - - value that is passed to this constructor specifies the allowable targets. - - ]]> - + To be added. The parameter is not a valid . @@ -140,16 +124,7 @@ Creates and returns a new instance of the class. A that corresponds to the security declaration. - - is stored in the metadata of the attribute target, which is the class to which is applied. The system then accesses the information at run time and calls . The system uses the returned to enforce the specified security requirements. - - ]]> - + To be added. diff --git a/xml/System.Net/FileWebRequest.xml b/xml/System.Net/FileWebRequest.xml index ef7670dfb42..cbe6413290d 100644 --- a/xml/System.Net/FileWebRequest.xml +++ b/xml/System.Net/FileWebRequest.xml @@ -67,10 +67,8 @@ When you want to write data to a file, the method returns a instance to write to. The and methods provide asynchronous access to the write data stream. - The class relies on the class for error handling and code access security. - - - + The class relies on the class for error handling. + ## Examples The following code example uses the class to access a file system resource. @@ -196,7 +194,7 @@ ## Remarks The method cancels a request to a resource. After a request is canceled, calling the , , , , , or method causes a with the property set to . - **Note** This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). +This member outputs trace information when you enable network tracing in your application. ]]> diff --git a/xml/System.Net/FileWebResponse.xml b/xml/System.Net/FileWebResponse.xml index 753d7db7083..da735d3e130 100644 --- a/xml/System.Net/FileWebResponse.xml +++ b/xml/System.Net/FileWebResponse.xml @@ -65,7 +65,7 @@ The method returns a instance that provides read-only access to a file system resource. - The class relies on the class for error handling and code access security. + The class relies on the class for error handling. ]]> @@ -587,14 +587,7 @@ Gets a value that indicates whether the property is supported by the instance. if the property is supported by the instance; otherwise, . - - - + To be added. diff --git a/xml/System.Net/FtpWebRequest.xml b/xml/System.Net/FtpWebRequest.xml index d4b9ed14921..a9e8e650883 100644 --- a/xml/System.Net/FtpWebRequest.xml +++ b/xml/System.Net/FtpWebRequest.xml @@ -60,7 +60,7 @@ To obtain an instance of , use the method. You can also use the class to upload and download information from an FTP server. Using either of these approaches, when you specify a network resource that uses the FTP scheme (for example, `"ftp://contoso.com"`) the class provides the ability to programmatically interact with FTP servers. - The URI may be relative or absolute. If the URI is of the form `"ftp://contoso.com/%2fpath"` (%2f is an escaped '/'), then the URI is absolute, and the current directory is `/path`. If, however, the URI is of the form `"ftp://contoso.com/path"`, first the .NET Framework logs into the FTP server (using the user name and password set by the property), then the current directory is set to `/path`. + The URI can be relative or absolute. If the URI is of the form `"ftp://contoso.com/%2fpath"` (%2f is an escaped '/'), then the URI is absolute, and the current directory is `/path`. If, however, the URI is of the form `"ftp://contoso.com/path"`, first .NET logs into the FTP server (using the user name and password set by the property), then the current directory is set to `/path`. You must have a valid user name and password for the server or the server must allow anonymous logon. You can specify the credentials used to connect to the server by setting the property or you can include them in the portion of the URI passed to the method. If you include information in the URI, the property is set to a new network credential with the specified user name and password information. @@ -157,9 +157,7 @@ If there is no operation in progress, this method does nothing. If a file transfer is in progress, this method terminates the transfer. > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - +> This member emits trace information when you enable network tracing in your application. ## Examples The following code example demonstrates how the user can terminate an asynchronous upload of a file from the local directory to the server. @@ -238,9 +236,7 @@ For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - +> This member emits trace information when you enable network tracing in your application. ## Examples The following code example demonstrates beginning an asynchronous operation to get a request's stream. This code example is part of a larger example provided for the class overview. @@ -326,9 +322,9 @@ For more information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). - This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - -> [!NOTE] + This member emits trace information when you enable network tracing in your application. + + > [!NOTE] > If a is thrown, use the and properties of the exception to determine the response from the server. @@ -404,7 +400,7 @@ Client certificates are used to authenticate the client during the initial SSL connection negotiation. For more information, see . > [!NOTE] -> The .NET Framework caches SSL sessions as they are created and attempts to reuse a cached session for a new request, if possible. When attempting to reuse an SSL session, the .NET Framework uses the first element of (if there is one), or tries to reuse an anonymous session if is empty. +> .NET caches SSL sessions as they are created and attempts to reuse a cached session for a new request, if possible. When attempting to reuse an SSL session, .NET uses the first element of (if there is one), or tries to reuse an anonymous session if is empty. ]]> @@ -460,14 +456,12 @@ property after calling the , , , or method causes an exception. - - ## Examples The following code example retrieves the value of this property. @@ -782,7 +776,6 @@ ]]> The caller tried to set this property to . - defaultFtpCachePolicy (Network Settings) @@ -903,9 +896,7 @@ In addition to the exceptions noted in "Exceptions," rethrows exceptions that were thrown while opening the stream for writing. > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - +> This member emits trace information when you enable network tracing in your application. ## Examples The following code example demonstrates ending an asynchronous operation to get a request's stream. This code example is part of a larger example provided for the class overview. @@ -978,9 +969,7 @@ In addition to the exceptions noted in "Exceptions," rethrows exceptions that were thrown while communicating with the server. > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - +> This member emits trace information when you enable network tracing in your application. ## Examples The following code example demonstrates ending an asynchronous operation to get a response. This code example is part of a larger example provided for the class overview. @@ -1057,9 +1046,7 @@ blocks while waiting for the stream. To prevent this, call the method in place of . > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - +> This member emits trace information when you enable network tracing in your application. ## Examples The following code example demonstrates copying a file to a request's data stream and sending a request to the server to upload the data and append it to a file. @@ -1138,9 +1125,7 @@ If a is thrown, use the and properties of the exception to determine the response from the server. - This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - -> [!NOTE] + This member emits trace information when you enable network tracing in your application.> [!NOTE] > Multiple calls to return the same response object; the request is not reissued. @@ -1464,32 +1449,19 @@ Gets or sets the proxy used to communicate with the FTP server. - An instance responsible for communicating with the FTP server. On .NET Core, its value is . + Always . [!NOTE] -> This property is not supported on .NET Core, and setting it has no effect. Getting the property value returns `null`. +> This property is not supported, and setting it has no effect. Getting the property value returns `null`. For more information about this API, see [Supplemental API remarks for System.Net.FtpWebRequest.Proxy](/dotnet/fundamentals/runtime-libraries/system-net-ftpwebrequest-proxy). - ]]> - - - - + This property cannot be set to . A new value was specified for this property for a request that is already in progress. - - - - - - - - diff --git a/xml/System.Net/FtpWebResponse.xml b/xml/System.Net/FtpWebResponse.xml index 3286f48bd69..255c23197aa 100644 --- a/xml/System.Net/FtpWebResponse.xml +++ b/xml/System.Net/FtpWebResponse.xml @@ -183,9 +183,7 @@ The method closes the data stream returned by the method if the property is `false`. During the close, data might be sent to the server on the control connection. > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - +> This member outputs trace information when you enable network tracing in your application. ## Examples The following code example downloads data from a server, reads the data from the response stream, and then closes it. @@ -783,17 +781,9 @@ This property is provided only for compatibility with other implementations of t Gets a value that indicates whether the property is supported by the instance. - Returns . - - if the property is supported by the instance; otherwise, . - - - + + if the property is supported by the instance; otherwise, . + To be added. diff --git a/xml/System.Net/GlobalProxySelection.xml b/xml/System.Net/GlobalProxySelection.xml index 2dd133a32c5..bc1980cb789 100644 --- a/xml/System.Net/GlobalProxySelection.xml +++ b/xml/System.Net/GlobalProxySelection.xml @@ -75,7 +75,6 @@ ]]> - DefaultProxy Element (Network Settings) diff --git a/xml/System.Net/HttpListener.xml b/xml/System.Net/HttpListener.xml index c533cca2f1b..6956a0f232e 100644 --- a/xml/System.Net/HttpListener.xml +++ b/xml/System.Net/HttpListener.xml @@ -117,7 +117,7 @@ This class cannot be used on the current operating system. Windows Server 2003 or Windows XP SP2 is required to use instances of this class. - Note: This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in the .NET Framework. + Note: This member outputs trace information when you enable network tracing in your application. @@ -178,7 +178,7 @@ ]]> - This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in the .NET Framework. + This member outputs trace information when you enable network tracing in your application. @@ -406,7 +406,7 @@ This object has not been started or is currently stopped. This object is closed. - This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in the .NET Framework. + This member outputs trace information when you enable network tracing in your application. @@ -466,7 +466,7 @@ The following code example demonstrates calling the `Close` method: ]]> - This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in the .NET Framework. + This member outputs trace information when you enable network tracing in your application. @@ -620,7 +620,7 @@ The following code example demonstrates calling the `Close` method: The method was already called for the specified object. This object is closed. - This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in the .NET Framework. + This member outputs trace information when you enable network tracing in your application. @@ -828,7 +828,7 @@ The following code example demonstrates calling the `Close` method: The does not have any Uniform Resource Identifier (URI) prefixes to respond to. This object is closed. - This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in the .NET Framework. + This member outputs trace information when you enable network tracing in your application. @@ -1237,7 +1237,7 @@ The following code example demonstrates calling the `Close` method: A Win32 function call failed. Check the exception's property to determine the cause of the exception. This object is closed. - This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in the .NET Framework. + This member outputs trace information when you enable network tracing in your application. @@ -1300,7 +1300,7 @@ The following code example demonstrates using the This object has been closed. - This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in the .NET Framework. + This member outputs trace information when you enable network tracing in your application. diff --git a/xml/System.Net/HttpListenerContext.xml b/xml/System.Net/HttpListenerContext.xml index 74b42b5774d..afda2695819 100644 --- a/xml/System.Net/HttpListenerContext.xml +++ b/xml/System.Net/HttpListenerContext.xml @@ -508,7 +508,7 @@ ]]> - Note: This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in the .NET Framework. + Note: This member outputs trace information when you enable network tracing in your application. diff --git a/xml/System.Net/HttpListenerPrefixCollection.xml b/xml/System.Net/HttpListenerPrefixCollection.xml index 61016737cd5..e3c9e11ca4d 100644 --- a/xml/System.Net/HttpListenerPrefixCollection.xml +++ b/xml/System.Net/HttpListenerPrefixCollection.xml @@ -220,7 +220,7 @@ A Windows function call failed. Check the exception's property to determine the cause of the exception. The associated with this collection is closed. - This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in the .NET Framework. + This member outputs trace information when you enable network tracing in your application. @@ -719,7 +719,7 @@ A Windows function call failed. To determine the cause of the exception, check the exception's error code. The associated with this collection is closed. - This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in the .NET Framework. + This member outputs trace information when you enable network tracing in your application. diff --git a/xml/System.Net/HttpListenerRequest.xml b/xml/System.Net/HttpListenerRequest.xml index ba7c69441db..588060e0d7b 100644 --- a/xml/System.Net/HttpListenerRequest.xml +++ b/xml/System.Net/HttpListenerRequest.xml @@ -917,7 +917,7 @@ ]]> - This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in the .NET Framework. + This member outputs trace information when you enable network tracing in your application. @@ -1817,8 +1817,6 @@ - Network Settings Schema - <httpListener> Element (Network Settings) diff --git a/xml/System.Net/HttpListenerResponse.xml b/xml/System.Net/HttpListenerResponse.xml index 220cb7a5620..af418871386 100644 --- a/xml/System.Net/HttpListenerResponse.xml +++ b/xml/System.Net/HttpListenerResponse.xml @@ -195,7 +195,6 @@ -or- or contains invalid characters. - .NET Framework and .NET Core versions 2.0 - 3.1 only: The length of is greater than 65,535 characters. @@ -330,8 +329,8 @@ -or- - or contains invalid characters. - .NET Framework and .NET Core versions 2.0 - 3.1 only: The length of is greater than 65,535 characters. + or contains invalid characters. + diff --git a/xml/System.Net/HttpWebRequest.xml b/xml/System.Net/HttpWebRequest.xml index 4e617ea5c55..f67b6e97584 100644 --- a/xml/System.Net/HttpWebRequest.xml +++ b/xml/System.Net/HttpWebRequest.xml @@ -68,124 +68,22 @@ [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The class provides support for the properties and methods defined in and for additional properties and methods that enable the user to interact directly with servers using HTTP. - - Do not use the constructor. Use the method to initialize new objects. If the scheme for the Uniform Resource Identifier (URI) is `http://` or `https://`, returns an object. - - The method makes a synchronous request to the resource specified in the property and returns an that contains the response object. The response data can be received by using the stream returned by . If the response object or the response stream is closed, remaining data will be forfeited. The remaining data will be drained and the socket will be re-used for subsequent requests when closing the response object or stream if the following conditions hold: it's a keep-alive or pipelined request, only a small amount of data needs to be received, or the remaining data is received in a small time interval. If none of the mentioned conditions hold or the drain time is exceeded, the socket will be closed. For keep-alive or pipelined connections, we strongly recommend that the application reads the streams until EOF. This ensures that the socket will be re-used for subsequent requests resulting in better performance and less resources used. - - When you want to send data to the resource, the method returns a object to use to send data. The and methods provide asynchronous access to the send data stream. - - For client authentication with , the client certificate must be installed in the My certificate store of the current user. - - The class throws a when errors occur while accessing a resource. The property contains a value that indicates the source of the error. When is , the property contains the received from the resource. - - exposes common HTTP header values sent to the Internet resource as properties, set by methods, or set by the system; the following table contains a complete list. You can set other headers in the property as name/value pairs. Note that servers and caches may change or add headers during the request. - - The following table lists the HTTP headers that are set either by properties or methods or the system. - -|Header|Set by| -|------------|------------| -|`Accept`|Set by the property.| -|`Connection`|Set by the property, property.| -|`Content-Length`|Set by the property.| -|`Content-Type`|Set by the property.| -|`Expect`|Set by the property.| -|`Date`|Set by the system to current date.| -|`Host`|Set by the system to current host information.| -|`If-Modified-Since`|Set by the property.| -|`Range`|Set by the method.| -|`Referer`|Set by the property.| -|`Transfer-Encoding`|Set by the property (the property must be `true`).| -|`User-Agent`|Set by the property.| - -> [!NOTE] -> is registered automatically. You do not need to call the method to register before using URIs beginning with `http://` or `https://`. - - The local computer or application config file may specify that a default proxy be used. If the property is specified, then the proxy settings from the property override the local computer or application config file and the instance will use the proxy settings specified. If no proxy is specified in a config file and the property is unspecified, the class uses the proxy settings inherited from Internet options on the local computer. If there are no proxy settings in Internet options, the request is sent directly to the server. - -> [!NOTE] -> The Framework caches SSL sessions as they are created and attempts to reuse a cached session for a new request, if possible. When attempting to reuse an SSL session, the Framework uses the first element of (if there is one), or tries to reuse an anonymous sessions if is empty. - -> [!NOTE] -> For security reasons, cookies are disabled by default. If you want to use cookies, use the property to enable cookies. - -For apps that use TLS/SSL through APIs such as HttpClient, HttpWebRequest, FTPClient, SmtpClient, and SsStream, .NET blocks insecure cipher and hashing algorithms for connections by default. You might need to opt out of this behavior to maintain interoperability with existing SSL3 services OR TLS w/ RC4 services. [Cannot connect to a server by using the ServicePointManager or SslStream APIs after upgrade to the .NET Framework 4.6](https://support.microsoft.com/kb/3069494) explains how to modify your code to disable this behavior, if necessary. - -## Examples - The following code example creates an for the URI `http://www.contoso.com/`. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/Overview/source.vb" id="Snippet1"::: - ]]> - DefaultProxy Element (Network Settings) - Changes to NTLM authentication for HTTPWebRequest in Version 3.5 SP1 - - System - 4.0.0.0 - - Initializes a new instance of the class. These constructors are obsolete; see the Remarks section for details. + Initializes a new instance of the class. These constructors are obsolete. constructors are obsolete and should not be used. Call the method to initialize new objects. - - ]]> +]]> - - - - - - - Constructor - - System - 4.0.0.0 - - - System.Net.Requests - - - netstandard - - - System.Net - - - - System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Never) - - - System.Obsolete("This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.", true) - - - [System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Never)] - [<System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Never)>] - - - [System.Obsolete("This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.", true)] - [<System.Obsolete("This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.", true)>] - - - - - Initializes a new instance of the class. This constructor is obsolete. - To be added. - - @@ -249,16 +147,7 @@ Both constructors are obsolete and should not b A object that contains the information required to serialize the new object. A object that contains the source and destination of the serialized stream associated with the new object. Initializes a new instance of the class from the specified instances of the and classes. This constructor is obsolete. - - - - XML and SOAP Serialization + To be added. @@ -304,25 +193,9 @@ Both constructors are obsolete and should not b method cancels a request to a resource. After a request is canceled, calling the , , , , , or method causes a with the property set to . - - The method will synchronously execute the callback specified to the or methods if the method is called while either of these operations are outstanding. This can lead to potential deadlock issues. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing](/dotnet/framework/network-programming/network-tracing). - - - -## Examples - In the case of asynchronous requests, it is the responsibility of the client application to implement its own time-out mechanism. The following code example shows how to do this. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Abort/begingetresponse.cs" id="Snippet1"::: - - ]]> +]]> @@ -370,24 +243,9 @@ Both constructors are obsolete and should not b property to `null`. - -> [!NOTE] -> The value for this property is stored in . If WebHeaderCollection is set, the property value is lost. - - - -## Examples - The following code example sets the property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Accept/httpwebrequest_accept.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/Accept/httpwebrequest_accept.vb" id="Snippet1"::: - - ]]> +]]> @@ -402,16 +260,9 @@ Both constructors are obsolete and should not b +]]> @@ -460,43 +311,9 @@ Both constructors are obsolete and should not b method adds a byte range header to the request. - - If `range` is positive, the `range` parameter specifies the starting point of the range. The server should start sending data from the `range` parameter specified to the end of the data in the HTTP entity. - - If `range` is negative, the `range` parameter specifies the ending point of the range. The server should start sending data from the start of the data in the HTTP entity to the `range` parameter specified. - - Since all HTTP entities are represented in HTTP messages as sequences of bytes, the concept of a byte range is meaningful for any HTTP entity. However, not all clients and servers need to support byte-range operations. - - The Range header on a request allows a client to request that it only wants to receive some part of the specified range of bytes in an HTTP entity. Servers are not required to support Range header requests. - - An example of a Range header in an HTTP protocol request that requests the server send the first 100 bytes (from the start to byte position 99) would be the following: - - `Range: bytes=0-99\r\n\r\n` - - For this example, the `range` parameter would be -99. - - A HTTP server indicates support for Range headers with the Accept-Ranges header. An example of the Accept-Ranges header from a server that supports byte-ranges would be as follows: - - `Accept-Ranges: bytes\r\n\r\n` - - If an Accept-Ranges header is not received in the header of the response from the server, then the server does not support Range headers. An example of the Accept-Ranges header from a server that does not support ranges, but recognizes the Accept-Ranges header, would be as follows: - - `Accept-Ranges: none\r\n\r\n` - - When receiving the response from a range request, only the HTTP headers associated with the entire request are parsed and made available via properties on the class. Headers associated with each range are returned in the response. - -## Examples - The following code example adds a range header to the request. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/AddRange/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.net.httpwebrequest.addrange/vb/source.vb" id="Snippet1"::: - - ]]> +]]> is invalid. @@ -547,37 +364,9 @@ Both constructors are obsolete and should not b method adds a byte range header to the request. - - If `range` is positive, the `range` parameter specifies the starting point of the range. The server should start sending data from the `range` parameter specified to the end of the data in the HTTP entity. - - If `range` is negative, the `range` parameter specifies the ending point of the range. The server should start sending data from the start of the data in the HTTP entity to the `range` parameter specified. - - Since all HTTP entities are represented in HTTP messages as sequences of bytes, the concept of a byte range is meaningful for any HTTP entity. However, not all clients and servers need to support byte-range operations. - - The Range header on a request allows a client to request that it only wants to receive some part of the specified range of bytes in an HTTP entity. Servers are not required to support Range header requests. - - An example of a Range header in an HTTP protocol request that requests the server send the first 100 bytes (from the start to byte position 99) would be the following: - - `Range: bytes=0-99\r\n\r\n` - - For this example, the `range` parameter would be -99. - - A HTTP server indicates support for Range headers with the Accept-Ranges header. An example of the Accept-Ranges header from a server that supports byte-ranges would be as follows: - - `Accept-Ranges: bytes\r\n\r\n` - - If an Accept-Ranges header is not received in the header of the response from the server, then the server does not support Range headers. An example of the Accept-Ranges header from a server that does not support ranges, but recognizes the Accept-Ranges header, would be as follows: - - `Accept-Ranges: none\r\n\r\n` - - When receiving the response from a range request, only the HTTP headers associated with the entire request are parsed and made available via properties on the class. Headers associated with each range are returned in the response. - - ]]> +]]> is invalid. @@ -632,39 +421,9 @@ Both constructors are obsolete and should not b method adds a byte range header to the request. - - Since all HTTP entities are represented in HTTP messages as sequences of bytes, the concept of a byte range is meaningful for any HTTP entity. However, not all clients and servers need to support byte-range operations. - - The Range header on a request allows a client to request that it only wants to receive some part of the specified range of bytes in an HTTP entity. Servers are not required to support Range header requests. - - An example of a Range header in an HTTP protocol request that requests the first 100 bytes would be would be the following: - - `Range: bytes=0-99\r\n\r\n` - - For this example, the `from` parameter would be specified as 0 and the `to` parameter would be specified as 99. The range specifier is automatically set as "bytes" by this method. - - A HTTP server indicates support for Range headers with the Accept-Ranges header. An example of the Accept-Ranges header from a server that supports byte-ranges would be as follows: - - `Accept-Ranges: bytes\r\n\r\n` - - If an Accept-Ranges header is not received in the header of the response from the server, then the server does not support Range headers. An example of the Accept-Ranges header from a server that does not support ranges, but recognizes the Accept-Ranges header, would be as follows: - - `Accept-Ranges: none\r\n\r\n` - - When receiving the response from a range request, only the HTTP headers associated with the entire request are parsed and made available via properties on the class. Headers associated with each range are returned in the response. - -## Examples - The following code example adds a range header to the request. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/AddRange/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.net.httpwebrequest.addrange2/vb/source.vb" id="Snippet1"::: - - ]]> +]]> is greater than @@ -721,33 +480,9 @@ Both constructors are obsolete and should not b method adds a byte range header to the request. - - Since all HTTP entities are represented in HTTP messages as sequences of bytes, the concept of a byte range is meaningful for any HTTP entity. However, not all clients and servers need to support byte-range operations. - - The Range header on a request allows a client to request that it only wants to receive some part of the specified range of bytes in an HTTP entity. Servers are not required to support Range header requests. - - An example of a Range header in an HTTP protocol request that requests the first 100 bytes would be would be the following: - - `Range: bytes=0-99\r\n\r\n` - - For this example, the `from` parameter would be specified as 0 and the `to` parameter would be specified as 99. The range specifier is automatically set as "bytes" by this method. - - A HTTP server indicates support for Range headers with the Accept-Ranges header. An example of the Accept-Ranges header from a server that supports byte-ranges would be as follows: - - `Accept-Ranges: bytes\r\n\r\n` - - If an Accept-Ranges header is not received in the header of the response from the server, then the server does not support Range headers. An example of the Accept-Ranges header from a server that does not support ranges, but recognizes the Accept-Ranges header, would be as follows: - - `Accept-Ranges: none\r\n\r\n` - - When receiving the response from a range request, only the HTTP headers associated with the entire request are parsed and made available via properties on the class. Headers associated with each range are returned in the response. - - ]]> +]]> is greater than @@ -806,39 +541,9 @@ Both constructors are obsolete and should not b method adds a Range header to the request. - - If `range` is positive, the `range` parameter specifies the starting point of the range. The server should start sending data from the `range` parameter specified to the end of the data in the HTTP entity. - - If `range` is negative, the `range` parameter specifies the ending point of the range. The server should start sending data from the start of the data in the HTTP entity to the `range` parameter specified. - - Since all HTTP entities are represented in HTTP messages as sequences of bytes, the concept of a byte range is meaningful for any HTTP entity. However, not all clients and servers need to support byte-range operations. - - The Range header on a request allows a client to request that it only wants to receive some part of the specified range of bytes in an HTTP entity. Servers are not required to support Range header requests. - - The `rangeSpecifier` parameter would normally be specified as a "bytes", since this is the only range specifier recognized by most HTTP servers. Setting the `rangeSpecifier` parameter to some other string allows support for custom range specifiers other than bytes (the byte-range specifier defined in RFC 2616 by the IETF). - - An example of a Range header in an HTTP protocol request that requests the first 100 bytes would be would be the following: - - `Range: bytes=-99\r\n\r\n` - - For this example, the `rangeSpecifier` parameter would be specified as "bytes" and the `range` parameter would be -99. - - A HTTP server indicates support for Range headers with the Accept-Ranges header in the response. An example of the Accept-Ranges header from a server that supports byte-ranges would be as follows: - - `Accept-Ranges: bytes\r\n\r\n` - - If an Accept-Ranges header is not received in the header of the response from the server, then the server does not support Range headers. An example of the Accept-Ranges header from a server that does not support ranges, but recognizes the Accept-Ranges header, would be as follows: - - `Accept-Ranges: none\r\n\r\n` - - When receiving the response from a range request, only the HTTP headers associated with the entire request are parsed and made available via properties on the class. Headers associated with each range are returned in the response. - - ]]> +]]> is . @@ -893,39 +598,9 @@ Both constructors are obsolete and should not b method adds a Range header to the request. - - If `range` is positive, the `range` parameter specifies the starting point of the range. The server should start sending data from the `range` parameter specified to the end of the data in the HTTP entity. - - If `range` is negative, the `range` parameter specifies the ending point of the range. The server should start sending data from the start of the data in the HTTP entity to the `range` parameter specified. - - Since all HTTP entities are represented in HTTP messages as sequences of bytes, the concept of a byte range is meaningful for any HTTP entity. However, not all clients and servers need to support byte-range operations. - - The Range header on a request allows a client to request that it only wants to receive some part of the specified range of bytes in an HTTP entity. Servers are not required to support Range header requests. - - The `rangeSpecifier` parameter would normally be specified as a "bytes", since this is the only range specifier recognized by most HTTP servers. Setting the `rangeSpecifier` parameter to some other string allows support for custom range specifiers other than bytes (the byte-range specifier defined in RFC 2616 by the IETF). - - An example of a Range header in an HTTP protocol request that requests the first 100 bytes would be would be the following: - - `Range: bytes=-99\r\n\r\n` - - For this example, the `rangeSpecifier` parameter would be specified as "bytes" and the `range` parameter would be -99. - - A HTTP server indicates support for Range headers with the Accept-Ranges header in the response. An example of the Accept-Ranges header from a server that supports byte-ranges would be as follows: - - `Accept-Ranges: bytes\r\n\r\n` - - If an Accept-Ranges header is not received in the header of the response from the server, then the server does not support Range headers. An example of the Accept-Ranges header from a server that does not support ranges, but recognizes the Accept-Ranges header, would be as follows: - - `Accept-Ranges: none\r\n\r\n` - - When receiving the response from a range request, only the HTTP headers associated with the entire request are parsed and made available via properties on the class. Headers associated with each range are returned in the response. - - ]]> +]]> is . @@ -984,37 +659,9 @@ Both constructors are obsolete and should not b method adds a Range header to the request. - - Since all HTTP entities are represented in HTTP messages as sequences of bytes, the concept of a byte range is meaningful for any HTTP entity. However, not all clients and servers need to support byte-range operations. - - The Range header on a request allows a client to request that it only wants to receive some part of the specified range of bytes in an HTTP entity. Servers are not required to support Range header requests. - - The `rangeSpecifier` parameter would normally be specified as a "bytes", since this is the only range specifier recognized by most HTTP servers. Setting the `rangeSpecifier` parameter to some other string allows support for custom range specifiers other than bytes (the byte-range specifier defined in RFC 2616 by the IETF). - - An example of a Range header in an HTTP protocol request that requests the first 100 bytes would be would be the following: - - `Range: bytes=0-99\r\n\r\n` - - For this example, the `rangeSpecifier` parameter would be specified as a "bytes", the `from` parameter would be 0, and the `to` parameter would be 99. - - A HTTP server indicates support for Range headers with the Accept-Ranges header in the response. An example of the Accept-Ranges header from a server that supports byte-ranges would be as follows: - - `Accept-Ranges: bytes\r\n\r\n` - - The string specified in the Accept-Ranges header is the range-specifier that would be by specified in the `rangeSpecifier` parameter for this method. - - If an Accept-Ranges header is not received in the header of the response from the server, then the server does not support Range headers. An example of the Accept-Ranges header from a server that does not support ranges, but recognizes the Accept-Ranges header, would be as follows: - - `Accept-Ranges: none\r\n\r\n` - - When receiving the response from a range request, only the HTTP headers associated with the entire request are parsed and made available via properties on the class. Headers associated with each range are returned in the response. - - ]]> +]]> is . @@ -1077,37 +724,9 @@ Both constructors are obsolete and should not b method adds a Range header to the request. - - Since all HTTP entities are represented in HTTP messages as sequences of bytes, the concept of a byte range is meaningful for any HTTP entity. However, not all clients and servers need to support byte-range operations. - - The Range header on a request allows a client to request that it only wants to receive some part of the specified range of bytes in an HTTP entity. Servers are not required to support Range header requests. - - The `rangeSpecifier` parameter would normally be specified as a "bytes", since this is the only range specifier recognized by most HTTP servers. Setting the `rangeSpecifier` parameter to some other string allows support for custom range specifiers other than bytes (the byte-range specifier defined in RFC 2616 by the IETF). - - An example of a Range header in an HTTP protocol request that requests the first 100 bytes would be would be the following: - - `Range: bytes=0-99\r\n\r\n` - - For this example, the `rangeSpecifier` parameter would be specified as a "bytes", the `from` parameter would be 0, and the `to` parameter would be 99. - - A HTTP server indicates support for Range headers with the Accept-Ranges header in the response. An example of the Accept-Ranges header from a server that supports byte-ranges would be as follows: - - `Accept-Ranges: bytes\r\n\r\n` - - The string specified in the Accept-Ranges header is the range-specifier that would be by specified in the `rangeSpecifier` parameter for this method. - - If an Accept-Ranges header is not received in the header of the response from the server, then the server does not support Range headers. An example of the Accept-Ranges header from a server that does not support ranges, but recognizes the Accept-Ranges header, would be as follows: - - `Accept-Ranges: none\r\n\r\n` - - When receiving the response from a range request, only the HTTP headers associated with the entire request are parsed and made available via properties on the class. Headers associated with each range are returned in the response. - - ]]> +]]> is . @@ -1171,23 +790,9 @@ Both constructors are obsolete and should not b property is set to the URI after any redirections that happen during the request are complete. - - The URI of the original request is kept in the property. - - - -## Examples - The following code example checks to see if the object `req` was redirected to another location to fulfill the request, and sets the value of the `hasChanged` variable to `true` if the request was redirected; otherwise `hasChanged` is set to `false`. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Address/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/Address/source.vb" id="Snippet1"::: - - ]]> +]]> @@ -1234,25 +839,9 @@ Both constructors are obsolete and should not b to `true` if you want the request to automatically follow HTTP redirection headers to the new location of the resource. The maximum number of redirections to follow is set by the property. - - If is set to `false`, all responses with an HTTP status code from 300 to 399 is returned to the application. - - The Authorization header is cleared on auto-redirects and automatically tries to re-authenticate to the redirected location. In practice, this means that an application can't put custom authentication information into the Authorization header if it is possible to encounter redirection. Instead, the application must implement and register a custom authentication module. The and related class are used to implement a custom authentication module. The method registers a custom authentication module. - - - -## Examples - The following code example uses the property to allow the request to follow redirection responses. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/AllowAutoRedirect/httpwebrequest_allowautoredirect.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/AllowAutoRedirect/httpwebrequest_allowautoredirect.vb" id="Snippet2"::: - - ]]> +]]> @@ -1341,19 +930,9 @@ Both constructors are obsolete and should not b is `true`, the data is buffered in memory so it is ready to be resent in the event of redirections or authentication requests. - -## Examples - The following code example uses the property to disable data buffering. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/AllowWriteStreamBuffering/httpwebrequest_allowwritestreambuffering.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/AllowWriteStreamBuffering/httpwebrequest_allowwritestreambuffering.vb" id="Snippet1"::: - - ]]> +]]> Setting to might cause performance problems when uploading large datasets because the data buffer could use all available memory. @@ -1458,31 +1037,9 @@ Both constructors are obsolete and should not b method starts an asynchronous request for a stream used to send data for the . The asynchronous callback method uses the method to return the actual stream. - - The method requires some synchronous setup tasks to complete (DNS resolution, proxy detection, and TCP socket connection, for example) before this method becomes asynchronous. As a result, this method should never be called on a user interface (UI) thread because it might take considerable time (up to several minutes depending on network settings) to complete the initial synchronous setup tasks before an exception for an error is thrown or the method succeeds. - - To learn more about the thread pool, see [The managed thread pool](/dotnet/standard/threading/the-managed-thread-pool). - -> [!NOTE] -> Your application cannot mix synchronous and asynchronous methods for a particular request. If you call the method, you must use the method to retrieve the response. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - - -## Examples - The following code example uses the method to make an asynchronous request for a stream instance. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/BeginGetRequestStream/httpwebrequest_begingetrequeststream.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/BeginGetRequestStream/httpwebrequest_begingetrequeststream.vb" id="Snippet2"::: - - ]]> +]]> The property is GET or HEAD. @@ -1502,7 +1059,6 @@ Both constructors are obsolete and should not b was previously called. In a .NET Compact Framework application, a request stream with zero content length was not obtained and closed correctly. - DefaultProxy Element (Network Settings) @@ -1561,37 +1117,9 @@ Both constructors are obsolete and should not b method starts an asynchronous request for a response from the Internet resource. The asynchronous callback method uses the method to return the actual . - - A is thrown in several cases when the properties set on the class are conflicting. This exception occurs if an application sets the property and the property to `true`, and then sends an HTTP GET request. This exception occurs if an application tries to send chunked to a server that only supports HTTP 1.0 protocol, where this is not supported. This exception occurs if an application tries to send data without setting the property or the is `false` when buffering is disabled and on a keepalive connection (the property is `true`)`.` - - If a is thrown, use the and properties of the exception to determine the response from the server. - - The method requires some synchronous setup tasks to complete (DNS resolution, proxy detection, and TCP socket connection, for example) before this method becomes asynchronous. As a result, this method should never be called on a user interface (UI) thread because it might take considerable time (up to several minutes depending on network settings) to complete the initial synchronous setup tasks before an exception for an error is thrown or the method succeeds. - - To learn more about the thread pool, see [The managed thread pool](/dotnet/standard/threading/the-managed-thread-pool). - -> [!NOTE] -> Your application cannot mix synchronous and asynchronous methods for a particular request. If you call the method, you must use the method to retrieve the response. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - - -## Examples - The following code example uses the method to make an asynchronous request for an Internet resource. - -> [!NOTE] -> In the case of asynchronous requests, it is the responsibility of the client application to implement its own time-out mechanism. The following code example shows how to do it. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Abort/begingetresponse.cs" id="Snippet1"::: - - ]]> +]]> The stream is already in use by a previous call to @@ -1618,7 +1146,6 @@ Both constructors are obsolete and should not b The is greater than zero, but the application does not write all of the promised data. was previously called. - DefaultProxy Element (Network Settings) @@ -1669,21 +1196,9 @@ Both constructors are obsolete and should not b [!NOTE] -> The Framework caches SSL sessions as they are created and attempts to reuse a cached session for a new request, if possible. When attempting to reuse an SSL session, the Framework uses the first element of (if there is one), or tries to reuse an anonymous sessions if is empty. - -> [!NOTE] -> For performance reasons, you shouldn't add a client certificate to a unless you know the server will ask for it. -> -> For a code example illustrating how to enumerate the certificates in the client certificate store, see the class. - - ]]> +]]> The value specified for a set operation is . @@ -1731,28 +1246,9 @@ Both constructors are obsolete and should not b property to the Internet resource as the `Connection` HTTP header. If the value of the property is `true`, the value "Keep-alive" is appended to the end of the `Connection` header. - - To clear the `Connection` HTTP header, set the property to `null`. - - Changing the property after the request has been started by calling the , , , or method throws an . - -> [!NOTE] -> The value for this property is stored in . If WebHeaderCollection is set, the property value is lost. - - - -## Examples - The following code example uses the property to set the value of the Connection HTTP Header. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Connection/httpwebrequest_connection.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/Connection/httpwebrequest_connection.vb" id="Snippet1"::: - - ]]> +]]> The value of is set to Keep-alive or Close. @@ -1800,13 +1296,9 @@ Both constructors are obsolete and should not b property enables you to associate a request with a connection group. This is useful when your application makes requests to one server for different users, such as a web site that retrieves customer information from a database server. - - ]]> +]]> Each connection group creates additional connections for a server. This may result in exceeding the number of connections set by the property for that server. @@ -1857,28 +1349,9 @@ Both constructors are obsolete and should not b property contains the value to send as the `Content-length` HTTP header with the request. - - Any value other than -1 in the property indicates that the request uploads data and that only methods that upload data are allowed to be set in the property. - - After the property is set to a value, that number of bytes must be written to the request stream that is returned by calling the method or both the and the methods. - -> [!NOTE] -> The value for this property is stored in . If WebHeaderCollection is set, the property value is lost. - - - -## Examples - The following code example sets the property to the length of the string being posted. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ContentLength/httpwebrequest_contentlength.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/ContentLength/httpwebrequest_contentlength.vb" id="Snippet4"::: - - ]]> +]]> The request has been started by calling the , , , or method. The new value is less than 0. @@ -1928,26 +1401,9 @@ Both constructors are obsolete and should not b property contains the media type of the request. Values assigned to the property replace any existing contents when the request sends the `Content-type` HTTP header. - - To clear the `Content-type` HTTP header, set the property to `null`. - -> [!NOTE] -> The value for this property is stored in . If is set, the property value is lost. - - - -## Examples - The following code example sets the property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ContentLength/httpwebrequest_contentlength.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/ContentLength/httpwebrequest_contentlength.vb" id="Snippet1"::: - - ]]> +]]> @@ -1994,15 +1450,9 @@ Both constructors are obsolete and should not b property specifies the callback method to call when the client receives a 100-Continue response. - - When the property is set, the client calls the delegate whenever protocol responses of type (100) are received. This is useful if you want the client to display the status of the data being received from the Internet resource. - - ]]> +]]> @@ -2047,13 +1497,9 @@ Both constructors are obsolete and should not b +]]> @@ -2101,26 +1547,9 @@ Both constructors are obsolete and should not b property provides an instance of the class that contains the cookies associated with this request. - - is `null` by default. You must assign a object to the property to have cookies returned in the property of the returned by the method. - -> [!NOTE] -> For security reasons, cookies are disabled by default. If you want to use cookies, use the property to enable cookies. - - - -## Examples - The following code example sends a request to a URL and displays the cookies returned in the response. - - :::code language="csharp" source="~/snippets/csharp/System.Net/Cookie/Overview/cookiessnippets.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/Cookie/Overview/cookiessnippets.vb" id="Snippet1"::: - - ]]> +]]> @@ -2169,32 +1598,9 @@ Both constructors are obsolete and should not b property contains authentication information to identify the maker of the request. The property can be either a , in which case the user, password, and domain information contained in the object is used to authenticate the request, or it can be a , in which case the Uniform Resource Identifier (URI) of the request is used to determine the user, password, and domain information to use to authenticate the request. - - In most client scenarios, you should use the property, which contains the credentials of the currently logged on user. To do this, set the property to `true` instead of setting this property. - - If the class is being used in a middle-tier application, such as an ASP.NET application, the credentials in the property belong to the account running the ASP page (the server-side credentials). Typically, you would set this property to the credentials of the client on whose behalf the request is made. - -> [!NOTE] -> The NTLM authentication scheme cannot be used to impersonate another user. Kerberos must be specially configured to support impersonation. - - To restrict HttpWebRequest to one or more authentication methods, use the class and bind your credentials to one or more authentication schemes - - Supported authentication schemes include Digest, Negotiate, Kerberos, NTLM, and Basic. - - For security reasons, when automatically following redirects, store the credentials that you want to be included in the redirect in a and assign it to this property. This property will automatically be set to `null` upon redirection if it contains anything except a . Having this property value be automatically set to `null` under those conditions prevents credentials from being sent to any unintended destination. - -## Examples - The following code example sets the credentials for a request. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Credentials/httpwebrequest1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/Credentials/httpwebrequest1.vb" id="Snippet1"::: - - ]]> +]]> @@ -2238,26 +1644,9 @@ Both constructors are obsolete and should not b . - - The property is a standard object and can contain a field of , , or . Any kind of time can be set when using the property. If is set or retrieved, the property is assumed to be (local time). - - The classes in the namespace always write it out the property on the wire during transmission in standard form using GMT (Utc) format. - - If the property is set to , then the `Date` HTTP header is removed from the property and the . - - If the property is , this indicates that the `Date` HTTP header is not included in the property and the . - -> [!NOTE] -> The value for this property is stored in . If WebHeaderCollection is set, the property value is lost. - - If the is set and an attempt is made to send a with no body, then a will be thrown by the , , and methods. - - ]]> +]]> @@ -2302,23 +1691,9 @@ Both constructors are obsolete and should not b property specified for this request. - --or- - - The machine and application configuration files do not specify a cache policy that is applicable to the Uniform Resource Identifier (URI) used to create this request. - - The cache policy determines whether the requested resource can be taken from a cache instead of sending the request to the resource host computer. - - A copy of a resource is only added to the cache if the response stream for the resource is retrieved and read to the end of the stream. So another request for the same resource could use a cached copy, depending on the cache policy level for this request. - - ]]> +]]> @@ -2410,15 +1785,9 @@ Both constructors are obsolete and should not b property on an instance of the class. - - ]]> +]]> The value is less than zero. @@ -2480,26 +1849,9 @@ Both constructors are obsolete and should not b method completes an asynchronous request for a stream that was started by the method. After the object has been returned, you can send data with the by using the method. - -> [!NOTE] -> - You must set the value of the property before writing data to the stream. -> - You must call the method to close the stream and release the connection for reuse. Failure to close the stream causes your application to run out of connections. -> - This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - - -## Examples - The following code example uses the method to end an asynchronous request for a stream instance. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/BeginGetRequestStream/httpwebrequest_begingetrequeststream.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/BeginGetRequestStream/httpwebrequest_begingetrequeststream.vb" id="Snippet2"::: - - ]]> +]]> is . @@ -2570,20 +1922,9 @@ Both constructors are obsolete and should not b method completes an asynchronous request for a stream that was started by the method and outputs the associated with the stream. After the object has been returned, you can send data with the by using the method. - - Some applications that use integrated Windows authentication with extended protection may need to be able to query the transport layer used by in order to retrieve the channel binding token (CBT) from the underlying TLS channel. The method provides access to this information for HTTP methods which have a request body (`POST` and `PUT` requests). This is only needed if the application is implementing its own authentication and needs access to the CBT. - -> [!NOTE] -> - If you need to set the value of the property before writing data to the stream. -> - You must call the method to close the stream and release the connection for reuse. Failure to close the stream causes your application to run out of connections. -> - This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> was not returned by the current instance from a call to . @@ -2651,26 +1992,9 @@ Both constructors are obsolete and should not b method completes an asynchronous request for an Internet resource that was started by calling the method. - -> [!CAUTION] -> You must call the method to close the stream and release the connection. Failure to do so may cause your application to run out of connections. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - - -## Examples - The following code example uses the method to end an asynchronous request for an Internet resource. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Abort/begingetresponse.cs" id="Snippet1"::: - - ]]> +]]> is . @@ -2732,7 +2056,6 @@ Both constructors are obsolete and should not b The value for this property is stored in . If WebHeaderCollection is set, the property value is lost. is set to a string that contains "100-continue" as a substring. - DefaultProxy Element (Network Settings) @@ -2856,31 +2179,9 @@ Both constructors are obsolete and should not b method returns a stream to use to send data for the . After the object has been returned, you can send data with the by using the method. - - If an application needs to set the value of the property, then this must be done before retrieving the stream. - - You must call the method to close the stream and release the connection for reuse. Failure to close the stream causes your application to run out of connections. - -> [!NOTE] -> Your application cannot mix synchronous and asynchronous methods for a particular request. If you call the method, you must use the method to retrieve the response. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - - -## Examples - The following code example uses the method to return a stream instance. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ContentLength/httpwebrequest_contentlength.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/ContentLength/httpwebrequest_contentlength.vb" id="Snippet4"::: - - ]]> +]]> The property is GET or HEAD. @@ -2904,7 +2205,6 @@ Both constructors are obsolete and should not b An error occurred while processing the request. In a .NET Compact Framework application, a request stream with zero content length was not obtained and closed correctly. - DefaultProxy Element (Network Settings) @@ -2960,25 +2260,9 @@ Both constructors are obsolete and should not b method returns a stream to use to send data for the and outputs the associated with the stream. After the object has been returned, you can send data with the by using the method. - - Some applications that use integrated Windows authentication with extended protection may need to be able to query the transport layer used by in order to retrieve the channel binding token (CBT) from the underlying TLS channel. The method provides access to this information for HTTP methods which have a request body (`POST` and `PUT` requests). This is only needed if the application is implementing its own authentication and needs access to the CBT. - - If an application needs to set the value of the property, then this must be done before retrieving the stream. - - You must call the method to close the stream and release the connection for reuse. Failure to close the stream causes your application to run out of connections. - -> [!NOTE] -> Your application cannot mix synchronous and asynchronous methods for a particular request. If you call the method, you must use the method to retrieve the response. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The method was unable to obtain the . The method is called more than once. @@ -3042,53 +2326,19 @@ Both constructors are obsolete and should not b 10.0.0.0 11.0.0.0 - - System.Net.WebResponse - - - - Returns a response from an Internet resource. - A that contains the response from the Internet resource. - - method returns a object that contains the response from the Internet resource. The actual instance returned is an , and can be typecast to that class to access HTTP-specific properties. - - A is thrown in several cases when the properties set on the class are conflicting. This exception occurs if an application sets the property and the property to `true`, and then sends an HTTP GET request. This exception occurs if an application tries to send chunked to a server that only supports HTTP 1.0 protocol, where this is not supported. This exception occurs if an application tries to send data without setting the property or the is `false` when buffering is disabled and on a keepalive connection (the property is `true`)`.` - -> [!CAUTION] -> You must call the method to close the stream and release the connection. Failure to do so may cause your application to run out of connections. - - When using the POST method, you must get the request stream, write the data to be posted, and close the stream. This method blocks waiting for content to post; if there is no time-out set and you do not provide content, the calling thread blocks indefinitely. - -> [!NOTE] -> Multiple calls to return the same response object; the request is not reissued. - -> [!NOTE] -> Your application cannot mix synchronous and asynchronous methods for a particular request. If you call the method, you must use the method to retrieve the response. - -> [!NOTE] -> If a is thrown, use the and properties of the exception to determine the response from the server. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - -> [!NOTE] -> For security reasons, cookies are disabled by default. If you wish to use cookies, use the property to enable cookies. - - - -## Examples - The following code example gets the response for a request. + + System.Net.WebResponse + + + + Returns a response from an Internet resource. + A that contains the response from the Internet resource. + + +]]> The stream is already in use by a previous call to . @@ -3121,7 +2371,6 @@ Both constructors are obsolete and should not b An error occurred while processing the request. - DefaultProxy Element (Network Settings) @@ -3227,42 +2476,9 @@ Both constructors are obsolete and should not b collection contains the protocol headers associated with the request. The following table lists the HTTP headers that are not stored in the collection but are either set by the system or set by properties or methods. - -|Header|Set by| -|------------|------------| -|Accept|Set by the property.| -|Connection|Set by the property and property.| -|Content-Length|Set by the property.| -|Content-Type|Set by the property.| -|Expect|Set by the property.| -|Date|Set by the property.| -|Host|Set by the property.| -|If-Modified-Since|Set by the property.| -|Range|Set by the method.| -|Referer|Set by the property.| -|Transfer-Encoding|Set by the property (the property must be true).| -|User-Agent|Set by the property.| - - The method throws an if you try to set one of these protected headers. - - Changing the property after the request has been started by calling , , , or method throws an . - - You should not assume that the header values will remain unchanged, because Web servers and caches may change or add headers to a Web request. - - - -## Examples - The following code example uses the property to print the HTTP header name/value pairs to the console. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Headers/httpwebrequest_headers.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/Headers/httpwebrequest_headers.vb" id="Snippet1"::: - - ]]> +]]> The request has been started by calling the , , , or method. @@ -3313,21 +2529,9 @@ Both constructors are obsolete and should not b property can be used to set the Host header value to use in an HTTP request independent from the request URI. The property can consist of a hostname and an optional port number. A Host header without port information implies the default port for the service requested (port 80 for an HTTP URL, for example). - - The format for specifying a host and port must follow the rules in section 14.23 of RFC2616 published by the IETF. An example complying with these requirements that specifies a port of 8080 would be the following value for the property: - - `www.contoso.com:8080` - - Using the property to explicitly specify a custom Host header value also affects areas caching, cookies, and authentication. When an application provides credentials for a specific URI prefix, the applications needs to make sure to use the URI containing the value of the Host header, not the target server in the URI. The key used when caching resources, uses the Host header value rather than the request URI. Cookies are stored in a and logically grouped by the server domain name. If the application specifies a Host header, then this value will be used as domain. - - If the property is not set, then the Host header value to use in an HTTP request is based on the request URI. - - ]]> +]]> The Host header cannot be set to . The Host header cannot be set to an invalid value. @@ -3376,34 +2580,9 @@ Both constructors are obsolete and should not b . - - The property is a standard object and can contain a field of , , or . Any kind of time can be set when using the property. If is set or retrieved, the property is assumed to be (local time). - - The classes in the namespace always write it out the property on the wire during transmission in standard form using GMT (Utc) format. - - If the property is set to , then the `If-Modified-Since` HTTP header is removed from the property and the . - - If the property is , this indicates that the `If-Modified-Since` HTTP header is not included in the property and the . - -> [!NOTE] -> The value for this property is stored in . If WebHeaderCollection is set, the property value is lost. - - If the property is set and 304 (Not Modified) status code is returned, then a will be thrown by the , , and methods. - - - -## Examples - The following code example checks the property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/IfModifiedSince/httpwebrequest_ifmodifiedsince.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/IfModifiedSince/httpwebrequest_ifmodifiedsince.vb" id="Snippet1"::: - - ]]> +]]> @@ -3450,24 +2629,9 @@ Both constructors are obsolete and should not b to indicate a preference for persistent connections. When the property is `true`, the application makes persistent connections to the servers that support them. - -> [!NOTE] -> When using HTTP/1.1, Keep-Alive is on by default. Setting to `false` may result in sending a `Connection: Close` header to the server. - - - -## Examples - The following code example sets the property to `false` to avoid establishing a persistent connection with the Internet resource. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Connection/httpwebrequest_connection.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/Connection/httpwebrequest_connection.vb" id="Snippet1"::: - - ]]> +]]> @@ -3513,21 +2677,9 @@ Both constructors are obsolete and should not b property sets the maximum number of redirections for the request to follow if the property is `true`. - - - -## Examples - The following code example sets the value of this property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Credentials/httpwebrequest1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/Credentials/httpwebrequest1.vb" id="Snippet1"::: - - ]]> +]]> The value is set to 0 or less. @@ -3574,25 +2726,9 @@ Both constructors are obsolete and should not b property is not explicitly set, it defaults to the value of the property. - - If the length of the response header received exceeds the value of the property, the or methods will throw a with the property set to . - - - -## Examples - The following code example sets the value of this property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Credentials/httpwebrequest1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/Credentials/httpwebrequest1.vb" id="Snippet1"::: - - ]]> +]]> The property is set after the request has already been submitted. The value is less than 0. @@ -3641,13 +2777,9 @@ Both constructors are obsolete and should not b property affects the property. When you set the in the request, the corresponding media type is chosen from the list of character sets returned in the response `Content-type` HTTP header. - - ]]> +]]> @@ -3700,23 +2832,9 @@ Both constructors are obsolete and should not b property can be set to any of the HTTP 1.1 protocol verbs: GET, HEAD, POST, PUT, DELETE, TRACE, or OPTIONS. - - If the property is set to any value other than -1, the property must be set to a protocol property that uploads data. - - - -## Examples - The following code example sets the property to POST. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ContentLength/httpwebrequest_contentlength.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/ContentLength/httpwebrequest_contentlength.vb" id="Snippet4"::: - - ]]> +]]> No method is supplied. @@ -3768,23 +2886,9 @@ Both constructors are obsolete and should not b property to indicate a preference for pipelined connections. When is `true`, an application makes pipelined connections to the servers that support them. - - Pipelined connections are made only when the property is also `true`. - - - -## Examples - The following code example prints the value of the property to the console. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Pipelined/httpwebrequest_pipelined.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/Pipelined/httpwebrequest_pipelined.vb" id="Snippet1"::: - - ]]> +]]> @@ -3831,73 +2935,9 @@ Both constructors are obsolete and should not b is successfully authenticated, if is `true` and credentials are supplied, the Authorization header is sent with each request to any that matches the specific up to the last forward slash. So if the client request successfully authenticated to a specific that contains the following: - - `http://www.contoso.com/firstpath/` - - Then the Authorization header for preauthentication is sent with each request to any of the following instances: - - `http://www.contoso.com/firstpath/` - - `http://www.contoso.com/firstpath/default` - - `http://www.contoso.com/firstpath/default.html` - - `http://www.contoso.com/firstpath/sample.html` - - However, the Authorization header is not sent with requests to any of the following instances: - - `http://www.contoso.com/` - - `http://www.contoso.com/firstpath` - - `http://www.contoso.com/secondpath/` - - `http://www.contoso.com/firstpath/thirdpath/` - - If the client request to a specific is not successfully authenticated, the request uses standard authentication procedures. - - With the exception of the first request, the property indicates whether to send authentication information with subsequent requests to a that matches the specific up to the last forward slash without waiting to be challenged by the server. - - The following dialog between client and server illustrates the effect of this property. The dialog assumes that basic authentication is in use. - - is `false`: - - Client: GET someUrl - - Server: 401 WWW-Authenticate Basic - - Client: GET with Authorization headers - - Server: 200 OK - - Client: GET someUrl - - Server: 401 WWW-Authenticate Basic - - Client: GET with Authorization headers - - Server: 200 OK - - is `true`: - - Client: GET someUrl - - Server: 401 WWW-Authenticate Basic - - Client: GET with Authorization headers - - Server: 200 OK - - Client: GET someUrl with Authorization headers - - If the authentication scheme does not support preauthentication, the value of this property is ignored. - - ]]> +]]> @@ -3949,24 +2989,9 @@ Both constructors are obsolete and should not b class supports only versions 1.0 and 1.1 of HTTP. Setting to a different version throws an exception. - -> [!NOTE] -> To set the HTTP version of the current request, use the and fields of the class. - - - -## Examples - The following code example sets the property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ProtocolVersion/httpwebrequest_protocolversion.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/ProtocolVersion/httpwebrequest_protocolversion.vb" id="Snippet1"::: - - ]]> +]]> The HTTP version is set to a value other than 1.0 or 1.1. @@ -4014,39 +3039,14 @@ Both constructors are obsolete and should not b property identifies the object to use to process requests to Internet resources. To specify that no proxy should be used, set the property to the proxy instance returned by the method. - - The local computer or application config file may specify that a default proxy be used. If the property is specified, then the proxy settings from the property override the local computer or application config file and the instance will use the proxy settings specified. If no proxy is specified in a config file and the property is unspecified, the class uses the proxy settings inherited from Internet options on the local computer. If there are no proxy settings in Internet options, the request is sent directly to the server. - - The class supports local proxy bypass. The class considers a destination to be local if any of the following conditions are met: - -- The destination contains a flat name (no dots in the URL). - -- The destination contains a loopback address ( or ) or the destination contains an assigned to the local computer. - -- The domain suffix of the destination matches the local computer's domain suffix (). - - Changing the property after the request has been started by calling the , , , or method throws an . For information on the proxy element see [\<defaultProxy\> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/defaultproxy-element-network-settings). - - - -## Examples - The following code example uses the method to get the proxy information for the request. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Proxy/httpwebrequest_proxy.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/Proxy/httpwebrequest_proxy.vb" id="Snippet1"::: - - ]]> +]]> is set to . The request has been started by calling , , , or . The caller does not have permission for the requested operation. - DefaultProxy Element (Network Settings) Configuring Internet Applications Proxy Configuration Automatic Proxy Detection @@ -4094,24 +3094,9 @@ Both constructors are obsolete and should not b property is used when writing to the stream returned by the method or reading from the stream returned by the method. - - Specifically, the property controls the time-out for the method, which is used to read the stream returned by the method, and for the method, which is used to write to the stream returned by the method. - - To specify the amount of time to wait for the request to complete, use the property. - - - -## Examples - The following code example shows how to set the property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Overview/source.cs" id="Snippet2"::: - - ]]> +]]> The request has already been sent. The value specified for a set operation is less than or equal to zero and is not equal to @@ -4161,24 +3146,9 @@ Both constructors are obsolete and should not b property to `null`. - -> [!NOTE] -> The value for this property is stored in . If WebHeaderCollection is set, the property value is lost. - - - -## Examples - The following code example sets the property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Referer/httpwebrequest_referer.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/Referer/httpwebrequest_referer.vb" id="Snippet1"::: - - ]]> +]]> @@ -4231,23 +3201,9 @@ Both constructors are obsolete and should not b object passed to by the call to . - - Following a redirection header does not change the property. To get the actual URI that responded to the request, examine the property. - - - -## Examples - The following code example checks to see if the object `req` was redirected to another location to fulfill the request, and sets the value of the `hasChanged` variable to `true` if the request was redirected; otherwise, `hasChanged` is set to `false`. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Address/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/Address/source.vb" id="Snippet1"::: - - ]]> +]]> @@ -4294,23 +3250,9 @@ Both constructors are obsolete and should not b is `true`, the request sends data to the Internet resource in segments. The Internet resource must support receiving chunked data. - - Changing the property after the request has been started by calling the , , , or method throws an . - - - -## Examples - The following code example sets the property to `true` so that data can be sent in segments to the Internet resource. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/SendChunked/httpwebrequest_sendchunked.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/SendChunked/httpwebrequest_sendchunked.vb" id="Snippet2"::: - - ]]> +]]> The request has been started by calling the , , , or method. @@ -4356,13 +3298,9 @@ Both constructors are obsolete and should not b property is `null`. - - ]]> +]]> @@ -4414,19 +3352,9 @@ Both constructors are obsolete and should not b property may be different from if the request is redirected. - - - -## Examples - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/ServicePoint/servicepoint.vb" id="Snippet6"::: - - ]]> +]]> @@ -4587,32 +3515,9 @@ Both constructors are obsolete and should not b is the number of milliseconds that a subsequent synchronous request made with the method waits for a response, and the method waits for a stream. The applies to the entire request and response, not individually to the and method calls. If the resource is not returned within the time-out period, the request throws a with the property set to . - - The property must be set before the or method is called. Changing the property after calling the or method has no effect - - The property has no effect on asynchronous requests made with the or method. - -> [!CAUTION] -> In the case of asynchronous requests, the client application implements its own time-out mechanism. Refer to the example in the method. - - To specify the amount of time to wait before a read or write operation times out, use the property. - - A Domain Name System (DNS) query may take up to 15 seconds to return or time out. If your request contains a host name that requires resolution and you set to a value less than 15 seconds, it may take 15 seconds or more before a is thrown to indicate a timeout on your request. - - - -## Examples - The following code example sets the property of the object. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Timeout/httpwebrequest_timeout.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/Timeout/httpwebrequest_timeout.vb" id="Snippet1"::: - - ]]> +]]> The value specified is less than zero and is not . @@ -4661,18 +3566,9 @@ Both constructors are obsolete and should not b property, you must first set the property to `true`. Clearing by setting it to `null` has no effect on the value of . - - Values assigned to the property replace any existing contents. - -> [!NOTE] -> The value for this property is stored in . If WebHeaderCollection is set, the property value is lost. - - ]]> +]]> is set when is . @@ -4723,31 +3619,9 @@ Both constructors are obsolete and should not b [!CAUTION] -> Because it is possible for an application to use the connection without being authenticated, you need to be sure that there is no administrative vulnerability in your system when setting this property to `true`. If your application sends requests for multiple users (impersonates multiple user accounts) and relies on authentication to protect resources, do not set this property to `true` unless you use connection groups as described below. - - You may want to consider enabling this mechanism if your are having performance problems and your application is running on a Web server with integrated Windows authentication. - - Enabling this setting opens the system to security risks. If you set the property to `true` be sure to take the following precautions: - -- Use the property to manage connections for different users. This avoids the potential use of the connection by non-authenticated applications. For example, user A should have a unique connection group name that is different from user B. This provides a layer of isolation for each user account. - -- Run your application in a protected environment to help avoid possible connection exploits. - - If you control the back-end server, as an alternative you might consider turning off authentication persistence. This increases performance to a lesser degree, but it is safer. - -> [!NOTE] -> If both and are set to `true`, each request is sent using a connection from the unsafe pool, but with an Authorization header. - - ]]> +]]> @@ -4794,13 +3668,9 @@ Both constructors are obsolete and should not b object should, if requested by the server, be authenticated using the credentials of the currently logged on user. For client applications, this is the desired behavior in most scenarios. For middle-tier applications, such as ASP.NET applications, instead of using this property, you would typically set the property to the credentials of the client on whose behalf the request is made. - - ]]> +]]> You attempted to set this property after the request was sent. @@ -4848,19 +3718,9 @@ Both constructors are obsolete and should not b . If `WebHeaderCollection` is set, the property value is lost. - -## Examples - The following code example sets the property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/UserAgent/httpwebrequest_useragent.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/UserAgent/httpwebrequest_useragent.vb" id="Snippet1"::: - - ]]> +]]> diff --git a/xml/System.Net/HttpWebResponse.xml b/xml/System.Net/HttpWebResponse.xml index 9139f110391..4995d6a0885 100644 --- a/xml/System.Net/HttpWebResponse.xml +++ b/xml/System.Net/HttpWebResponse.xml @@ -332,14 +332,12 @@ The contents of the response from the Internet resource are returned as a method closes the response stream and releases the connection to the resource for reuse by other requests. - You should not access any properties of the object after the call to the `Close` method. On .NET Core, an is thrown. + You should not access any properties of the object after the call to the `Close` method. If you do, an is thrown. You must call either the or the method to close the stream and release the connection for reuse. It is not necessary to call both and , but doing so does not cause an error. Failure to close the stream can cause your application to run out of connections. > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - +> This member outputs trace information when you enable network tracing in your application. ## Examples The following example demonstrates how to close a . @@ -349,7 +347,7 @@ The contents of the response from the Internet resource are returned as a - **.NET Core only:** This object has been disposed. + This object has been disposed. @@ -646,8 +644,7 @@ The contents of the response from the Internet resource are returned as a references. This method invokes the `Dispose()` method of each referenced object. > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - +> This member outputs trace information when you enable network tracing in your application. ]]> @@ -838,9 +835,7 @@ The contents of the response from the Internet resource are returned as a You must call one of the , , , or methods to close the stream and release the connection for reuse. It's not necessary to close or dispose both and instances, but doing so doesn't cause an error. Failure to close or dispose the stream will cause your application to run out of connections. > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - +> This member outputs trace information when you enable network tracing in your application. ## Examples The following example demonstrates how to use to return the instance used to read the response from the server. diff --git a/xml/System.Net/ICredentialPolicy.xml b/xml/System.Net/ICredentialPolicy.xml index 8544fd7cf2f..099c67b892f 100644 --- a/xml/System.Net/ICredentialPolicy.xml +++ b/xml/System.Net/ICredentialPolicy.xml @@ -49,13 +49,11 @@ The credential policy determines whether to send credentials when sending a for a network resource, such as the content of a Web page. If credentials are sent, servers that require client authentication can attempt to authenticate the client when the request is received instead of sending a response that indicates that the client's credentials are required. While this saves a round trip to the server, this performance gain must be balanced against the security risk inherent in sending credentials across the network. When the destination server does not require client authentication, it is best not to send credentials. > [!NOTE] -> policies are invoked only if the or the that is associated with the request has credentials that are not `null`. Setting this policy has no effect on requests that do not specify credentials. +> policies are invoked only if the or the that is associated with the request has credentials that are not `null`. Setting this policy has no effect on requests that do not specify credentials. Use the property to set an policy. The that handles authentication for the request will invoke the method before performing the authentication. If the method returns `false`, authentication is not performed. - An policy affects all instances of with non-null credentials in the current application domain. The policy cannot be overridden on individual requests. - - + An policy affects all instances of with non-null credentials. The policy cannot be overridden on individual requests. ## Examples The following code example shows an implementation of this interface that permits credentials to be sent only for requests that target specific hosts. diff --git a/xml/System.Net/IWebProxyScript.xml b/xml/System.Net/IWebProxyScript.xml index b6ef757590f..22cfa6d6ee6 100644 --- a/xml/System.Net/IWebProxyScript.xml +++ b/xml/System.Net/IWebProxyScript.xml @@ -181,19 +181,8 @@ Internal only. Internal only. Runs a script. - A . - - An internal-only value returned. - - object is run, it may need to run the WPAD (Web Proxy Automatic Detection) protocol to detect whether a proxy is required for reaching the destination URL. During this process, the system downloads and compiles the PAC (Proxy Auto-Configuration) script in memory and tries to execute the FindProxyForURL function as per the PAC specification. - - When doing so, the system creates an internal application domain inside the application which runs with minimal permissions, and, most importantly, it does not grant the UI permission to this new application domain. The evaluation of a proxy and running the FindProxyForURL javascript function happens in the context of this new application domain and during this process the system may need to run several helper functions as per the PAC specification. - - ]]> - + An internal-only value. + To be added. diff --git a/xml/System.Net/SecurityProtocolType.xml b/xml/System.Net/SecurityProtocolType.xml index 986d926f1b8..8c060fbd225 100644 --- a/xml/System.Net/SecurityProtocolType.xml +++ b/xml/System.Net/SecurityProtocolType.xml @@ -60,13 +60,12 @@ property. Use this enumeration to determine your transport security protocol policy when you're using HTTP APIs in the .NET Framework such as , , , and (when using TLS/SSL). + This enumeration defines the set of values that you can use to specify which transport security protocol to use. It is the enumerated type for the property. Use this enumeration to determine your transport security protocol policy when you're using HTTP APIs such as , , , and (when using TLS/SSL). The Transport Layer Security (TLS) protocols assume that a connection-oriented protocol, typically TCP, is in use. ]]> - Transport Layer Security (TLS) best practices with the .NET Framework diff --git a/xml/System.Net/ServicePoint.xml b/xml/System.Net/ServicePoint.xml index 410da7f9f8f..9ba795a2b4e 100644 --- a/xml/System.Net/ServicePoint.xml +++ b/xml/System.Net/ServicePoint.xml @@ -64,24 +64,6 @@ [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The class handles connections to an Internet resource based on the host information passed in the resource's Uniform Resource Identifier (URI). The initial connection to the resource determines the information that the object maintains, which is then shared by all subsequent requests to that resource. - - objects are managed by the class and are created, if necessary, by the method. objects are never created directly but are always created and managed by the class. The maximum number of objects that can be created is set by the property. - - Each object maintains its connection to an Internet resource until it has been idle longer than the time specified in the property. When a exceeds the value, it can be recycled to another connection. The default value of is set by the property. - - When the property is set to a value other than -1, and after the specified time elapses, an active connection is closed after it services the next request. This is useful for applications that do not require active connections that are opened indefinitely, as they are by default. - -> [!NOTE] -> In high load conditions, some applications may run out of free threads in the ThreadPool, which may lead to poor system performance (such as high and variable transaction times). - - -## Examples - The following code example creates a object that connects to the URI `www.contoso.com`. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/ServicePoint/servicepoint.vb" id="Snippet1"::: - ]]> @@ -193,16 +175,9 @@ (or for Internet Protocol Version 6) and an ephemeral port. Your can satisfy this requirement. - -> [!NOTE] -> Since .NET 9, uses to bind the underlying socket to the endpoint from this delegate. - - ]]> +]]> @@ -258,22 +233,9 @@ object can make multiple connections to an Internet resource, it can maintain only one certificate. - -> [!NOTE] -> Since .NET 9, returns the remote certificate retrieved via on . - -## Examples - The following code example displays the value of this property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/ServicePoint/servicepoint.vb" id="Snippet5"::: - - ]]> +]]> @@ -391,13 +353,9 @@ Although a object can make multiple connections t +]]> @@ -445,30 +403,9 @@ Although a object can make multiple connections t object's active connections do not remain open indefinitely. This property is intended for scenarios where connections should be dropped and reestablished periodically, such as load balancing scenarios. - - By default, when is `true` for a request, the property sets the time-out for closing connections due to inactivity. If the has active connections, has no effect and the connections remain open indefinitely. - - When the property is set to a value other than -1, and after the specified time elapses, an active connection is closed after servicing a request by setting to `false` in that request. - - Setting this value affects all connections managed by the object. - - -> [!NOTE] -> Since .NET 9, this property maps to . However, handlers are not being reused between requests so it doesn't have any meaningful impact. - - -## Examples - The following code example sets the value of this property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/ServicePoint/ConnectionLeaseTimeout/nclservicepoint.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/ServicePoint/ConnectionLeaseTimeout/nclservicepoint.vb" id="Snippet1"::: - - ]]> +]]> The value specified for a set operation is a negative number less than -1. @@ -521,25 +458,9 @@ Although a object can make multiple connections t property sets the maximum number of connections that the object can make to an Internet resource. The value of the property is set to the value of the property when the object is created; subsequent changes to have no effect on existing objects. - - The connection limit doesn't apply to proxied connections or proxy tunnels. - -> [!NOTE] -> Since .NET 9, this property maps to . However, handlers are not being reused between requests so it doesn't have any meaningful impact. - - -## Examples - The following code example uses the property to check the maximum number of connections that the object can make to the specified Uniform Resource Identifier (URI). - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/ServicePoint/servicepoint.vb" id="Snippet4"::: - - ]]> +]]> The connection limit is equal to or less than 0. Managing Connections @@ -590,21 +511,9 @@ Although a object can make multiple connections t object was constructed by calling a overload with a argument, then the property represents the property of the object used. - - If the object was constructed from a network host and port, the property contains a string that represents the host and the network port. If the property is set when constructed from a host and port, only objects with the same value can use this object. - - - -## Examples - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/ServicePoint/servicepoint.vb" id="Snippet4"::: - - ]]> +]]> Connection Grouping @@ -654,22 +563,9 @@ Although a object can make multiple connections t property contains the number of open Internet connections associated with this object. The value of cannot exceed that of . - -> [!NOTE] -> This property is only implemented on .NET Framework. - -## Examples - The following code example uses the property to determine the number of open Internet connections associated with this object. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/ServicePoint/servicepoint.vb" id="Snippet2"::: - - ]]> +]]> @@ -719,30 +615,9 @@ Although a object can make multiple connections t property is `false`. When the request is sent to the server, it includes the data. If, after reading the request headers, the server requires authentication and sends a 401 response, the client must resend the data with proper authentication headers. - - If the property is `true`, the request headers are sent to the server. If the server has not rejected the request, it sends a 100-Continue response signaling that the data can be transmitted. If, as in the preceding example, the server requires authentication, it sends the 401 response and the client has not unnecessarily transmitted the data. - - Changing the value of this property does not affect existing connections. Only new connections created after the change are affected. - - The Expect 100-Continue behavior is fully described in IETF RFC 2616 Section 10.1.1. - -> [!NOTE] -> Since .NET 9, this property sets on the . - -## Examples - The following code example displays the value of this property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/ServicePoint/servicepoint.vb" id="Snippet9"::: - - ]]> +]]> @@ -791,20 +666,9 @@ Although a object can make multiple connections t property records the last date and time at which a service point was disconnected from a host. When the difference between the current time and exceeds the value of , the object is available for recycling to another connection. - - -## Examples - The following code example uses the property to set and retrieve the date and time that the object was last connected to a host. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/ServicePoint/servicepoint.vb" id="Snippet3"::: - - ]]> +]]> @@ -853,26 +717,9 @@ Although a object can make multiple connections t to to indicate that a connection associated with the object should never time out. - - The default value of the property is the value of the property when the object is created. Subsequent changes to the property have no effect on existing objects. - - When the for a connection associated with a is exceeded, the connection remains open until the application tries to use the connection. At that time, the Framework closes the connection and creates a new connection to the remote host. - -> [!NOTE] -> Since .NET 9, this property maps to . However, handlers are not being reused between requests so it doesn't have any meaningful impact. - -## Examples - The following code example uses the property to set and retrieve the idle time. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/ServicePoint/servicepoint.vb" id="Snippet3"::: - - ]]> +]]> is set to less than or greater than Int32.MaxValue. @@ -923,22 +770,9 @@ Although a object can make multiple connections t [!NOTE] -> Since .NET 9, this property returns . - -## Examples - The following code example displays the value of this property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/ServicePoint/servicepoint.vb" id="Snippet5"::: - - ]]> +]]> @@ -986,22 +820,9 @@ Although a object can make multiple connections t . - -> [!NOTE] -> Since .NET 9, uses to set to the value of this property. - -## Examples - The following code example sets the value of this property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/ServicePoint/ConnectionLeaseTimeout/nclservicepoint.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/ServicePoint/ConnectionLeaseTimeout/nclservicepoint.vb" id="Snippet1"::: - - ]]> +]]> The value specified for a set operation is greater than Int32.MaxValue. @@ -1065,22 +886,9 @@ Although a object can make multiple connections t of is returned to any calls in progress on the socket, and any subsequent calls will fail with a of . - - This method is not thread-safe. Any new connection created at the same time might see partially changed values for the TCP keep-alive. - -> [!NOTE] -> Since .NET 9, uses to set TCP keep alive options on the underlying socket to the values provided to this method. - - ]]> +]]> The value specified for or parameter is less than or equal to 0. @@ -1131,24 +939,9 @@ Although a object can make multiple connections t [!NOTE] -> This property is only implemented on .NET Framework. - -## Examples - The following code example displays the value of this property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/ServicePoint/servicepoint.vb" id="Snippet5"::: - - ]]> +]]> @@ -1198,26 +991,9 @@ Although a object can make multiple connections t [!NOTE] -> Since .NET 9, uses to set to the opposite value than this property. - -## Examples - The following code example displays the value of this property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/ServicePoint/servicepoint.vb" id="Snippet9"::: - - ]]> +]]> diff --git a/xml/System.Net/ServicePointManager.xml b/xml/System.Net/ServicePointManager.xml index f8f9b3ffee6..1615d2db3b6 100644 --- a/xml/System.Net/ServicePointManager.xml +++ b/xml/System.Net/ServicePointManager.xml @@ -69,9 +69,7 @@ When an application requests a connection to an Internet resource Uniform Resource Identifier (URI) through the object, the returns a object that contains connection information for the host and scheme identified by the URI. If there is an existing object for that host and scheme, the object returns the existing object; otherwise, the object creates a new object. - The .NET Framework 4.6 includes a security feature that blocks insecure cipher and hashing algorithms for connections. Applications using TLS/SSL through APIs such as , , , , and and targeting .NET Framework 4.6 or later get the more-secure behavior by default. - - Developers may want to opt out of this behavior in order to maintain interoperability with their existing SSL3 services or TLS w/ RC4 services. [This article](https://support.microsoft.com/kb/3069494) explains how to modify your code so that the new behavior is disabled. +To opt out of the behavior that blocks insecure cipher and hashing algorithms for connections in order to maintain interoperability with your existing SSL3 services or TLS w/ RC4 services, see [Cannot connect to a server by using the ServicePointManager or SslStream APIs after upgrade to the .NET Framework 4.6](https://support.microsoft.com/kb/3069494). > [!IMPORTANT] > We don't recommend that you use the `ServicePointManager` class for new development. Instead, use the class. @@ -85,7 +83,6 @@ ]]> - ServicePointManager Element (Network Settings) @@ -263,7 +260,7 @@ 4 - The default number of non-persistent connections (4) allowed on a object connected to an HTTP/1.0 or later server. This field is constant but is no longer used as of .NET Framework 2.0. + The default number of non-persistent connections (4) allowed on a object connected to an HTTP/1.0 or later server. This field is constant but is no longer used. To be added. @@ -504,7 +501,6 @@ - ServicePointManager Element (Network Settings) @@ -1042,22 +1038,18 @@ Gets or sets the security protocol used by the objects managed by the object. - One of the values defined in the enumeration. + One of the values defined in the enumeration. The default value is . . This allows .NET Framework networking APIs based on (such as FTP, HTTP, and SMTP) to inherit the default security protocols from the operating system or from any custom configurations performed by a system administrator. For information about which SSL/TLS protocols are enabled by default on each version of the Windows operating system, see [Protocols in TLS/SSL (Schannel SSP)](/windows/win32/secauthn/protocols-in-tls-ssl--schannel-ssp-). - -For versions of the .NET Framework through the .NET Framework 4.6.2, no default value is listed for this property. The security landscape changes constantly, and default protocols and protection levels are changed over time in order to avoid known weaknesses. Defaults vary depending on individual machine configuration, installed software, and applied patches. +The default value of this property is , which allows networking APIs based on (such as FTP, HTTP, and SMTP) to inherit the default security protocols from the operating system or from any custom configurations performed by a system administrator. For information about which SSL/TLS protocols are enabled by default on each version of the Windows operating system, see [Protocols in TLS/SSL (Schannel SSP)](/windows/win32/secauthn/protocols-in-tls-ssl--schannel-ssp-). Your code should never implicitly depend on using a particular protection level, or on the assumption that a given security level is used by default. If your app depends on the use of a particular security level, you must explicitly specify that level and then check to be sure that it is actually in use on the established connection. Further, your code should be designed to be robust in the face of changes to which protocols are supported, as such changes are often made with little advance notice in order to mitigate emerging threats. - The .NET Framework 4.6 includes a security feature that blocks insecure cipher and hashing algorithms for connections. Applications using TLS/SSL through APIs such as HttpClient, HttpWebRequest, FTPClient, SmtpClient, and SslStream and targeting .NET Framework 4.6 get the more-secure behavior by default. - - Developers may want to opt out of this behavior in order to maintain interoperability with their existing SSL3 services OR TLS w/ RC4 services. [This article](https://support.microsoft.com/kb/3069494) explains how to modify your code so that the new behavior is disabled. +To opt out of the behavior that blocks insecure cipher and hashing algorithms for connections in order to maintain interoperability with your existing SSL3, or TLS with RC4, services, see [Cannot connect to a server by using the ServicePointManager or SslStream APIs after upgrade to the .NET Framework 4.6](https://support.microsoft.com/kb/3069494). > [!NOTE] > Since .NET 9, this property maps to on . diff --git a/xml/System.Net/SocketPermission.xml b/xml/System.Net/SocketPermission.xml index 12169991282..f317197959c 100644 --- a/xml/System.Net/SocketPermission.xml +++ b/xml/System.Net/SocketPermission.xml @@ -51,11 +51,6 @@ [!INCLUDE[cas-deprecated](~/includes/cas-deprecated.md)] - instances control permission to accept connections or initiate connections. A permission can be established for a host name or IP address, a port number, and a transport protocol. - -> [!NOTE] -> Avoid creating socket permissions using host names, as these names have to be resolved to IP addresses, and this might block the stack. - ]]> @@ -103,14 +98,7 @@ One of the values. Initializes a new instance of the class that allows unrestricted access to the or disallows access to the . - - instance is created with the `Unrestricted` value from then the instance passes all demands. Any other value for `state` results in a instance that fails all demands unless a transport address permission is added with . - - ]]> - + To be added. @@ -152,18 +140,7 @@ The host name for the transport address. The port number for the transport address. Initializes a new instance of the class for the given transport address with the specified permission. - - that controls access to the specified `hostName` and `portNumber` using the specified `transport`. - - The `hostName` can be a DNS name, an IP address, or a specified IP subnet, such as 192.168.1.*. - - The `portNumber` can be any valid port number defined by the transport, or . - - ]]> - + To be added. is . @@ -246,14 +223,7 @@ The host name for the transport address. The port number for the transport address. Adds a permission to the set of permissions for a transport address. - - - + To be added. is . @@ -291,14 +261,7 @@ -1 Defines a constant that represents all ports. - - - + To be added. @@ -371,14 +334,7 @@ Creates a copy of a instance. A new instance of the class that is a copy of the current instance. - - and is implemented to support the interface. - - ]]> - + To be added. @@ -417,16 +373,7 @@ The XML encoding used to reconstruct the instance. Reconstructs a instance for an XML encoding. - - method reconstructs a instance from an XML encoding defined by the class. - - Use the method to encode the instance, including state information, in XML. - - ]]> - + To be added. The is . The is not a permission element for this type. @@ -468,14 +415,7 @@ The instance to intersect with the current instance. Returns the logical intersection between two instances. The instance that represents the intersection of two instances. If the intersection is empty, the method returns . If the parameter is a null reference, the method returns . - - and is implemented to support the interface. - - ]]> - + To be added. The parameter is not a . is not granted to the method caller. @@ -518,16 +458,7 @@ A that is to be tested for the subset relationship. Determines if the current permission is a subset of the specified permission. If is , this method returns if the current instance defines no permissions; otherwise, . If is not , this method returns if the current instance defines a subset of permissions; otherwise, . - - - + To be added. is not a . @@ -609,16 +540,7 @@ Creates an XML encoding of a instance and its current state. A instance that contains an XML-encoded representation of the instance, including state information. - - method creates a instance to encode a representation of the instance, including state information, in XML. - - Use the method to restore the state information from a instance. - - ]]> - + To be added. @@ -658,14 +580,7 @@ The instance to combine with the current instance. Returns the logical union between two instances. The instance that represents the union of two instances. If parameter is , it returns a copy of the current instance. - - is a permission that represents all of the access to connections represented by the current instance as well as the access represented by `target`. Any demand that passes either the current instance or `target` passes their union. This method overrides and is implemented to support the interface. - - ]]> - + To be added. is not a . diff --git a/xml/System.Net/SocketPermissionAttribute.xml b/xml/System.Net/SocketPermissionAttribute.xml index 21d7d7f421f..09460d0772f 100644 --- a/xml/System.Net/SocketPermissionAttribute.xml +++ b/xml/System.Net/SocketPermissionAttribute.xml @@ -51,14 +51,6 @@ [!INCLUDE[cas-deprecated](~/includes/cas-deprecated.md)] - To use this attribute, your connection must conform to the properties that are specified in your . For example, to apply the permission to a connection on port 80, set the property of the to "80". The security information that is specified in is stored in the metadata of the attribute target, which is the class to which the is applied. The system then accesses the information at run time. The that is passed to the constructor determines the allowable targets. - -> [!NOTE] -> The properties of a must have values that are not `null`. Also, once set, the values of the properties cannot be changed. - -> [!NOTE] -> For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). - ]]> @@ -97,14 +89,7 @@ One of the values. Initializes a new instance of the class with the specified value. - - value that is passed to this constructor specifies the allowable targets. - - ]]> - + To be added. is not a valid value. @@ -142,14 +127,7 @@ Gets or sets the network access method that is allowed by this . A string that contains the network access method that is allowed by this instance of . Valid values are "Accept" and "Connect." - - enumeration values. - - ]]> - + To be added. The property is not when you attempt to set the value. To specify more than one Access method, use an additional attribute declaration statement. @@ -187,14 +165,7 @@ Creates and returns a new instance of the class. An instance of the class that corresponds to the security declaration. - - method is called by the security system, not by the application code. The security information described by is stored in the metadata of the attribute target, which is the class to which the is applied. The system then accesses the information at run-time and calls . The system uses the returned to enforce the specified security requirements. - - ]]> - + To be added. One or more of the current instance's , , , or properties is . @@ -232,14 +203,7 @@ Gets or sets the DNS host name or IP address that is specified by this . A string that contains the DNS host name or IP address that is associated with this instance of . - - - + To be added. is not when you attempt to set the value. To specify more than one host, use an additional attribute declaration statement. @@ -277,14 +241,7 @@ Gets or sets the port number that is associated with this . A string that contains the port number that is associated with this instance of . - - - + To be added. The property is when you attempt to set the value. To specify more than one port, use an additional attribute declaration statement. @@ -321,14 +278,7 @@ Gets or sets the that is specified by this . A string that contains the that is associated with this . - - , , , , and . - - ]]> - + To be added. is not when you attempt to set the value. To specify more than one transport type, use an additional attribute declaration statement. diff --git a/xml/System.Net/WebClient.xml b/xml/System.Net/WebClient.xml index 0205c6358cd..8e6c6dd333c 100644 --- a/xml/System.Net/WebClient.xml +++ b/xml/System.Net/WebClient.xml @@ -58,54 +58,6 @@ [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The class provides common methods for sending data to or receiving data from any local, intranet, or Internet resource identified by a URI. - - The class uses the class to provide access to resources. instances can access data with any descendant registered with the method. - -> [!NOTE] -> By default, .NET Framework supports URIs that begin with `http:`, `https:`, `ftp:`, and `file:` scheme identifiers. - - The following table describes methods for uploading data to a resource. - -|Method|Description| -|------------|-----------------| -||Retrieves a used to send data to the resource.| -||Retrieves a used to send data to the resource, without blocking the calling thread.| -||Sends a byte array to the resource and returns a array containing any response.| -||Sends a array to the resource, without blocking the calling thread.| -||Sends a local file to the resource and returns a array containing any response.| -||Sends a local file to the resource, without blocking the calling thread.| -||Sends a to the resource and returns a array containing any response.| -||Sends a to the resource and returns a array containing any response, without blocking the calling thread.| -||Sends a to the resource and returns a containing any response.| -||Sends a to the resource, without blocking the calling thread.| - - The following table describes methods for downloading data from a resource. - -|Method|Description| -|------------|-----------------| -||Returns the data from a resource as a .| -||Returns the data from a resource, without blocking the calling thread.| -||Downloads data from a resource and returns a array.| -||Downloads data from a resource and returns a array, without blocking the calling thread.| -||Downloads data from a resource to a local file.| -||Downloads data from a resource to a local file, without blocking the calling thread.| -||Downloads a from a resource and returns a .| -||Downloads a from a resource, without blocking the calling thread.| - - You can use the method to attempt to cancel asynchronous operations. - - A instance does not send optional HTTP headers by default. If your request requires an optional header, you must add the header to the collection. For example, to retain queries in the response, you must add a user-agent header. Also, servers may return 500 (Internal Server Error) if the user agent header is missing. - - is set to `true` in instances. - -## Examples - The following code example takes the URI of a resource, retrieves it, and displays the response. - - [!code-cpp[NCLWebClientUserAgent#1](~/snippets/cpp/VS_Snippets_Remoting/NCLWebClientUserAgent/CPP/useragent.cpp#1)] - [!code-csharp[NCLWebClientUserAgent#1](~/snippets/csharp/System.Net/WebClient/Overview/useragent.cs#1)] - [!code-vb[NCLWebClientUserAgent#1](~/snippets/visualbasic/System.Net/WebClient/Overview/useragent.vb#1)] - ]]> @@ -225,13 +177,9 @@ property is `true`, the data is buffered in memory so it is ready to be read by the app. - - ]]> +]]> @@ -334,24 +282,9 @@ property contains a base URI that is combined with a relative address. When you call a method that uploads or downloads data, the object combines this base URI with the relative address you specify in the method call. If you specify an absolute URI, does not use the property value. - - To remove a previously set value, set this property to `null` or an empty string (""). - - - -## Examples - The following code example downloads data from an Internet server and displays it on the console. It assumes that the server's address (such as http://www.contoso.com) is in `hostUri` and that the path to the resource (such as /default.htm) is in `uriSuffix`. - - [!code-cpp[WebClient_BaseAddress_ResponseHeaders#1](~/snippets/cpp/VS_Snippets_Remoting/WebClient_BaseAddress_ResponseHeaders/CPP/webclient_baseaddress_responseheaders.cpp#1)] - [!code-csharp[WebClient_BaseAddress_ResponseHeaders#1](~/snippets/csharp/System.Net/WebClient/BaseAddress/webclient_baseaddress_responseheaders.cs#1)] - [!code-vb[WebClient_BaseAddress_ResponseHeaders#1](~/snippets/visualbasic/System.Net/WebClient/BaseAddress/webclient_baseaddress_responseheaders.vb#1)] - - ]]> +]]> is set to an invalid URI. The inner exception may contain information that will help you locate the error. @@ -450,15 +383,6 @@ [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - If an operation is pending, this method calls on the underlying . - - > [!NOTE] - > Starting in .NET Core 2.0, doesn't cancel the request immediately if the response has started to fetch. For optimum cancellation behavior, use the class instead of . - - When you call , your application still receives the completion event associated with the operation. For example, when you call to cancel a operation, if you have specified an event handler for the event, your event handler receives notification that the operation has ended. To learn whether the operation completed successfully, check the property on the base class of in the event data object passed to the event handler. - - If no asynchronous operation is in progress, this method does nothing. - ]]> @@ -512,24 +436,9 @@ property contains the authentication credentials used to access a resource on a host. In most client-side scenarios, you should use the , which are the credentials of the currently logged on user. To do this, set the property to `true` instead of setting this property. - - If the class is being used in a middle tier application, such as an ASP.NET application, the belong to the account running the ASP page (the server-side credentials). Typically, you would set this property to the credentials of the client on whose behalf the request is made. - - For security reasons, when automatically following redirects, store the credentials that you want to be included in the redirect in a and assign it to this property. This property will automatically be set to `null` upon redirection if it contains anything except a . Having this property value be automatically set to `null` under those conditions prevents credentials from being sent to any unintended destination. - -## Examples - The following code example uses the user's system credentials to authenticate a request. - - [!code-cpp[WebClientAuthentication#1](~/snippets/cpp/VS_Snippets_Remoting/WebClientAuthentication/CPP/webclientauth.cpp#1)] - [!code-csharp[WebClientAuthentication#1](~/snippets/csharp/System.Net/WebClient/Credentials/webclientauth.cs#1)] - [!code-vb[WebClientAuthentication#1](~/snippets/visualbasic/System.Net/WebClient/Credentials/webclientauth.vb#1)] - - ]]> +]]> @@ -592,27 +501,9 @@ method downloads the resource with the URI specified by the `address` parameter. This method blocks while downloading the resource. To download a resource and continue executing while waiting for the server's response, use one of the methods. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - -## Examples - The following code example requests data from a server and displays the data returned. It assumes that `remoteUri` contains a valid URI for the requested data. - - [!code-cpp[WebClient_DownloadData#1](~/snippets/cpp/VS_Snippets_Remoting/WebClient_DownloadData/CPP/webclient_downloaddata.cpp#1)] - [!code-csharp[WebClient_DownloadData#1](~/snippets/csharp/System.Net/WebClient/DownloadData/webclient_downloaddata.cs#1)] - [!code-vb[WebClient_DownloadData#1](~/snippets/visualbasic/System.Net/WebClient/DownloadData/webclient_downloaddata.vb#1)] - - ]]> +]]> The parameter is . The URI formed by combining and is invalid. @@ -668,20 +559,9 @@ method downloads the resource with the URI specified by the `address` parameter. This method blocks while downloading the resource. To download a resource and continue executing while waiting for the server's response, use one of the methods. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . @@ -740,25 +620,8 @@ methods. When the download completes, the event is raised. Your application must handle this event to receive notification. The downloaded data is available in the property. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - ]]> The parameter is . @@ -823,24 +686,9 @@ methods. When the download completes, the event is raised. Your application must handle this event to receive notification. The downloaded data is available in the property. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . The URI formed by combining and is invalid. @@ -897,32 +745,9 @@ methods. - - The is the delegate for this event. The class provides the event handler with event data. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - The following code example demonstrates setting an event handler for this event. - - [!code-cpp[NCLWebClientAsync#21](~/snippets/cpp/VS_Snippets_Remoting/NCLWebClientAsync/CPP/asyncmethods.cpp#21)] - [!code-csharp[NCLWebClientAsync#21](~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs#21)] - [!code-vb[NCLWebClientAsync#21](~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb#21)] - - The following code example shows an implementation of a handler for this event. - - [!code-cpp[NCLWebClientAsync#22](~/snippets/cpp/VS_Snippets_Remoting/NCLWebClientAsync/CPP/asyncmethods.cpp#22)] - [!code-csharp[NCLWebClientAsync#22](~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs#22)] - [!code-vb[NCLWebClientAsync#22](~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb#22)] - - ]]> +]]> @@ -980,24 +805,9 @@ object will complete after the data resource has been downloaded. - - This method retrieves the specified resource using the default method for the protocol associated with the URI scheme specified in the `address` parameter. The data is downloaded asynchronously using thread resources that are automatically allocated from the thread pool. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - The following code example requests data from a server and displays the data returned. It assumes that `remoteUri` contains a valid URI for the requested data. - - ]]> +]]> The parameter is . The URI formed by combining and is invalid. @@ -1051,22 +861,9 @@ object will complete after the data resource has been downloaded. - - This method retrieves the specified resource using the default method for the protocol associated with the URI scheme specified in the `address` parameter. The data is downloaded asynchronously using thread resources that are automatically allocated from the thread pool. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . The URI formed by combining and is invalid. @@ -1133,29 +930,9 @@ method downloads to a local file data from the URI specified by in the `address` parameter. This method blocks while downloading the resource. To download a resource and continue executing while waiting for the server's response, use one of the methods. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - When using this method in a middle tier application, such as an ASP.NET page, you will receive an error if the account under which the application executes does not have permission to access the file. - -## Examples - The following code example downloads a file from http://www.contoso.com to the local hard drive. - - [!code-cpp[WebClient_DownloadFile#1](~/snippets/cpp/VS_Snippets_Remoting/WebClient_DownloadFile/CPP/webclient_downloadfile.cpp#1)] - [!code-csharp[WebClient_DownloadFile#1](~/snippets/csharp/System.Net/WebClient/DownloadFile/webclient_downloadfile.cs#1)] - [!code-vb[WebClient_DownloadFile#1](~/snippets/visualbasic/System.Net/WebClient/DownloadFile/webclient_downloadfile.vb#1)] - - ]]> +]]> The parameter is . The URI formed by combining and is invalid. @@ -1218,22 +995,9 @@ method downloads to a local file data from the URI specified by in the `address` parameter. This method blocks while downloading the resource. To download a resource and continue executing while waiting for the server's response, use one of the methods. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - When using this method in a middle tier application, such as an ASP.NET page, you will receive an error if the account under which the application executes does not have permission to access the file. - - ]]> +]]> The parameter is . @@ -1312,27 +1076,8 @@ event. - - This method does not block the calling thread while the resource is being downloaded. To block while waiting for the download to complete, use one of the methods. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - When using this method in an ASP.NET page, you will receive an error if the account that the page executes under does not have permission to access the local file. - - This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - ]]> The parameter is . @@ -1404,26 +1149,9 @@ event. - - This method does not block the calling thread while the resource is being downloaded. To block while waiting for the download to complete, use one of the methods. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - When using this method in an ASP.NET page, you will receive an error if the account that the page executes under does not have permission to access the local file. - - ]]> +]]> The parameter is . @@ -1485,24 +1213,9 @@ methods. - - The is the delegate for this event. The class provides the event handler with event data. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - -## Examples - The following code example demonstrates setting an event handler for the `DownloadFileCompleted` event. - - [!code-cpp[NCLWebClientAsync#19](~/snippets/cpp/VS_Snippets_Remoting/NCLWebClientAsync/CPP/asyncmethods.cpp#19)] - [!code-csharp[NCLWebClientAsync#19](~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs#19)] - [!code-vb[NCLWebClientAsync#19](~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb#19)] - - ]]> +]]> @@ -1562,26 +1275,9 @@ object will complete after the data resource has been downloaded. - - This method downloads the resource at the URI specified by in the `address` parameter. When the download completes successfully, the downloaded file is named `fileName` on the local computer. The file is downloaded asynchronously using thread resources that are automatically allocated from the thread pool. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - When using this method in an ASP.NET page, you will receive an error if the account that the page executes under does not have permission to access the local file. - - ]]> +]]> The parameter is . @@ -1642,26 +1338,9 @@ object will complete after the data resource has been downloaded. - - This method downloads the resource at the URI specified by in the `address` parameter. When the download completes successfully, the downloaded file is named `fileName` on the local computer. The file is downloaded asynchronously using thread resources that are automatically allocated from the thread pool. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - When using this method in an ASP.NET page, you will receive an error if the account that the page executes under does not have permission to access the local file. - - ]]> +]]> The parameter is . @@ -1723,45 +1402,9 @@ |Downloads data from a resource and returns a array, without blocking the calling thread.| -||Downloads data from a resource to a local file, without blocking the calling thread.| -||Returns the data from a resource, without blocking the calling thread.| - - The is the delegate for this event. The class provides the event handler with event data. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - -> [!NOTE] -> A passive FTP file transfer will always show a progress percentage of zero, since the server did not send the file size. To show progress, you can change the FTP connection to active by overriding the virtual method: - -```csharp -internal class MyWebClient : WebClientProtocol -{ - protected override WebRequest GetWebRequest(Uri address) - { - FtpWebRequest req = (FtpWebRequest)base.GetWebRequest(address); - req.UsePassive = false; - return req; - } -} -``` - -## Examples - The following code example demonstrates setting an event handler for the `DownloadProgressChanged` event. - -[!code-cpp[DownloadProgressChanged](~/snippets/cpp/VS_Snippets_Remoting/NCLWebClientAsync/CPP/asyncmethods.cpp#SnippetDownloadProgressChanged)] -[!code-csharp[DownloadProgressChanged](~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs#SnippetDownloadProgressChanged)] -[!code-vb[DownloadProgressChanged](~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb#SnippetDownloadProgressChanged)] - - ]]> +]]> @@ -1820,27 +1463,9 @@ internal class MyWebClient : WebClientProtocol property to convert the resource to a . This method blocks while downloading the resource. To download a resource and continue executing while waiting for the server's response, use one of the methods. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - -## Examples - The following code example demonstrates calling this method. - - [!code-cpp[NCLWebClientAsync#25](~/snippets/cpp/VS_Snippets_Remoting/NCLWebClientAsync/CPP/asyncmethods.cpp#25)] - [!code-csharp[NCLWebClientAsync#25](~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs#25)] - [!code-vb[NCLWebClientAsync#25](~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb#25)] - - ]]> +]]> The parameter is . The URI formed by combining and is invalid. @@ -1896,20 +1521,9 @@ internal class MyWebClient : WebClientProtocol property to convert the resource to a . This method blocks while downloading the resource. To download a resource and continue executing while waiting for the server's response, use one of the methods. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . The URI formed by combining and is invalid. @@ -1974,25 +1588,8 @@ internal class MyWebClient : WebClientProtocol property to convert the resource to a . This method does not block the calling thread while downloading the resource. To download a resource and block while waiting for the server's response, use the method. When the download completes, the event is raised. Your application must handle this event to receive notification. The downloaded string is available in the property. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - ]]> The parameter is . @@ -2057,24 +1654,9 @@ internal class MyWebClient : WebClientProtocol property to convert the resource to a . This method does not block the calling thread while downloading the resource. To download a resource and block while waiting for the server's response, use the method. When the download completes, the event is raised. Your application must handle this event to receive notification. The downloaded string is available in the property. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . The URI formed by combining and is invalid. @@ -2131,32 +1713,9 @@ internal class MyWebClient : WebClientProtocol methods. - - The is the delegate for this event. The class provides the event handler with event data. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - The following code example demonstrates setting an event handler for this event. - - [!code-cpp[NCLWebClientAsync#28](~/snippets/cpp/VS_Snippets_Remoting/NCLWebClientAsync/CPP/asyncmethods.cpp#28)] - [!code-csharp[NCLWebClientAsync#28](~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs#28)] - [!code-vb[NCLWebClientAsync#28](~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb#28)] - - The following code example shows an implementation of a handler for this event. - - [!code-cpp[NCLWebClientAsync#29](~/snippets/cpp/VS_Snippets_Remoting/NCLWebClientAsync/CPP/asyncmethods.cpp#29)] - [!code-csharp[NCLWebClientAsync#29](~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs#29)] - [!code-vb[NCLWebClientAsync#29](~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb#29)] - - ]]> +]]> @@ -2214,23 +1773,9 @@ internal class MyWebClient : WebClientProtocol object will complete after the data resource has been downloaded. The resource is downloaded asynchronously using thread resources that are automatically allocated from the thread pool. - - After downloading the resource, this method uses the encoding specified in the property to convert the resource to a . This method does not block the calling thread while downloading the resource. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. - - This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . The URI formed by combining and is invalid. @@ -2284,23 +1829,9 @@ internal class MyWebClient : WebClientProtocol object will complete after the data resource has been downloaded. The resource is downloaded asynchronously using thread resources that are automatically allocated from the thread pool. - - After downloading the resource, this method uses the encoding specified in the property to convert the resource to a . This method does not block the calling thread while downloading the resource. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. - - This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . The URI formed by combining and is invalid. @@ -2351,24 +1882,9 @@ internal class MyWebClient : WebClientProtocol and methods use this property to convert the specified string to a array before uploading the string. For additional information, see the method. - - When a string is downloaded using the or methods, uses the returned by this to convert the downloaded array into a string. For additional information, see the method. - - - -## Examples - The following code example demonstrates setting the value of this property. - - [!code-cpp[NCLWebClientAsync#1](~/snippets/cpp/VS_Snippets_Remoting/NCLWebClientAsync/CPP/asyncmethods.cpp#1)] - [!code-csharp[NCLWebClientAsync#1](~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs#1)] - [!code-vb[NCLWebClientAsync#1](~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb#1)] - - ]]> +]]> @@ -2417,23 +1933,9 @@ internal class MyWebClient : WebClientProtocol , , and method to the newly created object. - - This method can be called only by classes that inherit from . It is provided to give inheritors access to the underlying object. Derived classes should call the base class implementation of to ensure the method works as expected. - - - -## Examples - The following code example shows an implementation of this method that can be customized by a class derived from . - - [!code-cpp[NCLCustomWebClient#1](~/snippets/cpp/VS_Snippets_Remoting/NCLCustomWebClient/CPP/mywebclient.cpp#1)] - [!code-csharp[NCLCustomWebClient#1](~/snippets/csharp/System.Net/WebClient/GetWebRequest/mywebclient.cs#1)] - - ]]> +]]> @@ -2492,23 +1994,9 @@ internal class MyWebClient : WebClientProtocol method on the specified object. - - This method can be called only by classes that inherit from . It is provided to give inheritors access to the underlying object. - - - -## Examples - The following code example shows an implementation of this method that can be customized by a class derived from . - - [!code-cpp[NCLCustomWebClient#2](~/snippets/cpp/VS_Snippets_Remoting/NCLCustomWebClient/CPP/mywebclient.cpp#2)] - [!code-csharp[NCLCustomWebClient#2](~/snippets/csharp/System.Net/WebClient/GetWebRequest/mywebclient.cs#2)] - - ]]> +]]> @@ -2559,23 +2047,9 @@ internal class MyWebClient : WebClientProtocol method on the specified object. - - This method can be called only by classes that inherit from . It is provided to give inheritors access to the underlying object. - - - -## Examples - The following code example shows an implementation of this method that can be customized by a class derived from . - - [!code-cpp[NCLCustomWebClient#3](~/snippets/cpp/VS_Snippets_Remoting/NCLCustomWebClient/CPP/mywebclient.cpp#3)] - [!code-csharp[NCLCustomWebClient#3](~/snippets/csharp/System.Net/WebClient/GetWebRequest/mywebclient.cs#3)] - - ]]> +]]> @@ -2621,50 +2095,9 @@ internal class MyWebClient : WebClientProtocol property contains a instance containing protocol headers that the sends with the request. - - Some common headers are considered restricted and are protected by the system and cannot be set or changed in a object. Any attempt to set one of these restricted headers in the object associated with a object will throw an exception later when attempting to send the request. - - Restricted headers protected by the system include, but are not limited to the following: - -- Date - -- Host - - In addition, some other headers are also restricted when using a object. These restricted headers include, but are not limited to the following: - -- Accept - -- Connection - -- Content-Length - -- Expect (when the value is set to "100-continue" - -- If-Modified-Since - -- Range - -- Transfer-Encoding - - The class has properties for setting some of the above headers. If it is important for an application to set these headers, then the class should be used instead of the class. - - You should not assume that the header values will remain unchanged, because Web servers and caches may change or add headers to a Web request. - - - -## Examples - The following code example uses the collection to set the HTTP `Content-Type` header to `application/x-www-form-urlencoded,` to notify the server that form data is attached to the post. - - [!code-cpp[WebClient_UpLoadData_Headers#2](~/snippets/cpp/VS_Snippets_Remoting/WebClient_UpLoadData_Headers/CPP/webclient_uploaddata_headers.cpp#2)] - [!code-csharp[WebClient_UpLoadData_Headers#2](~/snippets/csharp/System.Net/WebClient/Headers/webclient_uploaddata_headers.cs#2)] - [!code-vb[WebClient_UpLoadData_Headers#2](~/snippets/visualbasic/System.Net/WebClient/Headers/webclient_uploaddata_headers.vb#2)] - - ]]> +]]> @@ -2756,25 +2189,9 @@ internal class MyWebClient : WebClientProtocol event occurs. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - - - -## Examples - The following code example shows an implementation of this method that can be customized by a class derived from . - - [!code-cpp[NCLCustomWebClient#4](~/snippets/cpp/VS_Snippets_Remoting/NCLCustomWebClient/CPP/mywebclient.cpp#4)] - [!code-csharp[NCLCustomWebClient#4](~/snippets/csharp/System.Net/WebClient/GetWebRequest/mywebclient.cs#4)] - - ]]> +]]> When overriding in a derived class, be sure to call the base class' method so that registered delegates receive the event. @@ -2825,25 +2242,9 @@ internal class MyWebClient : WebClientProtocol event occurs. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - - - -## Examples - The following code example shows an implementation of this method that can be customized by a class derived from . - - [!code-cpp[NCLCustomWebClient#5](~/snippets/cpp/VS_Snippets_Remoting/NCLCustomWebClient/CPP/mywebclient.cpp#5)] - [!code-csharp[NCLCustomWebClient#5](~/snippets/csharp/System.Net/WebClient/GetWebRequest/mywebclient.cs#5)] - - ]]> +]]> When overriding in a derived class, be sure to call the base class' method so that registered delegates receive the event. @@ -2894,25 +2295,9 @@ internal class MyWebClient : WebClientProtocol event occurs. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - - - -## Examples - The following code example shows an implementation of this method that can be customized by a class derived from . - - [!code-cpp[NCLCustomWebClient#12](~/snippets/cpp/VS_Snippets_Remoting/NCLCustomWebClient/CPP/mywebclient.cpp#12)] - [!code-csharp[NCLCustomWebClient#12](~/snippets/csharp/System.Net/WebClient/GetWebRequest/mywebclient.cs#12)] - - ]]> +]]> When overriding in a derived class, be sure to call the base class' method so that registered delegates receive the event. @@ -2963,25 +2348,9 @@ internal class MyWebClient : WebClientProtocol event occurs. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - - - -## Examples - The following code example shows an implementation of this method that can be customized by a class derived from . - - [!code-cpp[NCLCustomWebClient#6](~/snippets/cpp/VS_Snippets_Remoting/NCLCustomWebClient/CPP/mywebclient.cpp#6)] - [!code-csharp[NCLCustomWebClient#6](~/snippets/csharp/System.Net/WebClient/GetWebRequest/mywebclient.cs#6)] - - ]]> +]]> When overriding in a derived class, be sure to call the base class' method so that registered delegates receive the event. @@ -3032,25 +2401,9 @@ internal class MyWebClient : WebClientProtocol event occurs. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - - - -## Examples - The following code example shows an implementation of this method that can be customized by a class derived from . - - [!code-cpp[NCLCustomWebClient#7](~/snippets/cpp/VS_Snippets_Remoting/NCLCustomWebClient/CPP/mywebclient.cpp#7)] - [!code-csharp[NCLCustomWebClient#7](~/snippets/csharp/System.Net/WebClient/GetWebRequest/mywebclient.cs#7)] - - ]]> +]]> When overriding in a derived class, be sure to call the base class' method so that registered delegates receive the event. @@ -3101,25 +2454,9 @@ internal class MyWebClient : WebClientProtocol event occurs. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - - - -## Examples - The following code example shows an implementation of this method that can be customized by a class derived from . - - [!code-cpp[NCLCustomWebClient#8](~/snippets/cpp/VS_Snippets_Remoting/NCLCustomWebClient/CPP/mywebclient.cpp#8)] - [!code-csharp[NCLCustomWebClient#8](~/snippets/csharp/System.Net/WebClient/GetWebRequest/mywebclient.cs#8)] - - ]]> +]]> When overriding in a derived class, be sure to call the base class' method so that registered delegates receive the event. @@ -3170,25 +2507,9 @@ internal class MyWebClient : WebClientProtocol event occurs. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - - - -## Examples - The following code example shows an implementation of this method that can be customized by a class derived from . - - [!code-cpp[NCLCustomWebClient#9](~/snippets/cpp/VS_Snippets_Remoting/NCLCustomWebClient/CPP/mywebclient.cpp#9)] - [!code-csharp[NCLCustomWebClient#9](~/snippets/csharp/System.Net/WebClient/GetWebRequest/mywebclient.cs#9)] - - ]]> +]]> When overriding in a derived class, be sure to call the base class' method so that registered delegates receive the event. @@ -3239,25 +2560,9 @@ internal class MyWebClient : WebClientProtocol event occurs. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - - - -## Examples - The following code example shows an implementation of this method that can be customized by a class derived from . - - [!code-cpp[NCLCustomWebClient#10](~/snippets/cpp/VS_Snippets_Remoting/NCLCustomWebClient/CPP/mywebclient.cpp#10)] - [!code-csharp[NCLCustomWebClient#10](~/snippets/csharp/System.Net/WebClient/GetWebRequest/mywebclient.cs#10)] - - ]]> +]]> When overriding in a derived class, be sure to call the base class' method so that registered delegates receive the event. @@ -3308,25 +2613,9 @@ internal class MyWebClient : WebClientProtocol event occurs. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - - - -## Examples - The following code example shows an implementation of this method that can be customized by a class derived from . - - [!code-cpp[NCLCustomWebClient#13](~/snippets/cpp/VS_Snippets_Remoting/NCLCustomWebClient/CPP/mywebclient.cpp#13)] - [!code-csharp[NCLCustomWebClient#13](~/snippets/csharp/System.Net/WebClient/GetWebRequest/mywebclient.cs#13)] - - ]]> +]]> When overriding in a derived class, be sure to call the base class' method so that registered delegates receive the event. @@ -3443,25 +2732,9 @@ internal class MyWebClient : WebClientProtocol event occurs. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - - - -## Examples - The following code example shows an implementation of this method that can be customized by a class derived from . - - [!code-cpp[NCLCustomWebClient#14](~/snippets/cpp/VS_Snippets_Remoting/NCLCustomWebClient/CPP/mywebclient.cpp#14)] - [!code-csharp[NCLCustomWebClient#14](~/snippets/csharp/System.Net/WebClient/GetWebRequest/mywebclient.cs#14)] - - ]]> +]]> When overriding in a derived class, be sure to call the base class' method so that registered delegates receive the event. @@ -3575,30 +2848,9 @@ internal class MyWebClient : WebClientProtocol method creates a instance used to read the contents of the resource specified by the `address` parameter. This method blocks while opening the stream. To continue executing while waiting for the stream, use one of the methods. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not `null`, it is appended to `address`. - - This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. - -> [!NOTE] -> You must call when finished with the to avoid running out of system resources. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - -## Examples - The following code example opens the resource identified by `uriString` and displays the results on the system console. The returned by is closed when the data has been read. - - [!code-cpp[WebClient_OpenRead#1](~/snippets/cpp/VS_Snippets_Remoting/WebClient_OpenRead/CPP/webclient_openread.cpp#1)] - [!code-csharp[WebClient_OpenRead#1](~/snippets/csharp/System.Net/WebClient/OpenRead/webclient_openread.cs#1)] - [!code-vb[WebClient_OpenRead#1](~/snippets/visualbasic/System.Net/WebClient/OpenRead/webclient_openread.vb#1)] - - ]]> +]]> The parameter is . The URI formed by combining , is invalid. @@ -3653,23 +2905,9 @@ internal class MyWebClient : WebClientProtocol method creates a instance used to read the contents of the resource specified by the `address` parameter. This method blocks while opening the stream. To continue executing while waiting for the stream, use one of the methods. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not `null`, it is appended to `address`. - - This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. - -> [!NOTE] -> You must call when finished with the to avoid running out of system resources. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . The URI formed by combining , is invalid. @@ -3733,28 +2971,8 @@ internal class MyWebClient : WebClientProtocol instance used to access the resource specified by the `address` parameter. The stream is obtained using thread resources that are automatically allocated from the thread pool. To receive notification when the stream is available, add an event handler to the event. - -> [!NOTE] -> You must call when you are finished with the to avoid running out of system resources. - - This method does not block the calling thread while the stream is opening. To block while waiting for the stream, use the method. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested resource. If the property is not `null`, it is appended to `address`. - - This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - ]]> The parameter is . @@ -3823,27 +3041,9 @@ internal class MyWebClient : WebClientProtocol instance used to access the resource specified by the `address` parameter. The stream is obtained using thread resources that are automatically allocated from the thread pool. To receive notification when the stream is available, add an event handler to the event. - -> [!NOTE] -> You must call when you are finished with the to avoid running out of system resources. - - This method does not block the calling thread while the stream is opening. To block while waiting for the stream, use the method. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested resource. If the property is not `null`, it is appended to `address`. - - This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . The URI formed by combining and address is invalid. @@ -3904,32 +3104,9 @@ internal class MyWebClient : WebClientProtocol methods. - - The is the delegate for this event. The class provides the event handler with event data. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - The following code example demonstrates setting an event handler for this event. - - [!code-cpp[NCLWebClientAsync#30](~/snippets/cpp/VS_Snippets_Remoting/NCLWebClientAsync/CPP/asyncmethods.cpp#30)] - [!code-csharp[NCLWebClientAsync#30](~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs#30)] - [!code-vb[NCLWebClientAsync#30](~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb#30)] - - The following code example shows an implementation of a handler for this event. - - [!code-cpp[NCLWebClientAsync#31](~/snippets/cpp/VS_Snippets_Remoting/NCLWebClientAsync/CPP/asyncmethods.cpp#31)] - [!code-csharp[NCLWebClientAsync#31](~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs#31)] - [!code-vb[NCLWebClientAsync#31](~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb#31)] - - ]]> +]]> @@ -3987,27 +3164,9 @@ internal class MyWebClient : WebClientProtocol object will complete after the a readable stream to the data resource has been opened. This method does not block the calling thread while the stream is opening. - - This method retrieves a instance used to access the resource specified by the `address` parameter. The stream is obtained using thread resources that are automatically allocated from the thread pool. - -> [!NOTE] -> You must call when you are finished with the to avoid running out of system resources. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested resource. If the property is not `null`, it is appended to `address`. - - This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . The URI formed by combining and address is invalid. @@ -4066,27 +3225,9 @@ internal class MyWebClient : WebClientProtocol object will complete after the a readable stream to the data resource has been opened. This method does not block the calling thread while the stream is opening. - - This method retrieves a instance used to access the resource specified by the `address` parameter. The stream is obtained using thread resources that are automatically allocated from the thread pool. - -> [!NOTE] -> You must call when you are finished with the to avoid running out of system resources. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested resource. If the property is not `null`, it is appended to `address`. - - This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . The URI formed by combining and address is invalid. @@ -4157,27 +3298,9 @@ internal class MyWebClient : WebClientProtocol method returns a writable stream that is used to send data to a resource. This method blocks while opening the stream. To continue executing while waiting for the stream, use one of the methods. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - -## Examples - The following code example reads data from the command line and uses to obtain a stream for writing the data. The returned by is closed after the data is sent. - - [!code-cpp[WebClient_OpenWrite2#1](~/snippets/cpp/VS_Snippets_Remoting/WebClient_OpenWrite2/CPP/webclient_openwrite2.cpp#1)] - [!code-csharp[WebClient_OpenWrite2#1](~/snippets/csharp/System.Net/WebClient/OpenWrite/webclient_openwrite2.cs#1)] - [!code-vb[WebClient_OpenWrite2#1](~/snippets/visualbasic/System.Net/WebClient/OpenWrite/webclient_openwrite2.vb#1)] - - ]]> +]]> The parameter is . The URI formed by combining , and is invalid. @@ -4232,20 +3355,9 @@ internal class MyWebClient : WebClientProtocol method returns a writable stream that is used to send data to a resource. This method blocks while opening the stream. To continue executing while waiting for the stream, use one of the methods. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . The URI formed by combining , and is invalid. @@ -4311,27 +3423,9 @@ internal class MyWebClient : WebClientProtocol method returns a writable stream that is used to send data to a resource. The underlying request is made with the method specified in the `method` parameter. The data is sent to the server when you close the stream. This method blocks while opening the stream. To continue executing while waiting for the stream, use one of the methods. - - If the `method` parameter specifies a method that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - - If the property is not an empty string ("") and `address` does not specify an absolute address, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - -## Examples - The following code example reads data from the command line and uses to obtain a stream used to write the data. The returned by must be closed to send the data. - - [!code-cpp[WebClient_OpenWrite#1](~/snippets/cpp/VS_Snippets_Remoting/WebClient_OpenWrite/CPP/webclient_openwrite.cpp#1)] - [!code-csharp[WebClient_OpenWrite#1](~/snippets/csharp/System.Net/WebClient/OpenWrite/webclient_openwrite.cs#1)] - [!code-vb[WebClient_OpenWrite#1](~/snippets/visualbasic/System.Net/WebClient/OpenWrite/webclient_openwrite.vb#1)] - - ]]> +]]> The parameter is . The URI formed by combining , and is invalid. @@ -4396,18 +3490,9 @@ internal class MyWebClient : WebClientProtocol method returns a writable stream that is used to send data to a resource. This method blocks while opening the stream. To continue executing while waiting for the stream, use one of the methods. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . The URI formed by combining , and is invalid. @@ -4471,23 +3556,8 @@ internal class MyWebClient : WebClientProtocol event. When you close the stream, the thread blocks until the request is sent to `address` and a response is received. - - This method does not block the calling thread while the stream is being opened. To block while waiting for the stream, use one of the methods. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - ]]> The parameter is . @@ -4547,21 +3617,8 @@ internal class MyWebClient : WebClientProtocol event. When you close the stream, the thread blocks until the request is sent to `address` and a response is received. - - This method does not block the calling thread while the stream is being opened. To block while waiting for the stream, use one of the methods. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - ]]> The parameter is . @@ -4623,24 +3680,9 @@ internal class MyWebClient : WebClientProtocol event. The contents of the stream are sent to the server when you close the stream. - - If the `method` parameter specifies a method that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - This method does not block the calling thread while the stream is being opened. To block while waiting for the stream, use one of the methods. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . The URI formed by combining and is invalid. @@ -4697,32 +3739,9 @@ internal class MyWebClient : WebClientProtocol methods. - - The is the delegate for this event. The class provides the event handler with event data. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - The following code example demonstrates setting an event handler for this event. - - [!code-cpp[NCLWebClientAsync#14](~/snippets/cpp/VS_Snippets_Remoting/NCLWebClientAsync/CPP/asyncmethods.cpp#14)] - [!code-csharp[NCLWebClientAsync#14](~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs#14)] - [!code-vb[NCLWebClientAsync#14](~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb#14)] - - The following code example shows an implementation of a handler for this event. - - [!code-cpp[NCLWebClientAsync#15](~/snippets/cpp/VS_Snippets_Remoting/NCLWebClientAsync/CPP/asyncmethods.cpp#15)] - [!code-csharp[NCLWebClientAsync#15](~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs#15)] - [!code-vb[NCLWebClientAsync#15](~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb#15)] - - ]]> +]]> @@ -4780,26 +3799,9 @@ internal class MyWebClient : WebClientProtocol object will complete after the a writable stream to the data resource has been opened. This method does not block the calling thread while the stream is opening. - - This method retrieves a instance used to write data to the resource specified by the `address` parameter. The stream is obtained using thread resources that are automatically allocated from the thread pool. - -> [!NOTE] -> You must call when you are finished with the to avoid running out of system resources. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - - This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . The URI formed by combining and is invalid. @@ -4854,26 +3856,9 @@ internal class MyWebClient : WebClientProtocol object will complete after the a writable stream to the data resource has been opened. This method does not block the calling thread while the stream is opening. - - This method retrieves a instance used to write data to the resource specified by the `address` parameter. The stream is obtained using thread resources that are automatically allocated from the thread pool. - -> [!NOTE] -> You must call when you are finished with the to avoid running out of system resources. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - - This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . The URI formed by combining and is invalid. @@ -4937,28 +3922,9 @@ internal class MyWebClient : WebClientProtocol object will complete after the a writable stream to the data resource has been opened. This method does not block the calling thread while the stream is opening. - - This method retrieves a instance used to write data to the resource specified by the `address` parameter. The stream is obtained using thread resources that are automatically allocated from the thread pool. - -> [!NOTE] -> You must call when you are finished with the to avoid running out of system resources. - - If the `method` parameter specifies a method that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - - This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . The URI formed by combining and is invalid. @@ -5023,28 +3989,9 @@ internal class MyWebClient : WebClientProtocol object will complete after the a writable stream to the data resource has been opened. This method does not block the calling thread while the stream is opening. - - This method retrieves a instance used to write data to the resource specified by the `address` parameter. The stream is obtained using thread resources that are automatically allocated from the thread pool. - -> [!NOTE] -> You must call when you are finished with the to avoid running out of system resources. - - If the `method` parameter specifies a method that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - - This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . The URI formed by combining and is invalid. @@ -5103,15 +4050,9 @@ internal class MyWebClient : WebClientProtocol property identifies the instance that communicates with remote servers on behalf of this object. The proxy is set by the system using configuration files and the Local Area Network settings. To specify that no proxy should be used, set the property to `null`. - - For information on automatic proxy detection, see [Automatic Proxy Detection](/dotnet/framework/network-programming/automatic-proxy-detection). - - ]]> +]]> @@ -5165,22 +4106,9 @@ internal class MyWebClient : WebClientProtocol property contains a instance containing name/value pairs that are appended to the URI as a query string. The contents of the property are preceded by a question mark (?), and name/value pairs are separated from one another by an ampersand (&). - - - -## Examples - The following code example takes user input from the command line and builds a that is assigned to the property. It then downloads the response from the server to a local file. - - [!code-cpp[WebClient_QueryString#1](~/snippets/cpp/VS_Snippets_Remoting/WebClient_QueryString/CPP/webclient_querystring.cpp#1)] - [!code-csharp[WebClient_QueryString#1](~/snippets/csharp/System.Net/WebClient/QueryString/webclient_querystring.cs#1)] - [!code-vb[WebClient_QueryString#1](~/snippets/visualbasic/System.Net/WebClient/QueryString/webclient_querystring.vb#1)] - - ]]> +]]> @@ -5233,22 +4161,9 @@ internal class MyWebClient : WebClientProtocol property contains a instance containing header information the receives with the response. - - - -## Examples - The following code example downloads and displays the returned by a server. - - [!code-cpp[WebClient_BaseAddress_ResponseHeaders#2](~/snippets/cpp/VS_Snippets_Remoting/WebClient_BaseAddress_ResponseHeaders/CPP/webclient_baseaddress_responseheaders.cpp#2)] - [!code-csharp[WebClient_BaseAddress_ResponseHeaders#2](~/snippets/csharp/System.Net/WebClient/BaseAddress/webclient_baseaddress_responseheaders.cs#2)] - [!code-vb[WebClient_BaseAddress_ResponseHeaders#2](~/snippets/visualbasic/System.Net/WebClient/BaseAddress/webclient_baseaddress_responseheaders.vb#2)] - - ]]> +]]> @@ -5310,29 +4225,9 @@ internal class MyWebClient : WebClientProtocol method sends a data buffer to a resource. - - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - - The method sends the content of `data` to the server without encoding it. This method blocks while uploading the data. To continue executing while waiting for the server's response, use one of the methods. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - -## Examples - The following code example converts a string entered from the console to a array and posts the array to the specified server using . Any response from the server is displayed to the console. - - [!code-cpp[WebClient_UpLoadData2#1](~/snippets/cpp/VS_Snippets_Remoting/WebClient_UpLoadData2/CPP/webclient_uploaddata2.cpp#1)] - [!code-csharp[WebClient_UpLoadData2#1](~/snippets/csharp/System.Net/WebClient/UploadData/webclient_uploaddata2.cs#1)] - [!code-vb[WebClient_UpLoadData2#1](~/snippets/visualbasic/System.Net/WebClient/UploadData/webclient_uploaddata2.vb#1)] - - ]]> +]]> The parameter is . The URI formed by combining , and is invalid. @@ -5397,22 +4292,9 @@ internal class MyWebClient : WebClientProtocol method sends a data buffer to a resource. - - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - - The method sends the content of `data` to the server without encoding it. This method blocks while uploading the data. To continue executing while waiting for the server's response, use one of the methods. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . The URI formed by combining , and is invalid. @@ -5488,29 +4370,9 @@ internal class MyWebClient : WebClientProtocol method sends a data buffer to a resource using the HTTP method specified in the `method` parameter, and returns any response from the server. This method blocks while uploading the data. To continue executing while waiting for the server's response, use one of the methods. - - The method sends the content of `data` to the server without encoding it. - - If the `method` parameter specifies a verb that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - -## Examples - The following code example converts a string entered from the console into a byte array and posts the array to the specified server using . Any response from the server is displayed to the console. - - [!code-cpp[WebClient_UpLoadData_Headers#2](~/snippets/cpp/VS_Snippets_Remoting/WebClient_UpLoadData_Headers/CPP/webclient_uploaddata_headers.cpp#2)] - [!code-csharp[WebClient_UpLoadData_Headers#2](~/snippets/csharp/System.Net/WebClient/Headers/webclient_uploaddata_headers.cs#2)] - [!code-vb[WebClient_UpLoadData_Headers#2](~/snippets/visualbasic/System.Net/WebClient/Headers/webclient_uploaddata_headers.vb#2)] - - ]]> +]]> The parameter is . The URI formed by combining , and is invalid. @@ -5585,22 +4447,9 @@ internal class MyWebClient : WebClientProtocol method sends a data buffer to a resource using the HTTP method specified in the `method` parameter, and returns any response from the server. This method blocks while uploading the data. To continue executing while waiting for the server's response, use one of the methods. - - The method sends the content of `data` to the server without encoding it. - - If the `method` parameter specifies a verb that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . The URI formed by combining , and is invalid. @@ -5674,25 +4523,8 @@ internal class MyWebClient : WebClientProtocol event. - - This method does not block the calling thread while the data is being sent. To send data and block while waiting for the server's response, use one of the methods. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - ]]> The parameter is . @@ -5763,23 +4595,8 @@ internal class MyWebClient : WebClientProtocol event. - - This method does not block the calling thread while the data is being sent. To send data and block while waiting for the server's response, use one of the methods. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - ]]> The parameter is . @@ -5859,22 +4676,9 @@ internal class MyWebClient : WebClientProtocol event. - - This method does not block the calling thread while the data is being sent. To send data and block while waiting for the server's response, use one of the methods. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . The URI formed by combining and is invalid. @@ -5935,32 +4739,9 @@ internal class MyWebClient : WebClientProtocol methods. - - The is the delegate for this event. The class provides the event handler with event data. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - The following code example demonstrates setting an event handler for this event. - - [!code-cpp[NCLWebClientAsync#36](~/snippets/cpp/VS_Snippets_Remoting/NCLWebClientAsync/CPP/asyncmethods.cpp#36)] - [!code-csharp[NCLWebClientAsync#36](~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs#36)] - [!code-vb[NCLWebClientAsync#36](~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb#36)] - - The following code example shows an implementation of a handler for this event. - - [!code-cpp[NCLWebClientAsync#37](~/snippets/cpp/VS_Snippets_Remoting/NCLWebClientAsync/CPP/asyncmethods.cpp#37)] - [!code-csharp[NCLWebClientAsync#37](~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs#37)] - [!code-vb[NCLWebClientAsync#37](~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb#37)] - - ]]> +]]> @@ -6020,24 +4801,9 @@ internal class MyWebClient : WebClientProtocol object will complete after the a data buffer has been uploaded to the resource. - - This method sends a data buffer to a resource. The data buffer is sent asynchronously using thread resources that are automatically allocated from the thread pool. The data is not encoded. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . The URI formed by combining and is invalid. @@ -6097,24 +4863,9 @@ internal class MyWebClient : WebClientProtocol object will complete after the a data buffer has been uploaded to the resource. - - This method sends a data buffer to a resource. The data buffer is sent asynchronously using thread resources that are automatically allocated from the thread pool. The data is not encoded. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . The URI formed by combining and is invalid. @@ -6184,22 +4935,9 @@ internal class MyWebClient : WebClientProtocol object will complete after the a data buffer has been uploaded to the resource. - - This method sends a data buffer to a resource. The data buffer is sent asynchronously using thread resources that are automatically allocated from the thread pool. The data is not encoded. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . The URI formed by combining and is invalid. @@ -6269,22 +5007,9 @@ internal class MyWebClient : WebClientProtocol object will complete after the a data buffer has been uploaded to the resource. - - This method sends a data buffer to a resource. The data buffer is sent asynchronously using thread resources that are automatically allocated from the thread pool. The data is not encoded. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . The URI formed by combining and is invalid. @@ -6356,34 +5081,9 @@ internal class MyWebClient : WebClientProtocol method sends a local file to a resource. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - - This method blocks while uploading the file. To continue executing while waiting for the server's response, use one of the methods. - - The `POST` method is defined by HTTP. If the underlying request does not use HTTP and `POST` is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - -## Examples - The following code example uploads the specified file to the specified URI using . Any response returned by the server is displayed on the console. - - [!code-cpp[WebClient_UpLoadFile#1](~/snippets/cpp/VS_Snippets_Remoting/WebClient_UpLoadFile/CPP/webclient_uploadfile.cpp#1)] - [!code-csharp[WebClient_UpLoadFile#1](~/snippets/csharp/System.Net/WebClient/UploadFile/webclient_uploadfile.cs#1)] - [!code-vb[WebClient_UpLoadFile#1](~/snippets/visualbasic/System.Net/WebClient/UploadFile/webclient_uploadfile.vb#1)] - - The following code example shows an ASP.NET page that can accept posted files and is suitable for use with the method. The page must reside on a Web server. Its address provides the value for the `address` parameter of the method. - - [!code-aspx-csharp[NCLWebClientAsp#1](~/snippets/csharp/System.Net/WebClient/UploadFile/fileuploadercs.aspx#1)] - [!code-aspx-vb[NCLWebClientAsp#1](~/snippets/visualbasic/VS_Snippets_Remoting/NCLWebClientAsp/VB/fileuploadervb.aspx#1)] - - ]]> +]]> The parameter is . @@ -6456,22 +5156,9 @@ internal class MyWebClient : WebClientProtocol method sends a local file to a resource. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - - This method blocks while uploading the file. To continue executing while waiting for the server's response, use one of the methods. - - The `POST` method is defined by HTTP. If the underlying request does not use HTTP and `POST` is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . @@ -6555,32 +5242,9 @@ internal class MyWebClient : WebClientProtocol method sends a local file to a resource using the HTTP method specified in the `method` parameter and returns any response from the server. This method blocks while uploading the file. To continue executing while waiting for the server's response, use one of the methods. - - If the `method` parameter specifies a verb that is not understood by the server or the `address` resource, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - -## Examples - The following code example uploads the specified file to the specified URI using . Any response returned by the server is displayed on the console. - - [!code-cpp[WebClient_UpLoadFile2#1](~/snippets/cpp/VS_Snippets_Remoting/WebClient_UpLoadFile2/CPP/webclient_uploadfile2.cpp#1)] - [!code-csharp[WebClient_UpLoadFile2#1](~/snippets/csharp/System.Net/WebClient/UploadFile/webclient_uploadfile2.cs#1)] - [!code-vb[WebClient_UpLoadFile2#1](~/snippets/visualbasic/System.Net/WebClient/UploadFile/webclient_uploadfile2.vb#1)] - - The following code example shows an ASP.NET page that can accept posted files and is suitable for use with the method. The page must reside on a Web server. Its address provides the value for the `address` parameter of the method. - - [!code-aspx-csharp[NCLWebClientAsp#1](~/snippets/csharp/System.Net/WebClient/UploadFile/fileuploadercs.aspx#1)] - [!code-aspx-vb[NCLWebClientAsp#1](~/snippets/visualbasic/VS_Snippets_Remoting/NCLWebClientAsp/VB/fileuploadervb.aspx#1)] - - ]]> +]]> The parameter is . @@ -6663,20 +5327,9 @@ internal class MyWebClient : WebClientProtocol method sends a local file to a resource using the HTTP method specified in the `method` parameter and returns any response from the server. This method blocks while uploading the file. To continue executing while waiting for the server's response, use one of the methods. - - If the `method` parameter specifies a verb that is not understood by the server or the `address` resource, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . @@ -6758,25 +5411,8 @@ internal class MyWebClient : WebClientProtocol event. - - This method does not block the calling thread while the file is being sent. To send a file and block while waiting for the server's response, use one of the methods. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - ]]> The parameter is . @@ -6859,25 +5495,8 @@ internal class MyWebClient : WebClientProtocol event. - - This method does not block the calling thread while the file is being sent. To send a file and block while waiting for the server's response, use one of the methods. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - ]]> The parameter is . @@ -6969,24 +5588,9 @@ internal class MyWebClient : WebClientProtocol event. - - This method does not block the calling thread while the file is being sent. To send a file and block while waiting for the server's response, use one of the methods. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . @@ -7059,32 +5663,9 @@ internal class MyWebClient : WebClientProtocol methods. - - The is the delegate for this event. The class provides the event handler with event data. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - The following code example demonstrates setting an event handler for this event. - - [!code-cpp[NCLWebClientAsync#4](~/snippets/cpp/VS_Snippets_Remoting/NCLWebClientAsync/CPP/asyncmethods.cpp#4)] - [!code-csharp[NCLWebClientAsync#4](~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs#4)] - [!code-vb[NCLWebClientAsync#4](~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb#4)] - - The following code example shows an implementation of a handler for this event. - - [!code-cpp[NCLWebClientAsync#5](~/snippets/cpp/VS_Snippets_Remoting/NCLWebClientAsync/CPP/asyncmethods.cpp#5)] - [!code-csharp[NCLWebClientAsync#5](~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs#5)] - [!code-vb[NCLWebClientAsync#5](~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb#5)] - - ]]> +]]> @@ -7144,22 +5725,9 @@ internal class MyWebClient : WebClientProtocol object will complete after the file has been uploaded to the resource. The file is sent asynchronously using thread resources that are automatically allocated from the thread pool. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . @@ -7231,22 +5799,9 @@ internal class MyWebClient : WebClientProtocol object will complete after the file has been uploaded to the resource. The file is sent asynchronously using thread resources that are automatically allocated from the thread pool. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . @@ -7328,22 +5883,9 @@ internal class MyWebClient : WebClientProtocol object will complete after the file has been uploaded to the resource. The file is sent asynchronously using thread resources that are automatically allocated from the thread pool. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - BY default, this method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . @@ -7425,22 +5967,9 @@ internal class MyWebClient : WebClientProtocol object will complete after the file has been uploaded to the resource. The file is sent asynchronously using thread resources that are automatically allocated from the thread pool. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - BY default, this method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . @@ -7513,38 +6042,9 @@ internal class MyWebClient : WebClientProtocol |Sends a array to the resource, without blocking the calling thread.| -||Sends a local file to the resource, without blocking the calling thread.| -||Sends a to the resource and returns a array containing any response, without blocking the calling thread.| - - The is the delegate for this event. The class provides the event handler with event data. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - The following code example demonstrates setting an event handler for this event. - - [!code-cpp[NCLWebClientAsync#4](~/snippets/cpp/VS_Snippets_Remoting/NCLWebClientAsync/CPP/asyncmethods.cpp#4)] - [!code-csharp[NCLWebClientAsync#4](~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs#4)] - [!code-vb[NCLWebClientAsync#4](~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb#4)] - - The following code example shows an implementation of a handler for this event. - - [!code-cpp[NCLWebClientAsync#42](~/snippets/cpp/VS_Snippets_Remoting/NCLWebClientAsync/CPP/asyncmethods.cpp#42)] - [!code-csharp[NCLWebClientAsync#42](~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs#42)] - [!code-vb[NCLWebClientAsync#42](~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb#42)] - - ]]> +]]> @@ -7605,27 +6105,9 @@ internal class MyWebClient : WebClientProtocol array using the encoding specified in the property. This method blocks while the string is transmitted. To send a string and continue executing while waiting for the server's response, use one of the methods. - - If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - -## Examples - The following code example demonstrates calling this method. - - [!code-cpp[NCLWebClientAsync#1](~/snippets/cpp/VS_Snippets_Remoting/NCLWebClientAsync/CPP/asyncmethods.cpp#1)] - [!code-csharp[NCLWebClientAsync#1](~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs#1)] - [!code-vb[NCLWebClientAsync#1](~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb#1)] - - ]]> +]]> The parameter is . @@ -7686,20 +6168,9 @@ internal class MyWebClient : WebClientProtocol array using the encoding specified in the property. This method blocks while the string is transmitted. To send a string and continue executing while waiting for the server's response, use one of the methods. - - If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . @@ -7770,25 +6241,9 @@ internal class MyWebClient : WebClientProtocol array using the encoding specified in the property. This method blocks while the string is transmitted. To send a string and continue executing while waiting for the server's response, use one of the methods. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - -## Examples - The following code example demonstrates calling this method. - - [!code-cpp[NCLWebClientAsync#2](~/snippets/cpp/VS_Snippets_Remoting/NCLWebClientAsync/CPP/asyncmethods.cpp#2)] - [!code-csharp[NCLWebClientAsync#2](~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs#2)] - [!code-vb[NCLWebClientAsync#2](~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb#2)] - - ]]> +]]> The parameter is . @@ -7863,18 +6318,9 @@ internal class MyWebClient : WebClientProtocol array using the encoding specified in the property. This method blocks while the string is transmitted. To send a string and continue executing while waiting for the server's response, use one of the methods. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . @@ -7948,25 +6394,8 @@ internal class MyWebClient : WebClientProtocol array using the encoding specified in the property. To receive notification when the string upload completes, you can add an event handler to the event. - - This method does not block the calling thread while the string is being sent. To send a string and block while waiting for the server's response, use one of the methods. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - ]]> The parameter is . @@ -8037,23 +6466,8 @@ internal class MyWebClient : WebClientProtocol array using the encoding specified in the property. To receive notification when the string upload completes, you can add an event handler to the event. - - This method does not block the calling thread while the string is being sent. To send a string and block while waiting for the server's response, use one of the methods. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - ]]> The parameter is . @@ -8137,22 +6551,9 @@ internal class MyWebClient : WebClientProtocol array using the encoding specified in the property. To receive notification when the string upload completes, you can add an event handler to the event. - - This method does not block the calling thread while the string is being sent. To send a string and block while waiting for the server's response, use one of the methods. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . @@ -8217,32 +6618,9 @@ internal class MyWebClient : WebClientProtocol methods. - - The is the delegate for this event. The class provides the event handler with event data. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - The following code example demonstrates setting an event handler for this event. - - [!code-cpp[NCLWebClientAsync#38](~/snippets/cpp/VS_Snippets_Remoting/NCLWebClientAsync/CPP/asyncmethods.cpp#38)] - [!code-csharp[NCLWebClientAsync#38](~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs#38)] - [!code-vb[NCLWebClientAsync#38](~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb#38)] - - The following code example shows an implementation of a handler for this event. - - [!code-cpp[NCLWebClientAsync#39](~/snippets/cpp/VS_Snippets_Remoting/NCLWebClientAsync/CPP/asyncmethods.cpp#39)] - [!code-csharp[NCLWebClientAsync#39](~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs#39)] - [!code-vb[NCLWebClientAsync#39](~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb#39)] - - ]]> +]]> @@ -8302,22 +6680,9 @@ internal class MyWebClient : WebClientProtocol object will complete after the string has been uploaded to the resource. The string is sent asynchronously using thread resources that are automatically allocated from the thread pool. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . @@ -8377,22 +6742,9 @@ internal class MyWebClient : WebClientProtocol object will complete after the string has been uploaded to the resource. The string is sent asynchronously using thread resources that are automatically allocated from the thread pool. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . @@ -8462,22 +6814,9 @@ internal class MyWebClient : WebClientProtocol object will complete after the string has been uploaded to the resource. The string is sent asynchronously using thread resources that are automatically allocated from the thread pool. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . @@ -8551,22 +6890,9 @@ internal class MyWebClient : WebClientProtocol object will complete after the string has been uploaded to the resource. The string is sent asynchronously using thread resources that are automatically allocated from the thread pool. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . @@ -8642,31 +6968,9 @@ internal class MyWebClient : WebClientProtocol method sends a to a server. This method blocks while uploading the data. To continue executing while waiting for the server's response, use one of the methods. - - If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - - If the Content-type header is `null`, the method sets it to "application/x-www-form-urlencoded". - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - -## Examples - The following code example gathers information from the user (name, age, and address) and posts the values to the server using . Any response from the server is displayed on the console. - - [!code-cpp[WebClient_UploadValues#1](~/snippets/cpp/VS_Snippets_Remoting/WebClient_UploadValues/CPP/webclient_uploadvalues.cpp#1)] - [!code-csharp[WebClient_UploadValues#1](~/snippets/csharp/System.Net/WebClient/UploadValues/webclient_uploadvalues.cs#1)] - [!code-vb[WebClient_UploadValues#1](~/snippets/visualbasic/System.Net/WebClient/UploadValues/webclient_uploadvalues.vb#1)] - - ]]> +]]> The parameter is . @@ -8739,24 +7043,9 @@ internal class MyWebClient : WebClientProtocol method sends a to a server. This method blocks while uploading the data. To continue executing while waiting for the server's response, use one of the methods. - - If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - - If the Content-type header is `null`, the method sets it to "application/x-www-form-urlencoded". - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . @@ -8840,29 +7129,9 @@ internal class MyWebClient : WebClientProtocol method sends a to a resource using the method specified in the `method` parameter and returns any response from the server. This method blocks while uploading the data. To continue executing while waiting for the server's response, use one of the methods. - - If the `Content-type` header is `null`, the method sets it to `application/x-www-form-urlencoded`. - - If the `method` parameter specifies a verb that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - -## Examples - The following code example gathers information from the user (name, age, and address) and posts the values to the server using . Any response from the server is displayed on the console. - - [!code-cpp[WebClient_UploadValues2#1](~/snippets/cpp/VS_Snippets_Remoting/WebClient_UploadValues2/CPP/webclient_uploadvalues2.cpp#1)] - [!code-csharp[WebClient_UploadValues2#1](~/snippets/csharp/System.Net/WebClient/UploadValues/webclient_uploadvalues2.cs#1)] - [!code-vb[WebClient_UploadValues2#1](~/snippets/visualbasic/System.Net/WebClient/UploadValues/webclient_uploadvalues2.vb#1)] - - ]]> +]]> The parameter is . @@ -8945,22 +7214,9 @@ internal class MyWebClient : WebClientProtocol method sends a to a resource using the method specified in the `method` parameter and returns any response from the server. This method blocks while uploading the data. To continue executing while waiting for the server's response, use one of the methods. - - If the `Content-type` header is `null`, the method sets it to `application/x-www-form-urlencoded`. - - If the `method` parameter specifies a verb that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . @@ -9042,25 +7298,8 @@ internal class MyWebClient : WebClientProtocol array using the encoding specified in the property. To receive notification when the string upload completes, you can add an event handler to the event. - - This method does not block the calling thread while the string is being sent. To send a string and block while waiting for the server's response, use one of the methods. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - ]]> The parameter is . @@ -9131,27 +7370,8 @@ internal class MyWebClient : WebClientProtocol to the `address` resource. Use this method to send form data to a URI for processing. The data is sent using the form-urlencoded media type; the Content-Type header value must be set to "application/x-www-form-urlencoded". The header is set correctly by default. The methods throw a if you call this method with a different Content-Type header value set in the collection. - - If the `method` method is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - - The is sent asynchronously using thread resources that are automatically allocated from the thread pool. To receive notification when the upload operation completes, add an event handler to the event. - - This method does not block the calling thread while the string is being sent. To send a string and block while waiting for the server's response, use one of the methods. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not empty, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - ]]> The parameter is . @@ -9235,26 +7455,9 @@ internal class MyWebClient : WebClientProtocol to the `address` resource. Use this method to send form data to a URI for processing. The data is sent using the form-urlencoded media type; the Content-Type header value must be set to "application/x-www-form-urlencoded". The header is set correctly by default. The methods throw a if you call this method with a different Content-Type header value set in the collection. - - If the `method` method is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - - The is sent asynchronously using thread resources that are automatically allocated from the thread pool. To receive notification when the upload operation completes, add an event handler to the event. - - This method does not block the calling thread while the string is being sent. To send a string and block while waiting for the server's response, use one of the methods. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not empty, it is appended to `address`. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . @@ -9319,17 +7522,9 @@ internal class MyWebClient : WebClientProtocol object's data completes. These uploads are started by calling the methods. - - The is the delegate for this event. The class provides the event handler with event data. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - ]]> +]]> @@ -9389,26 +7584,9 @@ internal class MyWebClient : WebClientProtocol object will complete after the name/value collection has been uploaded to the resource. The name/value collection is sent asynchronously using thread resources that are automatically allocated from the thread pool. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - - If the Content-type header is `null`, this method sets it to "application/x-www-form-urlencoded". - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . @@ -9476,26 +7654,9 @@ internal class MyWebClient : WebClientProtocol object will complete after the name/value collection has been uploaded to the resource. The name/value collection is sent asynchronously using thread resources that are automatically allocated from the thread pool. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - - If the Content-type header is `null`, this method sets it to "application/x-www-form-urlencoded". - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . @@ -9573,26 +7734,9 @@ internal class MyWebClient : WebClientProtocol object will complete after the name/value collection has been uploaded to the resource. The name/value collection is sent asynchronously using thread resources that are automatically allocated from the thread pool. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - - If the Content-type header is `null`, this method sets it to "application/x-www-form-urlencoded". - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . @@ -9674,26 +7818,9 @@ internal class MyWebClient : WebClientProtocol object will complete after the name/value collection has been uploaded to the resource. The name/value collection is sent asynchronously using thread resources that are automatically allocated from the thread pool. - - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - - If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - - If the Content-type header is `null`, this method sets it to "application/x-www-form-urlencoded". - - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. - - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). - - ]]> +]]> The parameter is . @@ -9761,22 +7888,9 @@ internal class MyWebClient : WebClientProtocol object should, if requested by the server, be authenticated using the default credentials of the currently logged on user. For client applications, this is the desired behavior in most scenarios. For middle tier applications, such as ASP.NET applications, instead of using this property, you would typically set the property to the credentials of the client on whose behalf the request is made. - - - -## Examples - The following code example demonstrates setting this property. - - [!code-cpp[NCLWebClientAsync#3](~/snippets/cpp/VS_Snippets_Remoting/NCLWebClientAsync/CPP/asyncmethods.cpp#3)] - [!code-csharp[NCLWebClientAsync#3](~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs#3)] - [!code-vb[NCLWebClientAsync#3](~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb#3)] - - ]]> +]]> @@ -9832,17 +7946,9 @@ internal class MyWebClient : WebClientProtocol methods. - - The is the delegate for this event. The class provides the event handler with event data. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - ]]> +]]> diff --git a/xml/System.Net/WebException.xml b/xml/System.Net/WebException.xml index ecd75a4c4fe..162b9995e07 100644 --- a/xml/System.Net/WebException.xml +++ b/xml/System.Net/WebException.xml @@ -618,11 +618,6 @@ The value of is one of the values. -> [!WARNING] -> The error is not returned to Windows 8.x Store apps. - - - ## Examples The following example checks the property and prints to the console the and of the underlying instance. diff --git a/xml/System.Net/WebHeaderCollection.xml b/xml/System.Net/WebHeaderCollection.xml index d34779f6e4e..055d70eb963 100644 --- a/xml/System.Net/WebHeaderCollection.xml +++ b/xml/System.Net/WebHeaderCollection.xml @@ -83,37 +83,8 @@ class is generally accessed through or . - On .NET Framework, some common headers are considered restricted and are either exposed directly by the API (such as `Content-Type`) or protected by the system and cannot be changed. This does *not* apply to .NET Core and .NET 5+, where none of the headers are restricted. - - The restricted headers are: - -- Accept - -- Connection - -- Content-Length - -- Content-Type - -- Date - -- Expect - -- Host - -- If-Modified-Since - -- Range - -- Referer - -- Transfer-Encoding - -- User-Agent - -- Proxy-Connection +The class is generally accessed through or . ]]> @@ -310,10 +281,7 @@ :::code language="vb" source="~/snippets/visualbasic/System.Net/WebHeaderCollection/Add/webheadercollection_add.vb" id="Snippet1"::: > [!NOTE] -> The length of the *value* portion of `header`, that is, the string after the colon (:), is validated only in .NET Framework and .NET Core versions 2.0 - 3.1. -> - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of the *value* portion of `header` is greater than 65535. All other instances accept a *value* of any length. -> - On .NET Core versions through version 3.1: A instance used with any header of type will throw an if the length of the *value* portion of `header` is greater than 65535. All other instances accept a *value* of any length. -> - On .NET 5 and later versions: accepts a *value* of any length. +> accepts a *value* of any length. ]]> @@ -336,7 +304,6 @@ -or- The value part of contains invalid characters. - .NET Framework and .NET Core versions 2.0 - 3.1 only: The length of the string after the colon (:) is greater than 65535. @@ -395,13 +362,9 @@ If the specified header is already present, `value` is added to the comma-separated list of values associated with the header. > [!NOTE] -> The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1. -> - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. -> - On .NET Core versions through version 3.1: A instance used with any header of type will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. -> - On .NET 5 and later versions: accepts a `value` of any length. +> accepts a `value` of any length. ]]> - .NET Framework and .NET Core versions 2.0 - 3.1 only: The length of is greater than 65535. This instance does not allow instances of . @@ -461,13 +424,9 @@ If the specified header is already present, `value` is added to the comma-separated list of values associated with the header. > [!NOTE] -> The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1. -> - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. -> - On .NET Core versions through version 3.1: A instance used with any header of type will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. -> - On .NET 5 and later versions: accepts a `value` of any length. +> accepts a `value` of any length. ]]> - .NET Framework and .NET Core versions 2.0 - 3.1 only: The length of is greater than 65535. This instance does not allow instances of . @@ -543,10 +502,7 @@ :::code language="vb" source="~/snippets/visualbasic/System.Net/WebHeaderCollection/Add/webheadercollection_add.vb" id="Snippet1"::: > [!NOTE] -> The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1. -> - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. -> - On .NET Core versions through version 3.1: A instance used with any header of type will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. -> - On .NET 5 and later versions: accepts a `value` of any length. +> accepts a `value` of any length. ]]> @@ -559,7 +515,6 @@ -or- contains invalid characters. - .NET Framework and .NET Core versions 2.0 - 3.1 only: The length of is greater than 65535. @@ -624,10 +579,7 @@ The method adds a header to the collection without checking whether the header is on the restricted header list. > [!NOTE] -> The length of `headerValue` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1. -> - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `headerValue` is greater than 65535. All other instances accept a `headerValue` of any length. -> - On .NET Core versions through version 3.1: A instance used with any header of type will throw an if the length of `headerValue` is greater than 65535. All other instances accept a `headerValue` of any length. -> - On .NET 5 and later versions: accepts a `headerValue` of any length. +> accepts a `headerValue` of any length. ]]> @@ -636,8 +588,6 @@ -or- contains invalid characters. - - .NET Framework and .NET Core only: is not and the length of is too long (greater than 65,535 characters). Use the method to add headers that are normally exposed through properties. @@ -1600,13 +1550,9 @@ ## Remarks > [!NOTE] -> The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1. -> - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. -> - On .NET Core versions through version 3.1: A instance used with any header of type will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. -> - On .NET 5 and later versions: accepts a `value` of any length. +> accepts a `value` of any length. ]]> - .NET Framework and .NET Core versions 2.0 - 3.1 only: The length of is greater than 65535. This instance does not allow instances of . @@ -2008,13 +1954,9 @@ If the header specified in `header` is already present, `value` replaces the existing value. > [!NOTE] -> The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1. -> - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. -> - On .NET Core versions through version 3.1: A instance used with any header of type will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. -> - On .NET 5 and later versions: accepts a `value` of any length. +> accepts a `value` of any length. ]]> - .NET Framework and .NET Core versions 2.0 - 3.1 only: The length of is greater than 65535. This instance does not allow instances of . @@ -2074,13 +2016,9 @@ If the header specified in `header` is already present, `value` replaces the existing value. > [!NOTE] -> The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1. -> - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. -> - On .NET Core versions through version 3.1: A instance used with any header of type will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. -> - On .NET 5 and later versions: accepts a `value` of any length. +> accepts a `value` of any length. ]]> - .NET Framework and .NET Core versions 2.0 - 3.1 only: The length of is greater than 65535. This instance does not allow instances of . @@ -2156,15 +2094,11 @@ :::code language="vb" source="~/snippets/visualbasic/System.Net/WebHeaderCollection/Set/webheadercollection_set.vb" id="Snippet1"::: > [!NOTE] -> The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1. -> - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. -> - On .NET Core versions through version 3.1: A instance used with any header of type will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. -> - On .NET 5 and later versions: accepts a `value` of any length. +> accepts a `value` of any length. ]]> is or . - .NET Framework and .NET Core versions 2.0 - 3.1 only: The length of is greater than 65535. is a restricted header. diff --git a/xml/System.Net/WebPermission.xml b/xml/System.Net/WebPermission.xml index 5b3d2bc4321..85faba726b2 100644 --- a/xml/System.Net/WebPermission.xml +++ b/xml/System.Net/WebPermission.xml @@ -51,29 +51,6 @@ [!INCLUDE[cas-deprecated](~/includes/cas-deprecated.md)] - provides a set of methods and properties to control access to Internet resources. You can use a to provide either restricted or unrestricted access to your resource, based on the that is set when the is created. - - Create a instance by calling its constructor using one of the following sets of parameters: - -- No parameters. The default is . - -- A . Specify either to allow any URI to be used in the target class, or to allow access only to URIs that you specify through the use of the method. - -- A value and a URI string. The specified URI has permissions granted by the value. - -- A specifier and URI regular expression. - - The and hold the URIs to which you have granted access permission. To add a URI to either of these lists, use . If you pass as the parameter, the URI will be added to the . will allow connections to your target class with URIs matching the . - -> [!CAUTION] -> To deny access to an Internet resource, you must deny access to all the possible paths to that resource. This requires calling with state parameter set to . A better approach is to allow access to the specific resource only. - -> [!NOTE] -> You need to deny access using only the resource canonical path. There is no need to use all the path's syntactical variations. - -> [!NOTE] -> User name and default port information is stripped from the before the comparison with the regular expression argument that is supplied to the constructor. If the regular expression contains user information or the default port number, then all incoming s will fail to match the regular expression. - ]]> @@ -120,14 +97,7 @@ Creates a new instance of the class. - - class. This constructor creates an empty permission that does not grant any rights. - - ]]> - + To be added. @@ -164,14 +134,7 @@ A value. Creates a new instance of the class that passes all demands or fails all demands. - - or , respectively yielding fully restricted or fully unrestricted access to all security variables. If you specify , then you can give access to individual URIs using . - - ]]> - + To be added. @@ -210,14 +173,7 @@ A NetworkAccess value that indicates what kind of access to grant to the specified URI. indicates that the application is allowed to accept connections from the Internet on a local resource. indicates that the application is allowed to connect to specific Internet resources. A URI string to which access rights are granted. Initializes a new instance of the class with the specified access rights for the specified URI. - - and grants its target permission to either make a remote host connection or accept a remote host connection using the URI described by the `uriString` parameter. - - ]]> - + To be added. is . @@ -258,20 +214,7 @@ A value that indicates what kind of access to grant to the specified URI. indicates that the application is allowed to accept connections from the Internet on a local resource. indicates that the application is allowed to connect to specific Internet resources. A regular expression that describes the URI to which access is to be granted. Initializes a new instance of the class with the specified access rights for the specified URI regular expression. - - and grants its target permission to either make a remote host connection or accept a remote host connection using the URI described by the `uriRegex` parameter. - -> [!NOTE] -> It is recommended that you create `uriRegex` using the , , and flags. - -> [!NOTE] -> A candidate URI string is checked against the list of relevant regular expressions ( or ) in two ways. First, the candidate URI string is checked against the appropriate list; then, if there is no match, the candidate URI string is converted into a and checked against the appropriate list. - - ]]> - + To be added. @@ -308,20 +251,7 @@ This property returns an enumeration of a single accept permissions held by this . The possible objects types contained in the returned enumeration are and . The interface that contains accept permissions. - - . The class to which you have applied only has permission to receive an incoming connection to local resources found in this list. - -> [!NOTE] -> You can add URIs to this list using . - -> [!NOTE] -> A candidate URI string is checked against the list of relevant regular expressions ( or ) in two ways. First, the candidate URI string is checked against the appropriate list; then, if there is no match, the candidate URI string is converted into a and checked against the appropriate list. - - ]]> - + To be added. @@ -373,20 +303,7 @@ A that specifies the access rights that are granted to the URI. A string that describes the URI to which access rights are granted. Adds the specified URI string with the specified access rights to the current . - - as the , use to permit the use of `uriString` in the target class. The way that `uriString` can be used by the target class is specified by `access`. Specify as the access parameter to add the URI specified by the `uriString` parameter to the list of URI accept strings, or specify as the access parameter to add the URI to the list of URI connect strings. - -> [!NOTE] -> Calling on will have no effect, because permission is granted to all URIs. - -> [!NOTE] -> A candidate URI string is checked against the list of relevant regular expressions ( or ) in two ways. First, the candidate URI string is checked against the appropriate list; then, if there is no match, the candidate URI string is converted into a and checked against the appropriate list. - - ]]> - + To be added. is . @@ -430,23 +347,7 @@ A NetworkAccess that specifies the access rights that are granted to the URI. A regular expression that describes the set of URIs to which access rights are granted. Adds the specified URI with the specified access rights to the current . - - as the , use to allow the use of `uriRegex` in the target class. Specify as the `access` parameter to add the URI specified by the `uriRegex` parameter to the list of URI accept strings, or specify as the access parameter to add the URI to the list of URI connect strings. - -> [!NOTE] -> Calling on an instance will have no effect as permission is granted to all URIs. - -> [!NOTE] -> It is recommended that you create `uriRegex` using the , , and flags. - -> [!NOTE] -> A candidate URI string is checked against the list of relevant regular expressions ( or ) in two ways. First, the candidate URI string is checked against the appropriate list; then, if there is no match, the candidate URI string is converted into a and checked against the appropriate list. - - ]]> - + To be added. The parameter is . @@ -484,20 +385,7 @@ This property returns an enumeration of a single connect permissions held by this . The possible objects types contained in the returned enumeration are and . The interface that contains connect permissions. - - . The class to which you have applied only has permission to connect with resources found in this list. - -> [!NOTE] -> You can add URIs to this list using . - -> [!NOTE] -> A candidate URI string is checked against the list of relevant regular expressions ( or ) in two ways. First, the candidate URI string is checked against the appropriate list; then, if there is no match, the candidate URI string is converted into a and checked against the appropriate list. - - ]]> - + To be added. @@ -535,14 +423,7 @@ Creates a copy of a . A new instance of the class that has the same values as the original. - - returned by this method represents the same access to resources as the original . This method overrides and is implemented to support the interface. - - ]]> - + To be added. @@ -581,16 +462,7 @@ The XML encoding from which to reconstruct the . Reconstructs a from an XML encoding. - - method reconstructs a from an XML encoding that is defined by the class. - - Use the method to XML-encode the , including state information. - - ]]> - + To be added. The parameter is . is not a permission element for this type. @@ -634,16 +506,7 @@ The to compare with the current instance. Returns the logical intersection of two instances. A new that represents the intersection of the current instance and the parameter. If the intersection is empty, the method returns . - - returns a that contains those permissions that are common in both `target` and the current instance. - - This method overrides and is implemented to support the interface. - - ]]> - + To be added. is not or of type @@ -686,14 +549,7 @@ Determines whether the current is a subset of the specified object. if the current instance is a subset of the parameter; otherwise, . If the target is , the method returns for an empty current permission that is not unrestricted and otherwise. - - specifies a set of associated resources that is wholly contained by the `target` parameter, then the current is a subset of `target`. This method overrides and is implemented to support the interface. - - ]]> - + To be added. The target parameter is not an instance of . The current instance contains a Regex-encoded right and there is not exactly the same right found in the target instance. @@ -736,17 +592,7 @@ Checks the overall permission state of the . if the was created with the ; otherwise, . - - is , then the target class can use all URIs. Otherwise, specific permission must be given for any URI you want to use with the target class. - -> [!NOTE] -> Use to add a URI and specify its permissions. - - ]]> - + To be added. @@ -784,14 +630,7 @@ Creates an XML encoding of a and its current state. A that contains an XML-encoded representation of the , including state information. - - method to restore the state information from a . - - ]]> - + To be added. @@ -832,14 +671,7 @@ The to combine with the current . Returns the logical union between two instances of the class. A that represents the union of the current instance and the parameter. If either is , the method returns a that is . If the target is , the method returns a copy of the current . - - returns a that contains all the permissions in both `target` and the current instance. - - ]]> - + To be added. target is not or of type . diff --git a/xml/System.Net/WebPermissionAttribute.xml b/xml/System.Net/WebPermissionAttribute.xml index cd1d90e678d..be2ce22ec36 100644 --- a/xml/System.Net/WebPermissionAttribute.xml +++ b/xml/System.Net/WebPermissionAttribute.xml @@ -51,13 +51,6 @@ [!INCLUDE[cas-deprecated](~/includes/cas-deprecated.md)] - allows you to declaratively specify which URI strings and regular expression strings your class can use. - - The security information specified in the is stored in the metadata of the attribute target, which is the class to which is applied. The system accesses this information at run time. The passed to the constructor determines the allowable targets. The system uses the returned by the method to convert the security information of the attribute target to a serializable form stored in metadata. - -> [!NOTE] -> is used only for Declarative Security. For Imperative Security, use the corresponding . - ]]> @@ -95,14 +88,7 @@ One of the values. Initializes a new instance of the class with a value that specifies the security actions that can be performed on this class. - - value passed to this constructor specifies the allowable security actions that can be performed on this class. - - ]]> - + To be added. is not a valid value. @@ -140,14 +126,7 @@ Gets or sets the URI string accepted by the current . A string containing the URI accepted by the current . - - to your class, this property specifies what URI string will be accepted for use within your class. This permission is applied when the security system calls . This property is write-once. - - ]]> - + To be added. is not when you attempt to set the value. If you wish to specify more than one Accept URI, use an additional attribute declaration statement. Introducing Pluggable Protocols @@ -186,14 +165,7 @@ Gets or sets a regular expression pattern that describes the URI accepted by the current . A string containing a regular expression pattern that describes the URI accepted by the current . This string must be escaped according to the rules for encoding a constructor string. - - to your class, this property specifies what regular expression string will be accepted for use within your class. This property is write-once. - - ]]> - + To be added. is not when you attempt to set the value. If you wish to specify more than one Accept URI, use an additional attribute declaration statement. Regular Expression Language - Quick Reference @@ -232,14 +204,7 @@ Gets or sets the URI connection string controlled by the current . A string containing the URI connection controlled by the current . - - to your class, this property specifies what URI connection is accepted for use within your class. This property is write-once. - - ]]> - + To be added. is not when you attempt to set the value. If you wish to specify more than one Connect URI, use an additional attribute declaration statement. Introducing Pluggable Protocols @@ -278,14 +243,7 @@ Gets or sets a regular expression pattern that describes the URI connection controlled by the current . A string containing a regular expression pattern that describes the URI connection controlled by this . - - to your class, this property specifies what regular expression connect string is accepted for use within your class. This property is write-once. - - ]]> - + To be added. is not when you attempt to set the value. If you wish to specify more than one connect URI, use an additional attribute declaration statement. Regular Expression Language - Quick Reference @@ -325,16 +283,7 @@ Creates and returns a new instance of the class. A corresponding to the security declaration. - - method is called by the security system, not by application code. - - The security information described by is stored in the metadata of the attribute target, which is the class to which is applied. The system accesses the information at run time. The system uses the returned by to convert the security information of the attribute target to a serializable form stored in metadata. - - ]]> - + To be added. diff --git a/xml/System.Net/WebProxy.xml b/xml/System.Net/WebProxy.xml index 9d6ee4404c3..dd7ad8b1ccc 100644 --- a/xml/System.Net/WebProxy.xml +++ b/xml/System.Net/WebProxy.xml @@ -1170,18 +1170,12 @@ method reads the nondynamic proxy settings from the computer's Internet options and creates a instance with those settings. - - The method does not pick up any dynamic settings that are generated from scripts run by Internet Explorer, from automatic configuration entries, or from DHCP or DNS lookups. - - Applications should use the property instead of the method. - > [!NOTE] -> This property is not supported on .NET Core. +> This method is not supported. ]]> - On .NET Core. + In all cases. diff --git a/xml/System.Net/WebRequest.xml b/xml/System.Net/WebRequest.xml index e54962170b1..359ab268ea4 100644 --- a/xml/System.Net/WebRequest.xml +++ b/xml/System.Net/WebRequest.xml @@ -69,26 +69,6 @@ [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - is the `abstract` base class for .NET's request/response model for accessing data from the Internet. An application that uses the request/response model can request data from the Internet in a protocol-agnostic manner, in which the application works with instances of the class while protocol-specific descendant classes carry out the details of the request. - - Requests are sent from an application to a particular URI, such as a Web page on a server. The URI determines the proper descendant class to create from a list of descendants registered for the application. descendants are typically registered to handle a specific protocol, such as HTTP or FTP, but can be registered to handle a request to a specific server or path on a server. - - The class throws a when errors occur while accessing an Internet resource. The property is one of the values that indicates the source of the error. When is , the property contains the received from the Internet resource. - - Because the class is an `abstract` class, the actual behavior of instances at run time is determined by the descendant class returned by method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - -> [!NOTE] -> Use the method to initialize new instances. Do not use the constructor. - -> [!NOTE] -> If the application that creates the WebRequest object runs with the credentials of a Normal user, the application will not be able to access certificates installed in the local machine store unless permission has been explicitly given to the user to do so. - -## Examples - The following example shows how to create a instance and return the response. - - :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/Overview/webrequestget.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/WebRequest/Overview/webrequestget.vb" id="Snippet1"::: - ]]> @@ -219,20 +199,8 @@ The information required to serialize the new instance. A that indicates the source of the serialized stream associated with the new instance. Initializes a new instance of the class from the specified instances of the and classes. - - interface for the descendant. - -> [!NOTE] -> An application must run in full trust mode when using serialization. - - ]]> - + To be added. Any attempt is made to access the constructor, when the constructor is not overridden in a descendant class. - XML and SOAP Serialization @@ -282,16 +250,9 @@ method cancels asynchronous requests to Internet resources started with the method. - -> [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - - ]]> +]]> Any attempt is made to access the method, when the method is not overridden in a descendant class. @@ -412,24 +373,9 @@ method starts an asynchronous request for a stream used to send data to an Internet resource. The callback method that implements the delegate uses the method to return the request stream. - -> [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - - - -## Examples - The following example uses the to asynchronously obtain the request stream. - - :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/BeginGetRequestStream/webrequest_begingetrequest.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/WebRequest/BeginGetRequestStream/webrequest_begingetrequest.vb" id="Snippet3"::: - - ]]> +]]> Any attempt is made to access the method, when the method is not overridden in a descendant class. @@ -496,26 +442,9 @@ method starts an asynchronous request for a response. The callback method that implements the delegate uses the method to return the from the Internet resource. - -> [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - -> [!NOTE] -> If a WebException is thrown, use the and properties of the exception to determine the response from the server. - - - -## Examples - The following example uses to asynchronously request the target resource. When the resource has been obtained, the specified callback method will be executed. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Abort/begingetresponse.cs" id="Snippet1"::: - - ]]> +]]> Any attempt is made to access the method, when the method is not overridden in a descendant class. @@ -571,24 +500,9 @@ property for requests that use the Hypertext Transfer Protocol (HTTP) or Secure Hypertext Transfer Protocol (HTTPS) URI scheme. - - A copy of a resource is only added to the cache if the response stream for the resource is retrieved and read to the end of the stream. So another request for the same resource could use a cached copy, depending on the cache policy level for this request. - - - -## Examples - The following code example demonstrates setting the cache policy for a Web request. - - :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/CachePolicy/example.cs" id="Snippet2"::: - - ]]> +]]> @@ -646,16 +560,9 @@ property associates specific requests within an application to one or more connection pools. - -> [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - - ]]> +]]> Any attempt is made to get or set the property, when the property is not overridden in a descendant class. @@ -707,24 +614,9 @@ property contains the number of bytes of data sent to the Internet resource by the instance. - -> [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - - - -## Examples - The following example sets the property to the amount of bytes in the outgoing byte buffer. - - :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/ContentLength/webrequest_contenttype.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/WebRequest/ContentLength/webrequest_contenttype.vb" id="Snippet4"::: - - ]]> +]]> Any attempt is made to get or set the property, when the property is not overridden in a descendant class. @@ -783,24 +675,9 @@ property contains the media type of the request. This is typically the MIME encoding of the content. - -> [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - - - -## Examples - The following example sets the property to the appropriate media type. - - :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/ContentLength/webrequest_contenttype.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/WebRequest/ContentLength/webrequest_contenttype.vb" id="Snippet4"::: - - ]]> +]]> Any attempt is made to get or set the property, when the property is not overridden in a descendant class. @@ -1273,24 +1150,9 @@ property contains the authentication credentials required to access the Internet resource. - -> [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - - - -## Examples - The following example sets the property using the default credentials of the current user. When the request is made, credentials stored in this property are used to validate the client. This is identical to setting the property to `true`. - - :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/Overview/webrequestget.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/WebRequest/Overview/webrequestget.vb" id="Snippet2"::: - - ]]> +]]> Any attempt is made to get or set the property, when the property is not overridden in a descendant class. @@ -1346,28 +1208,9 @@ property specified for this request. - -- The machine and application configuration files do not specify a cache policy that is applicable to the Uniform Resource Identifier (URI) used to create this request. - - The cache policy determines whether the requested resource can be taken from a cache instead of sending the request to the resource host computer. - - A copy of a resource is only added to the cache if the response stream for the resource is retrieved and read to the end of the stream. So another request for the same resource could use a cached copy, depending on the cache policy level for this request. - - - -## Examples - The following code example demonstrates setting the default cache policy for Web requests. - - :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/CachePolicy/example.cs" id="Snippet15"::: - - ]]> +]]> @@ -1425,17 +1268,9 @@ property gets or sets the global proxy. The property determines the default proxy that all instances use if the request supports proxies and no proxy is set explicitly using the property. Proxies are currently supported by and . - - The property reads proxy settings from the app.config file. If there is no config file, the current user's Internet options proxy settings are used. - - If the property is set to null, all subsequent instances of the class created by the or methods do not have a proxy. - - ]]> +]]> @@ -1490,27 +1325,9 @@ method completes an asynchronous stream request that was started by the method. - -> [!NOTE] -> To avoid timing issues with garbage collection, be sure to close the response stream by calling the method on the stream returned by after calling . - -> [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - - - -## Examples - The following example obtains and uses the request stream by calling the . The method completes the asynchronous call to . - - :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/BeginGetRequestStream/webrequest_begingetrequest.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/WebRequest/BeginGetRequestStream/webrequest_begingetrequest.vb" id="Snippet3"::: - - ]]> +]]> Any attempt is made to access the method, when the method is not overridden in a descendant class. @@ -1568,23 +1385,9 @@ method completes an asynchronous request for an Internet resource that was started with the method. - -> [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - - - -## Examples - The following example calls the to retrieve the target resource. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Abort/begingetresponse.cs" id="Snippet1"::: - - ]]> +]]> Any attempt is made to access the method, when the method is not overridden in a descendant class. @@ -1694,26 +1497,9 @@ method initiates a request to send data to the Internet resource and returns a instance for sending data to the Internet resource. - - The method provides synchronous access to the . For asynchronous access, use the and methods. - -> [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - - - -## Examples - The following example uses the method to obtain a stream and then writes data that stream. - - :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/ContentLength/webrequest_contenttype.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/WebRequest/ContentLength/webrequest_contenttype.vb" id="Snippet4"::: - - ]]> +]]> Any attempt is made to access the method, when the method is not overridden in a descendant class. @@ -1762,16 +1548,8 @@ object will complete when the for writing data to the Internet resource is available. - - After you call , make sure you close the request stream before you call . - - This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - ]]> @@ -1819,29 +1597,9 @@ method sends a request to an Internet resource and returns a instance. If the request has already been initiated by a call to , the method completes the request and returns any response. - - The method provides synchronous access to the . For asynchronous access, use the and methods. - -> [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - -> [!NOTE] -> If a WebException is thrown, use the and properties of the exception to determine the response from the server. - - - -## Examples - The following example sets the property to 10000 milliseconds. If the timeout period expires before the resource can be returned, a is thrown. - - :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/GetResponse/webrequest_timeout.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/WebRequest/GetResponse/webrequest_timeout.vb" id="Snippet1"::: - - ]]> +]]> Any attempt is made to access the method, when the method is not overridden in a descendant class. @@ -1890,14 +1648,8 @@ object will complete after a response to an Internet request is available. - - This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - ]]> @@ -1944,15 +1696,9 @@ method reads the current user's Internet options proxy settings. This process includes the options to automatically detect proxy settings, use an automatic configuration script, manual proxy server settings, and advanced manual proxy server settings. - - If your application impersonates several users, you can use the method to retrieve a proxy for each impersonated user. - - ]]> +]]> @@ -2002,24 +1748,9 @@ property contains a instance containing the header information to send to the Internet resource. - -> [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - - - -## Examples - The following example displays the header name/value pairs associated with this request. - - :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/Headers/webrequest_headers.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/WebRequest/Headers/webrequest_headers.vb" id="Snippet1"::: - - ]]> +]]> Any attempt is made to get or set the property, when the property is not overridden in a descendant class. @@ -2067,13 +1798,9 @@ +]]> @@ -2123,24 +1850,9 @@ property contains the request method to use in this request. - -> [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - - - -## Examples - The following example sets the property to POST to indicate that the request will post data to the target host. - - :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/BeginGetRequestStream/webrequest_begingetrequest.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/WebRequest/BeginGetRequestStream/webrequest_begingetrequest.vb" id="Snippet3"::: - - ]]> +]]> If the property is not overridden in a descendant class, any attempt is made to get or set the property. @@ -2192,16 +1904,9 @@ property indicates whether to send authentication information with subsequent requests without waiting to be challenged by the server. When is `false`, the waits for an authentication challenge before sending authentication information. - -> [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - - ]]> +]]> Any attempt is made to get or set the property, when the property is not overridden in a descendant class. @@ -2257,24 +1962,9 @@ property identifies the network proxy that the request uses to access the Internet resource. The request is made through the proxy server rather than directly to the Internet resource. - -> [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - - - -## Examples - The following example displays the current network proxy address and allows the user to assign a new network proxy address and port number. - - :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/Proxy/webrequest_proxy.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/WebRequest/Proxy/webrequest_proxy.vb" id="Snippet1"::: - - ]]> +]]> Any attempt is made to get or set the property, when the property is not overridden in a descendant class. @@ -2332,30 +2022,9 @@ method registers descendants to service requests. descendants are typically registered to handle a specific protocol, such HTTP or FTP, but can be registered to handle a request to a specific server or path on a server. - - The pre-registered reserve types already registered include the following: - -- `http://` - -- `https://` - -- `ftp://` - -- `file://` - - For more information, see the and methods. - - Duplicate prefixes are not allowed. returns `false` if an attempt is made to register a duplicate prefix. - -> [!NOTE] -> The class is registered to service requests for HTTP and HTTPS schemes by default. Attempts to register a different descendant for these schemes will fail. - - ]]> +]]> is @@ -2411,24 +2080,9 @@ property contains the instance that method uses to create the request. - -> [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - - - -## Examples - The following example checks the property to determine the site originally requested. - - :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/RequestUri/webrequest_requesturi.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/WebRequest/RequestUri/webrequest_requesturi.vb" id="Snippet1"::: - - ]]> +]]> Any attempt is made to get or set the property, when the property is not overridden in a descendant class. @@ -2538,24 +2192,9 @@ property indicates the length of time, in milliseconds, until the request times out and throws a . The property affects only synchronous requests made with the method. To time out asynchronous requests, use the method. - -> [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - - - -## Examples - The following example sets the property to 10000 milliseconds. If the timeout period expires before the resource can be returned, a is thrown. - - :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/GetResponse/webrequest_timeout.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/WebRequest/GetResponse/webrequest_timeout.vb" id="Snippet1"::: - - ]]> +]]> Any attempt is made to get or set the property, when the property is not overridden in a descendant class. @@ -2607,13 +2246,9 @@ object should, if requested by the server, be authenticated using the credentials of the currently logged on user. For client applications, this is the desired behavior in most scenarios. For middle tier applications, such as ASP.NET applications, instead of using this property, you would typically set the property to the credentials of the client on whose behalf the request is made. - - ]]> +]]> You attempted to set this property after the request was sent. Any attempt is made to access the property, when the property is not overridden in a descendant class. diff --git a/xml/System.Net/WebResponse.xml b/xml/System.Net/WebResponse.xml index a84f48ed5e2..d2ea99cbdb8 100644 --- a/xml/System.Net/WebResponse.xml +++ b/xml/System.Net/WebResponse.xml @@ -513,9 +513,6 @@ When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the `Dispose()` method of each referenced object. -> [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - ]]> @@ -922,17 +919,8 @@ Gets a value that indicates if headers are supported. - Returns . - - if headers are supported; otherwise, . - - - + if headers are supported; otherwise, . + To be added. diff --git a/xml/System.Net/WriteStreamClosedEventArgs.xml b/xml/System.Net/WriteStreamClosedEventArgs.xml index 1e976715630..8fc38f9628d 100644 --- a/xml/System.Net/WriteStreamClosedEventArgs.xml +++ b/xml/System.Net/WriteStreamClosedEventArgs.xml @@ -73,8 +73,8 @@ [<System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Never)>] - [System.Obsolete("This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.", true)] - [<System.Obsolete("This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.", true)>] + [System.Obsolete("This API supports the .NET infrastructure and is not intended to be used directly from your code.", true)] + [<System.Obsolete("This API supports the .NET infrastructure and is not intended to be used directly from your code.", true)>] @@ -116,8 +116,8 @@ [<System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Never)>] - [System.Obsolete("This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.", true)] - [<System.Obsolete("This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.", true)>] + [System.Obsolete("This API supports the .NET infrastructure and is not intended to be used directly from your code.", true)] + [<System.Obsolete("This API supports the .NET infrastructure and is not intended to be used directly from your code.", true)>]