diff --git a/xml/System.AddIn.Hosting/AddInToken.xml b/xml/System.AddIn.Hosting/AddInToken.xml index d920fc17488..937614eb63f 100644 --- a/xml/System.AddIn.Hosting/AddInToken.xml +++ b/xml/System.AddIn.Hosting/AddInToken.xml @@ -30,38 +30,38 @@ Represents an add-in that can be activated. - object represents an add-in, and its associated pipeline segments, that can be activated. The token contains the name, assembly name, description, publisher, and version of the add-in that it represents. - - Use the method to get a collection of tokens that represent add-ins whose pipelines match a specified host view. Use the method to get a collection of tokens that represent all the pipelines for a specified add-in that match a specified host view. - - To activate an add-in, pass the token that represents the desired add-in to the method. This method returns an instance of the type that represents the host view of the add-in. - - The method has several overloads. When you use an overload that does not require the name of an application domain as one of its parameters, a new application domain for the add-in is automatically created. - - You can use Language-Integrated Query (LINQ) extension methods to perform queries on an , treating the token as a collection of structures. - - - -## Examples - This section contains two examples. The first example activates an add-in that has been selected by using the `ChooseAddIn` method, and the second example shows the `ChooseAddIn` method. - - **Example 1** - - The following example shows how to activate an add-in with a token. - + object represents an add-in, and its associated pipeline segments, that can be activated. The token contains the name, assembly name, description, publisher, and version of the add-in that it represents. + + Use the method to get a collection of tokens that represent add-ins whose pipelines match a specified host view. Use the method to get a collection of tokens that represent all the pipelines for a specified add-in that match a specified host view. + + To activate an add-in, pass the token that represents the desired add-in to the method. This method returns an instance of the type that represents the host view of the add-in. + + The method has several overloads. When you use an overload that does not require the name of an application domain as one of its parameters, a new application domain for the add-in is automatically created. + + You can use Language-Integrated Query (LINQ) extension methods to perform queries on an , treating the token as a collection of structures. + + + +## Examples + This section contains two examples. The first example activates an add-in that has been selected by using the `ChooseAddIn` method, and the second example shows the `ChooseAddIn` method. + + **Example 1** + + The following example shows how to activate an add-in with a token. + :::code language="csharp" source="~/snippets/csharp/System.AddIn.Hosting/AddInController/Overview/P3Host.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet5"::: - - **Example 2** - - The following example shows the custom `ChooseAddIn` method, which enumerates an collection. The user selects a token from this collection to activate the corresponding add-in. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet5"::: + + **Example 2** + + The following example shows the custom `ChooseAddIn` method, which enumerates an collection. The user selects a token from this collection to activate the corresponding add-in. + :::code language="csharp" source="~/snippets/csharp/System.AddIn.Hosting/AddInController/Overview/P3Host.cs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet13"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet13"::: + ]]> Add-Ins and Extensibility @@ -104,19 +104,19 @@ Activates an add-in in the environment of another add-in. The host view of the add-in. - object. - + object. + :::code language="csharp" source="~/snippets/csharp/System.AddIn.Hosting/AddInController/Overview/P3Host.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet8"::: + ]]> Add-Ins and Extensibility @@ -150,21 +150,21 @@ Activates an add-in with a specified trust level in a new application domain. The host view of the add-in. - overload. - - This method sets the base directory for the application domain to be the location of the add-in assembly. It also looks for the configuration file [addinassemblyname].dll.config and, if found, sets it to be the configuration file for the new application domain. - - - -## Examples - The following example shows how to activate an add-in, identified by the chosen token, in an automatically generated application domain with a specified security level. - + overload. + + This method sets the base directory for the application domain to be the location of the add-in assembly. It also looks for the configuration file [addinassemblyname].dll.config and, if found, sets it to be the configuration file for the new application domain. + + + +## Examples + The following example shows how to activate an add-in, identified by the chosen token, in an automatically generated application domain with a specified security level. + :::code language="csharp" source="~/snippets/csharp/System.AddIn.Hosting/AddInController/Overview/P3Host.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet5"::: + ]]> Add-Ins and Extensibility @@ -198,19 +198,19 @@ Activates an add-in in an existing application domain. The host view of the add-in. - overload to generate a new application domain with a specified security level or the overload to include a friendly name for the application domain. - - - -## Examples - The following example activates an add-in in an application domain that is being used by another add-in. The code for the first add-in is provided in the class. - + overload to generate a new application domain with a specified security level or the overload to include a friendly name for the application domain. + + + +## Examples + The following example activates an add-in in an application domain that is being used by another add-in. The code for the first add-in is provided in the class. + :::code language="csharp" source="~/snippets/csharp/System.AddIn.Hosting/AddInController/Overview/P3Host.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet9"::: + ]]> Full-trust permission is demanded. A caller in the call chain does not have sufficient permission. @@ -244,11 +244,11 @@ Activates an add-in with a specified permission set in a new application domain. The host view of the add-in. - @@ -291,19 +291,19 @@ Activates an add-in in an external process, in a new application domain, and with a specified trust level. The host view of the add-in. - @@ -344,11 +344,11 @@ Activates an add-in in an external process, in a new application domain, and with a specified permission set. The host view of the add-in. - @@ -383,13 +383,13 @@ Activates an add-in in a new application domain with a specified name and trust level. The host view of the add-in. - overload. - - This method sets the base directory for the application domain to be the location of the add-in assembly. It also looks for the configuration file `[addinassemblyname].dll.config` and, if found, sets it to be the configuration file for the new application domain. - + overload. + + This method sets the base directory for the application domain to be the location of the add-in assembly. It also looks for the configuration file `[addinassemblyname].dll.config` and, if found, sets it to be the configuration file for the new application domain. + ]]> @@ -414,19 +414,19 @@ Gets the namespace and type of the add-in. The type of the add-in, fully qualified by its namespace. - property. This value is always available on an instance of an object. - - - -## Examples - The following example displays the value of the , , , , , and properties to the console. This code example is part of a larger example provided for the class. - + property. This value is always available on an instance of an object. + + + +## Examples + The following example displays the value of the , , , , , and properties to the console. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.AddIn.Hosting/AddInController/Overview/P3Host.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet7"::: + ]]> @@ -451,19 +451,19 @@ Gets the name of the assembly that contains the add-in. The name of the assembly. - property. This value is always available on an instance of an object. - - - -## Examples - The following example displays the value of the , , , , , and properties to the console. This code example is part of a larger example provided for the class. - + property. This value is always available on an instance of an object. + + + +## Examples + The following example displays the value of the , , , , , and properties to the console. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.AddIn.Hosting/AddInController/Overview/P3Host.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet7"::: + ]]> @@ -488,19 +488,19 @@ Gets the description of the add-in. A description of the add-in, or if the description is not specified in the attribute. - attribute. - - - -## Examples - The following example displays the value of the , , , , , and properties to the console. This code example is part of a larger example provided for the class. - + attribute. + + + +## Examples + The following example displays the value of the , , , , , and properties to the console. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.AddIn.Hosting/AddInController/Overview/P3Host.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet7"::: + ]]> @@ -536,21 +536,21 @@ if the add-in should be directly connected to the host; otherwise, . The default is . - @@ -606,26 +606,24 @@ Returns an enumerator for the qualification data of the pipeline segments that are associated with this token. An enumerator that can be used to iterate through the qualification data of the pipeline segments that are associated with the current token. - structure that identifies the pipeline segment and contains a name/value pair from a attribute applied to that segment. - + structure that identifies the pipeline segment and contains a name/value pair from a attribute applied to that segment. + > [!NOTE] -> The add-in model does not use qualification data that is applied to the host view of the add-in. As a result, when you enumerate qualification data you will not find any items whose property is . - - Alternatively, you can use the property to get a nested set of dictionaries that contain the qualification data of the pipeline segments. - - - -## Examples - The following example lists the qualification data for the pipeline segments associated with each in a collection of tokens. - +> The add-in model does not use qualification data that is applied to the host view of the add-in. As a result, when you enumerate qualification data you will not find any items whose property is . + + Alternatively, you can use the property to get a nested set of dictionaries that contain the qualification data of the pipeline segments. + +## Examples + The following example lists the qualification data for the pipeline segments associated with each in a collection of tokens. + :::code language="csharp" source="~/snippets/csharp/System.AddIn.Hosting/AddInController/Overview/P3Host.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet12"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet12"::: + ]]> @@ -673,19 +671,19 @@ Gets the name of the add-in. The name of the add-in. - attribute. This value is always available on an instance of an object. - - - -## Examples - The following example displays the value of the , , , , , and properties to the console. This code example is part of a larger example provided for the class. - + attribute. This value is always available on an instance of an object. + + + +## Examples + The following example displays the value of the , , , , , and properties to the console. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.AddIn.Hosting/AddInController/Overview/P3Host.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet7"::: + ]]> @@ -710,19 +708,19 @@ Gets the publisher of the add-in. The publisher of the add-in, or if the publisher is not specified in the attribute. - attribute. - - - -## Examples - The following example displays the value of the , , , , , and properties to the console. This code example is part of a larger example provided for the class. - + attribute. + + + +## Examples + The following example displays the value of the , , , , , and properties to the console. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.AddIn.Hosting/AddInController/Overview/P3Host.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet7"::: + ]]> @@ -747,28 +745,26 @@ Gets a dictionary of data about the segments in the pipeline associated with the current token. A dictionary whose keys are pipeline segments and whose values are dictionaries of name/value pairs that represent qualification data for each segment. - attribute. You can use this data to identify and work with the types that compose your pipelines. - - This property returns a dictionary of dictionaries. The top dictionary always has six keys. Each key is an value for a segment in the pipeline. Each value is a generic of strings with string keys that contains the segment's qualification data. - - The keys and values of these inner dictionaries are the names and values specified in the attributes for the segments. If no qualification data has been applied to a segment, its dictionary is empty. - + attribute. You can use this data to identify and work with the types that compose your pipelines. + + This property returns a dictionary of dictionaries. The top dictionary always has six keys. Each key is an value for a segment in the pipeline. Each value is a generic of strings with string keys that contains the segment's qualification data. + + The keys and values of these inner dictionaries are the names and values specified in the attributes for the segments. If no qualification data has been applied to a segment, its dictionary is empty. + > [!NOTE] -> The add-in model does not use qualification data that is applied to the host view of the add-in. As a result, the dictionary for is always empty. - - Alternatively, you can obtain qualification data by enumerating an as if it were a collection of structures, using a `foreach` statement (`For Each` in Visual Basic, `for each` in Visual C++). See the example provided for the structure. - - - -## Examples - The following example shows how to examine an add-in's qualification data. - +> The add-in model does not use qualification data that is applied to the host view of the add-in. As a result, the dictionary for is always empty. + + Alternatively, you can obtain qualification data by enumerating an as if it were a collection of structures, using a `foreach` statement in C#. See the example provided for the structure. + +## Examples + The following example shows how to examine an add-in's qualification data. + :::code language="csharp" source="~/snippets/csharp/System.AddIn.Hosting/AddInController/Overview/P3Host.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet11"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet11"::: + ]]> @@ -803,18 +799,18 @@ Returns an enumerator for the qualification data of the pipeline segments that are associated with this token. An enumerator that can be used to iterate through the qualification data of the pipeline segments that are associated with the current token. - structure that identifies the pipeline segment and contains the name/value pair from a attribute applied to that segment. - + structure that identifies the pipeline segment and contains the name/value pair from a attribute applied to that segment. + > [!NOTE] -> The add-in model does not use qualification data that is applied to the host view of the add-in. As a result, when you enumerate qualification data you will not find any items whose property is . - - Alternatively, you can use the property to get a nested set of dictionaries containing the qualification data of the pipeline segments. - +> The add-in model does not use qualification data that is applied to the host view of the add-in. As a result, when you enumerate qualification data you will not find any items whose property is . + + Alternatively, you can use the property to get a nested set of dictionaries containing the qualification data of the pipeline segments. + ]]> @@ -862,19 +858,19 @@ Gets the version of the add-in, as specified in the attribute. The version of the add-in, or if the version number is not specified in the attribute. - , , , , , and properties to the console. This code example is part of a larger example provided for the class. - + , , , , , and properties to the console. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.AddIn.Hosting/AddInController/Overview/P3Host.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet7"::: + ]]> diff --git a/xml/System.AddIn.Hosting/QualificationDataItem.xml b/xml/System.AddIn.Hosting/QualificationDataItem.xml index acc729f0253..7dbceb4a742 100644 --- a/xml/System.AddIn.Hosting/QualificationDataItem.xml +++ b/xml/System.AddIn.Hosting/QualificationDataItem.xml @@ -23,23 +23,21 @@ Represents information supplied by the developer of a pipeline segment, for use by the host. - attribute, to provide information that qualifies the use of the segment (for example, the recommended isolation level for the segment). The structure contains one name/value pair and the type of pipeline segment it was applied to. - - Use the property to get a nested set of dictionaries that contains structures for the pipeline segments associated with an . - - Alternatively, use the method to get an enumerator for the structures of the pipeline segments associated with a token, or simply use a `foreach` statement (`For Each` in Visual Basic, `for each` in Visual C++) to treat the token as if it were a collection of structures. - - - -## Examples - The following example lists the qualification data for the pipeline segments associated with each in a collection of tokens. - + attribute, to provide information that qualifies the use of the segment (for example, the recommended isolation level for the segment). The structure contains one name/value pair and the type of pipeline segment it was applied to. + + Use the property to get a nested set of dictionaries that contains structures for the pipeline segments associated with an . + + Alternatively, use the method to get an enumerator for the structures of the pipeline segments associated with a token, or simply use a `foreach` statement (`For Each` in Visual Basic) to treat the token as if it were a collection of structures. + +## Examples + The following example lists the qualification data for the pipeline segments associated with each in a collection of tokens. + :::code language="csharp" source="~/snippets/csharp/System.AddIn.Hosting/AddInController/Overview/P3Host.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet12"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet12"::: + ]]> @@ -120,19 +118,19 @@ Gets the name of the qualification data item. The name of the qualification data item. - attribute, to provide information to consumers of the add-in. The property gets the name. Use the property to get the value. - - - -## Examples - The following example lists the qualification data for the pipeline segments associated with each in a collection of tokens. The property is used to display the name of each item. - + attribute, to provide information to consumers of the add-in. The property gets the name. Use the property to get the value. + + + +## Examples + The following example lists the qualification data for the pipeline segments associated with each in a collection of tokens. The property is used to display the name of each item. + :::code language="csharp" source="~/snippets/csharp/System.AddIn.Hosting/AddInController/Overview/P3Host.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet12"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet12"::: + ]]> @@ -221,22 +219,22 @@ Gets a value that identifies the pipeline segment the qualification data item was applied to. The kind of pipeline segment the data item was applied to. - [!NOTE] -> The add-in model does not use qualification data that is applied to the host view of the add-in. As a result, when you enumerate qualification data you will not find any items whose property is . - - - -## Examples - The following example lists the qualification data for the pipeline segments associated with each in a collection of tokens. The property is used to display the kind of segment. - +> The add-in model does not use qualification data that is applied to the host view of the add-in. As a result, when you enumerate qualification data you will not find any items whose property is . + + + +## Examples + The following example lists the qualification data for the pipeline segments associated with each in a collection of tokens. The property is used to display the kind of segment. + :::code language="csharp" source="~/snippets/csharp/System.AddIn.Hosting/AddInController/Overview/P3Host.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet12"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet12"::: + ]]> @@ -267,19 +265,19 @@ Gets the value of the qualification data item. The value of the item. - attribute, to provide information to consumers of the add-in. The property gets the value. Use the property to get the name. - - - -## Examples - The following example lists the qualification data for the pipeline segments associated with each in a collection of tokens. The property is used to display the value of the item. - + attribute, to provide information to consumers of the add-in. The property gets the value. Use the property to get the name. + + + +## Examples + The following example lists the qualification data for the pipeline segments associated with each in a collection of tokens. The property is used to display the value of the item. + :::code language="csharp" source="~/snippets/csharp/System.AddIn.Hosting/AddInController/Overview/P3Host.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet12"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/addinP3Host/vb/p3host.vb" id="Snippet12"::: + ]]> diff --git a/xml/System.Collections.Generic/Dictionary`2+Enumerator.xml b/xml/System.Collections.Generic/Dictionary`2+Enumerator.xml index 5ef1a0dcddb..c4800515109 100644 --- a/xml/System.Collections.Generic/Dictionary`2+Enumerator.xml +++ b/xml/System.Collections.Generic/Dictionary`2+Enumerator.xml @@ -80,27 +80,27 @@ Enumerates the elements of a . - is undefined. You must call to advance the enumerator to the first element of the collection before reading the value of . - - returns the same object until is called. sets to the next element. - - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. - + is undefined. You must call to advance the enumerator to the first element of the collection before reading the value of . + + returns the same object until is called. sets to the next element. + + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding elements or changing the capacity, the enumerator is irrecoverably invalidated and the next call to or throws an . .NET Core 3.0+ only: The only mutating methods which do not invalidate enumerators are and . - - The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - Default implementations of collections in are not synchronized. - + + The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + Default implementations of collections in are not synchronized. + ]]> @@ -158,19 +158,19 @@ Gets the element at the current position of the enumerator. The element in the at the current position of the enumerator. - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - + is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. + - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + ]]> @@ -266,17 +266,17 @@ if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the collection. - advances the enumerator to the first element of the collection. - - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. - + advances the enumerator to the first element of the collection. + + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding elements or changing the capacity, the enumerator is irrecoverably invalidated and the next call to or throws an . .NET Core 3.0+ only: The only mutating methods which do not invalidate enumerators are and . - + ]]> The collection was modified after the enumerator was created. @@ -326,19 +326,19 @@ Gets the element at the current position of the enumerator. The element in the dictionary at the current position of the enumerator, as a . - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - + is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. + - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + ]]> @@ -397,19 +397,19 @@ Gets the key of the element at the current position of the enumerator. The key of the element in the dictionary at the current position of the enumerator. - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - + is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. + - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. -- The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. +- The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. + + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - ]]> @@ -469,19 +469,19 @@ Gets the value of the element at the current position of the enumerator. The value of the element in the dictionary at the current position of the enumerator. - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - + is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. + - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + ]]> @@ -541,20 +541,20 @@ Gets the element at the current position of the enumerator. The element in the collection at the current position of the enumerator, as an . - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - + is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. + - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + ]]> @@ -606,15 +606,15 @@ Sets the enumerator to its initial position, which is before the first element in the collection. - method, you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. - + method, you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding elements or changing the capacity, the enumerator is irrecoverably invalidated and the next call to or throws an . .NET Core 3.0+ only: The only mutating methods which do not invalidate enumerators are and . - + ]]> The collection was modified after the enumerator was created. diff --git a/xml/System.Collections.Generic/Dictionary`2+KeyCollection+Enumerator.xml b/xml/System.Collections.Generic/Dictionary`2+KeyCollection+Enumerator.xml index e10b839e4ff..c3aba8d3ffc 100644 --- a/xml/System.Collections.Generic/Dictionary`2+KeyCollection+Enumerator.xml +++ b/xml/System.Collections.Generic/Dictionary`2+KeyCollection+Enumerator.xml @@ -75,27 +75,27 @@ Enumerates the elements of a . - is undefined. You must call to advance the enumerator to the first element of the collection before reading the value of . - - returns the same object until is called. sets to the next element. - - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. - + is undefined. You must call to advance the enumerator to the first element of the collection before reading the value of . + + returns the same object until is called. sets to the next element. + + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding elements or changing the capacity, the enumerator is irrecoverably invalidated and the next call to or throws an . .NET Core 3.0+ only: The only mutating methods which do not invalidate enumerators are and . - - The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - Default implementations of collections in are not synchronized. - + + The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + Default implementations of collections in are not synchronized. + ]]> @@ -153,19 +153,19 @@ Gets the element at the current position of the enumerator. The element in the at the current position of the enumerator. - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - + is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. + - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + ]]> @@ -265,17 +265,17 @@ if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the collection. - advances the enumerator to the first element of the collection. - - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. - + advances the enumerator to the first element of the collection. + + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding elements or changing the capacity, the enumerator is irrecoverably invalidated and the next call to or throws an . .NET Core 3.0+ only: The only mutating methods which do not invalidate enumerators are and . - + ]]> The collection was modified after the enumerator was created. @@ -332,20 +332,20 @@ Gets the element at the current position of the enumerator. The element in the collection at the current position of the enumerator. - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - + is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. + - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + ]]> @@ -398,15 +398,15 @@ Sets the enumerator to its initial position, which is before the first element in the collection. - method, you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. - + method, you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding elements or changing the capacity, the enumerator is irrecoverably invalidated and the next call to or throws an . .NET Core 3.0+ only: The only mutating methods which do not invalidate enumerators are and . - + ]]> The collection was modified after the enumerator was created. diff --git a/xml/System.Collections.Generic/Dictionary`2+KeyCollection.xml b/xml/System.Collections.Generic/Dictionary`2+KeyCollection.xml index ae3ba09ec7b..ff56cafbeb4 100644 --- a/xml/System.Collections.Generic/Dictionary`2+KeyCollection.xml +++ b/xml/System.Collections.Generic/Dictionary`2+KeyCollection.xml @@ -354,7 +354,7 @@ Enumerates the elements of a . - is undefined. You must call to advance the enumerator to the first element of the collection before reading the value of . - - returns the same object until is called. sets to the next element. - - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. - - An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . - - The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - Default implementations of collections in are not synchronized. - + is undefined. You must call to advance the enumerator to the first element of the collection before reading the value of . + + returns the same object until is called. sets to the next element. + + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. + + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . + + The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + Default implementations of collections in are not synchronized. + ]]> @@ -151,20 +151,20 @@ Gets the element at the current position of the enumerator. The element in the at the current position of the enumerator. - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - + is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. + - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + ]]> @@ -261,15 +261,15 @@ if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the collection. - advances the enumerator to the first element of the collection. - - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. - - An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . - + advances the enumerator to the first element of the collection. + + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. + + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . + ]]> The collection was modified after the enumerator was created. @@ -326,20 +326,20 @@ Gets the element at the current position of the enumerator. The element in the collection at the current position of the enumerator. - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - + is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. + - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + ]]> @@ -392,13 +392,13 @@ Sets the enumerator to its initial position, which is before the first element in the collection. - method, you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. - - An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . - + method, you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. + + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . + ]]> The collection was modified after the enumerator was created. diff --git a/xml/System.Collections.Generic/Dictionary`2+ValueCollection.xml b/xml/System.Collections.Generic/Dictionary`2+ValueCollection.xml index a2320f792d1..1caa8a7c33d 100644 --- a/xml/System.Collections.Generic/Dictionary`2+ValueCollection.xml +++ b/xml/System.Collections.Generic/Dictionary`2+ValueCollection.xml @@ -328,7 +328,7 @@ structure representing a value and its key. The order in which the items are returned is undefined. - The `foreach` statement of the C# language (`for each` in C++, `For Each` in Visual Basic) returns an object of the type of the elements in the collection. Since the is a collection of keys and values, the element type is not the type of the key or the type of the value. Instead, the element type is a of the key type and the value type. For example: + The `foreach` statement of the C# language (`For Each` in Visual Basic) returns an object of the type of the elements in the collection. Since the is a collection of keys and values, the element type is not the type of the key or the type of the value. Instead, the element type is a of the key type and the value type. For example: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Generic.Dictionary/cpp/source2.cpp" id="Snippet11"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/Overview/source2.cs" id="Snippet11"::: @@ -1375,7 +1375,7 @@ ## Remarks For purposes of enumeration, each item is a structure representing a value and its key. - The `foreach` statement of the C# language (`for each` in C++, `For Each` in Visual Basic) hides the complexity of enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. + The `foreach` statement of the C# language (`For Each` in Visual Basic) hides the complexity of enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. @@ -2725,7 +2725,7 @@ Getting the value of this property is an O(1) operation. ## Remarks For purposes of enumeration, each item is a structure. - The `foreach` statement of the C# language (`for each` in C++, `For Each` in Visual Basic) hides the complexity of enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. + The `foreach` statement of the C# language (`For Each` in Visual Basic) hides the complexity of enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. @@ -2748,7 +2748,7 @@ Getting the value of this property is an O(1) operation. ## Examples - The following code example shows how to enumerate the key/value pairs in the dictionary by using the `foreach` statement (`For Each` in Visual Basic, `for each` in C++), which hides the use of the enumerator. In particular, note that the enumerator for the interface returns objects rather than objects. + The following code example shows how to enumerate the key/value pairs in the dictionary by using the `foreach` statement (`For Each` in Visual Basic), which hides the use of the enumerator. In particular, note that the enumerator for the interface returns objects rather than objects. The code example is part of a larger example, including output, provided for the method. @@ -3246,7 +3246,7 @@ Getting the value of this property is an O(1) operation. ## Remarks - The `foreach` statement of the C# language (`for each` in C++, `For Each` in Visual Basic) hides the complexity of enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. + The `foreach` statement of the C# language (`For Each` in Visual Basic) hides the complexity of enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. diff --git a/xml/System.Collections.Generic/HashSet`1+Enumerator.xml b/xml/System.Collections.Generic/HashSet`1+Enumerator.xml index 584c7cd03f8..50aef05e827 100644 --- a/xml/System.Collections.Generic/HashSet`1+Enumerator.xml +++ b/xml/System.Collections.Generic/HashSet`1+Enumerator.xml @@ -74,25 +74,25 @@ Enumerates the elements of a object. - property is undefined. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . - - returns the same object until is called. sets to the next element. - - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator object instead. - - An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . - - The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - Default implementations of collections in the namespace are not synchronized. - + property is undefined. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . + + returns the same object until is called. sets to the next element. + + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator object instead. + + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . + + The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + Default implementations of collections in the namespace are not synchronized. + ]]> @@ -150,20 +150,20 @@ Gets the element at the current position of the enumerator. The element in the collection at the current position of the enumerator. - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - + is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. + - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + ]]> @@ -258,15 +258,15 @@ if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the collection. - method advances the enumerator to the first element of the collection. - - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. - - An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . - + method advances the enumerator to the first element of the collection. + + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. + + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . + ]]> The collection was modified after the enumerator was created. @@ -322,20 +322,20 @@ Gets the element at the current position of the enumerator. The element in the collection at the current position of the enumerator, as an . - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - + is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. + - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + ]]> The enumerator is positioned before the first element of the collection or after the last element. @@ -384,13 +384,13 @@ Sets the enumerator to its initial position, which is before the first element in the collection. - , you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. - - An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . - + , you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. + + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . + ]]> The collection was modified after the enumerator was created. diff --git a/xml/System.Collections.Generic/HashSet`1.xml b/xml/System.Collections.Generic/HashSet`1.xml index 8469914c693..071ce0e7d05 100644 --- a/xml/System.Collections.Generic/HashSet`1.xml +++ b/xml/System.Collections.Generic/HashSet`1.xml @@ -1376,7 +1376,7 @@ The following example demonstrates how to merge two disparate sets. This example interface allows the contained keys and values to be enumerated, but it does not imply any particular sort order. - The `foreach` statement of the C# language (`For Each` in Visual Basic, `for each` in C++) returns an object of the type of the elements in the collection. Since each element of the is a key/value pair, the element type is not the type of the key or the type of the value. Instead, the element type is . For example: + The `foreach` statement of the C# language (`For Each` in Visual Basic) returns an object of the type of the elements in the collection. Since each element of the is a key/value pair, the element type is not the type of the key or the type of the value. Instead, the element type is . For example: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source2.cpp" id="Snippet11"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/IDictionaryTKey,TValue/Overview/source2.cs" id="Snippet11"::: diff --git a/xml/System.Collections.Generic/IEnumerator`1.xml b/xml/System.Collections.Generic/IEnumerator`1.xml index 5d1f909a8f3..0100545dbef 100644 --- a/xml/System.Collections.Generic/IEnumerator`1.xml +++ b/xml/System.Collections.Generic/IEnumerator`1.xml @@ -73,42 +73,42 @@ The type of objects to enumerate. Supports a simple iteration over a generic collection. - is the base interface for all generic enumerators. - - The `foreach` statement of the C# language (`for each` in C++, `For Each` in Visual Basic) hides the complexity of the enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. - - Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. - - Initially, the enumerator is positioned before the first element in the collection. At this position, is undefined. Therefore, you must call to advance the enumerator to the first element of the collection before reading the value of . - - returns the same object until is called. sets to the next element. - - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. - - The method is provided for COM interoperability. It does not necessarily need to be implemented; instead, the implementer can simply throw a . However, if you choose to do this, you should make sure no callers are relying on the functionality. - - If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. - - The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - Default implementations of collections in the namespace are not synchronized. - - - -## Examples - The following example shows an implementation of the interface for a collection class of custom objects. The custom object is an instance of the type `Box`, and the collection class is `BoxCollection`. This code example is part of a larger example provided for the interface. - + is the base interface for all generic enumerators. + + The `foreach` statement of the C# language (`For Each` in Visual Basic) hides the complexity of the enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. + + Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. + + Initially, the enumerator is positioned before the first element in the collection. At this position, is undefined. Therefore, you must call to advance the enumerator to the first element of the collection before reading the value of . + + returns the same object until is called. sets to the next element. + + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. + + The method is provided for COM interoperability. It does not necessarily need to be implemented; instead, the implementer can simply throw a . However, if you choose to do this, you should make sure no callers are relying on the functionality. + + If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. + + The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + Default implementations of collections in the namespace are not synchronized. + + + +## Examples + The following example shows an implementation of the interface for a collection class of custom objects. The custom object is an instance of the type `Box`, and the collection class is `BoxCollection`. This code example is part of a larger example provided for the interface. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ICollectionT/Overview/program.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.boxexamples/vb/program.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.boxexamples/vb/program.vb" id="Snippet3"::: + ]]> - Implementing this interface requires implementing the nongeneric interface. The and methods do not depend on , and appear only on the nongeneric interface. The property appears on both interfaces, and has different return types. Implement the nongeneric property as an explicit interface implementation. This allows any consumer of the nongeneric interface to consume the generic interface. - + Implementing this interface requires implementing the nongeneric interface. The and methods do not depend on , and appear only on the nongeneric interface. The property appears on both interfaces, and has different return types. Implement the nongeneric property as an explicit interface implementation. This allows any consumer of the nongeneric interface to consume the generic interface. + In addition, implements , which requires you to implement the method. This enables you to close database connections or release file handles or similar operations when using other resources. If there are no additional resources to dispose of, provide an empty implementation. @@ -164,19 +164,19 @@ Gets the element in the collection at the current position of the enumerator. The element in the collection at the current position of the enumerator. - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element in the collection, immediately after the enumerator is created. must be called to advance the enumerator to the first element of the collection before reading the value of . - -- The last call to returned `false`, which indicates the end of the collection. - -- The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - - returns the same object until is called. sets to the next element. - + is undefined under any of the following conditions: + +- The enumerator is positioned before the first element in the collection, immediately after the enumerator is created. must be called to advance the enumerator to the first element of the collection before reading the value of . + +- The last call to returned `false`, which indicates the end of the collection. + +- The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. + + returns the same object until is called. sets to the next element. + ]]> diff --git a/xml/System.Collections.Generic/IReadOnlyDictionary`2.xml b/xml/System.Collections.Generic/IReadOnlyDictionary`2.xml index f14e3c80ebc..88399f287f9 100644 --- a/xml/System.Collections.Generic/IReadOnlyDictionary`2.xml +++ b/xml/System.Collections.Generic/IReadOnlyDictionary`2.xml @@ -80,21 +80,21 @@ The type of values in the read-only dictionary. Represents a generic read-only collection of key/value pairs. - object. - - Each pair must have a unique key. Implementations can vary in whether they allow you to specify a key that is `null`. The value can be `null` and does not have to be unique. The interface allows the contained keys and values to be enumerated, but it does not imply any particular sort order. - - The `foreach` statement of the C# language (`For Each` in Visual Basic, `for each` in C++) requires the type of each element in the collection. Because each element of the interface is a key/value pair, the element type is not the type of the key or the type of the value. Instead, the element type is , as the following example illustrates. - + object. + + Each pair must have a unique key. Implementations can vary in whether they allow you to specify a key that is `null`. The value can be `null` and does not have to be unique. The interface allows the contained keys and values to be enumerated, but it does not imply any particular sort order. + + The `foreach` statement of the C# language (`For Each` in Visual Basic) requires the type of each element in the collection. Because each element of the interface is a key/value pair, the element type is not the type of the key or the type of the value. Instead, the element type is , as the following example illustrates. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source2.cpp" id="Snippet11"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/IDictionaryTKey,TValue/Overview/source2.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source2.vb" id="Snippet11"::: - - The `foreach` statement is a wrapper around the enumerator; it allows only reading from the collection, not writing to the collection. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.IDictionary/VB/source2.vb" id="Snippet11"::: + + The `foreach` statement is a wrapper around the enumerator; it allows only reading from the collection, not writing to the collection. + ]]> @@ -145,13 +145,13 @@ if the read-only dictionary contains an element that has the specified key; otherwise, . - might use the property, or it might implement the method. - - Implementations can vary in whether they allow `key` to be `null`. - + might use the property, or it might implement the method. + + Implementations can vary in whether they allow `key` to be `null`. + ]]> @@ -203,15 +203,15 @@ Gets the element that has the specified key in the read-only dictionary. The element that has the specified key in the read-only dictionary. - might use the property, or it might implement the method. - - Implementations can vary in whether they allow `key` to be `null`. - + might use the property, or it might implement the method. + + Implementations can vary in whether they allow `key` to be `null`. + ]]> @@ -260,11 +260,11 @@ Gets an enumerable collection that contains the keys in the read-only dictionary. An enumerable collection that contains the keys in the read-only dictionary. - property. - + property. + ]]> @@ -324,13 +324,13 @@ if the object that implements the interface contains an element that has the specified key; otherwise, . - method and the property. - - If the key is not found, the `value` parameter gets the appropriate default value for the type `TValue`: for example, 0 (zero) for integer types, `false` for Boolean types, and `null` for reference types. - + method and the property. + + If the key is not found, the `value` parameter gets the appropriate default value for the type `TValue`: for example, 0 (zero) for integer types, `false` for Boolean types, and `null` for reference types. + ]]> @@ -378,11 +378,11 @@ Gets an enumerable collection that contains the values in the read-only dictionary. An enumerable collection that contains the values in the read-only dictionary. - property. - + property. + ]]> diff --git a/xml/System.Collections.Generic/KeyValuePair`2.xml b/xml/System.Collections.Generic/KeyValuePair`2.xml index 97a71140628..551be8a1551 100644 --- a/xml/System.Collections.Generic/KeyValuePair`2.xml +++ b/xml/System.Collections.Generic/KeyValuePair`2.xml @@ -85,30 +85,30 @@ The type of the value. Defines a key/value pair that can be set or retrieved. - property returns an instance of this type. - - The `foreach` statement of the C# language (`for each` in C++, `For Each` in Visual Basic) returns an object of the type of the elements in the collection. Since each element of a collection based on is a key/value pair, the element type is not the type of the key or the type of the value. Instead, the element type is . For example: - + property returns an instance of this type. + + The `foreach` statement of the C# language (`For Each` in Visual Basic) returns an object of the type of the elements in the collection. Since each element of a collection based on is a key/value pair, the element type is not the type of the key or the type of the value. Instead, the element type is . For example: + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Generic.Dictionary/cpp/source2.cpp" id="Snippet11"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/Overview/source2.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source2.vb" id="Snippet11"::: - - The `foreach` statement is a wrapper around the enumerator, which allows only reading from, not writing to, the collection. - - - -## Examples - The following code example shows how to enumerate the keys and values in a dictionary, using the structure. - - This code is part of a larger example provided for the class. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source2.vb" id="Snippet11"::: + + The `foreach` statement is a wrapper around the enumerator, which allows only reading from, not writing to, the collection. + + + +## Examples + The following code example shows how to enumerate the keys and values in a dictionary, using the structure. + + This code is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Generic.Dictionary/cpp/source.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/Overview/source.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet7"::: + ]]> @@ -251,22 +251,22 @@ Gets the key in the key/value pair. A that is the key of the . - structure. - - This code is part of a larger example provided for the class. - + structure. + + This code is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Generic.Dictionary/cpp/source.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/Overview/source.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet7"::: + ]]> @@ -314,14 +314,14 @@ Returns a string representation of the , using the string representations of the key and value. A string representation of the , which includes the string representations of the key and value. - method for a structure with the string "Test" and the integer 14 returns the string "[Test, 14]". - + method for a structure with the string "Test" and the integer 14 returns the string "[Test, 14]". + > [!NOTE] -> This method uses the `ToString` methods provided by the key and value types. Some types do not return useful or informative values for their `ToString` methods. - +> This method uses the `ToString` methods provided by the key and value types. Some types do not return useful or informative values for their `ToString` methods. + ]]> @@ -368,22 +368,22 @@ Gets the value in the key/value pair. A that is the value of the . - structure. - - This code is part of a larger example provided for the class. - + structure. + + This code is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Generic.Dictionary/cpp/source.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/Overview/source.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet7"::: + ]]> diff --git a/xml/System.Collections.Generic/LinkedList`1+Enumerator.xml b/xml/System.Collections.Generic/LinkedList`1+Enumerator.xml index 632f1b3d7cc..9511e68aa72 100644 --- a/xml/System.Collections.Generic/LinkedList`1+Enumerator.xml +++ b/xml/System.Collections.Generic/LinkedList`1+Enumerator.xml @@ -88,7 +88,7 @@ Enumerates the elements of a . - is undefined. Therefore, you must call to advance the enumerator to the first element of the collection before reading the value of . - - returns the same object until is called. sets to the next element. - - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. - - An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . - - The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - Default implementations of collections in are not synchronized. - + is undefined. Therefore, you must call to advance the enumerator to the first element of the collection before reading the value of . + + returns the same object until is called. sets to the next element. + + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. + + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . + + The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + Default implementations of collections in are not synchronized. + ]]> @@ -148,19 +148,19 @@ Gets the element at the current position of the enumerator. The element in the at the current position of the enumerator. - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - + is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. + - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + ]]> @@ -263,15 +263,15 @@ if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the collection. - advances the enumerator to the first element of the collection. - - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. - - An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to throws an . - + advances the enumerator to the first element of the collection. + + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. + + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to throws an . + ]]> The collection was modified after the enumerator was created. @@ -328,19 +328,19 @@ Gets the element at the current position of the enumerator. The element in the at the current position of the enumerator. - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - + is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. + - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + ]]> @@ -392,13 +392,13 @@ Sets the enumerator to its initial position, which is before the first element in the collection. - , you must call to advance the enumerator to the first element of the collection before reading the value of . - + , you must call to advance the enumerator to the first element of the collection before reading the value of . + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to throws an . - + ]]> The collection was modified after the enumerator was created. diff --git a/xml/System.Collections.Generic/List`1.xml b/xml/System.Collections.Generic/List`1.xml index 3f9844a76ff..be53559f1f0 100644 --- a/xml/System.Collections.Generic/List`1.xml +++ b/xml/System.Collections.Generic/List`1.xml @@ -616,7 +616,7 @@ ## Examples The following example demonstrates the method overload and the method overload. A of strings is created and populated with four strings, in no particular order. The list is displayed, sorted, and displayed again. - The method overload is then used to search for two strings that are not in the list, and the method is used to insert them. The return value of the method is negative in each case, because the strings are not in the list. Taking the bitwise complement (the ~ operator in C# and Visual C++, `Xor` -1 in Visual Basic) of this negative number produces the index of the first element in the list that is larger than the search string, and inserting at this location preserves the sort order. The second search string is larger than any element in the list, so the insertion position is at the end of the list. + The method overload is then used to search for two strings that are not in the list, and the method is used to insert them. The return value of the method is negative in each case, because the strings are not in the list. Taking the bitwise complement (the ~ operator in C#, `Xor` -1 in Visual Basic) of this negative number produces the index of the first element in the list that is larger than the search string, and inserting at this location preserves the sort order. The second search string is larger than any element in the list, so the insertion position is at the end of the list. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_SortSearch/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/BinarySearch/source.cs" interactive="try-dotnet-method" id="Snippet1"::: @@ -708,11 +708,11 @@ ## Examples The following example demonstrates the method overload and the method overload. - The example defines an alternative comparer for strings named DinoCompare, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic, `IComparer` in Visual C++) generic interface. The comparer works as follows: First, the comparands are tested for `null`, and a null reference is treated as less than a non-null. Second, the string lengths are compared, and the longer string is deemed to be greater. Third, if the lengths are equal, ordinary string comparison is used. + The example defines an alternative comparer for strings named DinoCompare, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic) generic interface. The comparer works as follows: First, the comparands are tested for `null`, and a null reference is treated as less than a non-null. Second, the string lengths are compared, and the longer string is deemed to be greater. Third, if the lengths are equal, ordinary string comparison is used. A of strings is created and populated with four strings, in no particular order. The list is displayed, sorted using the alternate comparer, and displayed again. - The method overload is then used to search for several strings that are not in the list, employing the alternate comparer. The method is used to insert the strings. These two methods are located in the function named `SearchAndInsert`, along with code to take the bitwise complement (the ~ operator in C# and Visual C++, `Xor` -1 in Visual Basic) of the negative number returned by and use it as an index for inserting the new string. + The method overload is then used to search for several strings that are not in the list, employing the alternate comparer. The method is used to insert the strings. These two methods are located in the function named `SearchAndInsert`, along with code to take the bitwise complement (the ~ operator in C#, `Xor` -1 in Visual Basic) of the negative number returned by and use it as an index for inserting the new string. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_SortSearchComparer/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/BinarySearch/source1.cs" interactive="try-dotnet" id="Snippet1"::: @@ -805,11 +805,11 @@ ## Examples The following example demonstrates the method overload and the method overload. - The example defines an alternative comparer for strings named DinoCompare, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic, `IComparer` in Visual C++) generic interface. The comparer works as follows: First, the comparands are tested for `null`, and a null reference is treated as less than a non-null. Second, the string lengths are compared, and the longer string is deemed to be greater. Third, if the lengths are equal, ordinary string comparison is used. + The example defines an alternative comparer for strings named DinoCompare, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic) generic interface. The comparer works as follows: First, the comparands are tested for `null`, and a null reference is treated as less than a non-null. Second, the string lengths are compared, and the longer string is deemed to be greater. Third, if the lengths are equal, ordinary string comparison is used. A of strings is created and populated with the names of five herbivorous dinosaurs and three carnivorous dinosaurs. Within each of the two groups, the names are not in any particular sort order. The list is displayed, the range of herbivores is sorted using the alternate comparer, and the list is displayed again. - The method overload is then used to search only the range of herbivores for "Brachiosaurus". The string is not found, and the bitwise complement (the ~ operator in C# and Visual C++, `Xor` -1 in Visual Basic) of the negative number returned by the method is used as an index for inserting the new string. + The method overload is then used to search only the range of herbivores for "Brachiosaurus". The string is not found, and the bitwise complement (the ~ operator in C#, `Xor` -1 in Visual Basic) of the negative number returned by the method is used as an index for inserting the new string. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_SortSearchComparerRange/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/BinarySearch/source2.cs" interactive="try-dotnet" id="Snippet1"::: @@ -1540,7 +1540,7 @@ Finally, the method is called. It traverses the list from the beginning, passing each element in turn to the `EndsWithSaurus` method. The search stops and the method returns `true` if the `EndsWithSaurus` method returns `true` for any element. The method returns `false` because all such elements have been removed. > [!NOTE] -> In C# and Visual Basic, it is not necessary to create the `Predicate` delegate (`Predicate(Of String)` in Visual Basic) explicitly. These languages infer the correct delegate from context and create it automatically. +> In C# and Visual Basic, it is not necessary to create the `Predicate` delegate (`Predicate(Of String)` in Visual Basic) explicitly. These languages infer the correct delegate from context and create it automatically. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_FindEtAl/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Exists/source.cs" interactive="try-dotnet" id="Snippet1"::: @@ -1613,7 +1613,7 @@ The is a delegate to a method that returns `true` if the object passed to it matches the conditions defined in the delegate. The elements of the current are individually passed to the delegate, moving forward in the , starting with the first element and ending with the last element. Processing is stopped when a match is found. > [!IMPORTANT] -> When searching a list containing value types, make sure the default value for the type does not satisfy the search predicate. Otherwise, there is no way to distinguish between a default value indicating that no match was found and a list element that happens to have the default value for the type. If the default value satisfies the search predicate, use the method instead. +> When searching a list containing value types, make sure the default value for the type does not satisfy the search predicate. Otherwise, there is no way to distinguish between a default value indicating that no match was found and a list element that happens to have the default value for the type. If the default value satisfies the search predicate, use the method instead. This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . @@ -2095,7 +2095,7 @@ Public Function StartsWith(e As Employee) As Boolean The is a delegate to a method that returns `true` if the object passed to it matches the conditions defined in the delegate. The elements of the current are individually passed to the delegate, moving backward in the , starting with the last element and ending with the first element. Processing is stopped when a match is found. > [!IMPORTANT] -> When searching a list containing value types, make sure the default value for the type does not satisfy the search predicate. Otherwise, there is no way to distinguish between a default value indicating that no match was found and a list element that happens to have the default value for the type. If the default value satisfies the search predicate, use the method instead. +> When searching a list containing value types, make sure the default value for the type does not satisfy the search predicate. Otherwise, there is no way to distinguish between a default value indicating that no match was found and a list element that happens to have the default value for the type. If the default value satisfies the search predicate, use the method instead. This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . @@ -2456,7 +2456,7 @@ Public Function StartsWith(e As Employee) As Boolean The following example demonstrates the use of the delegate to print the contents of a object. In this example the `Print` method is used to display the contents of the list to the console. > [!NOTE] -> In addition to displaying the contents using the `Print` method, the C# example demonstrates the use of [anonymous methods](/dotnet/csharp/programming-guide/statements-expressions-operators/anonymous-methods) to display the results to the console. +> In addition to displaying the contents using the `Print` method, the C# example demonstrates the use of [anonymous methods](/dotnet/csharp/programming-guide/statements-expressions-operators/anonymous-methods) to display the results to the console. :::code language="csharp" source="~/snippets/csharp/System/ActionT/Overview/action.cs" interactive="try-dotnet-method" id="Snippet01"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Action_PrintExample/vb/action.vb" id="Snippet01"::: @@ -2519,7 +2519,7 @@ Public Function StartsWith(e As Employee) As Boolean property (the indexer in C#) and various other properties and methods of the generic class. After the list has been created and populated using the method, an element is retrieved and displayed using the property. (For an example that uses the property to set the value of a list element, see .) > [!NOTE] -> Visual Basic, C#, and C++ all have syntax for accessing the property without using its name. Instead, the variable containing the is used as if it were an array. +> Visual Basic, C#, and C++ all have syntax for accessing the property without using its name. Instead, the variable containing the is used as if it were an array. The C# language uses the [`this`](/dotnet/csharp/language-reference/keywords/this) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. @@ -3477,7 +3477,7 @@ Public Function StartsWith(e As Employee) As Boolean The method is used to remove all entries ending with "saurus". It traverses the list from the beginning, passing each element in turn to the `EndsWithSaurus` method. The element is removed if the `EndsWithSaurus` method returns `true`. > [!NOTE] -> In C# and Visual Basic, it is not necessary to create the `Predicate` delegate (`Predicate(Of String)` in Visual Basic) explicitly. These languages infer the correct delegate from context, and create it automatically. +> In C# and Visual Basic, it is not necessary to create the `Predicate` delegate (`Predicate(Of String)` in Visual Basic) explicitly. These languages infer the correct delegate from context, and create it automatically. Finally, the method verifies that there are no strings in the list that end with "saurus". @@ -3909,7 +3909,7 @@ Public Function StartsWith(e As Employee) As Boolean The following example demonstrates the method overload and the method overload. A of strings is created and populated with four strings, in no particular order. The list is displayed, sorted, and displayed again. - The method overload is then used to search for two strings that are not in the list, and the method is used to insert them. The return value of the method is negative in each case, because the strings are not in the list. Taking the bitwise complement (the ~ operator in C# and Visual C++, `Xor` -1 in Visual Basic) of this negative number produces the index of the first element in the list that is larger than the search string, and inserting at this location preserves the sort order. The second search string is larger than any element in the list, so the insertion position is at the end of the list. + The method overload is then used to search for two strings that are not in the list, and the method is used to insert them. The return value of the method is negative in each case, because the strings are not in the list. Taking the bitwise complement (the ~ operator in C#, `Xor` -1 in Visual Basic) of this negative number produces the index of the first element in the list that is larger than the search string, and inserting at this location preserves the sort order. The second search string is larger than any element in the list, so the insertion position is at the end of the list. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_SortSearch/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/BinarySearch/source.cs" interactive="try-dotnet-method" id="Snippet1"::: @@ -3994,11 +3994,11 @@ Public Function StartsWith(e As Employee) As Boolean ## Examples The following example demonstrates the method overload and the method overload. - The example defines an alternative comparer for strings named DinoCompare, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic, `IComparer` in Visual C++) generic interface. The comparer works as follows: First, the comparands are tested for `null`, and a null reference is treated as less than a non-null. Second, the string lengths are compared, and the longer string is deemed to be greater. Third, if the lengths are equal, ordinary string comparison is used. + The example defines an alternative comparer for strings named DinoCompare, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic) generic interface. The comparer works as follows: First, the comparands are tested for `null`, and a null reference is treated as less than a non-null. Second, the string lengths are compared, and the longer string is deemed to be greater. Third, if the lengths are equal, ordinary string comparison is used. A of strings is created and populated with four strings, in no particular order. The list is displayed, sorted using the alternate comparer, and displayed again. - The method overload is then used to search for several strings that are not in the list, employing the alternate comparer. The method is used to insert the strings. These two methods are located in the function named `SearchAndInsert`, along with code to take the bitwise complement (the ~ operator in C# and Visual C++, `Xor` -1 in Visual Basic) of the negative number returned by and use it as an index for inserting the new string. + The method overload is then used to search for several strings that are not in the list, employing the alternate comparer. The method is used to insert the strings. These two methods are located in the function named `SearchAndInsert`, along with code to take the bitwise complement (the ~ operator in C#, `Xor` -1 in Visual Basic) of the negative number returned by and use it as an index for inserting the new string. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_SortSearchComparer/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/BinarySearch/source1.cs" interactive="try-dotnet" id="Snippet1"::: @@ -4176,11 +4176,11 @@ Public Function StartsWith(e As Employee) As Boolean ## Examples The following example demonstrates the method overload and the method overload. - The example defines an alternative comparer for strings named DinoCompare, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic, `IComparer` in Visual C++) generic interface. The comparer works as follows: First, the comparands are tested for `null`, and a null reference is treated as less than a non-null. Second, the string lengths are compared, and the longer string is deemed to be greater. Third, if the lengths are equal, ordinary string comparison is used. + The example defines an alternative comparer for strings named DinoCompare, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic) generic interface. The comparer works as follows: First, the comparands are tested for `null`, and a null reference is treated as less than a non-null. Second, the string lengths are compared, and the longer string is deemed to be greater. Third, if the lengths are equal, ordinary string comparison is used. A of strings is created and populated with the names of five herbivorous dinosaurs and three carnivorous dinosaurs. Within each of the two groups, the names are not in any particular sort order. The list is displayed, the range of herbivores is sorted using the alternate comparer, and the list is displayed again. - The method overload is then used to search only the range of herbivores for "Brachiosaurus". The string is not found, and the bitwise complement (the ~ operator in C# and Visual C++, `Xor` -1 in Visual Basic) of the negative number returned by the method is used as an index for inserting the new string. + The method overload is then used to search only the range of herbivores for "Brachiosaurus". The string is not found, and the bitwise complement (the ~ operator in C#, `Xor` -1 in Visual Basic) of the negative number returned by the method is used as an index for inserting the new string. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_SortSearchComparerRange/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/BinarySearch/source2.cs" interactive="try-dotnet" id="Snippet1"::: @@ -4321,7 +4321,7 @@ Public Function StartsWith(e As Employee) As Boolean [!NOTE] -> If the type of the source cannot be cast automatically to the type of the destination `array`, the nongeneric implementations of throw , whereas the generic implementations throw . +> If the type of the source cannot be cast automatically to the type of the destination `array`, the nongeneric implementations of throw , whereas the generic implementations throw . This method is an O(*n*) operation, where *n* is . @@ -4616,7 +4616,7 @@ Retrieving the value of this property is an O(1) operation. can be considerable, however, so the method does nothing if the list is at more than 90 percent of capacity. This avoids incurring a large reallocation cost for a relatively small gain. > [!NOTE] -> The current threshold of 90 percent might change in future releases. +> The current threshold of 90 percent might change in future releases. This method is an O(*n*) operation, where *n* is . @@ -5342,7 +5342,7 @@ Retrieving the value of this property is an O(1) operation. The method traverses the list from the beginning, passing each element in turn to the `EndsWithSaurus` method. The search stops when the `EndsWithSaurus` method returns `false`. > [!NOTE] -> In C# and Visual Basic, it is not necessary to create the `Predicate` delegate (`Predicate(Of String)` in Visual Basic) explicitly. These languages infer the correct delegate from context and create it automatically. +> In C# and Visual Basic, it is not necessary to create the `Predicate` delegate (`Predicate(Of String)` in Visual Basic) explicitly. These languages infer the correct delegate from context and create it automatically. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_FindEtAl/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Exists/source.cs" interactive="try-dotnet" id="Snippet1"::: diff --git a/xml/System.Collections.Generic/Queue`1+Enumerator.xml b/xml/System.Collections.Generic/Queue`1+Enumerator.xml index e92d0e11b50..0f510331fc2 100644 --- a/xml/System.Collections.Generic/Queue`1+Enumerator.xml +++ b/xml/System.Collections.Generic/Queue`1+Enumerator.xml @@ -74,25 +74,25 @@ Enumerates the elements of a . - is undefined. Therefore, you must call to advance the enumerator to the first element of the collection before reading the value of . - - returns the same object until is called. sets to the next element. - - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. - - An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . - - The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - Default implementations of collections in are not synchronized. - + is undefined. Therefore, you must call to advance the enumerator to the first element of the collection before reading the value of . + + returns the same object until is called. sets to the next element. + + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. + + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . + + The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + Default implementations of collections in are not synchronized. + ]]> @@ -148,19 +148,19 @@ Gets the element at the current position of the enumerator. The element in the at the current position of the enumerator. - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - + is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. + - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + ]]> @@ -258,15 +258,15 @@ if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the collection. - advances the enumerator to the first element of the collection. - - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. - - An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . - + advances the enumerator to the first element of the collection. + + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. + + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . + ]]> The collection was modified after the enumerator was created. @@ -323,20 +323,20 @@ Gets the element at the current position of the enumerator. The element in the collection at the current position of the enumerator. - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - + is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. + - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + ]]> @@ -387,11 +387,11 @@ Sets the enumerator to its initial position, which is before the first element in the collection. - or throws an . - + or throws an . + ]]> The collection was modified after the enumerator was created. diff --git a/xml/System.Collections.Generic/Queue`1.xml b/xml/System.Collections.Generic/Queue`1.xml index 34d8f3a551f..8cdbaae207d 100644 --- a/xml/System.Collections.Generic/Queue`1.xml +++ b/xml/System.Collections.Generic/Queue`1.xml @@ -876,7 +876,7 @@ generic class is enumerable. The `foreach` statement (`For Each` in Visual Basic, `for each` in C++) is used to enumerate the queue. + The following code example demonstrates that the generic class is enumerable. The `foreach` statement (`For Each` in Visual Basic) is used to enumerate the queue. The code example creates a queue of strings with default capacity and uses the method to queue five strings. The elements of the queue are enumerated, which does not change the state of the queue. The method is used to dequeue the first string. The method is used to look at the next item in the queue, and then the method is used to dequeue it. @@ -1038,7 +1038,7 @@ Enumerates the elements of a . - is undefined. You must call the method to advance the enumerator to the first element of the collection before reading the value of . - - The property returns the same object until is called. sets to the next element. - - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. - - An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . - - The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - Default implementations of collections in the namespace are not synchronized. - + is undefined. You must call the method to advance the enumerator to the first element of the collection before reading the value of . + + The property returns the same object until is called. sets to the next element. + + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. + + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . + + The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + Default implementations of collections in the namespace are not synchronized. + ]]> @@ -149,19 +149,19 @@ Gets the element at the current position of the enumerator. The element in the at the current position of the enumerator. - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - + is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. + - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + ]]> @@ -257,15 +257,15 @@ if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the collection. - method advances the enumerator to the first element of the collection. - - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. - - An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . - + method advances the enumerator to the first element of the collection. + + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. + + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . + ]]> The collection was modified after the enumerator was created. @@ -315,20 +315,20 @@ Gets the element at the current position of the enumerator as a structure. The element in the collection at the current position of the dictionary, as a structure. - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - + is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. + - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + ]]> @@ -387,19 +387,19 @@ Gets the key of the element at the current position of the enumerator. The key of the element in the collection at the current position of the enumerator. - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - + is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. + - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + ]]> @@ -459,19 +459,19 @@ Gets the value of the element at the current position of the enumerator. The value of the element in the collection at the current position of the enumerator. - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - + is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. + - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + ]]> @@ -531,20 +531,20 @@ Gets the element at the current position of the enumerator. The element in the collection at the current position of the enumerator. - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - + is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. + - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + ]]> @@ -597,13 +597,13 @@ Sets the enumerator to its initial position, which is before the first element in the collection. - method, you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. - - An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . - + method, you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. + + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . + ]]> The collection was modified after the enumerator was created. diff --git a/xml/System.Collections.Generic/SortedDictionary`2+KeyCollection+Enumerator.xml b/xml/System.Collections.Generic/SortedDictionary`2+KeyCollection+Enumerator.xml index 758cf962511..fbd67c6b6ea 100644 --- a/xml/System.Collections.Generic/SortedDictionary`2+KeyCollection+Enumerator.xml +++ b/xml/System.Collections.Generic/SortedDictionary`2+KeyCollection+Enumerator.xml @@ -68,25 +68,25 @@ Enumerates the elements of a . - is undefined. You must call the method to advance the enumerator to the first element of the collection before reading the value of . - - The property returns the same object until is called. sets to the next element. - - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. - - An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . - - The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - Default implementations of collections in the namespace are not synchronized. - + is undefined. You must call the method to advance the enumerator to the first element of the collection before reading the value of . + + The property returns the same object until is called. sets to the next element. + + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. + + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . + + The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + Default implementations of collections in the namespace are not synchronized. + ]]> @@ -144,20 +144,20 @@ Gets the element at the current position of the enumerator. The element in the at the current position of the enumerator. - is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + ]]> @@ -254,15 +254,15 @@ if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the collection. - method advances the enumerator to the first element of the collection. - - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. - - An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . - + method advances the enumerator to the first element of the collection. + + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. + + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . + ]]> The collection was modified after the enumerator was created. @@ -319,20 +319,20 @@ Gets the element at the current position of the enumerator. The element in the collection at the current position of the enumerator. - is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. -- The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. +- The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. + + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - ]]> @@ -385,13 +385,13 @@ Sets the enumerator to its initial position, which is before the first element in the collection. - method, you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. - - An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . - + method, you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. + + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . + ]]> The collection was modified after the enumerator was created. diff --git a/xml/System.Collections.Generic/SortedDictionary`2+KeyCollection.xml b/xml/System.Collections.Generic/SortedDictionary`2+KeyCollection.xml index 8dfbf93404a..dbde7237165 100644 --- a/xml/System.Collections.Generic/SortedDictionary`2+KeyCollection.xml +++ b/xml/System.Collections.Generic/SortedDictionary`2+KeyCollection.xml @@ -359,7 +359,7 @@ Enumerates the elements of a . - interface. - - Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. - - Initially, the enumerator is positioned before the first element in the collection. At this position, is undefined. You must call the method to advance the enumerator to the first element of the collection before reading the value of . - - The property returns the same object until is called. sets to the next element. - - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. - - An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . - - The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - Default implementations of collections in the namespace are not synchronized. - + interface. + + Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. + + Initially, the enumerator is positioned before the first element in the collection. At this position, is undefined. You must call the method to advance the enumerator to the first element of the collection before reading the value of . + + The property returns the same object until is called. sets to the next element. + + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. + + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . + + The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + Default implementations of collections in the namespace are not synchronized. + ]]> @@ -144,20 +144,20 @@ Gets the element at the current position of the enumerator. The element in the at the current position of the enumerator. - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - + is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. + - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + ]]> @@ -254,15 +254,15 @@ if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the collection. - method advances the enumerator to the first element of the collection. - - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. - - An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . - + method advances the enumerator to the first element of the collection. + + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. + + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . + ]]> The collection was modified after the enumerator was created. @@ -319,20 +319,20 @@ Gets the element at the current position of the enumerator. The element in the collection at the current position of the enumerator. - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - + is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. + - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + ]]> @@ -385,13 +385,13 @@ Sets the enumerator to its initial position, which is before the first element in the collection. - method, you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. - - An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . - + method, you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. + + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . + ]]> The collection was modified after the enumerator was created. diff --git a/xml/System.Collections.Generic/SortedDictionary`2+ValueCollection.xml b/xml/System.Collections.Generic/SortedDictionary`2+ValueCollection.xml index 6340ca930bf..1642d7d89a0 100644 --- a/xml/System.Collections.Generic/SortedDictionary`2+ValueCollection.xml +++ b/xml/System.Collections.Generic/SortedDictionary`2+ValueCollection.xml @@ -328,7 +328,7 @@ requires a comparer implementation to perform key comparisons. You can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter; if you do not specify an implementation, the default generic comparer is used. If type `TKey` implements the generic interface, the default comparer uses that implementation. - The `foreach` statement of the C# language (`for each` in C++, `For Each` in Visual Basic) returns an object of the type of the elements in the collection. Since each element of the is a key/value pair, the element type is not the type of the key or the type of the value. Instead, the element type is . The following code shows C#, C++, and Visual Basic syntax. + The `foreach` statement of the C# language (`For Each` in Visual Basic) returns an object of the type of the elements in the collection. Since each element of the is a key/value pair, the element type is not the type of the key or the type of the value. Instead, the element type is . The following code shows the syntax. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Generic.Dictionary/cpp/source2.cpp" id="Snippet11"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/Overview/source2.cs" id="Snippet11"::: @@ -138,8 +138,6 @@ The `foreach` statement is a wrapper around the enumerator, which allows only reading from the collection, not writing to it. - - ## Examples The following code example creates an empty of strings with string keys and uses the method to add some elements. The example demonstrates that the method throws an when attempting to add a duplicate key. @@ -960,7 +958,7 @@ ## Remarks For purposes of enumeration, each item is a structure representing a value and its key. - The `foreach` statement of the C# language (`for each` in C++, `For Each` in Visual Basic) hides the complexity of enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. + The `foreach` statement of the C# language (`For Each` in Visual Basic) hides the complexity of enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. @@ -2061,7 +2059,7 @@ Getting the value of this property is an O(1) operation. ## Remarks For purposes of enumeration, each item is a structure. - The `foreach` statement of the C# language (`for each` in C++, `For Each` in Visual Basic) hides the complexity of enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. + The `foreach` statement of the C# language (`For Each` in Visual Basic) hides the complexity of enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. @@ -2082,7 +2080,7 @@ Getting the value of this property is an O(1) operation. ## Examples - The following code example shows how to enumerate the key/value pairs in the dictionary by using the `foreach` statement (`For Each` in Visual Basic, `for each` in C++), which hides the use of the enumerator. In particular, note that the enumerator for the interface returns objects rather than objects. + The following code example shows how to enumerate the key/value pairs in the dictionary by using the `foreach` statement (`For Each` in Visual Basic), which hides the use of the enumerator. In particular, note that the enumerator for the interface returns objects rather than objects. The code example is part of a larger example, including output, provided for the method. @@ -2581,7 +2579,7 @@ Getting the value of this property is an O(1) operation. ## Remarks - The `foreach` statement of the C# language (`for each` in C++, `For Each` Visual Basic) hides the complexity of enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. + The `foreach` statement of the C# language (`For Each` Visual Basic) hides the complexity of enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. diff --git a/xml/System.Collections.Generic/SortedList`2.xml b/xml/System.Collections.Generic/SortedList`2.xml index dd3062b9228..cbfd5bc244d 100644 --- a/xml/System.Collections.Generic/SortedList`2.xml +++ b/xml/System.Collections.Generic/SortedList`2.xml @@ -142,7 +142,7 @@ **.NET Framework only:** For very large objects, you can increase the maximum capacity to 2 billion elements on a 64-bit system by setting the `enabled` attribute of the [``](/dotnet/framework/configure-apps/file-schema/runtime/gcallowverylargeobjects-element) configuration element to `true` in the run-time environment. - The `foreach` statement of the C# language (`for each` in C++, `For Each` in Visual Basic) returns an object of the type of the elements in the collection. Since the elements of the are key/value pairs, the element type is not the type of the key or the type of the value. Instead, the element type is . For example: + The `foreach` statement of the C# language (`For Each` in Visual Basic) returns an object of the type of the elements in the collection. Since the elements of the are key/value pairs, the element type is not the type of the key or the type of the value. Instead, the element type is . For example: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Generic.SortedList/cpp/remarks.cpp" id="Snippet12"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/SortedListTKey,TValue/Overview/remarks.cs" id="Snippet12"::: @@ -1148,7 +1148,7 @@ interface returns objects rather than objects. + The following code example shows how to enumerate the key/value pairs in the sorted list by using the `foreach` statement (`For Each` in Visual Basic), which hides the use of the enumerator. In particular, note that the enumerator for the interface returns objects rather than objects. The code example is part of a larger example, including output, provided for the method. @@ -3111,7 +3111,7 @@ Retrieving the value of this property is an O(1) operation. Enumerates the elements of a . - is undefined. Therefore, you must call to advance the enumerator to the first element of the collection before reading the value of . - - returns the same object until is called. sets to the next element. - - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. - - An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . - - The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - Default implementations of collections in are not synchronized. - + is undefined. Therefore, you must call to advance the enumerator to the first element of the collection before reading the value of . + + returns the same object until is called. sets to the next element. + + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. If the last call to returned `false`, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. + + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . + + The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + Default implementations of collections in are not synchronized. + ]]> @@ -148,19 +148,19 @@ Gets the element at the current position of the enumerator. The element in the at the current position of the enumerator. - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - + is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. + - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + ]]> @@ -258,15 +258,15 @@ if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the collection. - advances the enumerator to the first element of the collection. - - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. - - An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . - + advances the enumerator to the first element of the collection. + + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns `false`. When the enumerator is at this position, subsequent calls to also return `false`. + + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . + ]]> The collection was modified after the enumerator was created. @@ -323,20 +323,20 @@ Gets the element at the current position of the enumerator. The element in the collection at the current position of the enumerator. - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - + is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. + - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + ]]> @@ -387,11 +387,11 @@ Sets the enumerator to its initial position, which is before the first element in the collection. This class cannot be inherited. - or throws an . - + or throws an . + ]]> The collection was modified after the enumerator was created. diff --git a/xml/System.Collections.Generic/Stack`1.xml b/xml/System.Collections.Generic/Stack`1.xml index 0f541852568..9a57f63105a 100644 --- a/xml/System.Collections.Generic/Stack`1.xml +++ b/xml/System.Collections.Generic/Stack`1.xml @@ -773,7 +773,7 @@ generic class is enumerable. The `foreach` statement (`For Each` in Visual Basic, `for each` in C++) is used to enumerate the stack. + The following code example demonstrates that the generic class is enumerable. The `foreach` statement (`For Each` in Visual Basic) is used to enumerate the stack. The code example creates a stack of strings with default capacity and uses the method to push five strings onto the stack. The elements of the stack are enumerated, which does not change the state of the stack. The method is used to pop the first string off the stack. The method is used to look at the next item on the stack, and then the method is used to pop it off. @@ -1086,7 +1084,7 @@ includes a lookup dictionary that you can obtain with the property. When an item is added to the , the item's key is extracted once and saved in the lookup dictionary for faster searches. This behavior is overridden by specifying a dictionary creation threshold when you create the . The lookup dictionary is created the first time the number of elements exceeds that threshold. If you specify -1 as the threshold, the lookup dictionary is never created. > [!NOTE] -> When the internal lookup dictionary is used, it contains references to all the items in the collection if `TItem` is a reference type, or copies of all the items in the collection if `TItem` is a value type. Thus, using the lookup dictionary may not be appropriate if `TItem` is a value type. +> When the internal lookup dictionary is used, it contains references to all the items in the collection if `TItem` is a reference type, or copies of all the items in the collection if `TItem` is a value type. Thus, using the lookup dictionary may not be appropriate if `TItem` is a value type. You can access an item by its index or key by using the property. You can add items without a key, but these items can subsequently be accessed only by index. @@ -190,7 +190,7 @@ By default, the includes a lookup dictionary that is created when the first item is added. When an item is added to the , the item's key is extracted once and saved in the lookup dictionary for faster searches. This behavior can be overridden by using the constructor and specifying a dictionary creation threshold. > [!NOTE] -> Because the class is abstract (`MustInherit` in Visual Basic), you must derive from it in order to use it. In the constructor for your derived type, call the appropriate constructor. It is not necessary to expose functionality like the equality comparer or the dictionary creation threshold in your constructors. +> Because the class is abstract (`MustInherit` in Visual Basic), you must derive from it in order to use it. In the constructor for your derived type, call the appropriate constructor. It is not necessary to expose functionality like the equality comparer or the dictionary creation threshold in your constructors. This constructor is an O(1) operation. @@ -264,7 +264,7 @@ By default, the includes a lookup dictionary that is created when the first item is added. When an item is added to the , the item's key is extracted once and saved in the lookup dictionary for faster searches. This behavior can be overridden by using the constructor and specifying a dictionary creation threshold. > [!NOTE] -> Because the class is abstract (`MustInherit` in Visual Basic), you must derive from it in order to use it. In the constructor for your derived type, call the appropriate constructor. It is not necessary to expose functionality like the equality comparer or the dictionary creation threshold in your constructors. +> Because the class is abstract (`MustInherit` in Visual Basic), you must derive from it in order to use it. In the constructor for your derived type, call the appropriate constructor. It is not necessary to expose functionality like the equality comparer or the dictionary creation threshold in your constructors. This constructor is an O(1) operation. @@ -331,7 +331,7 @@ For very small collections the improvement in retrieval speed provided by the lookup dictionary might not be worth the extra memory required by the dictionary. Setting a threshold allows you to decide when to make that tradeoff. > [!NOTE] -> Because the class is abstract (`MustInherit` in Visual Basic), you must derive from it in order to use it. In the constructor for your derived type, call the appropriate constructor. It is not necessary to expose functionality like the equality comparer or the dictionary creation threshold in your constructors. +> Because the class is abstract (`MustInherit` in Visual Basic), you must derive from it in order to use it. In the constructor for your derived type, call the appropriate constructor. It is not necessary to expose functionality like the equality comparer or the dictionary creation threshold in your constructors. This constructor is an O(1) operation. @@ -938,7 +938,7 @@ In order to maintain the connection between a `MutableKey` object and the `Mutab This property provides the ability to access a specific element in the collection by using the following syntax: `myCollection[key]` (`myCollection(key)` in Visual Basic). > [!NOTE] -> This property is distinct from the inherited property, which gets and sets elements by numeric index. However, if `TKey` is of type , this property masks the inherited property. In that case, you can access the inherited property by casting the to its base type. For example, `KeyedCollection` (`KeyedCollection(Of Integer, MyType)` in Visual Basic, `KeyedCollection` in C++) can be cast to `Collection` (`Collection(Of MyType)` in Visual Basic, `Collection` in C++). +> This property is distinct from the inherited property, which gets and sets elements by numeric index. However, if `TKey` is of type , this property masks the inherited property. In that case, you can access the inherited property by casting the to its base type. For example, `KeyedCollection` (`KeyedCollection(Of Integer, MyType)` in Visual Basic) can be cast to `Collection` (`Collection(Of MyType)` in Visual Basic). If the has a lookup dictionary, `key` is used to retrieve the element from the dictionary. If there is no lookup dictionary, the key of each element is extracted using the method and compared with the specified key. @@ -1018,7 +1018,7 @@ In order to maintain the connection between a `MutableKey` object and the `Mutab If the number of elements has exceeded the dictionary creation threshold and the is using a lookup dictionary, it will continue to use a lookup dictionary even though the number of elements is again under the threshold. > [!NOTE] -> To customize the behavior of this method, override the method. +> To customize the behavior of this method, override the method. This method is an O(`n`) operation, where `n` is . diff --git a/xml/System.Collections.ObjectModel/ReadOnlyCollection`1.xml b/xml/System.Collections.ObjectModel/ReadOnlyCollection`1.xml index 3bde909b91d..bfad36ee848 100644 --- a/xml/System.Collections.ObjectModel/ReadOnlyCollection`1.xml +++ b/xml/System.Collections.ObjectModel/ReadOnlyCollection`1.xml @@ -544,7 +544,7 @@ that wraps a . The enumerator is concealed by the `foreach` statement (`For Each` in Visual Basic, `for each` in C++). + The following code example uses the enumerator to display the contents of a that wraps a . The enumerator is concealed by the `foreach` statement (`For Each` in Visual Basic). :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/generic.ReadOnlyCollection/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/ReadOnlyCollectionT/Overview/source.cs" id="Snippet1"::: @@ -1479,7 +1477,7 @@ This member is an explicit interface member implementation. It can be used only are not sorted by the key, unlike the elements of a class. You can access elements either by the key or by the index. - The `foreach` statement of the C# language (`For Each` in Visual Basic) returns objects that are of the type of each element in the collection. Since each element of the collection is a key/value pair, the element type is not the type of the key or the type of the value. Instead, the element type is . The following code shows C#, Visual Basic and C++ syntax. + The `foreach` statement of the C# language (`For Each` in Visual Basic) returns objects that are of the type of each element in the collection. Since each element of the collection is a key/value pair, the element type is not the type of the key or the type of the value. Instead, the element type is . The following code shows the syntax. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/cpp/source2.cpp" id="Snippet06"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/OrderedDictionary/Overview/source2.cs" id="Snippet06"::: diff --git a/xml/System.Collections/ArrayList.xml b/xml/System.Collections/ArrayList.xml index c30f843970f..9a732e300af 100644 --- a/xml/System.Collections/ArrayList.xml +++ b/xml/System.Collections/ArrayList.xml @@ -1826,7 +1826,7 @@ This method is an `O(1)` operation. Indicates to compilers that a method call or attribute should be ignored unless a specified conditional compilation symbol is defined. - attribute to methods and classes. However, its use on classes is valid only for types that are derived from . either will be ignored or will produce a compiler warning or error message if you apply it to any other type. - - Applying to a method indicates to compilers that a call to the method should not be compiled into Microsoft intermediate language (MSIL) unless the conditional compilation symbol that is associated with is defined. You will get a compilation error in Visual Studio if you apply this attribute to a method that does not return void. Applying to an attribute indicates that the attribute should not be emitted to metadata unless the conditional compilation symbol is defined. Any arguments passed to the method or attribute are still type-checked by the compiler. - - You can use the following techniques to define conditional compilation symbols: - -- Use compiler command-line options; for example, **/define:DEBUG**. - -- Use environment variables in the operating system shell; for example, **set DEBUG=1**. - -- Use pragmas in the source code; for example, define the compilation variable as follows: - - ```csharp - #define DEBUG - ``` - - ```vb - #Const DEBUG=True - ``` - - To undefine the variable, use the following: - - ```csharp - #undef DEBUG - ``` - - ```vb - #Const DEBUG=False - ``` - - Compilers that comply with the Common Language Specification (CLS) are permitted to ignore . The C#, F#, Visual Basic, and C++ compilers support ; the JScript compiler does not support the attribute. - + attribute to methods and classes. However, its use on classes is valid only for types that are derived from . either will be ignored or will produce a compiler warning or error message if you apply it to any other type. + + Applying to a method indicates to compilers that a call to the method should not be compiled into Microsoft intermediate language (MSIL) unless the conditional compilation symbol that is associated with is defined. You will get a compilation error in Visual Studio if you apply this attribute to a method that does not return void. Applying to an attribute indicates that the attribute should not be emitted to metadata unless the conditional compilation symbol is defined. Any arguments passed to the method or attribute are still type-checked by the compiler. + + You can use the following techniques to define conditional compilation symbols: + +- Use compiler command-line options; for example, **/define:DEBUG**. + +- Use environment variables in the operating system shell; for example, **set DEBUG=1**. + +- Use pragmas in the source code; for example, define the compilation variable as follows: + + ```csharp + #define DEBUG + ``` + + ```vb + #Const DEBUG=True + ``` + + To undefine the variable, use the following: + + ```csharp + #undef DEBUG + ``` + + ```vb + #Const DEBUG=False + ``` + + Compilers that comply with the Common Language Specification (CLS) are permitted to ignore . The C#, F#, Visual Basic, and C++ compilers support ; the JScript compiler does not support the attribute. + > [!NOTE] -> In Visual Basic, the `AddressOf` operator is not affected by this attribute. For example, `Call CType(AddressOf delegate, Action)` always invokes `delegate`, although `Call delegate()` might not. - - is applied to the methods that are defined in the and classes. - - For more information about how to use attributes, see [Attributes](/dotnet/standard/attributes/). - - - -## Examples - The following example demonstrates the use of . The example assumes that the condition is defined with the **/define** compiler option. You can obtain different results by changing the compiler option. You can optionally define the conditions by using pragmas in the sample code instead of identifying them as compiler options. - +> In Visual Basic, the `AddressOf` operator is not affected by this attribute. For example, `Call CType(AddressOf delegate, Action)` always invokes `delegate`, although `Call delegate()` might not. + + is applied to the methods that are defined in the and classes. + + For more information about how to use attributes, see [Attributes](/dotnet/standard/attributes/). + +## Examples + The following example demonstrates the use of . The example assumes that the condition is defined with the **/define** compiler option. You can obtain different results by changing the compiler option. You can optionally define the conditions by using pragmas in the sample code instead of identifying them as compiler options. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/ConditionalAttribute/Overview/cas.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ConditionalAttributeSample1/VB/cas.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ConditionalAttributeSample1/VB/cas.vb" id="Snippet7"::: + ]]> @@ -170,14 +168,14 @@ A string that specifies the case-sensitive conditional compilation symbol that is associated with the attribute. Initializes a new instance of the class. - constructor. This example is part of a larger example provided for the class. - + constructor. This example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/ConditionalAttribute/Overview/cas.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ConditionalAttributeSample1/VB/cas.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ConditionalAttributeSample1/VB/cas.vb" id="Snippet8"::: + ]]> @@ -225,11 +223,11 @@ Gets the conditional compilation symbol that is associated with the attribute. A string that specifies the case-sensitive conditional compilation symbol that is associated with the attribute. - diff --git a/xml/System.Diagnostics/Trace.xml b/xml/System.Diagnostics/Trace.xml index 3ffc7d7e1bf..c33ac03aef6 100644 --- a/xml/System.Diagnostics/Trace.xml +++ b/xml/System.Diagnostics/Trace.xml @@ -51,56 +51,56 @@ Provides a set of methods and properties that help you trace the execution of your code. This class cannot be inherited. - class to instrument release builds. Instrumentation allows you to monitor the health of your application running in real-life settings. Tracing helps you isolate problems and fix them without disturbing a running system. - + class to instrument release builds. Instrumentation allows you to monitor the health of your application running in real-life settings. Tracing helps you isolate problems and fix them without disturbing a running system. + This class provides methods to display an dialog box, and to emit an assertion that will always . This class provides write methods in the following variations: - + - - - - - - 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). - - 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. - + + 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). + + 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. - +> 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. - - 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. - +> 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. + + 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] -> In Visual Studio projects, by default, the `DEBUG` conditional compilation symbol is defined for debug builds, and the `TRACE` symbol is defined for both debug and release builds. - - To define the `TRACE` conditional compilation symbol in C#, add the `/d:TRACE` option to the compiler command line when you compile your code using a command line, or add `#define TRACE` to the top of your file. In Visual Basic, add the `/d:TRACE=True` option to the compiler command line or add `#Const TRACE=True` to the file. - +> In Visual Studio projects, by default, the `DEBUG` conditional compilation symbol is defined for debug builds, and the `TRACE` symbol is defined for both debug and release builds. + + To define the `TRACE` conditional compilation symbol in C#, add the `/d:TRACE` option to the compiler command line when you compile your code using a command line, or add `#define TRACE` to the top of your file. In Visual Basic, add the `/d:TRACE=True` option to the compiler command line or add `#Const TRACE=True` to the file. + is not supported by the C++ compiler. To provide equivalent functionality, you must enclose calls to the methods of in an `#if defined(TRACE) ... #endif` block, and add the `/DTRACE` option to the compiler command line or add `#define TRACE` to the file. - -## Examples - The following example uses to indicate the beginning and the end of a program's execution. The example also uses the and methods to distinguish the tracing output. For a more complete example of the use of , see [How to: Add Trace Statements to Application Code](/dotnet/framework/debug-trace-profile/how-to-add-trace-statements-to-application-code). - + +## Examples + The following example uses to indicate the beginning and the end of a program's execution. The example also uses the and methods to distinguish the tracing output. For a more complete example of the use of , see [How to: Add Trace Statements to Application Code](/dotnet/framework/debug-trace-profile/how-to-add-trace-statements-to-application-code). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace Example/VB/source.vb" id="Snippet1"::: + ]]> This type is thread safe. @@ -185,39 +185,39 @@ In .NET Framework apps, you can set the The conditional expression to evaluate. If the condition is , a failure message is not sent and the message box is not displayed. Checks for a condition; if the condition is , displays a message box that shows the call stack. - method if you want to do assertions in release builds. The method works only in debug builds. For more information, see [Assertions in Managed Code](/visualstudio/debugger/assertions-in-managed-code). - - Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, it sends a failure message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. - - 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. - + method if you want to do assertions in release builds. The method works only in debug builds. For more information, see [Assertions in Managed Code](/visualstudio/debugger/assertions-in-managed-code). + + Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, it sends a failure message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. + + 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: - -```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()`). 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 + + + + + + + + + ``` - -## 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. - + +## 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. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.Assert Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/Assert/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Assert Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Assert Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -297,39 +297,39 @@ For .NET Framework apps, you can change the behavior of the The message to send to the collection. Checks for a condition; if the condition is , outputs a specified message and displays a message box that shows the call stack. - method if you want to do assertions in release builds. The method works only in debug builds. For more information, see [Assertions in Managed Code](/visualstudio/debugger/assertions-in-managed-code). - - Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, it sends the specified diagnostic message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. - - 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. - + method if you want to do assertions in release builds. The method works only in debug builds. For more information, see [Assertions in Managed Code](/visualstudio/debugger/assertions-in-managed-code). + + Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, it sends the specified diagnostic message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. + + 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: - -```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()`). 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 + + + + + + + + + ``` - -## Examples - The following example checks to see that the `type` parameter is valid. If the `type` passed in is `null`, the outputs a message. - + +## Examples + The following example checks to see that the `type` parameter is valid. If the `type` passed in is `null`, the outputs a message. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.Assert1 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/Assert/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Assert1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Assert1 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -402,39 +402,39 @@ For .NET Framework apps, you can change the behavior of the The detailed message to send to the collection. Checks for a condition; if the condition is , outputs two specified messages and displays a message box that shows the call stack. - method if you want to do assertions in release builds. The method works only in debug builds. For more information, see [Assertions in Managed Code](/visualstudio/debugger/assertions-in-managed-code). - - Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, it sends the specified diagnostic message and detailed message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. - - 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. - + method if you want to do assertions in release builds. The method works only in debug builds. For more information, see [Assertions in Managed Code](/visualstudio/debugger/assertions-in-managed-code). + + Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, it sends the specified diagnostic message and detailed message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. + + 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: - -```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()`). 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 + + + + + + + + + ``` - -## Examples - The following example checks to see that the `type` parameter is valid. If the `type` passed in is `null`, the outputs a message. - + +## Examples + The following example checks to see that the `type` parameter is valid. If the `type` passed in is `null`, the outputs a message. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.Assert2 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/Assert/source2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Assert2 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Assert2 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -487,23 +487,23 @@ For .NET Framework apps, you can change the behavior of the if is called on the after every write; otherwise, . - 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 - - - - - -``` - + 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 + + + + + +``` + ]]> @@ -561,22 +561,22 @@ For .NET Framework apps, you can change the behavior of the Flushes the output buffer, and then closes the . - . - - Flushing the stream will not 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. - - - -## Examples - The following example creates a named `myTextListener`. `myTextListener` uses a called `myOutputWriter` to write to a file named `TestFile.txt`. The example creates the file, stream and text writer, writes one line of text to the file, and then flushes and closes the output. - + . + + Flushing the stream will not 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. + + + +## Examples + The following example creates a named `myTextListener`. `myTextListener` uses a called `myOutputWriter` to write to a file named `TestFile.txt`. The example creates the file, stream and text writer, writes one line of text to the file, and then flushes and closes the output. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.Flush Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/Close/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Flush Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Flush Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -632,15 +632,15 @@ For .NET Framework apps, you can change the behavior of the Gets the correlation manager for the thread for this trace. The object associated with the thread for this trace. - [!NOTE] -> This is an advanced property that most applications should not have occasion to use. - - The class provides methods used to store a logical operation identity in a thread-bound context and automatically tag each trace event generated by the thread with the stored identity. - +> This is an advanced property that most applications should not have occasion to use. + + The class provides methods used to store a logical operation identity in a thread-bound context and automatically tag each trace event generated by the thread with the stored identity. + ]]> @@ -710,31 +710,31 @@ For .NET Framework apps, you can change the behavior of the A message to emit. Emits the specified error message. - instances in the collection. - + 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()`). - - 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. - +> 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()`). + + 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. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.Fail Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/Fail/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Fail Example/VB/source.vb" id="Snippet1"::: - - You can also use the method in a switch statement. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Fail Example/VB/source.vb" id="Snippet1"::: + + You can also use the method in a switch statement. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.Fail Example/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/Fail/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Fail Example/VB/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Fail Example/VB/source.vb" id="Snippet2"::: + ]]> @@ -802,31 +802,31 @@ For .NET Framework apps, you can change the behavior of the A detailed message to emit. Emits an error message, and a detailed error message. - instances in the collection. - + 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()`). - - 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. - +> 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()`). + + 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. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.Fail1 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/Fail/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Fail1 Example/VB/source.vb" id="Snippet1"::: - - You can also use the method in a switch statement. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Fail1 Example/VB/source.vb" id="Snippet1"::: + + You can also use the method in a switch statement. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.Fail1 Example/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/Fail/source1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Fail1 Example/VB/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Fail1 Example/VB/source.vb" id="Snippet2"::: + ]]> @@ -884,20 +884,20 @@ For .NET Framework apps, you can change the behavior of the Flushes the output buffer, and causes buffered data to be written to 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. - - - -## Examples - The following example creates a named `myTextListener`. `myTextListener` uses a called `myOutputWriter` to write to a file named `TestFile.txt`. The example creates the file, stream and text writer, writes one line of text to the file, and then flushes and closes the output. - + 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. + + + +## Examples + The following example creates a named `myTextListener`. `myTextListener` uses a called `myOutputWriter` to write to a file named `TestFile.txt`. The example creates the file, stream and text writer, writes one line of text to the file, and then flushes and closes the output. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.Flush Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/Close/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Flush Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Flush Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -955,24 +955,24 @@ For .NET Framework apps, you can change the behavior of the Increases the current by one. - @@ -1020,31 +1020,31 @@ End of list of errors Gets or sets the indent level. The indent level. The default is zero. - property represents the number of times the indent of size is applied. This property is stored on per-thread/per-request basis. - - - -## Examples - The following example increments and decrements the indent level and emits tracing messages. - + property represents the number of times the indent of size is applied. This property is stored on per-thread/per-request basis. + + + +## Examples + The following example increments and decrements the indent level and emits tracing messages. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.IndentLevel Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/Indent/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.IndentLevel Example/VB/source.vb" id="Snippet1"::: - - This example produces the following output: - -``` - -List of errors: - Error 1: File not found - Error 2: Directory not found -End of list of errors - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.IndentLevel Example/VB/source.vb" id="Snippet1"::: + + This example produces the following output: + +``` + +List of errors: + Error 1: File not found + Error 2: Directory not found +End of list of errors + +``` + ]]> @@ -1097,23 +1097,23 @@ End of list of errors Gets or sets the number of spaces in an indent. The number of spaces in an indent. The default is four. - interprets this number as spaces. An ignores this value. - - 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 - - - - - -``` - + interprets this number as spaces. An ignores this value. + + 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 + + + + + +``` + ]]> @@ -1172,23 +1172,23 @@ End of list of errors Gets the collection of listeners that is monitoring the trace output. A that represents a collection of type monitoring the trace output. - class. If you want to remove the default listener, call the method, and pass it the instance of the . To redirect output to the console window, add an instance of the class. - + class. If you want to remove the default listener, call the method, and pass it the instance of the . To redirect output to the console window, add an instance of the class. + > [!NOTE] -> The collection is shared by both the and the classes; adding a trace listener to either class adds the listener to both. - - - -## Examples - The following example creates a that outputs to the console screen. The code then adds the new listener to the . - +> The collection is shared by both the and the classes; adding a trace listener to either class adds the listener to both. + + + +## Examples + The following example creates a that outputs to the console screen. The code then adds the new listener to the . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.Listeners Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/Listeners/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Listeners Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Listeners Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1239,11 +1239,11 @@ End of list of errors Refreshes the trace configuration data. - method to update the trace configuration data. - + method to update the trace configuration data. + ]]> @@ -1333,11 +1333,11 @@ End of list of errors The informative message to write. Writes an error message to the trace listeners in the collection using the specified message. - calls the `TraceEvent` method for each trace listener, with the trace event type , passing the informative message as the message string. - + calls the `TraceEvent` method for each trace listener, with the trace event type , passing the informative message as the message string. + ]]> @@ -1418,11 +1418,11 @@ End of list of errors An array containing zero or more objects to format. Writes an error message to the trace listeners in the collection using the specified array of objects and formatting information. - calls the `TraceEvent` methods in the trace listeners with the trace event type , passing the message content as an object array with formatting information. See the method for more information about the `format` and `args` parameters. - + calls the `TraceEvent` methods in the trace listeners with the trace event type , passing the message content as an object array with formatting information. See the method for more information about the `format` and `args` parameters. + ]]> @@ -1493,11 +1493,11 @@ End of list of errors The informative message to write. Writes an informational message to the trace listeners in the collection using the specified message. - calls the `TraceEvent` method for each trace listener, with the trace event type , passing the informative message as the message string. - + calls the `TraceEvent` method for each trace listener, with the trace event type , passing the informative message as the message string. + ]]> @@ -1578,11 +1578,11 @@ End of list of errors An array containing zero or more objects to format. Writes an informational message to the trace listeners in the collection using the specified array of objects and formatting information. - calls the `TraceEvent` methods in the trace listeners with the trace event type , passing the message content as an object array with formatting information. See the method for more information about the `format` and `args` parameters. - + calls the `TraceEvent` methods in the trace listeners with the trace event type , passing the message content as an object array with formatting information. See the method for more information about the `format` and `args` parameters. + ]]> @@ -1653,11 +1653,11 @@ End of list of errors The informative message to write. Writes a warning message to the trace listeners in the collection using the specified message. - calls the `TraceEvent` method for each trace listener with the trace event type , passing the informative message as the message string. - + calls the `TraceEvent` method for each trace listener with the trace event type , passing the informative message as the message string. + ]]> @@ -1738,11 +1738,11 @@ End of list of errors An array containing zero or more objects to format. Writes a warning message to the trace listeners in the collection using the specified array of objects and formatting information. - calls the `TraceEvent` methods in the trace listeners with the trace event type , passing the message content as an object array with formatting information. See the method for more information about the `format` and `args` parameters. - + calls the `TraceEvent` methods in the trace listeners with the trace event type , passing the message content as an object array with formatting information. See the method for more information about the `format` and `args` parameters. + ]]> @@ -1800,26 +1800,26 @@ End of list of errors Decreases the current by one. - @@ -1867,21 +1867,21 @@ End of list of errors if the global lock is to be used; otherwise, . The default is . - . 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 - - - - - -``` - + . 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 + + + + + +``` + ]]> @@ -1946,31 +1946,31 @@ End of list of errors An whose name is sent to the . Writes the value of the object's method to the trace listeners in the collection. - . - - This method calls the method of the trace listener. - + . + + This method calls the method of the trace listener. + > [!NOTE] -> ASP.NET supplies tracing functionality tailored for Web pages. To write trace messages in ASP.NET pages, use the property. - - By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. - - - -## Examples - The following example creates a named `generalSwitch`. This switch is set outside the code sample. - - If the switch is set to the `Error` or higher, the example outputs the first name of the `value` parameter to the . For information on adding a listener to the collection, see the class. - - Then, if the is set to `Verbose`, the example outputs a message on the same line as the first message. The second message is followed by a line terminator. - +> ASP.NET supplies tracing functionality tailored for Web pages. To write trace messages in ASP.NET pages, use the property. + + By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. + + + +## Examples + The following example creates a named `generalSwitch`. This switch is set outside the code sample. + + If the switch is set to the `Error` or higher, the example outputs the first name of the `value` parameter to the . For information on adding a listener to the collection, see the class. + + Then, if the is set to `Verbose`, the example outputs a message on the same line as the first message. The second message is followed by a line terminator. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.Write1 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/Write/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Write1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Write1 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2032,31 +2032,31 @@ End of list of errors A message to write. Writes a message to the trace listeners in the collection. - . - - This method calls the method of the trace listener. - + . + + This method calls the method of the trace listener. + > [!NOTE] -> ASP.NET supplies tracing functionality tailored for Web pages. To write trace messages in ASP.NET pages, use the property. - - By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. - - - -## Examples - The following example creates a named `generalSwitch`. This switch is set outside the code sample. - - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. - - Then, if the is set to `Verbose`, the example outputs the second error message on the same line as the first message. A line terminator follows the second message. - +> ASP.NET supplies tracing functionality tailored for Web pages. To write trace messages in ASP.NET pages, use the property. + + By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. + + + +## Examples + The following example creates a named `generalSwitch`. This switch is set outside the code sample. + + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + + Then, if the is set to `Verbose`, the example outputs the second error message on the same line as the first message. A line terminator follows the second message. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.Write Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/Write/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Write Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Write Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2120,33 +2120,33 @@ End of list of errors A category name used to organize the output. Writes a category name and the value of the object's method to the trace listeners in the collection. - . - - The `category` parameter can be used to group output messages. - - This method calls the method of the trace listener. - + . + + The `category` parameter can be used to group output messages. + + This method calls the method of the trace listener. + > [!NOTE] -> ASP.NET supplies tracing functionality tailored for Web pages. To write trace messages in ASP.NET pages, use the property. - - By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. - - - -## Examples - The following example creates a named `generalSwitch`. This switch is set outside the code sample. - - If the switch is set to the `Verbose`, the example outputs the name of the `myObject` and the `category` to the . For information on adding a listener to the collection, see the class. - - Then, if the is set to `Error` or higher, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator. - +> ASP.NET supplies tracing functionality tailored for Web pages. To write trace messages in ASP.NET pages, use the property. + + By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. + + + +## Examples + The following example creates a named `generalSwitch`. This switch is set outside the code sample. + + If the switch is set to the `Verbose`, the example outputs the name of the `myObject` and the `category` to the . For information on adding a listener to the collection, see the class. + + Then, if the is set to `Error` or higher, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.Write3 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/Write/source3.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Write3 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Write3 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2210,33 +2210,33 @@ End of list of errors A category name used to organize the output. Writes a category name and a message to the trace listeners in the collection. - . - - The `category` parameter can be used to group output messages. - - This method calls the method of the trace listener. - + . + + The `category` parameter can be used to group output messages. + + This method calls the method of the trace listener. + > [!NOTE] -> ASP.NET supplies tracing functionality tailored for Web pages. To write trace messages in ASP.NET pages, use the property. - - By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. - - - -## Examples - The following example creates a named `generalSwitch`. This switch is set outside the code sample. - - If the switch is set to the `Verbose`, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. - - Then, if the is set to `Error` or higher, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator. - +> ASP.NET supplies tracing functionality tailored for Web pages. To write trace messages in ASP.NET pages, use the property. + + By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. + + + +## Examples + The following example creates a named `generalSwitch`. This switch is set outside the code sample. + + If the switch is set to the `Verbose`, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + + Then, if the is set to `Error` or higher, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.Write2 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/Write/source2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Write2 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Write2 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2311,42 +2311,42 @@ End of list of errors An whose name is sent to the . Writes the value of the object's method to the trace listeners in the collection if a condition is . - . - - This method calls the method of the trace listener. - - - -## Examples - The following example creates a named `generalSwitch`. This switch is set outside the code sample. - - If the switch is set to the `Error` or higher, the example outputs the first name of the value parameter to the . For information on adding a listener to the collection, see the class. - - Then, if the is set to `Verbose`, the example outputs a message on the same line as the first message. The second message is followed by a line terminator. - + . + + This method calls the method of the trace listener. + + + +## Examples + The following example creates a named `generalSwitch`. This switch is set outside the code sample. + + If the switch is set to the `Error` or higher, the example outputs the first name of the value parameter to the . For information on adding a listener to the collection, see the class. + + Then, if the is set to `Verbose`, the example outputs a message on the same line as the first message. The second message is followed by a line terminator. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.WriteIf1 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/WriteIf/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.WriteIf1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.WriteIf1 Example/VB/source.vb" id="Snippet1"::: + ]]> - You can minimize the performance penalty of instrumenting your application by using statements instead of using statements. The following two code examples send the same debugging message. However, the first example is much faster when tracing is off, because if mySwitch.TraceError evaluates to you do not call . The second example always calls , even when mySwitch.TraceError is and no tracing output is produced. This can result in unnecessary execution of arbitrarily complex code. - - **First example** - -```csharp -if(mySwitch.TraceError) - Trace.Write("aNumber = " + aNumber + " out of range"); -``` - - **Second example** - -```csharp -Trace.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); + You can minimize the performance penalty of instrumenting your application by using statements instead of using statements. The following two code examples send the same debugging message. However, the first example is much faster when tracing is off, because if mySwitch.TraceError evaluates to you do not call . The second example always calls , even when mySwitch.TraceError is and no tracing output is produced. This can result in unnecessary execution of arbitrarily complex code. + + **First example** + +```csharp +if(mySwitch.TraceError) + Trace.Write("aNumber = " + aNumber + " out of range"); +``` + + **Second example** + +```csharp +Trace.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); ``` @@ -2411,42 +2411,42 @@ Trace.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); A message to write. Writes a message to the trace listeners in the collection if a condition is . - . - - This method calls the method of the trace listener. - - - -## Examples - The following example creates a named `generalSwitch`. This switch is set outside the code sample. - - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. - - Then, if the is set to `Verbose`, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator. - + . + + This method calls the method of the trace listener. + + + +## Examples + The following example creates a named `generalSwitch`. This switch is set outside the code sample. + + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + + Then, if the is set to `Verbose`, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.WriteIf Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/WriteIf/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.WriteIf Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.WriteIf Example/VB/source.vb" id="Snippet1"::: + ]]> - You can minimize the performance penalty of instrumenting your application by using statements instead of using statements. The following two code examples send the same debugging message. However, the first example is much faster when tracing is off, because if mySwitch.TraceError evaluates to you do not call . The second example always calls , even when mySwitch.TraceError is and no tracing output is produced. This can result in unnecessary execution of arbitrarily complex code. - - **First example** - -```csharp -if(mySwitch.TraceError) - Trace.Write("aNumber = " + aNumber + " out of range"); -``` - - **Second example** - -```csharp -Trace.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); + You can minimize the performance penalty of instrumenting your application by using statements instead of using statements. The following two code examples send the same debugging message. However, the first example is much faster when tracing is off, because if mySwitch.TraceError evaluates to you do not call . The second example always calls , even when mySwitch.TraceError is and no tracing output is produced. This can result in unnecessary execution of arbitrarily complex code. + + **First example** + +```csharp +if(mySwitch.TraceError) + Trace.Write("aNumber = " + aNumber + " out of range"); +``` + + **Second example** + +```csharp +Trace.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); ``` @@ -2513,44 +2513,44 @@ Trace.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); A category name used to organize the output. Writes a category name and the value of the object's method to the trace listeners in the collection if a condition is . - . - - The `category` parameter can be used to group output messages. - - This method calls the method of the trace listener. - - - -## Examples - The following example creates a named `generalSwitch`. This switch is set outside the code sample. - - If the switch is set to the `Verbose`, the example outputs the name of the `myObject` and the `category` to the . For information on adding a listener to the collection, see the class. - - Then, if the is set to `Error` or higher, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator. - + . + + The `category` parameter can be used to group output messages. + + This method calls the method of the trace listener. + + + +## Examples + The following example creates a named `generalSwitch`. This switch is set outside the code sample. + + If the switch is set to the `Verbose`, the example outputs the name of the `myObject` and the `category` to the . For information on adding a listener to the collection, see the class. + + Then, if the is set to `Error` or higher, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.WriteIf3 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/WriteIf/source3.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.WriteIf3 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.WriteIf3 Example/VB/source.vb" id="Snippet1"::: + ]]> - You can minimize the performance penalty of instrumenting your application by using statements instead of using statements. The following two code examples send the same debugging message. However, the first example is much faster when tracing is off, because if mySwitch.TraceError evaluates to you do not call . The second example always calls , even when mySwitch.TraceError is and no tracing output is produced. This can result in unnecessary execution of arbitrarily complex code. - - **First example** - -```csharp -if(mySwitch.TraceError) - Trace.Write("aNumber = " + aNumber + " out of range"); -``` - - **Second example** - -```csharp -Trace.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); + You can minimize the performance penalty of instrumenting your application by using statements instead of using statements. The following two code examples send the same debugging message. However, the first example is much faster when tracing is off, because if mySwitch.TraceError evaluates to you do not call . The second example always calls , even when mySwitch.TraceError is and no tracing output is produced. This can result in unnecessary execution of arbitrarily complex code. + + **First example** + +```csharp +if(mySwitch.TraceError) + Trace.Write("aNumber = " + aNumber + " out of range"); +``` + + **Second example** + +```csharp +Trace.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); ``` @@ -2617,44 +2617,44 @@ Trace.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); A category name used to organize the output. Writes a category name and message to the trace listeners in the collection if a condition is . - . - - The `category` parameter can be used to group output messages. - - This method calls the method of the trace listener. - - - -## Examples - The following example creates a named `generalSwitch`. This switch is set outside the code sample. - - If the switch is set to the `Verbose`, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. - - Then, if the is set to `Error` or higher, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator. - + . + + The `category` parameter can be used to group output messages. + + This method calls the method of the trace listener. + + + +## Examples + The following example creates a named `generalSwitch`. This switch is set outside the code sample. + + If the switch is set to the `Verbose`, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + + Then, if the is set to `Error` or higher, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.WriteIf2 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/WriteIf/source2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.WriteIf2 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.WriteIf2 Example/VB/source.vb" id="Snippet1"::: + ]]> - You can minimize the performance penalty of instrumenting your application by using statements instead of using statements. The following two code examples send the same debugging message. However, the first example is much faster when tracing is off, because if mySwitch.TraceError evaluates to you do not call . The second example always calls , even when mySwitch.TraceError is and no tracing output is produced. This can result in unnecessary execution of arbitrarily complex code. - - **First example** - -```csharp -if(mySwitch.TraceError) - Trace.Write("aNumber = " + aNumber + " out of range"); -``` - - **Second example** - -```csharp -Trace.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); + You can minimize the performance penalty of instrumenting your application by using statements instead of using statements. The following two code examples send the same debugging message. However, the first example is much faster when tracing is off, because if mySwitch.TraceError evaluates to you do not call . The second example always calls , even when mySwitch.TraceError is and no tracing output is produced. This can result in unnecessary execution of arbitrarily complex code. + + **First example** + +```csharp +if(mySwitch.TraceError) + Trace.Write("aNumber = " + aNumber + " out of range"); +``` + + **Second example** + +```csharp +Trace.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); ``` @@ -2726,26 +2726,26 @@ Trace.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); An whose name is sent to the . Writes the value of the object's method to the trace listeners in the collection. - . - - This method calls the method of the trace listener. - - - -## Examples - The following example creates a named `generalSwitch`. This switch is set outside the code sample. - - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. - - Then, if the is set to `Verbose`, the example outputs the name of the object on the same line as the first message. The second message is followed by a line terminator. - + . + + This method calls the method of the trace listener. + + + +## Examples + The following example creates a named `generalSwitch`. This switch is set outside the code sample. + + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + + Then, if the is set to `Verbose`, the example outputs the name of the object on the same line as the first message. The second message is followed by a line terminator. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.WriteLine1 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/WriteLine/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.WriteLine1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.WriteLine1 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2807,26 +2807,26 @@ Trace.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); A message to write. Writes a message to the trace listeners in the collection. - . - - This method calls the method of the trace listener. - - - -## Examples - The following example creates a named `generalSwitch`. This switch is set outside the code sample. - - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. - - Then, if the is set to `Verbose`, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator. - + . + + This method calls the method of the trace listener. + + + +## Examples + The following example creates a named `generalSwitch`. This switch is set outside the code sample. + + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + + Then, if the is set to `Verbose`, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.Write Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/Write/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Write Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.Write Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2890,28 +2890,28 @@ Trace.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); A category name used to organize the output. Writes a category name and the value of the object's method to the trace listeners in the collection. - . - - The `category` parameter can be used to group output messages. - - This method calls the method of the trace listener. - - - -## Examples - The following example creates a named `generalSwitch`. This switch is set outside the code sample. - - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. - - Then, if the is set to `Verbose`, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator. - + . + + The `category` parameter can be used to group output messages. + + This method calls the method of the trace listener. + + + +## Examples + The following example creates a named `generalSwitch`. This switch is set outside the code sample. + + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + + Then, if the is set to `Verbose`, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.WriteLine3 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/WriteLine/source2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.WriteLine3 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.WriteLine3 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2975,28 +2975,28 @@ Trace.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); A category name used to organize the output. Writes a category name and message to the trace listeners in the collection. - . - - The `category` parameter can be used to group output messages. - - This method calls the method of the trace listener. - - - -## Examples - The following example creates a named `generalSwitch`. This switch is set outside the code sample. - - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. - - Then, if the is set to `Verbose`, the example outputs the second error message and the `category` on the same line as the first message. The second message is followed by a line terminator. - + . + + The `category` parameter can be used to group output messages. + + This method calls the method of the trace listener. + + + +## Examples + The following example creates a named `generalSwitch`. This switch is set outside the code sample. + + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + + Then, if the is set to `Verbose`, the example outputs the second error message and the `category` on the same line as the first message. The second message is followed by a line terminator. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.WriteLine2 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/WriteLine/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.WriteLine2 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.WriteLine2 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -3071,42 +3071,42 @@ Trace.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); An whose name is sent to the . Writes the value of the object's method to the trace listeners in the collection if a condition is . - . - - This method calls the method of the trace listener. - - - -## Examples - The following example creates a named `generalSwitch`. This switch is set outside the code sample. - - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. - - Then, if the is set to `Verbose`, the example outputs the name of the object on the same line as the first message. The second message is followed by a line terminator. - + . + + This method calls the method of the trace listener. + + + +## Examples + The following example creates a named `generalSwitch`. This switch is set outside the code sample. + + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + + Then, if the is set to `Verbose`, the example outputs the name of the object on the same line as the first message. The second message is followed by a line terminator. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.WriteLineIf1 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/WriteLineIf/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.WriteLineIf1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.WriteLineIf1 Example/VB/source.vb" id="Snippet1"::: + ]]> - You can minimize the performance penalty of instrumenting your application by using statements instead of using statements. The following two code examples send the same debugging message. However, the first example is much faster when tracing is off, because if mySwitch.TraceError evaluates to you do not call . The second example always calls , even when mySwitch.TraceError is and no tracing output is produced. This can result in unnecessary execution of arbitrarily complex code. - - **First example** - -```csharp -if(mySwitch.TraceError) - Trace.WriteLine("aNumber = " + aNumber + " out of range"); -``` - - **Second example** - -```csharp -Trace.WriteLineIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); + You can minimize the performance penalty of instrumenting your application by using statements instead of using statements. The following two code examples send the same debugging message. However, the first example is much faster when tracing is off, because if mySwitch.TraceError evaluates to you do not call . The second example always calls , even when mySwitch.TraceError is and no tracing output is produced. This can result in unnecessary execution of arbitrarily complex code. + + **First example** + +```csharp +if(mySwitch.TraceError) + Trace.WriteLine("aNumber = " + aNumber + " out of range"); +``` + + **Second example** + +```csharp +Trace.WriteLineIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); ``` @@ -3171,42 +3171,42 @@ Trace.WriteLineIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range") A message to write. Writes a message to the trace listeners in the collection if a condition is . - . - - This method calls the method of the trace listener. - - - -## Examples - The following example creates a named `generalSwitch`. This switch is set outside the code sample. - - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. - - Then, if the is set to `Verbose`, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator. - + . + + This method calls the method of the trace listener. + + + +## Examples + The following example creates a named `generalSwitch`. This switch is set outside the code sample. + + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + + Then, if the is set to `Verbose`, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.WriteIf Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/WriteIf/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.WriteIf Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.WriteIf Example/VB/source.vb" id="Snippet1"::: + ]]> - You can minimize the performance penalty of instrumenting your application by using statements instead of using statements. The following two code examples send the same debugging message. However, the first example is much faster when tracing is off, because if mySwitch.TraceError evaluates to you do not call . The second example always calls , even when mySwitch.TraceError is and no tracing output is produced. This can result in unnecessary execution of arbitrarily complex code. - - **First example** - -```csharp -if(mySwitch.TraceError) - Trace.WriteLine("aNumber = " + aNumber + " out of range"); -``` - - **Second example** - -```csharp -Trace.WriteLineIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); + You can minimize the performance penalty of instrumenting your application by using statements instead of using statements. The following two code examples send the same debugging message. However, the first example is much faster when tracing is off, because if mySwitch.TraceError evaluates to you do not call . The second example always calls , even when mySwitch.TraceError is and no tracing output is produced. This can result in unnecessary execution of arbitrarily complex code. + + **First example** + +```csharp +if(mySwitch.TraceError) + Trace.WriteLine("aNumber = " + aNumber + " out of range"); +``` + + **Second example** + +```csharp +Trace.WriteLineIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); ``` @@ -3273,44 +3273,44 @@ Trace.WriteLineIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range") A category name used to organize the output. Writes a category name and the value of the object's method to the trace listeners in the collection if a condition is . - . - - The `category` parameter can be used to group output messages. - - This method calls the method of the trace listener. - - - -## Examples - The following example creates a named `generalSwitch`. This switch is set outside the code sample. - - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. - - Then, if the is set to `Verbose`, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator. - + . + + The `category` parameter can be used to group output messages. + + This method calls the method of the trace listener. + + + +## Examples + The following example creates a named `generalSwitch`. This switch is set outside the code sample. + + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + + Then, if the is set to `Verbose`, the example outputs the second error message on the same line as the first message. The second message is followed by a line terminator. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.WriteLineIf3 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/WriteLineIf/source2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.WriteLineIf3 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.WriteLineIf3 Example/VB/source.vb" id="Snippet1"::: + ]]> - You can minimize the performance penalty of instrumenting your application by using statements instead of using statements. The following two code examples send the same debugging message. However, the first example is much faster when tracing is off, because if mySwitch.TraceError evaluates to you do not call . The second example always calls , even when mySwitch.TraceError is and no tracing output is produced. This can result in unnecessary execution of arbitrarily complex code. - - **First example** - -```csharp -if(mySwitch.TraceError) - Trace.WriteLine("aNumber = " + aNumber + " out of range"); -``` - - **Second example** - -```csharp -Trace.WriteLineIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); + You can minimize the performance penalty of instrumenting your application by using statements instead of using statements. The following two code examples send the same debugging message. However, the first example is much faster when tracing is off, because if mySwitch.TraceError evaluates to you do not call . The second example always calls , even when mySwitch.TraceError is and no tracing output is produced. This can result in unnecessary execution of arbitrarily complex code. + + **First example** + +```csharp +if(mySwitch.TraceError) + Trace.WriteLine("aNumber = " + aNumber + " out of range"); +``` + + **Second example** + +```csharp +Trace.WriteLineIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); ``` @@ -3377,44 +3377,44 @@ Trace.WriteLineIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range") A category name used to organize the output. Writes a category name and message to the trace listeners in the collection if a condition is . - . - - The `category` parameter can be used to group output messages. - - This method calls the method of the trace listener. - - - -## Examples - The following example creates a named `generalSwitch`. This switch is set outside the code sample. - - If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. - - Then, if the is set to `Verbose`, the example outputs the second error message and the `category` on the same line as the first message. The second message is followed by a line terminator. - + . + + The `category` parameter can be used to group output messages. + + This method calls the method of the trace listener. + + + +## Examples + The following example creates a named `generalSwitch`. This switch is set outside the code sample. + + If the switch is set to the `Error` or higher, the example outputs the first error message to the . For information on adding a listener to the collection, see the class. + + Then, if the is set to `Verbose`, the example outputs the second error message and the `category` on the same line as the first message. The second message is followed by a line terminator. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.WriteLineIf2 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Trace/WriteLineIf/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.WriteLineIf2 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Trace.WriteLineIf2 Example/VB/source.vb" id="Snippet1"::: + ]]> - You can minimize the performance penalty of instrumenting your application by using statements instead of using statements. The following two code examples send the same debugging message. However, the first example is much faster when tracing is off, because if mySwitch.TraceError evaluates to you do not call . The second example always calls , even when mySwitch.TraceError is and no tracing output is produced. This can result in unnecessary execution of arbitrarily complex code. - - **First example** - -```csharp -if(mySwitch.TraceError) - Trace.WriteLine("aNumber = " + aNumber + " out of range"); -``` - - **Second example** - -```csharp -Trace.WriteLineIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); + You can minimize the performance penalty of instrumenting your application by using statements instead of using statements. The following two code examples send the same debugging message. However, the first example is much faster when tracing is off, because if mySwitch.TraceError evaluates to you do not call . The second example always calls , even when mySwitch.TraceError is and no tracing output is produced. This can result in unnecessary execution of arbitrarily complex code. + + **First example** + +```csharp +if(mySwitch.TraceError) + Trace.WriteLine("aNumber = " + aNumber + " out of range"); +``` + + **Second example** + +```csharp +Trace.WriteLineIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); ``` diff --git a/xml/System.Reflection.Emit/TypeBuilder.xml b/xml/System.Reflection.Emit/TypeBuilder.xml index 5e9160077b3..57ac7fbec80 100644 --- a/xml/System.Reflection.Emit/TypeBuilder.xml +++ b/xml/System.Reflection.Emit/TypeBuilder.xml @@ -4674,7 +4674,7 @@ See for a description of the format of the ## Remarks The method provides a way to get a object that represents a constructor of a constructed generic type whose generic type definition is represented by a object. - For example, suppose you have a object that represents the type `G` in C# syntax (`G(Of T)` in Visual Basic, `generic ref class G` in C++) and a object that represents a constructor of `G`. Suppose that `G` has a generic method with type parameter `U` that creates an instance of the constructed type `G`. In order to emit the code to create an instance of the constructed type, you need a object that represents the constructor of this constructed type - in other words, that creates an instance of `G`. To do this, first call the method on the object, specifying the object that represents `U` as the type argument. Then call the method with the return value of the method as parameter `type` and the object that represents the constructor of `G` as parameter `constructor`. The return value is the object you need to emit the function call. The code example demonstrates this scenario. + For example, suppose you have a object that represents the type `G` in C# syntax (`G(Of T)` in Visual Basic) and a object that represents a constructor of `G`. Suppose that `G` has a generic method with type parameter `U` that creates an instance of the constructed type `G`. In order to emit the code to create an instance of the constructed type, you need a object that represents the constructor of this constructed type - in other words, that creates an instance of `G`. To do this, first call the method on the object, specifying the object that represents `U` as the type argument. Then call the method with the return value of the method as parameter `type` and the object that represents the constructor of `G` as parameter `constructor`. The return value is the object you need to emit the function call. The code example demonstrates this scenario. @@ -5340,7 +5340,7 @@ See for a description of the format of the ## Remarks The method provides a way to get a object that represents a field of a constructed generic type whose generic type definition is represented by a object. - For example, suppose you have a object that represents the type `G` in C# syntax (`G(Of T)` in Visual Basic, `generic ref class G` in C++) and a object that represents a field `public T F` in C# syntax (`Public F As T` in Visual Basic, `public: T F` in C++) that is defined by `G`. Suppose that `G` has a generic method with type parameter `U` that creates an instance of the constructed type `G` and calls field `F` on that instance. In order to emit the function call, you need a object that represents `F` on the constructed type - in other words, that is of type `U` rather than type `T`. To do this, first call the method on the object, specifying the object that represents `U` as the type argument. Then call the method with the return value of the method as parameter `type` and the object that represents `F` as parameter `field`. The return value is the object you need to emit the function call. The code example demonstrates this scenario. + For example, suppose you have a object that represents the type `G` in C# syntax (`G(Of T)` in Visual Basic) and a object that represents a field `public T F` in C# syntax (`Public F As T` in Visual Basic) that's defined by `G`. Suppose that `G` has a generic method with type parameter `U` that creates an instance of the constructed type `G` and calls field `F` on that instance. In order to emit the function call, you need a object that represents `F` on the constructed type - in other words, that is of type `U` rather than type `T`. To do this, first call the method on the object, specifying the object that represents `U` as the type argument. Then call the method with the return value of the method as parameter `type` and the object that represents `F` as parameter `field`. The return value is the object you need to emit the function call. The code example demonstrates this scenario. @@ -5939,7 +5939,7 @@ See for a description of the format of the ## Remarks The method provides a way to get a object that represents a method of a constructed generic type whose generic type definition is represented by a object. - For example, suppose you have a object that represents the type `G` in C# syntax (`G(Of T)` in Visual Basic, `generic ref class G` in C++) and a object that represents a method `T M()` in C# syntax (`Function M() As T` in Visual Basic, `T M()` in C++) that is defined by `G`. Suppose that `G` has a generic method with type parameter `U` that creates an instance of the constructed type `G` and calls method `M` on that instance. In order to emit the function call, you need a object that represents `M` on the constructed type - in other words, that returns type `U` rather than type `T`. To do this, first call the method on the object, specifying the object that represents `U` as the type argument. Then call the method with the return value of the method as parameter `type` and the object that represents `T M()` as parameter `method`. The return value is the object you need to emit the function call. The code example demonstrates a scenario similar to this. + For example, suppose you have a object that represents the type `G` in C# syntax (`G(Of T)` in Visual Basic) and a object that represents a method `T M()` in C# syntax (`Function M() As T` in Visual Basic) that is defined by `G`. Suppose that `G` has a generic method with type parameter `U` that creates an instance of the constructed type `G` and calls method `M` on that instance. In order to emit the function call, you need a object that represents `M` on the constructed type - in other words, that returns type `U` rather than type `T`. To do this, first call the method on the object, specifying the object that represents `U` as the type argument. Then call the method with the return value of the method as parameter `type` and the object that represents `T M()` as parameter `method`. The return value is the object you need to emit the function call. The code example demonstrates a scenario similar to this. diff --git a/xml/System.Reflection/AssemblyDelaySignAttribute.xml b/xml/System.Reflection/AssemblyDelaySignAttribute.xml index 74fc664fd72..df73e0add59 100644 --- a/xml/System.Reflection/AssemblyDelaySignAttribute.xml +++ b/xml/System.Reflection/AssemblyDelaySignAttribute.xml @@ -80,7 +80,7 @@ For more information, see the [Common Language Infrastructure (CLI) documentatio sn -k TestPublicKey.snk ``` - Compile the example as a .dll. If you compile from the command line, use the `/t:library` option for C# or Visual Basic, or the `/LD` linker option for Visual C++. + Compile the example as a .dll. If you compile from the command line, use the `/t:library` option. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyDelaySignAttribute/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyDelaySignAttribute/Overview/source.cs" id="Snippet1"::: diff --git a/xml/System.Reflection/AssemblyKeyFileAttribute.xml b/xml/System.Reflection/AssemblyKeyFileAttribute.xml index e88238e6a3b..686d82cfcee 100644 --- a/xml/System.Reflection/AssemblyKeyFileAttribute.xml +++ b/xml/System.Reflection/AssemblyKeyFileAttribute.xml @@ -68,31 +68,31 @@ Specifies the name of a file containing the key pair used to generate a strong name. - . If has also been specified, it is likely that this file will only contain the public key. - - An example of the syntax is `[assembly:AssemblyKeyFileAttribute("myKey.snk")]`. - + . If has also been specified, it is likely that this file will only contain the public key. + + An example of the syntax is `[assembly:AssemblyKeyFileAttribute("myKey.snk")]`. + > [!CAUTION] -> Since the path and file name persist, ensure that the string you use with `AssemblyKeyFileAttribute` does not contain sensitive information. - - - -## Examples - The following code example shows the use of the attribute with the . To compile this example, you must create a strong-name key file named TestPublicKey.snk using the [Sn.exe (Strong Name Tool)](/dotnet/framework/tools/sn-exe-strong-name-tool): - -```console -sn -k TestPublicKey.snk -``` - - Compile the example as a .dll. If you compile from the command line, use the `/t:library` option for C# or Visual Basic, or the `/LD` linker option for Visual C++. - +> Since the path and file name persist, ensure that the string you use with `AssemblyKeyFileAttribute` does not contain sensitive information. + + + +## Examples + The following code example shows the use of the attribute with the . To compile this example, you must create a strong-name key file named TestPublicKey.snk using the [Sn.exe (Strong Name Tool)](/dotnet/framework/tools/sn-exe-strong-name-tool): + +```console +sn -k TestPublicKey.snk +``` + + Compile the example as a .dll. If you compile from the command line, use the `/t:library` option. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyDelaySignAttribute/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyDelaySignAttribute/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyDelaySignAttribute/vb/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyDelaySignAttribute/vb/source.vb" id="Snippet1"::: + ]]> Metadata and Self-Describing Components @@ -142,16 +142,16 @@ sn -k TestPublicKey.snk The name of the file containing the key pair. Initializes a new instance of the class with the name of the file containing the key pair to generate a strong name for the assembly being attributed. - constructor. The value set by the constructor is interpreted by the linker, or by Microsoft Visual Studio 2005, that invokes the linker. - - The default setting for the [Al.exe (Assembly Linker)](/dotnet/framework/tools/al-exe-assembly-linker) tool assumes that the key file is in the current directory. In Visual Studio 2005, the Visual Basic and Visual C# compilers build and link to subdirectories of the project directory, so if you put the key file in the project directory the relative path might be "..\\..\keyfile.snk" or "..\keyfile.snk" in Visual Basic, or "..\\\\..\\\keyfile.snk" or "..\\\keyfile.snk" in C#. For C#, this attribute can be set in the project properties. - + constructor. The value set by the constructor is interpreted by the linker, or by Microsoft Visual Studio 2005, that invokes the linker. + + The default setting for the [Al.exe (Assembly Linker)](/dotnet/framework/tools/al-exe-assembly-linker) tool assumes that the key file is in the current directory. In Visual Studio 2005, the Visual Basic and Visual C# compilers build and link to subdirectories of the project directory, so if you put the key file in the project directory the relative path might be "..\\..\keyfile.snk" or "..\keyfile.snk" in Visual Basic, or "..\\\\..\\\keyfile.snk" or "..\\\keyfile.snk" in C#. For C#, this attribute can be set in the project properties. + > [!CAUTION] -> Because the path and file name persist, ensure that the string you use with `AssemblyKeyFileAttribute` does not contain sensitive information. - +> Because the path and file name persist, ensure that the string you use with `AssemblyKeyFileAttribute` does not contain sensitive information. + ]]> @@ -199,13 +199,13 @@ sn -k TestPublicKey.snk Gets the name of the file containing the key pair used to generate a strong name for the attributed assembly. A string containing the name of the file that contains the key pair. - [!CAUTION] -> Because the path and file name persist, ensure that the string you use with `AssemblyKeyFileAttribute` does not contain sensitive information. - +> Because the path and file name persist, ensure that the string you use with `AssemblyKeyFileAttribute` does not contain sensitive information. + ]]> diff --git a/xml/System.Reflection/FieldInfo.xml b/xml/System.Reflection/FieldInfo.xml index 6b3e9afcc34..7e87c54a3f9 100644 --- a/xml/System.Reflection/FieldInfo.xml +++ b/xml/System.Reflection/FieldInfo.xml @@ -1103,9 +1103,7 @@ Note: In .NET for Win ## Remarks The actual visibility of a field is limited by the visibility of its type. The property might be `true` for a field, but if it is a field of a private nested type then the field is not visible outside the containing type. - The visibility of a field is exactly described by if the only visibility modifier is `internal` (`Friend` in Visual Basic). This property is `false` for fields that are `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++); use the property to identify such fields. - - + The visibility of a field is exactly described by if the only visibility modifier is `internal` (`Friend` in Visual Basic). This property is `false` for fields that are `protected internal` in C# (`Protected Friend` in Visual Basic); use the property to identify such fields. ## Examples The following code example defines fields with varying levels of visibility, and displays the values of their , , , and properties. @@ -1174,9 +1172,7 @@ Note: In .NET for Win if the only visibility modifier is `protected`. This property is `false` for fields that are `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++); use the property to identify such fields. - - + The visibility of a field is exactly described by if the only visibility modifier is `protected`. This property is `false` for fields that are `protected internal` in C# (`Protected Friend` in Visual Basic); use the property to identify such fields. ## Examples The following code example defines fields with varying levels of visibility, and displays the values of their , , , and properties. @@ -1249,14 +1245,11 @@ Note: In .NET for Win ## Remarks If a field has level visibility, it can be called from any member in a derived class that is also in the same assembly, but not from any other type. - The visibility of a field is exactly described by if the visibility modifier is `private protected` in C#, `Private Protected` in Visual Basic, or `protected private` in C++. - - + The visibility of a field is exactly described by if the visibility modifier is `private protected` in C# or `Private Protected` in Visual Basic. ## Examples The following code example defines fields with varying levels of visibility, and displays the values of their , , , and properties. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic FieldInfo.IsAssembly Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/FieldInfo/IsAssembly/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic FieldInfo.IsAssembly Example/VB/source.vb" id="Snippet1"::: @@ -1325,14 +1318,11 @@ Note: In .NET for Win The actual visibility of a field is limited by the visibility of its type. The property might be `true` for a field, but if it is a field of a private nested type then the field is not visible outside the containing type. - The visibility of a field is exactly described by if the visibility modifier is `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++). - - + The visibility of a field is exactly described by if the visibility modifier is `protected internal` in C# (`Protected Friend` in Visual Basic). ## Examples The following code example defines fields with varying levels of visibility, and displays the values of their , , , and properties. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic FieldInfo.IsAssembly Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/FieldInfo/IsAssembly/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic FieldInfo.IsAssembly Example/VB/source.vb" id="Snippet1"::: diff --git a/xml/System.Reflection/MethodBase.xml b/xml/System.Reflection/MethodBase.xml index c646944a5b2..ece55bab79c 100644 --- a/xml/System.Reflection/MethodBase.xml +++ b/xml/System.Reflection/MethodBase.xml @@ -825,7 +825,7 @@ ## Remarks Handles are valid only in the application domain in which they were obtained. - A structure for a constructor or method of a generic type can represent different objects, depending on the types specified for the type parameters of the generic type. For example, if `class G` (`class G(Of T)` in Visual Basic, `generic ref class G` in C++) has a method that returns type `T`, the object for that method in a constructed class such as `G` is different from the object for that method in the generic type definition. + A structure for a constructor or method of a generic type can represent different objects, depending on the types specified for the type parameters of the generic type. For example, if `class G` (`class G(Of T)` in Visual Basic) has a method that returns type `T`, the object for that method in a constructed class such as `G` is different from the object for that method in the generic type definition. ]]> @@ -1370,9 +1370,7 @@ This method dynamically invokes the method reflected by this instance on `obj`, ## Remarks The actual visibility of a method is limited by the visibility of its type. The property might be `true` for a method, but if it is a method of a private nested type then the method is not visible outside the containing type. - The visibility of a method or constructor is exactly described by if the only visibility modifier is `internal` (`Friend` in Visual Basic). This property is `false` for methods that are `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++); use the property to identify such methods. - - + The visibility of a method or constructor is exactly described by if the only visibility modifier is `internal` (`Friend` in Visual Basic). This property is `false` for methods that are `protected internal` in C# (`Protected Friend` in Visual Basic); use the property to identify such methods. ## Examples The following code example defines methods with varying levels of visibility, and displays the values of their , , , and properties. @@ -1546,9 +1544,7 @@ This method dynamically invokes the method reflected by this instance on `obj`, if the only visibility modifier is `protected`. This property is `false` for methods that are `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++); use the property to identify such methods. - - + The visibility of a method or constructor is exactly described by if the only visibility modifier is `protected`. This property is `false` for methods that are `protected internal` in C# (`Protected Friend` in Visual Basic); use the property to identify such methods. ## Examples The following code example defines methods with varying levels of visibility, and displays the values of their , , , and properties. @@ -1617,9 +1613,7 @@ This method dynamically invokes the method reflected by this instance on `obj`, if the visibility modifier is `private protected` in C#, `Private Protected` in Visual Basic, or `protected private` in C++. - - + The visibility of a method or constructor is exactly described by if the visibility modifier is `private protected` in C# or `Private Protected` in Visual Basic. ## Examples The following code example defines methods with varying levels of visibility, and displays the values of their , , , and properties. @@ -1692,9 +1686,7 @@ This method dynamically invokes the method reflected by this instance on `obj`, The actual visibility of a method is limited by the visibility of its type. The property might be `true` for a method, but if it is a method of a private nested type then the method is not visible outside the containing type. - The visibility of a method or constructor is exactly described by if the visibility modifier is `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++). - - + The visibility of a method or constructor is exactly described by if the visibility modifier is `protected internal` in C# (`Protected Friend` in Visual Basic). ## Examples The following code example defines methods with varying levels of visibility, and displays the values of their , , , and properties. @@ -1764,7 +1756,7 @@ This method dynamically invokes the method reflected by this instance on `obj`, ## Remarks -If the virtual method is marked `final`, it can't be overridden in derived classes. The overridden virtual method can be marked `final` using the [sealed](/dotnet/csharp/language-reference/keywords/sealed) keyword in C#, [NotOverridable](/dotnet/visual-basic/language-reference/modifiers/notoverridable) keyword in Visual Basic, or [sealed](/cpp/extensions/sealed-cpp-component-extensions) keyword in C++/CLI. The method can also be marked `final` implicitly by the compiler. For example, a method might be defined as non-virtual in your code, but it implements an interface method. The Common Language Runtime requires that all methods that implement interface members must be marked as `virtual`; therefore, the compiler marks the method `virtual final`. +If the virtual method is marked `final`, it can't be overridden in derived classes. The overridden virtual method can be marked `final` using the [sealed](/dotnet/csharp/language-reference/keywords/sealed) keyword in C# or [NotOverridable](/dotnet/visual-basic/language-reference/modifiers/notoverridable) keyword in Visual Basic. The method can also be marked `final` implicitly by the compiler. For example, a method might be defined as non-virtual in your code, but it implements an interface method. The Common Language Runtime requires that all methods that implement interface members must be marked as `virtual`; therefore, the compiler marks the method `virtual final`. You can use this property, in conjunction with the property, to determine if a method is overridable. For a method to be overridable, property must be `true` and `IsFinal` property must be `false`. To establish with certainty whether a method is overridable, use code such as this: @@ -1778,8 +1770,6 @@ If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then If `IsVirtual` is `false` or `IsFinal` is `true`, then the method cannot be overridden. - - ## Examples The following example displays `false` for `IsFinal`, which might lead you to think that MyMethod is overridable. The code prints `false` even though MyMethod is not marked `virtual` and thus cannot be overridden. diff --git a/xml/System.Reflection/PropertyInfo.xml b/xml/System.Reflection/PropertyInfo.xml index 10de1965426..3b636fe94cf 100644 --- a/xml/System.Reflection/PropertyInfo.xml +++ b/xml/System.Reflection/PropertyInfo.xml @@ -98,13 +98,13 @@ Properties are logically the same as fields. A property is a named aspect of an object's state whose value is typically accessible through `get` and `set` accessors. Properties may be read-only, in which case a set routine is not supported. > [!NOTE] -> To determine whether a property is `static`, you must obtain the for the `get` or `set` accessor, by calling the or the method, and examine its property. +> To determine whether a property is `static`, you must obtain the for the `get` or `set` accessor, by calling the or the method, and examine its property. Several methods in this class assume that the `get` accessor and `set` accessor methods of a property have certain formats. The signatures of the `get` and `set` methods must match the following convention: -- The return type of the `get` method and the last argument of the `set` method must be identical. This is the type of the property. +- The return type of the `get` method and the last argument of the `set` method must be identical. This is the type of the property. -- The `get` and `set` methods must have the same number, type, and order of indices. +- The `get` and `set` methods must have the same number, type, and order of indices. If this format is not followed, the behavior of the `GetValue` and `SetValue` methods is undefined. @@ -116,7 +116,7 @@ This example shows how to use various reflection classes to analyze the metadata contained in an assembly. > [!NOTE] -> This example generates about 55,000 lines of data, which you can redirect to a text file at the command prompt, as follows: **example.exe > propertyinfo.txt** +> This example generates about 55,000 lines of data, which you can redirect to a text file at the command prompt, as follows: **example.exe > propertyinfo.txt** :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Reflection/CPP/reflection.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/Assembly/GetReferencedAssemblies/Reflection.cs" id="Snippet1"::: @@ -224,7 +224,7 @@ The property returns the attributes associated with the property represented by this object. The attributes are primarily modifiers applied by a compiler when creating a property; they indicate whether a property is the default property, a `SpecialName` property, and so on. Note that, for almost all properties found in types in the .NET Framework class library, the value of the property is . > [!TIP] -> In most cases, you probably want to retrieve the custom attributes associated with a property. To do this, retrieve the value of the property, or call one of the overloads of the method. +> In most cases, you probably want to retrieve the custom attributes associated with a property. To do this, retrieve the value of the property, or call one of the overloads of the method. To get the property: @@ -647,7 +647,7 @@ This method is provided for designers of managed compilers and code analyzers. > [!NOTE] -> Do not use this method in the reflection-only context, because it might cause code to execute. Use the method instead. +> Do not use this method in the reflection-only context, because it might cause code to execute. Use the method instead. In unmanaged metadata, the Constant table is used to store constant values for fields, parameters, and properties. Constant information does not directly influence runtime behavior. Compilers inspect this information, at compile time, when importing metadata. If used, the value of a constant is embedded in the Microsoft intermediate language (MSIL) stream the compiler emits. There are no MSIL instructions that can be used to access the Constant table at run time. @@ -1532,7 +1532,7 @@ Console.WriteLine("CurrCult: " + To use the `GetValue` method, first get the class `Type`. From the `Type`, get the `PropertyInfo`. From the `PropertyInfo`, use the `GetValue` method. > [!NOTE] -> Starting with .NET Framework 2.0, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. +> Starting with .NET Framework 2.0, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. @@ -1634,7 +1634,7 @@ Console.WriteLine("CurrCult: " + To use the `GetValue` method, first get the class `Type`. From the `Type`, get the `PropertyInfo`. From the `PropertyInfo`, use the `GetValue` method. > [!NOTE] -> Starting with .NET Framework 2.0, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. +> Starting with .NET Framework 2.0, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. ]]> @@ -2100,9 +2100,7 @@ Console.WriteLine("CurrCult: " + To use the method, first get a object that represents the class. From the , get the object. From the object, call the method. > [!NOTE] -> Starting with .NET Framework 2.0, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. - - +> Starting with .NET Framework 2.0, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. ## Examples The following example declares a class named `Example` with one `static` (`Shared` in Visual Basic) and one instance property. The example uses the method to change the original property values and displays the original and final values. @@ -2205,9 +2203,7 @@ Note: In attribute to give the indexer a different name. In this example, the name is `IndexedInstanceProperty`. +- In Visual Basic, the property name is always used to search for the property with reflection. You can use the `Default` keyword to make the property a default indexed property, in which case you can omit the name when accessing the property, as in this example. You can also use the property name. -- In C++, the `default` specifier can be used to make an indexed property a default indexed property (class indexer). In that case, the name of the property by default is `Item`, and you must use that name when you search for the property with reflection, as in this example. You can use the attribute to give the class indexer a different name in reflection, but you cannot use that name to access the property in code. An indexed property that is not a class indexer is accessed using its name, both in code and in reflection. +- In C#, the indexed instance property is a default property called an indexer, and the name is never used when accessing the property in code. By default, the name of the property is `Item`, and you must use that name when you search for the property with reflection. You can use the attribute to give the indexer a different name. In this example, the name is `IndexedInstanceProperty`. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/PropertyInfo.SetValue/cpp/Example.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/PropertyInfo/SetValue/Example.cs" id="Snippet1"::: @@ -2324,7 +2318,7 @@ Note: In to include the in the filtered list; otherwise . - objects. The method uses this delegate to filter the list of interfaces that it returns. Every derived class of and has a constructor and a `DynamicInvoke` method. See the Visual C++ code example given in the description for `Delegate`. - - - -## Examples - This example shows how to define a method matching the delegate prototype allowing you to use reflection to filter or return a subset of matching entries. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/TypeFilter/VB/Typefilter.vb" id="Snippet1"::: - + objects. The method uses this delegate to filter the list of interfaces that it returns. Every derived class of and has a constructor and a `DynamicInvoke` method. + +## Examples + This example shows how to define a method matching the delegate prototype allowing you to use reflection to filter or return a subset of matching entries. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/TypeFilter/VB/Typefilter.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Runtime.CompilerServices/CallConvCdecl.xml b/xml/System.Runtime.CompilerServices/CallConvCdecl.xml index 6794fef3551..9b5fec47e9f 100644 --- a/xml/System.Runtime.CompilerServices/CallConvCdecl.xml +++ b/xml/System.Runtime.CompilerServices/CallConvCdecl.xml @@ -61,25 +61,25 @@ Indicates that a method should use the calling convention. - are for compiler writers' use only. - - Compilers emit custom modifiers within metadata to change the way that the just-in-time (JIT) compiler handles values when the default behavior is not appropriate. When the JIT compiler encounters a custom modifier, it handles the value in the way that the modifier specifies. Compilers can apply custom modifiers to methods, parameters, and return values. The JIT compiler must respond to required modifiers but can ignore optional modifiers. A C++ compiler could emit a custom modifier to describe how a byte should be treated in cases where the JIT compiler treats bytes in a manner that is not compatible with C++ by default. - - You can emit custom modifiers into metadata using one of the following techniques: - -- Using methods in the class such as , , , and . - -- Generating a Microsoft intermediate language (MSIL) instruction file that contains calls to `modopt` and `modreq`, and assembling the file with the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). - -- Using the unmanaged reflection API. - + are for compiler writers' use only. + + Compilers emit custom modifiers within metadata to change the way that the just-in-time (JIT) compiler handles values when the default behavior is not appropriate. When the JIT compiler encounters a custom modifier, it handles the value in the way that the modifier specifies. Compilers can apply custom modifiers to methods, parameters, and return values. The JIT compiler must respond to required modifiers but can ignore optional modifiers. A C++ compiler could emit a custom modifier to describe how a byte should be treated in cases where the JIT compiler treats bytes in a manner that is not compatible with C++ by default. + + You can emit custom modifiers into metadata using one of the following techniques: + +- Using methods in the class such as , , , and . + +- Generating a Microsoft intermediate language (MSIL) instruction file that contains calls to `modopt` and `modreq`, and assembling the file with the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). + +- Using the unmanaged reflection API. + ]]> @@ -123,11 +123,11 @@ Initializes a new instance of the class. - are for compiler writers' use only. - + are for compiler writers' use only. + ]]> diff --git a/xml/System.Runtime.CompilerServices/CallConvFastcall.xml b/xml/System.Runtime.CompilerServices/CallConvFastcall.xml index 917305da7ab..8cc4b418066 100644 --- a/xml/System.Runtime.CompilerServices/CallConvFastcall.xml +++ b/xml/System.Runtime.CompilerServices/CallConvFastcall.xml @@ -61,23 +61,23 @@ This calling convention is not supported in this version of .NET. - are for compiler writers' use only. - - Compilers emit custom modifiers within metadata to change the way that the just-in-time (JIT) compiler handles values when the default behavior is not appropriate. When the JIT compiler encounters a custom modifier, it handles the value in the way that the modifier specifies. Compilers can apply custom modifiers to methods, parameters, and return values. The JIT compiler must respond to required modifiers but can ignore optional modifiers. A C++ compiler could emit a custom modifier to describe how a byte should be treated in cases where the JIT compiler treats bytes in manner that is not compatible with C++ by default. - - You can emit custom modifiers into metadata using one of the following techniques: - -- Using methods in the class like , , , and . - -- Generating a Microsoft intermediate language (MSIL) instruction file that contains calls to `modopt` and `modreq`, and assembling the file with the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). - -- Using the unmanaged reflection API. - + are for compiler writers' use only. + + Compilers emit custom modifiers within metadata to change the way that the just-in-time (JIT) compiler handles values when the default behavior is not appropriate. When the JIT compiler encounters a custom modifier, it handles the value in the way that the modifier specifies. Compilers can apply custom modifiers to methods, parameters, and return values. The JIT compiler must respond to required modifiers but can ignore optional modifiers. A C++ compiler could emit a custom modifier to describe how a byte should be treated in cases where the JIT compiler treats bytes in manner that is not compatible with C++ by default. + + You can emit custom modifiers into metadata using one of the following techniques: + +- Using methods in the class like , , , and . + +- Generating a Microsoft intermediate language (MSIL) instruction file that contains calls to `modopt` and `modreq`, and assembling the file with the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). + +- Using the unmanaged reflection API. + ]]> @@ -121,11 +121,11 @@ Initializes a new instance of the class. - are for compiler writers' use only. - + are for compiler writers' use only. + ]]> diff --git a/xml/System.Runtime.CompilerServices/CallConvStdcall.xml b/xml/System.Runtime.CompilerServices/CallConvStdcall.xml index 6475f7e545c..f612c2d110c 100644 --- a/xml/System.Runtime.CompilerServices/CallConvStdcall.xml +++ b/xml/System.Runtime.CompilerServices/CallConvStdcall.xml @@ -61,23 +61,23 @@ Indicates that a method should use the calling convention. - are for compiler writers' use only. - - Compilers emit custom modifiers within metadata to change the way that the just-in-time (JIT) compiler handles values when the default behavior is not appropriate. When the JIT compiler encounters a custom modifier, it handles the value in the way that the modifier specifies. Compilers can apply custom modifiers to methods, parameters, and return values. The JIT compiler must respond to required modifiers but can ignore optional modifiers. A C++ compiler could emit a custom modifier to describe how a byte should be treated in cases where the JIT compiler treats bytes in a manner that is not compatible with C++ by default. - - You can emit custom modifiers into metadata using one of the following techniques: - -- Using methods in the class such as , , , and . - -- Generating a Microsoft intermediate language (MSIL) instruction file that contains calls to `modopt` and `modreq`, and assembling the file with the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). - -- Using the unmanaged reflection API. - + are for compiler writers' use only. + + Compilers emit custom modifiers within metadata to change the way that the just-in-time (JIT) compiler handles values when the default behavior is not appropriate. When the JIT compiler encounters a custom modifier, it handles the value in the way that the modifier specifies. Compilers can apply custom modifiers to methods, parameters, and return values. The JIT compiler must respond to required modifiers but can ignore optional modifiers. A C++ compiler could emit a custom modifier to describe how a byte should be treated in cases where the JIT compiler treats bytes in a manner that is not compatible with C++ by default. + + You can emit custom modifiers into metadata using one of the following techniques: + +- Using methods in the class such as , , , and . + +- Generating a Microsoft intermediate language (MSIL) instruction file that contains calls to `modopt` and `modreq`, and assembling the file with the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). + +- Using the unmanaged reflection API. + ]]> @@ -121,11 +121,11 @@ Initializes a new instance of the class. - are for compiler writers' use only. - + are for compiler writers' use only. + ]]> diff --git a/xml/System.Runtime.CompilerServices/CallConvThiscall.xml b/xml/System.Runtime.CompilerServices/CallConvThiscall.xml index 991a87f15df..be1457695fe 100644 --- a/xml/System.Runtime.CompilerServices/CallConvThiscall.xml +++ b/xml/System.Runtime.CompilerServices/CallConvThiscall.xml @@ -61,23 +61,23 @@ Indicates that a method should use the calling convention. - are for compiler writers' use only. - - Compilers emit custom modifiers within metadata to change the way that the just-in-time (JIT) compiler handles values when the default behavior is not appropriate. When the JIT compiler encounters a custom modifier, it handles the value in the way that the modifier specifies. Compilers can apply custom modifiers to methods, parameters, and return values. The JIT compiler must respond to required modifiers but can ignore optional modifiers. A C++ compiler could emit a custom modifier to describe how a byte should be treated in cases where the JIT compiler treats bytes in a manner that is not compatible with C++ by default. - - You can emit custom modifiers into metadata using one of the following techniques: - -- Using methods in the class such as , , , and . - -- Generating a Microsoft intermediate language (MSIL) instruction file that contains calls to `modopt` and `modreq`, and assembling the file with the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). - -- Using the unmanaged reflection API. - + are for compiler writers' use only. + + Compilers emit custom modifiers within metadata to change the way that the just-in-time (JIT) compiler handles values when the default behavior is not appropriate. When the JIT compiler encounters a custom modifier, it handles the value in the way that the modifier specifies. Compilers can apply custom modifiers to methods, parameters, and return values. The JIT compiler must respond to required modifiers but can ignore optional modifiers. A C++ compiler could emit a custom modifier to describe how a byte should be treated in cases where the JIT compiler treats bytes in a manner that is not compatible with C++ by default. + + You can emit custom modifiers into metadata using one of the following techniques: + +- Using methods in the class such as , , , and . + +- Generating a Microsoft intermediate language (MSIL) instruction file that contains calls to `modopt` and `modreq`, and assembling the file with the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). + +- Using the unmanaged reflection API. + ]]> @@ -121,11 +121,11 @@ Initializes a new instance of the class. - are for compiler writers' use only. - + are for compiler writers' use only. + ]]> diff --git a/xml/System.Runtime.CompilerServices/FixedAddressValueTypeAttribute.xml b/xml/System.Runtime.CompilerServices/FixedAddressValueTypeAttribute.xml index c401e5b05bb..c15855e9480 100644 --- a/xml/System.Runtime.CompilerServices/FixedAddressValueTypeAttribute.xml +++ b/xml/System.Runtime.CompilerServices/FixedAddressValueTypeAttribute.xml @@ -54,22 +54,20 @@ Fixes the address of a static value type field throughout its lifetime. This class cannot be inherited. - attribute to mark static value types as pinned upon creation. - - This attribute is used by the Microsoft Visual C++ compiler. - - Static value type fields are created as boxed objects. This means that their address can change as garbage collection is performed. When you apply this attribute to a static value type, its address remains constant during its lifetime. - - - -## Examples - The following example illustrates the use of the attribute to pin a static field in memory. It defines an `Age` structure and initializes two classes that have static fields of type `Age`. The second class applies to pin the field's address. A number of memory allocations are made before and after these two objects are instantiated and the garbage collector is invoked. The output from the example shows that although the address of the first `Age` field has changed after garbage collection, the address of the field to which is applied has not. - - :::code language="csharp" source="~/snippets/csharp/System.Runtime.CompilerServices/FixedAddressValueTypeAttribute/Overview/example1.cs" id="Snippet1"::: - + attribute to mark static value types as pinned upon creation. + + This attribute is used by the Microsoft Visual C++ compiler. + + Static value type fields are created as boxed objects. This means that their address can change as garbage collection is performed. When you apply this attribute to a static value type, its address remains constant during its lifetime. + +## Examples + The following example illustrates the use of the attribute to pin a static field in memory. It defines an `Age` structure and initializes two classes that have static fields of type `Age`. The second class applies to pin the field's address. A number of memory allocations are made before and after these two objects are instantiated and the garbage collector is invoked. The output from the example shows that although the address of the first `Age` field has changed after garbage collection, the address of the field to which is applied has not. + + :::code language="csharp" source="~/snippets/csharp/System.Runtime.CompilerServices/FixedAddressValueTypeAttribute/Overview/example1.cs" id="Snippet1"::: + ]]> @@ -108,13 +106,13 @@ Initializes a new instance of the class. - attribute to pin a static field in memory. It defines an `Age` structure and initializes two classes that have static fields of type `Age`. The second class applies to pin the field's address. A number of memory allocations are made before and after these two objects are instantiated and the garbage collector is invoked. The output from the example shows that although the address of the first `Age` field has changed after garbage collection, the address of the field to which is applied has not. - - :::code language="csharp" source="~/snippets/csharp/System.Runtime.CompilerServices/FixedAddressValueTypeAttribute/Overview/example1.cs" id="Snippet1"::: - + attribute to pin a static field in memory. It defines an `Age` structure and initializes two classes that have static fields of type `Age`. The second class applies to pin the field's address. A number of memory allocations are made before and after these two objects are instantiated and the garbage collector is invoked. The output from the example shows that although the address of the first `Age` field has changed after garbage collection, the address of the field to which is applied has not. + + :::code language="csharp" source="~/snippets/csharp/System.Runtime.CompilerServices/FixedAddressValueTypeAttribute/Overview/example1.cs" id="Snippet1"::: + ]]> diff --git a/xml/System.Runtime.CompilerServices/IsBoxed.xml b/xml/System.Runtime.CompilerServices/IsBoxed.xml index 1da1912aaf7..748480dd134 100644 --- a/xml/System.Runtime.CompilerServices/IsBoxed.xml +++ b/xml/System.Runtime.CompilerServices/IsBoxed.xml @@ -44,28 +44,26 @@ Indicates that the modified reference type is a boxed value type. This class cannot be inherited. - class such as , , , and . - -- Generating a Microsoft intermediate language (MSIL) instruction file that contains calls to `modopt` and `modreq`, and assembling the file with the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). - -- Using the unmanaged reflection API. - - - -## Examples - The following example demonstrates how to emit an object into an assembly using reflection. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Runtime.CompilerServices.IsBoxed/cpp/sample.cpp" id="Snippet1"::: - + class such as , , , and . + +- Generating a Microsoft intermediate language (MSIL) instruction file that contains calls to `modopt` and `modreq`, and assembling the file with the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). + +- Using the unmanaged reflection API. + +## Examples + The following example demonstrates how to emit an object into an assembly using reflection. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Runtime.CompilerServices.IsBoxed/cpp/sample.cpp" id="Snippet1"::: + ]]> diff --git a/xml/System.Runtime.CompilerServices/IsConst.xml b/xml/System.Runtime.CompilerServices/IsConst.xml index 5998ee7c6a8..88deafeb1a9 100644 --- a/xml/System.Runtime.CompilerServices/IsConst.xml +++ b/xml/System.Runtime.CompilerServices/IsConst.xml @@ -47,28 +47,26 @@ Indicates that the modified type has a modifier. This class cannot be inherited. - class such as , , , and . - -- Generating a Microsoft intermediate language (MSIL) instruction file that contains calls to `modopt` and `modreq`, and assembling the file with the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). - -- Using the unmanaged reflection API. - - - -## Examples - The following example demonstrates how to emit an object into an assembly using reflection. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Runtime.CompilerServices.IsConst/cpp/sample.cpp" id="Snippet1"::: - + class such as , , , and . + +- Generating a Microsoft intermediate language (MSIL) instruction file that contains calls to `modopt` and `modreq`, and assembling the file with the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). + +- Using the unmanaged reflection API. + +## Examples + The following example demonstrates how to emit an object into an assembly using reflection. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Runtime.CompilerServices.IsConst/cpp/sample.cpp" id="Snippet1"::: + ]]> diff --git a/xml/System.Runtime.CompilerServices/IsCopyConstructed.xml b/xml/System.Runtime.CompilerServices/IsCopyConstructed.xml index 17d74b56a69..91118c6ed7c 100644 --- a/xml/System.Runtime.CompilerServices/IsCopyConstructed.xml +++ b/xml/System.Runtime.CompilerServices/IsCopyConstructed.xml @@ -48,25 +48,25 @@ - Indicates that any copying of values of this type must use the copy constructor provided by the type. This class cannot be inherited. + Indicates that any copying of values of this type must use the copy constructor provided by the type. This class cannot be inherited. - class must implement a method named `MarshalCopy` that calls the native copy constructor. - - Any native C++ type that is emitted into metadata with copy constructors needs to have those methods called by the marshaler when copying values across the marshaling boundary. The Microsoft C++ compiler modifies all native C++ types in method parameters and return types that have this modifier to trigger this behavior in the marshaling code. - - Compilers emit custom modifiers within metadata to change the way that the just-in-time (JIT) compiler handles values when the default behavior is not appropriate. When the JIT compiler encounters a custom modifier, it handles the value in the way that the modifier specifies. Compilers can apply custom modifiers to methods, parameters, and return values. The JIT compiler must respond to required modifiers but can ignore optional modifiers. - - You can emit custom modifiers into metadata using one of the following techniques: - -- Using methods in the class such as , , , and . - -- Generating a Microsoft intermediate language (MSIL) instruction file that contains calls to `modopt` and `modreq`, and assembling the file with the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). - -- Using the unmanaged reflection API. - + class must implement a method named `MarshalCopy` that calls the native copy constructor. + + Any native C++ type that is emitted into metadata with copy constructors needs to have those methods called by the marshaler when copying values across the marshaling boundary. The Microsoft C++ compiler modifies all native C++ types in method parameters and return types that have this modifier to trigger this behavior in the marshaling code. + + Compilers emit custom modifiers within metadata to change the way that the just-in-time (JIT) compiler handles values when the default behavior is not appropriate. When the JIT compiler encounters a custom modifier, it handles the value in the way that the modifier specifies. Compilers can apply custom modifiers to methods, parameters, and return values. The JIT compiler must respond to required modifiers but can ignore optional modifiers. + + You can emit custom modifiers into metadata using one of the following techniques: + +- Using methods in the class such as , , , and . + +- Generating a Microsoft intermediate language (MSIL) instruction file that contains calls to `modopt` and `modreq`, and assembling the file with the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). + +- Using the unmanaged reflection API. + ]]> diff --git a/xml/System.Runtime.CompilerServices/IsExplicitlyDereferenced.xml b/xml/System.Runtime.CompilerServices/IsExplicitlyDereferenced.xml index 73682ed3e20..ca4a3d7da2c 100644 --- a/xml/System.Runtime.CompilerServices/IsExplicitlyDereferenced.xml +++ b/xml/System.Runtime.CompilerServices/IsExplicitlyDereferenced.xml @@ -44,28 +44,26 @@ Indicates that a managed pointer represents a pointer parameter within a method signature. This class cannot be inherited. - class and its partner, the class, disambiguate reference parameters from pointer parameters. - - Compilers emit custom modifiers within metadata to change the way that the just-in-time (JIT) compiler handles values when the default behavior is not appropriate. When the JIT compiler encounters a custom modifier, it handles the value in the way that the modifier specifies. Compilers can apply custom modifiers to methods, parameters, and return values. The JIT compiler must respond to required modifiers but can ignore optional modifiers. - - You can emit custom modifiers into metadata using one of the following techniques: - -- Using methods in the class such as , , , and . - -- Generating a Microsoft intermediate language (MSIL) instruction file that contains calls to `modopt` and `modreq`, and assembling the file with the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). - -- Using the unmanaged reflection API. - - - -## Examples - The following example demonstrates how to emit an object into an assembly using reflection. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Runtime.CompilerServices.IsExplicitlyDereferenced/cpp/sample.cpp" id="Snippet1"::: - + class and its partner, the class, disambiguate reference parameters from pointer parameters. + + Compilers emit custom modifiers within metadata to change the way that the just-in-time (JIT) compiler handles values when the default behavior is not appropriate. When the JIT compiler encounters a custom modifier, it handles the value in the way that the modifier specifies. Compilers can apply custom modifiers to methods, parameters, and return values. The JIT compiler must respond to required modifiers but can ignore optional modifiers. + + You can emit custom modifiers into metadata using one of the following techniques: + +- Using methods in the class such as , , , and . + +- Generating a Microsoft intermediate language (MSIL) instruction file that contains calls to `modopt` and `modreq`, and assembling the file with the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). + +- Using the unmanaged reflection API. + +## Examples + The following example demonstrates how to emit an object into an assembly using reflection. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Runtime.CompilerServices.IsExplicitlyDereferenced/cpp/sample.cpp" id="Snippet1"::: + ]]> diff --git a/xml/System.Runtime.CompilerServices/IsImplicitlyDereferenced.xml b/xml/System.Runtime.CompilerServices/IsImplicitlyDereferenced.xml index b395e5c90b8..e6326c5b363 100644 --- a/xml/System.Runtime.CompilerServices/IsImplicitlyDereferenced.xml +++ b/xml/System.Runtime.CompilerServices/IsImplicitlyDereferenced.xml @@ -44,28 +44,26 @@ Indicates that the modified garbage collection reference represents a reference parameter within a method signature. This class cannot be inherited. - modifier to distinguish reference classes that are passed by managed reference from those passed by managed pointer. The class and its partner, the class, disambiguate reference parameters from pointer parameters. - - Compilers emit custom modifiers within metadata to change the way that the just-in-time (JIT) compiler handles values when the default behavior is not appropriate. When the JIT compiler encounters a custom modifier, it handles the value in the way that the modifier specifies. Compilers can apply custom modifiers to methods, parameters, and return values. The JIT compiler must respond to required modifiers but can ignore optional modifiers. - - You can emit custom modifiers into metadata using one of the following techniques: - -- Using methods in the class such as , , , and . - -- Generating a Microsoft intermediate language (MSIL) instruction file that contains calls to `modopt` and `modreq`, and assembling the file with the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). - -- Using the unmanaged reflection API. - - - -## Examples - The following example demonstrates how to emit an object into an assembly using reflection. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Runtime.CompilerServices.IsImplicitlyDereferenced/cpp/sample.cpp" id="Snippet1"::: - + modifier to distinguish reference classes that are passed by managed reference from those passed by managed pointer. The class and its partner, the class, disambiguate reference parameters from pointer parameters. + + Compilers emit custom modifiers within metadata to change the way that the just-in-time (JIT) compiler handles values when the default behavior is not appropriate. When the JIT compiler encounters a custom modifier, it handles the value in the way that the modifier specifies. Compilers can apply custom modifiers to methods, parameters, and return values. The JIT compiler must respond to required modifiers but can ignore optional modifiers. + + You can emit custom modifiers into metadata using one of the following techniques: + +- Using methods in the class such as , , , and . + +- Generating a Microsoft intermediate language (MSIL) instruction file that contains calls to `modopt` and `modreq`, and assembling the file with the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). + +- Using the unmanaged reflection API. + +## Examples + The following example demonstrates how to emit an object into an assembly using reflection. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Runtime.CompilerServices.IsImplicitlyDereferenced/cpp/sample.cpp" id="Snippet1"::: + ]]> diff --git a/xml/System.Runtime.CompilerServices/IsLong.xml b/xml/System.Runtime.CompilerServices/IsLong.xml index ec8d6d6667e..f100eb35143 100644 --- a/xml/System.Runtime.CompilerServices/IsLong.xml +++ b/xml/System.Runtime.CompilerServices/IsLong.xml @@ -44,28 +44,26 @@ Indicates that a modified integer is a standard C++ value. This class cannot be inherited. - modifier to any instance of a `long` when the instance is emited. This process is critically important for maintaining language-level type safety. - - Compilers emit custom modifiers within metadata to change the way that the just-in-time (JIT) compiler handles values when the default behavior is not appropriate. When the JIT compiler encounters a custom modifier, it handles the value in the way that the modifier specifies. Compilers can apply custom modifiers to methods, parameters, and return values. The JIT compiler must respond to required modifiers but can ignore optional modifiers. - - You can emit custom modifiers into metadata using one of the following techniques: - -- Using methods in the class such as , , , and . - -- Generating a Microsoft intermediate language (MSIL) instruction file that contains calls to `modopt` and `modreq`, and assembling the file with the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). - -- Using the unmanaged reflection API. - - - -## Examples - The following example demonstrates how to emit an object into an assembly using reflection. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Runtime.CompilerServices.IsLong/cpp/sample.cpp" id="Snippet1"::: - + modifier to any instance of a `long` when the instance is emited. This process is critically important for maintaining language-level type safety. + + Compilers emit custom modifiers within metadata to change the way that the just-in-time (JIT) compiler handles values when the default behavior is not appropriate. When the JIT compiler encounters a custom modifier, it handles the value in the way that the modifier specifies. Compilers can apply custom modifiers to methods, parameters, and return values. The JIT compiler must respond to required modifiers but can ignore optional modifiers. + + You can emit custom modifiers into metadata using one of the following techniques: + +- Using methods in the class such as , , , and . + +- Generating a Microsoft intermediate language (MSIL) instruction file that contains calls to `modopt` and `modreq`, and assembling the file with the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). + +- Using the unmanaged reflection API. + +## Examples + The following example demonstrates how to emit an object into an assembly using reflection. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Runtime.CompilerServices.IsLong/cpp/sample.cpp" id="Snippet1"::: + ]]> diff --git a/xml/System.Runtime.CompilerServices/IsPinned.xml b/xml/System.Runtime.CompilerServices/IsPinned.xml index 27b1e0aae04..ff354891bcf 100644 --- a/xml/System.Runtime.CompilerServices/IsPinned.xml +++ b/xml/System.Runtime.CompilerServices/IsPinned.xml @@ -43,26 +43,24 @@ Indicates that a modified instance is pinned in memory. This class cannot be inherited. - class such as , , , and . - -- Generating a Microsoft intermediate language (MSIL) instruction file that contains calls to `modopt` and `modreq`, and assembling the file with the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). - -- Using the unmanaged reflection API. - - - -## Examples - The following example demonstrates how to emit an object into an assembly using reflection. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Runtime.CompilerServices.IsPinned/cpp/sample.cpp" id="Snippet1"::: - + class such as , , , and . + +- Generating a Microsoft intermediate language (MSIL) instruction file that contains calls to `modopt` and `modreq`, and assembling the file with the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). + +- Using the unmanaged reflection API. + +## Examples + The following example demonstrates how to emit an object into an assembly using reflection. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Runtime.CompilerServices.IsPinned/cpp/sample.cpp" id="Snippet1"::: + ]]> diff --git a/xml/System.Runtime.CompilerServices/IsSignUnspecifiedByte.xml b/xml/System.Runtime.CompilerServices/IsSignUnspecifiedByte.xml index f0c114d5ba6..4c05f0c8c79 100644 --- a/xml/System.Runtime.CompilerServices/IsSignUnspecifiedByte.xml +++ b/xml/System.Runtime.CompilerServices/IsSignUnspecifiedByte.xml @@ -44,28 +44,28 @@ Indicates that a modifier is neither signed nor unsigned. This class cannot be inherited. - modifier to each `char` type emitted to an assembly. - - Compilers emit custom modifiers within metadata to change the way that the just-in-time (JIT) compiler handles values when the default behavior is not appropriate. When the JIT compiler encounters a custom modifier, it handles the value in the way that the modifier specifies. Compilers can apply custom modifiers to methods, parameters, and return values. The JIT compiler must respond to required modifiers but can ignore optional modifiers. - - You can emit custom modifiers into metadata using one of the following techniques: - -- Using methods in the class such as , , , and . - -- Generating a Microsoft intermediate language (MSIL) instruction file that contains calls to `modopt` and `modreq`, and assembling the file with the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). - -- Using the unmanaged reflection API. - - - -## Examples - The following code example creates an assembly using classes in the namespace and emits the modifier into that assembly. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Runtime.CompilerServices.IsSignUnspecifiedByte/cpp/sample.cpp" id="Snippet1"::: - + modifier to each `char` type emitted to an assembly. + + Compilers emit custom modifiers within metadata to change the way that the just-in-time (JIT) compiler handles values when the default behavior is not appropriate. When the JIT compiler encounters a custom modifier, it handles the value in the way that the modifier specifies. Compilers can apply custom modifiers to methods, parameters, and return values. The JIT compiler must respond to required modifiers but can ignore optional modifiers. + + You can emit custom modifiers into metadata using one of the following techniques: + +- Using methods in the class such as , , , and . + +- Generating a Microsoft intermediate language (MSIL) instruction file that contains calls to `modopt` and `modreq`, and assembling the file with the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). + +- Using the unmanaged reflection API. + + + +## Examples + The following code example creates an assembly using classes in the namespace and emits the modifier into that assembly. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Runtime.CompilerServices.IsSignUnspecifiedByte/cpp/sample.cpp" id="Snippet1"::: + ]]> diff --git a/xml/System.Runtime.CompilerServices/IsUdtReturn.xml b/xml/System.Runtime.CompilerServices/IsUdtReturn.xml index 913a7aec61a..9d685f127a9 100644 --- a/xml/System.Runtime.CompilerServices/IsUdtReturn.xml +++ b/xml/System.Runtime.CompilerServices/IsUdtReturn.xml @@ -44,28 +44,26 @@ Indicates that a return type is a user-defined type. This class cannot be inherited. - modifier is used by the C++ compiler to mark return types of methods that have native C++ object return semantics. The managed debugger recognizes this modifier to correctly determine that the native calling convention is in use. - - Compilers emit custom modifiers within metadata to change the way that the just-in-time (JIT) compiler handles values when the default behavior is not appropriate. When the JIT compiler encounters a custom modifier, it handles the value in the way that the modifier specifies. Compilers can apply custom modifiers to methods, parameters, and return values. The JIT compiler must respond to required modifiers but can ignore optional modifiers. - - You can emit custom modifiers into metadata using one of the following techniques: - -- Using methods in the class such as , , , and . - -- Generating a Microsoft intermediate language (MSIL) instruction file that contains calls to `modopt` and `modreq`, and assembling the file with the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). - -- Using the unmanaged reflection API. - - - -## Examples - The following code example creates an assembly using classes in the namespace and emits the modifier into that assembly. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Runtime.CompilerServices.IsUdtReturn/CPP/sample.cpp" id="Snippet1"::: - + modifier is used by the C++ compiler to mark return types of methods that have native C++ object return semantics. The managed debugger recognizes this modifier to correctly determine that the native calling convention is in use. + + Compilers emit custom modifiers within metadata to change the way that the just-in-time (JIT) compiler handles values when the default behavior is not appropriate. When the JIT compiler encounters a custom modifier, it handles the value in the way that the modifier specifies. Compilers can apply custom modifiers to methods, parameters, and return values. The JIT compiler must respond to required modifiers but can ignore optional modifiers. + + You can emit custom modifiers into metadata using one of the following techniques: + +- Using methods in the class such as , , , and . + +- Generating a Microsoft intermediate language (MSIL) instruction file that contains calls to `modopt` and `modreq`, and assembling the file with the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). + +- Using the unmanaged reflection API. + +## Examples + The following code example creates an assembly using classes in the namespace and emits the modifier into that assembly. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Runtime.CompilerServices.IsUdtReturn/CPP/sample.cpp" id="Snippet1"::: + ]]> diff --git a/xml/System.Runtime.CompilerServices/IsVolatile.xml b/xml/System.Runtime.CompilerServices/IsVolatile.xml index 091c43389dc..0af9f18f233 100644 --- a/xml/System.Runtime.CompilerServices/IsVolatile.xml +++ b/xml/System.Runtime.CompilerServices/IsVolatile.xml @@ -60,23 +60,23 @@ Marks a field as volatile. This class cannot be inherited. - are for compiler writers' use only. - - Compilers emit custom modifiers within metadata to change the way that the just-in-time (JIT) compiler handles values when the default behavior is not appropriate. When the JIT compiler encounters a custom modifier, it handles the value in the way that the modifier specifies. Compilers can apply custom modifiers to methods, parameters, and return values. The JIT compiler must respond to required modifiers but can ignore optional modifiers. A C++ compiler could emit a custom modifier to describe how a byte should be treated in cases where the JIT compiler treats bytes in a manner that is not compatible with C++ by default. - - You can emit custom modifiers into metadata using one of the following techniques: - -- Using methods in the class such as , , , and . - -- Generating a Microsoft intermediate language (MSIL) instruction file that contains calls to `modopt` and `modreq`, and assembling the file with the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). - -- Using the unmanaged reflection API. - + are for compiler writers' use only. + + Compilers emit custom modifiers within metadata to change the way that the just-in-time (JIT) compiler handles values when the default behavior is not appropriate. When the JIT compiler encounters a custom modifier, it handles the value in the way that the modifier specifies. Compilers can apply custom modifiers to methods, parameters, and return values. The JIT compiler must respond to required modifiers but can ignore optional modifiers. A C++ compiler could emit a custom modifier to describe how a byte should be treated in cases where the JIT compiler treats bytes in a manner that is not compatible with C++ by default. + + You can emit custom modifiers into metadata using one of the following techniques: + +- Using methods in the class such as , , , and . + +- Generating a Microsoft intermediate language (MSIL) instruction file that contains calls to `modopt` and `modreq`, and assembling the file with the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). + +- Using the unmanaged reflection API. + ]]> diff --git a/xml/System.Runtime.CompilerServices/NativeCppClassAttribute.xml b/xml/System.Runtime.CompilerServices/NativeCppClassAttribute.xml index a62ffd6db1e..f80faff9497 100644 --- a/xml/System.Runtime.CompilerServices/NativeCppClassAttribute.xml +++ b/xml/System.Runtime.CompilerServices/NativeCppClassAttribute.xml @@ -57,13 +57,13 @@ - Applies metadata to an assembly that indicates that a type is an unmanaged type. This class cannot be inherited. + Applies metadata to an assembly that indicates that a type is an unmanaged type. This class cannot be inherited. - attribute when building assemblies to indicate that a type is an unmanaged type defined in C or C++. This attribute is used later to correctly handle the unmanaged type when it is imported during interop. - + attribute when building assemblies to indicate that a type is an unmanaged type defined in C or C++. This attribute is used later to correctly handle the unmanaged type when it is imported during interop. + ]]> @@ -103,11 +103,11 @@ Initializes a new instance of the class. - attribute when building assemblies to indicate that a type is an unmanaged type defined in C or C++. This attribute is used later to correctly handle the unmanaged type when it is imported during interop. - + attribute when building assemblies to indicate that a type is an unmanaged type defined in C or C++. This attribute is used later to correctly handle the unmanaged type when it is imported during interop. + ]]> diff --git a/xml/System.Runtime.CompilerServices/RequiredAttributeAttribute.xml b/xml/System.Runtime.CompilerServices/RequiredAttributeAttribute.xml index 1ba5640dba7..b84c86ccc69 100644 --- a/xml/System.Runtime.CompilerServices/RequiredAttributeAttribute.xml +++ b/xml/System.Runtime.CompilerServices/RequiredAttributeAttribute.xml @@ -66,17 +66,17 @@ - Specifies that an importing compiler must fully understand the semantics of a type definition, or refuse to use it. This class cannot be inherited. + Specifies that an importing compiler must fully understand the semantics of a type definition, or refuse to use it. This class cannot be inherited. - are for compiler writers use only. - + are for compiler writers use only. + ]]> @@ -118,8 +118,8 @@ - A type that an importing compiler must fully understand. - + A type that an importing compiler must fully understand. + This parameter is not supported in the .NET Framework version 2.0 and later. Initializes a new instance of the class. To be added. @@ -165,11 +165,11 @@ Gets a type that an importing compiler must fully understand. A type that an importing compiler must fully understand. - diff --git a/xml/System.Runtime.CompilerServices/RuntimeCompatibilityAttribute.xml b/xml/System.Runtime.CompilerServices/RuntimeCompatibilityAttribute.xml index 7ed9e331683..f9a3624838d 100644 --- a/xml/System.Runtime.CompilerServices/RuntimeCompatibilityAttribute.xml +++ b/xml/System.Runtime.CompilerServices/RuntimeCompatibilityAttribute.xml @@ -60,22 +60,20 @@ Specifies whether to wrap exceptions that do not derive from the class with a object. This class cannot be inherited. - class. To maintain compatibility between languages, the common language runtime (CLR) wraps objects that do not derive from in a object. - - You can use the class to specify whether exceptions should appear wrapped inside catch blocks and exception filters for an assembly. Many language compilers, including the Microsoft C# and Visual Basic compilers, apply this attribute by default to specify the wrapping behavior. - - Note that the runtime still wraps exceptions even if you use the class to specify that you do not want them wrapped. In this case, exceptions are unwrapped only inside catch blocks or exception filters. - - - -## Examples - The following code example demonstrates how to apply the class to an assembly that throws a object as an exception in C++ and catches it using a object. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Runtime.CompilerServices.RuntimeWrappedException/cpp/sample.cpp" id="Snippet1"::: - + class. To maintain compatibility between languages, the common language runtime (CLR) wraps objects that do not derive from in a object. + + You can use the class to specify whether exceptions should appear wrapped inside catch blocks and exception filters for an assembly. Many language compilers, including the Microsoft C# and Visual Basic compilers, apply this attribute by default to specify the wrapping behavior. + + Note that the runtime still wraps exceptions even if you use the class to specify that you do not want them wrapped. In this case, exceptions are unwrapped only inside catch blocks or exception filters. + +## Examples + The following code example demonstrates how to apply the class to an assembly that throws a object as an exception in C++ and catches it using a object. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Runtime.CompilerServices.RuntimeWrappedException/cpp/sample.cpp" id="Snippet1"::: + ]]> @@ -118,13 +116,13 @@ Initializes a new instance of the class. - attribute to an assembly to disable exception wrapping. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Runtime.CompilerServices.RuntimeCompatibilityAttribute/cpp/sample.cpp" id="Snippet1"::: - + attribute to an assembly to disable exception wrapping. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Runtime.CompilerServices.RuntimeCompatibilityAttribute/cpp/sample.cpp" id="Snippet1"::: + ]]> @@ -172,13 +170,13 @@ if exceptions that do not derive from the class should appear wrapped with a object; otherwise, . - attribute to an assembly to disable exception wrapping. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Runtime.CompilerServices.RuntimeCompatibilityAttribute/cpp/sample.cpp" id="Snippet1"::: - + attribute to an assembly to disable exception wrapping. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Runtime.CompilerServices.RuntimeCompatibilityAttribute/cpp/sample.cpp" id="Snippet1"::: + ]]> diff --git a/xml/System.Runtime.CompilerServices/RuntimeWrappedException.xml b/xml/System.Runtime.CompilerServices/RuntimeWrappedException.xml index 7910bb1e035..91d332bbc09 100644 --- a/xml/System.Runtime.CompilerServices/RuntimeWrappedException.xml +++ b/xml/System.Runtime.CompilerServices/RuntimeWrappedException.xml @@ -54,22 +54,20 @@ Wraps an exception that does not derive from the class. This class cannot be inherited. - class. To maintain compatibility between languages, the common language runtime (CLR) wraps objects that do not derive from in a object. - - You can use the class to specify whether exceptions should appear wrapped inside catch blocks and exception filters for an assembly. Many language compilers, including the Microsoft C# and Visual Basic compilers, apply this attribute by default to specify the wrapping behavior. - - Note that the runtime still wraps exceptions even if you use the class to specify that you do not want them wrapped. In this case, exceptions are unwrapped only inside catch blocks or exception filters. - - - -## Examples - The following code example demonstrates how to throw a object as an exception in C++ and catch it using a object. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Runtime.CompilerServices.RuntimeWrappedException/cpp/sample.cpp" id="Snippet1"::: - + class. To maintain compatibility between languages, the common language runtime (CLR) wraps objects that do not derive from in a object. + + You can use the class to specify whether exceptions should appear wrapped inside catch blocks and exception filters for an assembly. Many language compilers, including the Microsoft C# and Visual Basic compilers, apply this attribute by default to specify the wrapping behavior. + + Note that the runtime still wraps exceptions even if you use the class to specify that you do not want them wrapped. In this case, exceptions are unwrapped only inside catch blocks or exception filters. + +## Examples + The following code example demonstrates how to throw a object as an exception in C++ and catch it using a object. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Runtime.CompilerServices.RuntimeWrappedException/cpp/sample.cpp" id="Snippet1"::: + ]]> @@ -163,11 +161,11 @@ The object that contains contextual information about the source or destination. Sets the object with information about the exception. - method sets a object with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the `SerializationInfo` transmitted over the stream. - + method sets a object with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the `SerializationInfo` transmitted over the stream. + ]]> The parameter is . @@ -211,11 +209,11 @@ Gets the object that was wrapped by the object. The object that was wrapped by the object. - property gets an object that was thrown as an exception from a language that allows exceptions that do not derive from the class. - + property gets an object that was thrown as an exception from a language that allows exceptions that do not derive from the class. + ]]> diff --git a/xml/System.Runtime.CompilerServices/ScopelessEnumAttribute.xml b/xml/System.Runtime.CompilerServices/ScopelessEnumAttribute.xml index c9e13b14843..607354afb3f 100644 --- a/xml/System.Runtime.CompilerServices/ScopelessEnumAttribute.xml +++ b/xml/System.Runtime.CompilerServices/ScopelessEnumAttribute.xml @@ -54,11 +54,11 @@ Indicates that a native enumeration is not qualified by the enumeration type name. This class cannot be inherited. - attribute to native enumeration types to indicate that they do not need to be qualified by the enumeration type name when referenced in C++ programs. This attribute distinguishes native enumeration types from managed enumeration types. - + attribute to native enumeration types to indicate that they do not need to be qualified by the enumeration type name when referenced in C++ programs. This attribute distinguishes native enumeration types from managed enumeration types. + ]]> diff --git a/xml/System.Runtime.CompilerServices/UnsafeValueTypeAttribute.xml b/xml/System.Runtime.CompilerServices/UnsafeValueTypeAttribute.xml index cb50ff09071..7d379c3fb25 100644 --- a/xml/System.Runtime.CompilerServices/UnsafeValueTypeAttribute.xml +++ b/xml/System.Runtime.CompilerServices/UnsafeValueTypeAttribute.xml @@ -60,13 +60,13 @@ Specifies that a type contains an unmanaged array that might potentially overflow. This class cannot be inherited. - class to instruct the common language runtime (CLR) that a type contains an unmanaged array that can potentially overflow. When this attribute is encountered, the CLR inserts runtime checks to prevent the array from overflowing and to prevent buffer overrun attacks. - - This class is used by the Microsoft Visual C++ and the Microsoft Visual C# compilers. - + class to instruct the common language runtime (CLR) that a type contains an unmanaged array that can potentially overflow. When this attribute is encountered, the CLR inserts runtime checks to prevent the array from overflowing and to prevent buffer overrun attacks. + + This class is used by the Microsoft Visual C++ and the Microsoft Visual C# compilers. + ]]> diff --git a/xml/System.Runtime.InteropServices.WindowsRuntime/ReadOnlyArrayAttribute.xml b/xml/System.Runtime.InteropServices.WindowsRuntime/ReadOnlyArrayAttribute.xml index f614d5f9a97..65ce8dd9e67 100644 --- a/xml/System.Runtime.InteropServices.WindowsRuntime/ReadOnlyArrayAttribute.xml +++ b/xml/System.Runtime.InteropServices.WindowsRuntime/ReadOnlyArrayAttribute.xml @@ -44,9 +44,9 @@ Applying both attributes to a parameter causes an error. For more information, including the standard pattern for making changes to an array, see [Passing arrays to a Windows Runtime component](https://go.microsoft.com/fwlink/?LinkId=251026) in the Windows Dev Center. > [!IMPORTANT] -> Parameters that have the attribute behave differently depending on whether the caller is written in native code or managed code. If the caller is native code (JavaScript or Visual C++ component extensions), the array is copied when the call crosses the application binary interface (ABI) boundary. Elements are converted if necessary. Therefore, any accidental changes the method makes to an input-only array are not visible to the caller. +> Parameters that have the attribute behave differently depending on whether the caller is written in native code or managed code. If the caller is native code (JavaScript or Visual C++ component extensions), the array is copied when the call crosses the application binary interface (ABI) boundary. Elements are converted if necessary. Therefore, any accidental changes the method makes to an input-only array are not visible to the caller. > -> If the caller is managed code, the array is not copied. The original array is available to the called method, as it would be in any method call in the .NET Framework. Array contents are mutable in .NET Framework code, so any changes the method makes to the array are visible to the caller. This is important to remember because it affects unit tests written for a Windows Runtime component. If the tests are written in managed code, the contents of an array will appear to be mutable during testing. +> If the caller is managed code, the array is not copied. The original array is available to the called method, as it would be in any method call in the .NET Framework. Array contents are mutable in .NET Framework code, so any changes the method makes to the array are visible to the caller. This is important to remember because it affects unit tests written for a Windows Runtime component. If the tests are written in managed code, the contents of an array will appear to be mutable during testing. Applying this attribute to a parameter that has the or attribute causes an error when the module is exported. Applying the attribute to an `out` parameter also causes an error. diff --git a/xml/System.Runtime.InteropServices.WindowsRuntime/WriteOnlyArrayAttribute.xml b/xml/System.Runtime.InteropServices.WindowsRuntime/WriteOnlyArrayAttribute.xml index c4f8d1eec25..ea3fc071fdb 100644 --- a/xml/System.Runtime.InteropServices.WindowsRuntime/WriteOnlyArrayAttribute.xml +++ b/xml/System.Runtime.InteropServices.WindowsRuntime/WriteOnlyArrayAttribute.xml @@ -44,9 +44,9 @@ Applying both attributes to a parameter causes an error. For more information, including the standard pattern for making changes to an array, see [Passing arrays to a Windows Runtime component](https://go.microsoft.com/fwlink/?LinkId=251026) in the Windows Dev Center. > [!IMPORTANT] -> Parameters that have the attribute behave differently depending on whether the caller is written in native code or managed code. If the caller is native code (JavaScript or Visual C++ component extensions), the called method can't make any assumptions about the contents of the original array. For example, the array the method receives might not be initialized, or might contain default values. The method is expected to set the values of all the elements in the array. +> Parameters that have the attribute behave differently depending on whether the caller is written in native code or managed code. If the caller is native code (JavaScript or Visual C++ component extensions), the called method can't make any assumptions about the contents of the original array. For example, the array the method receives might not be initialized, or might contain default values. The method is expected to set the values of all the elements in the array. > -> If the caller is managed code, the caller's original array is passed to the called method, as it would be in any method call in the .NET Framework. Array contents are mutable in managed code, so the method can selectively read and change those values. This is important to remember because it affects unit tests written for a Windows Runtime component. If the tests are written in managed code, the contents of an array will appear to be mutable during testing, and the results are likely to be different if the method is called from native code later. +> If the caller is managed code, the caller's original array is passed to the called method, as it would be in any method call in the .NET Framework. Array contents are mutable in managed code, so the method can selectively read and change those values. This is important to remember because it affects unit tests written for a Windows Runtime component. If the tests are written in managed code, the contents of an array will appear to be mutable during testing, and the results are likely to be different if the method is called from native code later. Applying this attribute to an `out` parameter or to a parameter that has the attribute causes an error when the module is exported. Applying the attribute to a parameter that has the attribute causes an error unless the parameter also has the Visual Basic `ByRef` modifier. In that case, the attribute is redundant but allowed. diff --git a/xml/System.Runtime.InteropServices/DefaultCharSetAttribute.xml b/xml/System.Runtime.InteropServices/DefaultCharSetAttribute.xml index 18a41354620..e90bdfacc50 100644 --- a/xml/System.Runtime.InteropServices/DefaultCharSetAttribute.xml +++ b/xml/System.Runtime.InteropServices/DefaultCharSetAttribute.xml @@ -60,27 +60,25 @@ Specifies the value of the enumeration. This class cannot be inherited. - attribute at the assembly level or module level to set the value for any call to that does not include a named argument specified by the user. - - A named argument specified by the user overrides the setting of . - + attribute at the assembly level or module level to set the value for any call to that does not include a named argument specified by the user. + + A named argument specified by the user overrides the setting of . + > [!NOTE] -> Only the C# and Visual Basic compilers recognize this attribute; it is not used by the C++ compiler. - - - -## Examples - The following code example changes the default value from to . - - `using System.Runtime.InteropServices;` - - `[module: DefaultCharSet(CharSet.Auto)]` - - `// …` - +> Only the C# and Visual Basic compilers recognize this attribute; it is not used by the C++ compiler. + +## Examples + The following code example changes the default value from to . + + `using System.Runtime.InteropServices;` + + `[module: DefaultCharSet(CharSet.Auto)]` + + `// …` + ]]> diff --git a/xml/System.Runtime.InteropServices/DllImportAttribute.xml b/xml/System.Runtime.InteropServices/DllImportAttribute.xml index a487b3c3886..00120e19732 100644 --- a/xml/System.Runtime.InteropServices/DllImportAttribute.xml +++ b/xml/System.Runtime.InteropServices/DllImportAttribute.xml @@ -65,30 +65,29 @@ Indicates that the attributed method is exposed by an unmanaged dynamic-link library (DLL) as a static entry point. - attribute provides the information needed to call a function exported from an unmanaged DLL. As a minimum requirement, you must supply the name of the DLL containing the entry point. - - You apply this attribute directly to C# and C++ method definitions; however, the Visual Basic compiler emits this attribute when you use the `Declare` statement. For complex method definitions that include , , , , , or fields, you apply this attribute directly to Visual Basic method definitions. - - **Note** JScript does not support this attribute. You can use C# or Visual Basic wrapper classes to access unmanaged API methods from JScript programs. - - For additional information about using the platform invoke service to access functions in unmanaged DLLs, see [Consuming Unmanaged DLL Functions](/dotnet/framework/interop/consuming-unmanaged-dll-functions). - + attribute provides the information needed to call a function exported from an unmanaged DLL. As a minimum requirement, you must supply the name of the DLL containing the entry point. + + You apply this attribute directly to C# method definitions; however, the Visual Basic compiler emits this attribute when you use the `Declare` statement. For complex method definitions that include , , , , , or fields, you apply this attribute directly to Visual Basic method definitions. + > [!NOTE] -> The does not support marshaling of generic types. - - - -## Examples - The following code example shows how to use the attribute to import the Win32 `MessageBox` function. The code example then calls the imported method. - +> JScript does not support this attribute. You can use C# or Visual Basic wrapper classes to access unmanaged API methods from JScript programs. + +For additional information about using the platform invoke service to access functions in unmanaged DLLs, see [Consuming Unmanaged DLL Functions](/dotnet/framework/interop/consuming-unmanaged-dll-functions). + +> [!NOTE] +> The does not support marshaling of generic types. + +## Examples + The following code example shows how to use the attribute to import the Win32 `MessageBox` function. The code example then calls the imported method. + :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/DllImportAttribute/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Runtime.InteropServices.DllImport.Canonical/vb/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Runtime.InteropServices.DllImport.Canonical/vb/sample.vb" id="Snippet1"::: + ]]> @@ -141,23 +140,23 @@ The name of the DLL that contains the unmanaged method. In .NET Framework, this can include an assembly display name, if the DLL is included in an assembly. Initializes a new instance of the class with the name of the DLL containing the method to import. - attribute to import the Win32 `MessageBox` function. The code example then calls the imported method. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/vb/source.vb" id="Snippet2"::: + + + +## Examples + The following code example shows how to use the attribute to import the Win32 `MessageBox` function. The code example then calls the imported method. + :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/DllImportAttribute/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Runtime.InteropServices.DllImport.Canonical/vb/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Runtime.InteropServices.DllImport.Canonical/vb/sample.vb" id="Snippet1"::: + ]]> @@ -205,26 +204,26 @@ Enables or disables best-fit mapping behavior when converting Unicode characters to ANSI characters. - field is `true` by default. Settings for this field override the any level settings for the attribute. - + > [!CAUTION] -> Certain Unicode characters are converted to dangerous characters, such as the backslash '\\' character, which can inadvertently change a path. By setting the field to `true`, you can signal the presence of an unmappable character to the caller by throwing an exception. - +> Certain Unicode characters are converted to dangerous characters, such as the backslash '\\' character, which can inadvertently change a path. By setting the field to `true`, you can signal the presence of an unmappable character to the caller by throwing an exception. + > [!CAUTION] -> You cannot change the default values provided by the and fields when passing a managed array whose elements are ANSI Chars or LPSTRs to an unmanaged safe array. Best-fit mapping is always enabled and no exception is thrown. Be aware that this combination can compromise your security model. - - - -## Examples - In some cases, Visual Basic developers use the , instead of the `Declare` statement, to define a DLL function in managed code. Setting the field is one of those cases. The following example shows how to apply the strictest character mapping security to a platform invoke method definitions by specifying the ANSI character set, disabling best fit mapping behavior, and throwing an exception on unmapped Unicode characters. - +> You cannot change the default values provided by the and fields when passing a managed array whose elements are ANSI Chars or LPSTRs to an unmanaged safe array. Best-fit mapping is always enabled and no exception is thrown. Be aware that this combination can compromise your security model. + + + +## Examples + In some cases, Visual Basic developers use the , instead of the `Declare` statement, to define a DLL function in managed code. Setting the field is one of those cases. The following example shows how to apply the strictest character mapping security to a platform invoke method definitions by specifying the ANSI character set, disabling best fit mapping behavior, and throwing an exception on unmapped Unicode characters. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/cpp/source.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/DllImportAttribute/.ctor/source.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/vb/source.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/vb/source.vb" id="Snippet3"::: + ]]> @@ -275,20 +274,20 @@ Indicates the calling convention of an entry point. - enumeration members. The default value for the field is , which in turn defaults to convention on Windows, and on all other platforms. - - - -## Examples - In some cases, Visual Basic developers use the , instead of the `Declare` statement, to define a DLL function in managed code. Setting the field is one of those cases. - + + + +## Examples + In some cases, Visual Basic developers use the , instead of the `Declare` statement, to define a DLL function in managed code. Setting the field is one of those cases. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/DllImportAttribute/.ctor/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/vb/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/vb/source.vb" id="Snippet1"::: + ]]> @@ -337,21 +336,19 @@ Indicates how to marshal string parameters to the method and controls name mangling. - enumeration to specify the marshaling behavior of string parameters and to specify which entry-point name to invoke (the exact name given or a name ending with "A" or "W"). The default enumeration member for C# and Visual Basic is `CharSet.Ansi` and the default enumeration member for C++ is `CharSet.None`, which is equivalent to `CharSet.Ansi`. In Visual Basic, you use the `Declare` statement to specify the `CharSet` field. - - The field influences the behavior of the `CharSet` field in determining which entry-point name to invoke. For a detailed description and examples of the string marshaling and name matching behavior associated with the `CharSet` field, see [Specifying a Character Set](/dotnet/framework/interop/specifying-a-character-set). - - - -## Examples - The following code example shows how to use the attribute to import the Win32 `MessageBox` function. The code example then calls the imported method. - + enumeration to specify the marshaling behavior of string parameters and to specify which entry-point name to invoke (the exact name given or a name ending with "A" or "W"). The default enumeration member for C# and Visual Basic is `CharSet.Ansi` and the default enumeration member for C++ is `CharSet.None`, which is equivalent to `CharSet.Ansi`. In Visual Basic, you use the `Declare` statement to specify the `CharSet` field. + + The field influences the behavior of the `CharSet` field in determining which entry-point name to invoke. For a detailed description and examples of the string marshaling and name matching behavior associated with the `CharSet` field, see [Specifying a Character Set](/dotnet/framework/interop/specifying-a-character-set). + +## Examples + The following code example shows how to use the attribute to import the Win32 `MessageBox` function. The code example then calls the imported method. + :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/DllImportAttribute/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Runtime.InteropServices.DllImport.Canonical/vb/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Runtime.InteropServices.DllImport.Canonical/vb/sample.vb" id="Snippet1"::: + ]]> @@ -407,21 +404,21 @@ Indicates the name or ordinal of the DLL entry point to be called. - . - - For additional information, see [Identifying Functions in DLLs](/dotnet/framework/interop/identifying-functions-in-dlls). For examples showing how to use the field, see [Specifying an Entry Point](/dotnet/framework/interop/specifying-an-entry-point). - - - -## Examples - The following code example shows how to use the attribute to import the Win32 `MessageBox` function. The code example uses the property to specify the function to import and then changes the name to `MyNewMessageBoxMethod`. - + . + + For additional information, see [Identifying Functions in DLLs](/dotnet/framework/interop/identifying-functions-in-dlls). For examples showing how to use the field, see [Specifying an Entry Point](/dotnet/framework/interop/specifying-an-entry-point). + + + +## Examples + The following code example shows how to use the attribute to import the Win32 `MessageBox` function. The code example uses the property to specify the function to import and then changes the name to `MyNewMessageBoxMethod`. + :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/DllImportAttribute/EntryPoint/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Runtime.InteropServices.DllImport.EntryPoint/vb/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Runtime.InteropServices.DllImport.EntryPoint/vb/sample.vb" id="Snippet1"::: + ]]> @@ -470,28 +467,28 @@ Controls whether the field causes the common language runtime to search an unmanaged DLL for entry-point names other than the one specified. - field is set to `CharSet.Ansi`, and the entry-point name appended with the letter W is invoked when the field is set to the `CharSet.Unicode`. Typically, managed compilers set this field. - - The following table shows the relationship between the and fields, based on default values imposed by the programming language. You can override the default setting, but do so with caution. - -|Language|ANSI|Unicode|Auto| -|--------------|----------|-------------|----------| -|Visual Basic|ExactSpelling:=True|ExactSpelling:=True|ExactSpelling:=False| -|C#|ExactSpelling=false|ExactSpelling=false|ExactSpelling=false| -|C++|ExactSpelling=false|ExactSpelling=false|ExactSpelling=false| - - - -## Examples - In some cases, Visual Basic developers use the , instead of using the `Declare` statement, to define a DLL function in managed code. Setting the field is one of those cases. - + field is set to `CharSet.Ansi`, and the entry-point name appended with the letter W is invoked when the field is set to the `CharSet.Unicode`. Typically, managed compilers set this field. + + The following table shows the relationship between the and fields, based on default values imposed by the programming language. You can override the default setting, but do so with caution. + +|Language|ANSI|Unicode|Auto| +|--------------|----------|-------------|----------| +|Visual Basic|ExactSpelling:=True|ExactSpelling:=True|ExactSpelling:=False| +|C#|ExactSpelling=false|ExactSpelling=false|ExactSpelling=false| +|C++|ExactSpelling=false|ExactSpelling=false|ExactSpelling=false| + + + +## Examples + In some cases, Visual Basic developers use the , instead of using the `Declare` statement, to define a DLL function in managed code. Setting the field is one of those cases. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/cpp/source.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/DllImportAttribute/.ctor/source.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/vb/source.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/vb/source.vb" id="Snippet4"::: + ]]> @@ -539,29 +536,29 @@ Indicates whether unmanaged methods that have return values are directly translated or whether return values are automatically converted to exceptions. - field to `true` to translate unmanaged signatures with `HRESULT` values directly; set it to `false` to automatically convert `HRESULT` return values to exceptions. By default, the field is `true`. - - When `true`, the managed method signature returns an integer value that contains the `HRESULT` value. In this case, you must manually inspect the return value and respond accordingly in your application. - + field to `true` to translate unmanaged signatures with `HRESULT` values directly; set it to `false` to automatically convert `HRESULT` return values to exceptions. By default, the field is `true`. + + When `true`, the managed method signature returns an integer value that contains the `HRESULT` value. In this case, you must manually inspect the return value and respond accordingly in your application. + When you set the field to `false`, the managed method signature has a void return type or the type of the last unmanaged [out, retval] parameter. When the unmanaged method produces an `HRESULT`, the runtime automatically ignores a return value of `S_OK` (or 0) and does not throw an exception. For `HRESULT`s other than `S_OK`, the runtime automatically throws an exception that corresponds to the `HRESULT`. - - You might decide to change the default error reporting behavior from `HRESULT`s to exceptions in cases where exceptions better fit the error reporting structure of your application. - - This field is similar to the ; however, in contrast to the field, the default value for the attribute is `false`. - - In some cases, Visual Basic developers use the , instead of using the `Declare` statement, to define a DLL function in managed code. Setting the field is one of those cases. - - - -## Examples - The following code example uses the to import the unmanaged `SHAutoComplete` function once with the field set to `true` and again with the field set to `false`. This code example causes the `SHAutoComplete` function to generate any errors with an exception one time and an `HRESULT` the next. - + + You might decide to change the default error reporting behavior from `HRESULT`s to exceptions in cases where exceptions better fit the error reporting structure of your application. + + This field is similar to the ; however, in contrast to the field, the default value for the attribute is `false`. + + In some cases, Visual Basic developers use the , instead of using the `Declare` statement, to define a DLL function in managed code. Setting the field is one of those cases. + + + +## Examples + The following code example uses the to import the unmanaged `SHAutoComplete` function once with the field set to `true` and again with the field set to `false`. This code example causes the `SHAutoComplete` function to generate any errors with an exception one time and an `HRESULT` the next. + :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/DllImportAttribute/PreserveSig/example.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Runtime.InteropServices.PreserveSigAttribute/vb/example.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Runtime.InteropServices.PreserveSigAttribute/vb/example.vb" id="Snippet1"::: + ]]> @@ -610,27 +607,27 @@ Indicates whether the callee sets an error ( on Windows or on other platforms) before returning from the attributed method. - on .NET 6.0 and above or on .NET 5 and below or .NET Framework. - + On .NET, the error information is cleared (set to `0`) before invoking the callee when this field is set to `true`. On .NET Framework, the error information is not cleared. This means that error information returned by and on .NET represents only the error information from the last p/invoke with set to `true`. On .NET Framework, the error information can persist from one p/invoke to the next. - -## Examples - In some cases, Visual Basic developers use the , instead of using the `Declare` statement, to define a DLL function in managed code. Setting the field is one of those cases. - + +## Examples + In some cases, Visual Basic developers use the , instead of using the `Declare` statement, to define a DLL function in managed code. Setting the field is one of those cases. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/cpp/source.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/DllImportAttribute/.ctor/source.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/vb/source.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/vb/source.vb" id="Snippet5"::: + ]]> @@ -680,26 +677,26 @@ Enables or disables the throwing of an exception on an unmappable Unicode character that is converted to an ANSI "?" character. - field is disabled. This field is `false` by default. - + > [!CAUTION] -> Certain Unicode characters are converted to dangerous characters, such as the backslash '\\' character, which can inadvertently change a path. By setting the field to `true`, you can signal the presence of an unmappable character to the caller by throwing an exception. - +> Certain Unicode characters are converted to dangerous characters, such as the backslash '\\' character, which can inadvertently change a path. By setting the field to `true`, you can signal the presence of an unmappable character to the caller by throwing an exception. + > [!CAUTION] -> You cannot change the default values provided by the and fields when passing a managed array whose elements are ANSI Chars or LPSTRs to an unmanaged safe array. Best-fit mapping is always enabled and no exception is thrown. Be aware that this combination can compromise your security model. - - - -## Examples - In some cases, Visual Basic developers use the to define a DLL function in managed code, instead of using the `Declare` statement. Setting the field is one of those cases. The following example shows how to apply the strictest character mapping security to a platform invoke method definitions by specifying the ANSI character set, disabling best fit mapping behavior, and throwing an exception on unmapped Unicode characters. - +> You cannot change the default values provided by the and fields when passing a managed array whose elements are ANSI Chars or LPSTRs to an unmanaged safe array. Best-fit mapping is always enabled and no exception is thrown. Be aware that this combination can compromise your security model. + + + +## Examples + In some cases, Visual Basic developers use the to define a DLL function in managed code, instead of using the `Declare` statement. Setting the field is one of those cases. The following example shows how to apply the strictest character mapping security to a platform invoke method definitions by specifying the ANSI character set, disabling best fit mapping behavior, and throwing an exception on unmapped Unicode characters. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/cpp/source.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/DllImportAttribute/.ctor/source.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/vb/source.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/vb/source.vb" id="Snippet3"::: + ]]> @@ -751,11 +748,11 @@ Gets the name of the DLL file that contains the entry point. The name of the DLL file that contains the entry point. - diff --git a/xml/System.Runtime.InteropServices/LayoutKind.xml b/xml/System.Runtime.InteropServices/LayoutKind.xml index 977cf8be126..411ff825f76 100644 --- a/xml/System.Runtime.InteropServices/LayoutKind.xml +++ b/xml/System.Runtime.InteropServices/LayoutKind.xml @@ -60,23 +60,23 @@ Controls the layout of an object when exported to unmanaged code. - . The common language runtime uses the `Auto` layout value by default. To reduce layout-related problems associated with the `Auto` value, C#, Visual Basic, and C++ compilers specify `Sequential` layout for value types. - + . The common language runtime uses the `Auto` layout value by default. To reduce layout-related problems associated with the `Auto` value, C#, Visual Basic, and C++ compilers specify `Sequential` layout for value types. + > [!IMPORTANT] -> The field controls the alignment of data fields, and thus affects the layout regardless of the value you specify. By default, the value of is 0, which indicates the default packing size for the current platform. For example, when you use the `Explicit` layout value and specify field alignments on byte boundaries, you must set to 1 to get the desired result. - - - -## Examples - The following example shows the managed declaration of the `PtInRect` function, which checks whether a point lies within a rectangle, and defines a `Point` structure with Sequential layout and a `Rect` structure with Explicit layout. - +> The field controls the alignment of data fields, and thus affects the layout regardless of the value you specify. By default, the value of is 0, which indicates the default packing size for the current platform. For example, when you use the `Explicit` layout value and specify field alignments on byte boundaries, you must set to 1 to get the desired result. + + + +## Examples + The following example shows the managed declaration of the `PtInRect` function, which checks whether a point lies within a rectangle, and defines a `Point` structure with Sequential layout and a `Rect` structure with Explicit layout. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/LayoutKind/CPP/layoutkind.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/LayoutKind/Overview/layoutkind.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/LayoutKind/VB/layoutkind.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/LayoutKind/VB/layoutkind.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Runtime.InteropServices/Marshal.xml b/xml/System.Runtime.InteropServices/Marshal.xml index 0b202c48b83..549fa4ef240 100644 --- a/xml/System.Runtime.InteropServices/Marshal.xml +++ b/xml/System.Runtime.InteropServices/Marshal.xml @@ -3475,17 +3475,15 @@ The code retrieves a reference to an instance of Microsoft Word successfully. Ho and methods to marshal delegates in both directions. With , `ptr` is imported as a . A can be obtained for a managed delegate by calling and passed as a parameter; it can then be called from inside the unmanaged method. Note that the parameter marshaler can also marshal function pointers to delegates in the .NET Framework 2.0 and later versions. + You can use the and methods to marshal delegates in both directions. With , `ptr` is imported as a . A can be obtained for a managed delegate by calling and passed as a parameter; it can then be called from inside the unmanaged method. Note that the parameter marshaler can also marshal function pointers to delegates. `ptr` is converted to a delegate that invokes the unmanaged method using [the default platform calling convention](/dotnet/standard/native-interop/calling-conventions#platform-default-calling-convention). You can set the calling convention by applying the to the delegate. The method has the following restrictions: -- Generics are not supported in interop scenarios. - -- You can use this method only for pure unmanaged function pointers. - -- You cannot use this method with function pointers obtained through C++. +- Generics are not supported in interop scenarios. +- You can use this method only for pure unmanaged function pointers. +- You cannot use this method with function pointers obtained through C++. ]]> @@ -3570,11 +3568,9 @@ The code retrieves a reference to an instance of Microsoft Word successfully. Ho The method has the following restrictions: -- Generics are not supported in interop scenarios. - -- You can use this method only for pure unmanaged function pointers. - -- You cannot use this method with function pointers obtained through C++. +- Generics are not supported in interop scenarios. +- You can use this method only for pure unmanaged function pointers. +- You cannot use this method with function pointers obtained through C++. ]]> @@ -4258,8 +4254,6 @@ The code retrieves a reference to an instance of Microsoft Word successfully. Ho ## Remarks The target function must have had the `setLastError` metadata flag set. For example, the `SetLastError` field of the must be `true`. The process for setting this flag depends on the source language used: C# and C++ are `false` by default, but the `Declare` statement in Visual Basic is `true`. - - ## Examples The following example demonstrates how to retrieve an HRESULT corresponding to a Win32 error code using the method. @@ -5142,9 +5136,9 @@ On .NET 6 and later versions, this method is functionally equivalent to method. @@ -6931,13 +6925,13 @@ On .NET 6 and later versions, this method is functionally equivalent to on a method outside of platform invoke has no effect. To execute setup tasks on all platform invoke methods in a type, use . diff --git a/xml/System.Runtime.InteropServices/MarshalAsAttribute.xml b/xml/System.Runtime.InteropServices/MarshalAsAttribute.xml index 75f75cb77f1..948dcc7732f 100644 --- a/xml/System.Runtime.InteropServices/MarshalAsAttribute.xml +++ b/xml/System.Runtime.InteropServices/MarshalAsAttribute.xml @@ -65,40 +65,40 @@ Indicates how to marshal the data between managed and unmanaged code. - , a , a , or a . By default, the common language runtime marshals a string parameter as a to COM methods. You can apply the attribute to an individual field or parameter to cause that particular string to be marshaled as a instead of a . The [Tlbexp.exe (Type Library Exporter)](/dotnet/framework/tools/tlbexp-exe-type-library-exporter) passes your marshaling preferences to the common language runtime. - - Some parameters and return values have different default marshaling behavior when used with COM interop or platform invoke. By default, the runtime marshals a string parameter (and fields in a value type) as a to a platform invoke method or function. For additional information, see [Default Marshaling Behavior](/dotnet/framework/interop/default-marshaling-behavior). - - In most cases, the attribute simply identifies the format of the unmanaged data using the enumeration, as shown in the following C# signature: - + , a , a , or a . By default, the common language runtime marshals a string parameter as a to COM methods. You can apply the attribute to an individual field or parameter to cause that particular string to be marshaled as a instead of a . The [Tlbexp.exe (Type Library Exporter)](/dotnet/framework/tools/tlbexp-exe-type-library-exporter) passes your marshaling preferences to the common language runtime. + + Some parameters and return values have different default marshaling behavior when used with COM interop or platform invoke. By default, the runtime marshals a string parameter (and fields in a value type) as a to a platform invoke method or function. For additional information, see [Default Marshaling Behavior](/dotnet/framework/interop/default-marshaling-behavior). + + In most cases, the attribute simply identifies the format of the unmanaged data using the enumeration, as shown in the following C# signature: + :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/MarshalAsAttribute/Overview/Signature1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.MarshalAsAttribute/vb/Signature1.vb" id="Snippet2"::: - - Some enumeration members require additional information. For example, additional information is needed when the is . For a complete description of how to use this attribute with arrays, see [Default Marshaling for Arrays](/dotnet/framework/interop/default-marshaling-for-arrays). - - The [Tlbimp.exe (Type Library Importer)](/dotnet/framework/tools/tlbimp-exe-type-library-importer) also applies this attribute to parameters, fields, and return values to indicate that the data type in the input type library is not the default type for the corresponding managed data type. Tlbimp.exe always applies the to and types for clarity, regardless of the type specified in the input type library. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.MarshalAsAttribute/vb/Signature1.vb" id="Snippet2"::: + + Some enumeration members require additional information. For example, additional information is needed when the is . For a complete description of how to use this attribute with arrays, see [Default Marshaling for Arrays](/dotnet/framework/interop/default-marshaling-for-arrays). + + The [Tlbimp.exe (Type Library Importer)](/dotnet/framework/tools/tlbimp-exe-type-library-importer) also applies this attribute to parameters, fields, and return values to indicate that the data type in the input type library is not the default type for the corresponding managed data type. Tlbimp.exe always applies the to and types for clarity, regardless of the type specified in the input type library. + > [!NOTE] -> The does not support marshaling of generic types. - - - -## Examples - The following example applies the to a field, a method parameter, and a method return value in a managed type. - +> The does not support marshaling of generic types. + + + +## Examples + The following example applies the to a field, a method parameter, and a method return value in a managed type. + :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/MarshalAsAttribute/Overview/marshalasattribute.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.MarshalAsAttribute/vb/marshalasattribute.vb" id="Snippet1"::: - - The following example applies the attribute to a property: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.MarshalAsAttribute/vb/marshalasattribute.vb" id="Snippet1"::: + + The following example applies the attribute to a property: + :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/MarshalAsAttribute/Overview/Signature1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.MarshalAsAttribute/vb/Signature1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.MarshalAsAttribute/vb/Signature1.vb" id="Snippet3"::: + ]]> @@ -164,11 +164,11 @@ The value the data is to be marshaled as. Initializes a new instance of the class with the specified value. - enumeration member. The [Tlbimp.exe (Type Library Importer)](/dotnet/framework/tools/tlbimp-exe-type-library-importer) uses this constructor. - + enumeration member. The [Tlbimp.exe (Type Library Importer)](/dotnet/framework/tools/tlbimp-exe-type-library-importer) uses this constructor. + ]]> @@ -219,11 +219,11 @@ The value the data is to be marshaled as. Initializes a new instance of the class with the specified enumeration member. - @@ -272,11 +272,11 @@ Specifies the element type of the unmanaged or . - enumeration to specify the type of the array's elements. If a type is not specified, the default unmanaged type corresponding to the managed array's element type is used. For example, the `ArraySubType` for a `LPWStr` array in COM is . For additional information, see [Default Marshaling for Arrays](/dotnet/framework/interop/default-marshaling-for-arrays). - + enumeration to specify the type of the array's elements. If a type is not specified, the default unmanaged type corresponding to the managed array's element type is used. For example, the `ArraySubType` for a `LPWStr` array in COM is . For additional information, see [Default Marshaling for Arrays](/dotnet/framework/interop/default-marshaling-for-arrays). + ]]> @@ -370,13 +370,13 @@ Provides additional information to a custom marshaler. - @@ -431,11 +431,11 @@ Specifies the fully qualified name of a custom marshaler. - or field specify a custom marshaler type for the attributed parameter, field, or return type. The field enables you to specify a string representing the fully qualified name of a custom marshaler. It is useful for late-bound references, but is less preferred than for specifying a custom marshaler. For additional information about creating and using custom marshalers, see [Custom Marshaling](https://msdn.microsoft.com/library/49f9ac47-1619-4d6e-9da6-bf06bba12079). - + or field specify a custom marshaler type for the attributed parameter, field, or return type. The field enables you to specify a string representing the fully qualified name of a custom marshaler. It is useful for late-bound references, but is less preferred than for specifying a custom marshaler. For additional information about creating and using custom marshalers, see [Custom Marshaling](https://msdn.microsoft.com/library/49f9ac47-1619-4d6e-9da6-bf06bba12079). + ]]> @@ -491,21 +491,21 @@ Implements as a type. - or field to specify a custom marshaler type for the attributed parameter, field, or return type. The field allows easier usage of by shortening the syntax. In the following example, the first line represents syntax using and the second line represents syntax using . - -``` -[MarshalAs(UnmanagedType.CustomMarshaler, MarshalType = "Assembly, NameSpace.TypeName")] -``` - -``` -[MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(NameSpace.TypeName))] -``` - - You can set a object using `typeof` in C#, `GetType` in Visual Basic, or `typeid` in C++. For additional information about creating and using custom marshalers, see [Custom Marshaling](https://msdn.microsoft.com/library/49f9ac47-1619-4d6e-9da6-bf06bba12079). - + or field to specify a custom marshaler type for the attributed parameter, field, or return type. The field allows easier usage of by shortening the syntax. In the following example, the first line represents syntax using and the second line represents syntax using . + +``` +[MarshalAs(UnmanagedType.CustomMarshaler, MarshalType = "Assembly, NameSpace.TypeName")] +``` + +``` +[MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(NameSpace.TypeName))] +``` + + You can set a object using `typeof` in C#, `GetType` in Visual Basic, or `typeid` in C++. For additional information about creating and using custom marshalers, see [Custom Marshaling](/previous-versions/dotnet/netframework-4.0/w22x2hw6(v=vs.100)). + ]]> @@ -554,11 +554,11 @@ Indicates the element type of the . - enumeration to specify the type of the safe array's elements. If a type is not specified, the managed element type's default type (if passed as a VARIANT) is used. For example, the `SafeArraySubType` for an `int` array in COM is . For additional information, see [Default Marshaling for Arrays](/dotnet/framework/interop/default-marshaling-for-arrays). - + enumeration to specify the type of the safe array's elements. If a type is not specified, the managed element type's default type (if passed as a VARIANT) is used. For example, the `SafeArraySubType` for an `int` array in COM is . For additional information, see [Default Marshaling for Arrays](/dotnet/framework/interop/default-marshaling-for-arrays). + ]]> @@ -609,11 +609,11 @@ Indicates the user-defined element type of the . - is either , , or . For additional information, see [Default Marshaling for Arrays](/dotnet/framework/interop/default-marshaling-for-arrays). - + is either , , or . For additional information, see [Default Marshaling for Arrays](/dotnet/framework/interop/default-marshaling-for-arrays). + ]]> @@ -663,13 +663,13 @@ Indicates the number of elements in the fixed-length array or the number of characters (not bytes) in a string to import. - and members of the enumeration. Because the compressed format of the metadata is limited to 0x1FFFFFFF, the range of allowed values for are (>= 0 and <= 0x1FFFFFFF). - - For additional information, see [Default Marshaling for Arrays](/dotnet/framework/interop/default-marshaling-for-arrays). - + and members of the enumeration. Because the compressed format of the metadata is limited to 0x1FFFFFFF, the range of allowed values for are (>= 0 and <= 0x1FFFFFFF). + + For additional information, see [Default Marshaling for Arrays](/dotnet/framework/interop/default-marshaling-for-arrays). + ]]> @@ -718,32 +718,32 @@ Indicates the zero-based parameter that contains the count of array elements, similar to in COM. - field supports managed-to-unmanaged and unmanaged-to-managed calls. It does not have any effect on managed code that calls COM objects. - - Depending on the managed type and the attributes applied to it, the array can be passed as a safe array or C-style array. - - When arrays are passed as C-style arrays, the marshaler cannot determine the size of the array. Therefore, to pass an managed array to an unmanaged function or method, you must provide two arguments: - -- The array, defined by reference or value. - -- The array size, defined by reference or value. - - The zero-based index of the array size parameter is defined by using the field. - - If you specify both and with a field, the sum of the fields' values produces a size total. - - For more information, see [Default Marshaling for Arrays](/dotnet/framework/interop/default-marshaling-for-arrays). - - - -## Examples + field supports managed-to-unmanaged and unmanaged-to-managed calls. It does not have any effect on managed code that calls COM objects. + + Depending on the managed type and the attributes applied to it, the array can be passed as a safe array or C-style array. + + When arrays are passed as C-style arrays, the marshaler cannot determine the size of the array. Therefore, to pass an managed array to an unmanaged function or method, you must provide two arguments: + +- The array, defined by reference or value. + +- The array size, defined by reference or value. + + The zero-based index of the array size parameter is defined by using the field. + + If you specify both and with a field, the sum of the fields' values produces a size total. + + For more information, see [Default Marshaling for Arrays](/dotnet/framework/interop/default-marshaling-for-arrays). + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Runtime.InteropServices.MarshalAsAttribute.SizeParamIndex/CPP/marshalas.sizeparamindex.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/MarshalAsAttribute/SizeParamIndex/marshalas.sizeparamindex.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Runtime.InteropServices.MarshalAsAttribute.SizeParamIndex/VB/marshalas.sizeparamindex.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Runtime.InteropServices.MarshalAsAttribute.SizeParamIndex/VB/marshalas.sizeparamindex.vb" id="Snippet1"::: + ]]> @@ -794,11 +794,11 @@ Gets the value the data is to be marshaled as. The value the data is to be marshaled as. - to indicate how types should be marshaled between managed and unmanaged code. In some cases, you can use this field with certain `UnmanagedType` enumeration members. For and , you must use additional named parameters. - + to indicate how types should be marshaled between managed and unmanaged code. In some cases, you can use this field with certain `UnmanagedType` enumeration members. For and , you must use additional named parameters. + ]]> diff --git a/xml/System.Security.Cryptography/CryptographicOperations.xml b/xml/System.Security.Cryptography/CryptographicOperations.xml index aad06fc657c..a976ec218c7 100644 --- a/xml/System.Security.Cryptography/CryptographicOperations.xml +++ b/xml/System.Security.Cryptography/CryptographicOperations.xml @@ -1180,7 +1180,7 @@ Fixed-time behavior is guaranteed in all other cases, including when `left` and ## Remarks This method exists to future-proof against potential optimizations in the .NET runtime that could eliminate memory writes that aren't followed by memory reads. -While the C and C++ compilers have similar optimizations, no such optimizations are planned at this time for .NET. +While the C and C++ compilers have similar optimizations, no such optimizations are planned for .NET. ]]> diff --git a/xml/System.ServiceModel.Channels/Message.xml b/xml/System.ServiceModel.Channels/Message.xml index 12b95689329..0a0cca6eef0 100644 --- a/xml/System.ServiceModel.Channels/Message.xml +++ b/xml/System.ServiceModel.Channels/Message.xml @@ -72,15 +72,10 @@ Special note for Managed C++ users deriving from this class: -- Put your cleanup code in (On)(Begin)Close (and/or OnAbort), not in a destructor. - -- Avoid destructors: they cause the compiler to auto-generate . - -- Avoid non-reference members: they can cause the compiler to auto-generate . - -- Avoid finalizers; but if you include one, suppress the build warning and call and the finalizer itself from (On)(Begin)Close (and/or OnAbort) to emulate what would have been the auto-generated behavior. - - +- Put your cleanup code in (On)(Begin)Close (and/or OnAbort), not in a destructor. +- Avoid destructors: they cause the compiler to auto-generate . +- Avoid non-reference members: they can cause the compiler to auto-generate . +- Avoid finalizers; but if you include one, suppress the build warning and call and the finalizer itself from (On)(Begin)Close (and/or OnAbort) to emulate what would have been the auto-generated behavior. ## Examples The following code example shows a client that uses the channel factory to send a message and read the reply. diff --git a/xml/System.ServiceModel.Channels/MessageBuffer.xml b/xml/System.ServiceModel.Channels/MessageBuffer.xml index ef38638992d..44318d4a818 100644 --- a/xml/System.ServiceModel.Channels/MessageBuffer.xml +++ b/xml/System.ServiceModel.Channels/MessageBuffer.xml @@ -57,29 +57,26 @@ Represents a memory buffer that stores an entire message for future consumption. - instance can only be consumed or written once. If you wish to consume a instance more than once, you should use the class to completely store an entire instance into memory. - - A instance is constructed by calling of a instance. A new is then created and returned, which assumes ownership of the and reads the entire content into memory. - - In order to retrieve a copy of a from the , you must call the method of the . This returns an identical copy of the original instance you provided. - - You can control the maximum size of the buffer by setting to the maximum number of bytes desired. This number does not necessarily cover any transient allocations related to building the buffer, or properties attached to the message. - - You should always close a instance by calling when finished working with it. This allows system resources to potentially be freed sooner. - - Special note for Managed C++ users deriving from this class: - -- Put your cleanup code in (On)(Begin)Close (and/or OnAbort), not in a destructor. - -- Avoid destructors: they cause the compiler to auto-generate - -- Avoid non-reference members: they can cause the compiler to auto-generate - -- Avoid finalizers; but if you include one, you should suppress the build warning and call and the finalizer itself from (On)(Begin)Close (and/or OnAbort) in order to emulate what would have been the auto-generated behavior. - + instance can only be consumed or written once. If you wish to consume a instance more than once, you should use the class to completely store an entire instance into memory. + + A instance is constructed by calling of a instance. A new is then created and returned, which assumes ownership of the and reads the entire content into memory. + + In order to retrieve a copy of a from the , you must call the method of the . This returns an identical copy of the original instance you provided. + + You can control the maximum size of the buffer by setting to the maximum number of bytes desired. This number does not necessarily cover any transient allocations related to building the buffer, or properties attached to the message. + + You should always close a instance by calling when finished working with it. This allows system resources to potentially be freed sooner. + + Special note for Managed C++ users deriving from this class: + +- Put your cleanup code in (On)(Begin)Close (and/or OnAbort), not in a destructor. +- Avoid destructors: they cause the compiler to auto-generate . +- Avoid non-reference members: they can cause the compiler to auto-generate . +- Avoid finalizers; but if you include one, you should suppress the build warning and call and the finalizer itself from (On)(Begin)Close (and/or OnAbort) in order to emulate what would have been the auto-generated behavior. + ]]> @@ -152,11 +149,11 @@ Gets the approximate number of bytes consumed by this . The approximate number of bytes consumed by this . - to the maximum number of bytes desired. This number does not necessarily cover any transient allocations related to building the buffer, or properties attached to the message. It is not related to the actual size of the message when serialized. - + to the maximum number of bytes desired. This number does not necessarily cover any transient allocations related to building the buffer, or properties attached to the message. It is not related to the actual size of the message when serialized. + ]]> @@ -193,38 +190,38 @@ Finishes working with the buffer. - instance by calling when finished working with it. This allows system resources to potentially be freed sooner. - - If you have called to create a message buffer of a message, and inspected the message using , you will get a when you attempt to close the buffer using this method. To avoid this problem, you need to recreate the message from the buffer before closing. See the code sample in the Example section for a demonstration of the previous scenario and a way to resolve this problem. - - - -## Examples - The following example demonstrates how to properly close a message buffer. - + instance by calling when finished working with it. This allows system resources to potentially be freed sooner. + + If you have called to create a message buffer of a message, and inspected the message using , you will get a when you attempt to close the buffer using this method. To avoid this problem, you need to recreate the message from the buffer before closing. See the code sample in the Example section for a demonstration of the previous scenario and a way to resolve this problem. + + + +## Examples + The following example demonstrates how to properly close a message buffer. + ```csharp -public void AfterReceiveReply(ref Message reply, object correlationState) -{ +public void AfterReceiveReply(ref Message reply, object correlationState) +{ // Create the buffer. - MessageBuffer buffer = reply.CreateBufferedCopy(13000); + MessageBuffer buffer = reply.CreateBufferedCopy(13000); // Inspect the response (for example, extract the body contents). Message thisReply = buffer.CreateMessage(); XmlDictionaryReader reader = thisReply.GetReaderAtBodyContents(); var info = new StringBuilder(); - XmlWriter writer = XmlWriter.Create(info); - writer.WriteNode(reader, true); - writer.Close(); - // Resolution: Re-create the message from the buffer before - // closing. - reply = buffer.CreateMessage(); - // You can close the buffer after the message has been recreated. + XmlWriter writer = XmlWriter.Create(info); + writer.WriteNode(reader, true); + writer.Close(); + // Resolution: Re-create the message from the buffer before + // closing. + reply = buffer.CreateMessage(); + // You can close the buffer after the message has been recreated. buffer.Close(); } -``` - +``` + ]]> @@ -262,11 +259,11 @@ public void AfterReceiveReply(ref Message reply, object correlationState) Returns a copy of the original message. An identical copy of the original instance you previously provided to the method of a instance. - instance you previously provided to the method of a instance. You can then save the message to a durable storage. - + instance you previously provided to the method of a instance. You can then save the message to a durable storage. + ]]> @@ -279,11 +276,11 @@ public void AfterReceiveReply(ref Message reply, object correlationState) Creates a new object for navigating this object. - @@ -321,11 +318,11 @@ public void AfterReceiveReply(ref Message reply, object correlationState) Creates a new object for navigating this object. This method cannot be inherited. An object for navigating this object. - @@ -363,11 +360,11 @@ public void AfterReceiveReply(ref Message reply, object correlationState) Creates a new object for navigating this object, with the navigator positioned on the node specified. An object for navigating this object. - @@ -405,11 +402,11 @@ public void AfterReceiveReply(ref Message reply, object correlationState) Creates a new object for navigating this object, with the specified scope. An object for navigating this object. - @@ -443,11 +440,11 @@ public void AfterReceiveReply(ref Message reply, object correlationState) Creates a new object for navigating this object, with the navigator positioned on the specified node and scope. An object for navigating this object. - @@ -527,14 +524,14 @@ public void AfterReceiveReply(ref Message reply, object correlationState) Releases the unmanaged resources used by the and optionally releases the managed resources. This method cannot be inherited. - . This method leaves the in an unusable state. After calling this method, you must release all references to the so the garbage collector can reclaim the memory that the was occupying. - + . This method leaves the in an unusable state. After calling this method, you must release all references to the so the garbage collector can reclaim the memory that the was occupying. + > [!NOTE] -> Always call this method before you release your last reference to the . Otherwise, the resources it is using are not freed until the garbage collector calls the object's `Finalize` method. - +> Always call this method before you release your last reference to the . Otherwise, the resources it is using are not freed until the garbage collector calls the object's `Finalize` method. + ]]> @@ -574,42 +571,42 @@ public void AfterReceiveReply(ref Message reply, object correlationState) An IO stream that the entire content of this buffer is written to. Writes the entire content of this buffer to the specified IO stream. - to a . The code in the example section shows how to work around this problem. - - - -## Examples - + to a . The code in the example section shows how to work around this problem. + + + +## Examples + ```csharp -private byte[] ConvertMessageToByteArray(ref Message message) -{ +private byte[] ConvertMessageToByteArray(ref Message message) +{ // Memory stream that contains the message. - var stream = new MemoryStream(); + var stream = new MemoryStream(); // Create an XmlWriter to serialize the message into a byte array. var settings = new XmlWriterSettings(); settings.Encoding = System.Text.Encoding.UTF8; XmlWriter writer = XmlWriter.Create(stream, settings); // Copy the message into a buffer. // Note: This call changes the original message's state. - MessageBuffer buffer = message.CreateBufferedCopy(int.MaxValue); + MessageBuffer buffer = message.CreateBufferedCopy(int.MaxValue); // Create a copy of the message. - message = buffer.CreateMessage(); + message = buffer.CreateMessage(); // Serialize the message to the XmlWriter. - message.WriteMessage(writer); + message.WriteMessage(writer); // Recreate the message. message = buffer.CreateMessage(); // Flush the contents of the writer so that the stream gets updated. - writer.Flush(); - stream.Flush(); + writer.Flush(); + stream.Flush(); // Convert the stream to an array. byte[] retval = stream.ToArray(); return retval; -} -``` - +} +``` + ]]> diff --git a/xml/System.ServiceModel.Channels/RequestContext.xml b/xml/System.ServiceModel.Channels/RequestContext.xml index e39ec7aa756..239fdc31389 100644 --- a/xml/System.ServiceModel.Channels/RequestContext.xml +++ b/xml/System.ServiceModel.Channels/RequestContext.xml @@ -49,25 +49,22 @@ Provides a reply that is correlated to an incoming request. - . Each encapsulates the information required to reply to the request, so that you do not have to block on the channel when waiting for each request message to receive a reply. - - In the request/reply model, the object is the link between the request that comes in and the reply that goes out. When the server receives a request, it provides a instance that represents the request to the channel. The request context contains the original request message among other useful properties. This request context is then stashed inside the for retrieval by your service. You typically use the property to access the request of the current operation. - - The value of the can be `null`. Because the role of the request context is to link requests to replies, it does not make sense to have a request context when you do not have a reply, and so in this case the context is set to `null`. For a one-way operation on top of the request/reply model, the server receives requests but does not send back a response to the client. So if the is `null` unexpectedly, check first whether the operation contract is IsOneWay. - - Special note for Managed C++ users deriving from this class: - -- Put your cleanup code in (On)(Begin)Close (and/or OnAbort), not in a destructor. - -- Avoid destructors: they cause the compiler to auto-generate . - -- Avoid non-reference members: they can cause the compiler to auto-generate . - -- Avoid finalizers; but if you include one, you should suppress the build warning and call and the finalizer itself from (On)(Begin)Close (and/or OnAbort) to emulate what would have been the auto-generated behavior. - + . Each encapsulates the information required to reply to the request, so that you do not have to block on the channel when waiting for each request message to receive a reply. + + In the request/reply model, the object is the link between the request that comes in and the reply that goes out. When the server receives a request, it provides a instance that represents the request to the channel. The request context contains the original request message among other useful properties. This request context is then stashed inside the for retrieval by your service. You typically use the property to access the request of the current operation. + + The value of the can be `null`. Because the role of the request context is to link requests to replies, it does not make sense to have a request context when you do not have a reply, and so in this case the context is set to `null`. For a one-way operation on top of the request/reply model, the server receives requests but does not send back a response to the client. So if the is `null` unexpectedly, check first whether the operation contract is IsOneWay. + + Special note for Managed C++ users deriving from this class: + +- Put your cleanup code in (On)(Begin)Close (and/or OnAbort), not in a destructor. +- Avoid destructors: they cause the compiler to auto-generate . +- Avoid non-reference members: they can cause the compiler to auto-generate . +- Avoid finalizers; but if you include one, you should suppress the build warning and call and the finalizer itself from (On)(Begin)Close (and/or OnAbort) to emulate what would have been the auto-generated behavior. + ]]> @@ -151,11 +148,11 @@ Begins an asynchronous operation to reply to the request associated with the current context. - @@ -200,13 +197,13 @@ When overridden in a derived class, begins an asynchronous operation to reply to the request associated with the current context. The that references the asynchronous reply operation. - method when the application processing must continue without waiting. Use one of the synchronous methods when it is acceptable for the current thread to be blocked while it replies to the request message or until the time-out interval is exceeded. - - This method receives notification, through a callback, of the identity of the event handler for the operation. The operation is not complete until either the reply is sent or the time-out occurs. - + method when the application processing must continue without waiting. Use one of the synchronous methods when it is acceptable for the current thread to be blocked while it replies to the request message or until the time-out interval is exceeded. + + This method receives notification, through a callback, of the identity of the event handler for the operation. The operation is not complete until either the reply is sent or the time-out occurs. + ]]> @@ -256,13 +253,13 @@ When overridden in a derived class, begins an asynchronous operation to reply to the request associated with the current context within a specified interval of time. The that references the asynchronous reply operation. - method to allow the application processing to continue without waiting for the request to complete. - - Use one of the synchronous methods when it is acceptable for the current thread to be blocked while it replies to the request message or until the time-out interval is exceeded. This method receives notification, through a callback, of the identity of the event handler for the operation. The operation is not complete until either the reply is sent or the time-out occurs. - + method to allow the application processing to continue without waiting for the request to complete. + + Use one of the synchronous methods when it is acceptable for the current thread to be blocked while it replies to the request message or until the time-out interval is exceeded. This method receives notification, through a callback, of the identity of the event handler for the operation. The operation is not complete until either the reply is sent or the time-out occurs. + ]]> @@ -474,13 +471,13 @@ The incoming that contains the request. When overridden in a derived class, replies to a request message. - when it is acceptable for the current thread to be blocked while it replies to the request message. The thread is blocked up to the specified `timeout`. - - If the application processing must continue without waiting for the reply to complete, use the asynchronous method. This method receives notification, through a callback, of the identity of the event handler for the operation. The operation is not complete until either a message becomes available in the channel or the time-out occurs. - + when it is acceptable for the current thread to be blocked while it replies to the request message. The thread is blocked up to the specified `timeout`. + + If the application processing must continue without waiting for the reply to complete, use the asynchronous method. This method receives notification, through a callback, of the identity of the event handler for the operation. The operation is not complete until either a message becomes available in the channel or the time-out occurs. + ]]> @@ -522,13 +519,13 @@ The that specifies the interval of time to wait for the reply to a request. When overridden in a derived class, replies to a request message within a specified interval of time. - when it is acceptable for the current thread to be blocked while it replies to the request message. The thread is blocked up to the specified `timeout`. - - If the application processing must continue without waiting for the reply to complete, use the asynchronous method. This method receives notification, through a callback, of the identity of the event handler for the operation. The operation is not complete until either a message becomes available in the channel or the time-out occurs. - + when it is acceptable for the current thread to be blocked while it replies to the request message. The thread is blocked up to the specified `timeout`. + + If the application processing must continue without waiting for the reply to complete, use the asynchronous method. This method receives notification, through a callback, of the identity of the event handler for the operation. The operation is not complete until either a message becomes available in the channel or the time-out occurs. + ]]> diff --git a/xml/System.ServiceModel.MsmqIntegration/MsmqIntegrationBinding.xml b/xml/System.ServiceModel.MsmqIntegration/MsmqIntegrationBinding.xml index daa8a74188a..132e34e46aa 100644 --- a/xml/System.ServiceModel.MsmqIntegration/MsmqIntegrationBinding.xml +++ b/xml/System.ServiceModel.MsmqIntegration/MsmqIntegrationBinding.xml @@ -17,36 +17,32 @@ The class maps Microsoft Message Queuing (MSMQ) messages to Windows Communication Foundation (WCF) messages. - namespace. - - - -## Examples - The following configuration file snippet illustrates how to configure the binding on the client: - - - - The following configuration file snippet illustrates how to configure the binding on the service: - + This binding can be used to enable WCF applications to send and receive messages to and from existing MSMQ applications that use COM, native C++ APIs, or the types defined in the namespace. + +## Examples + The following configuration file snippet illustrates how to configure the binding on the client: + + The following configuration file snippet illustrates how to configure the binding on the service: + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_msmqtowcf/cs/service.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_msmqtowcf/vb/service.vb" id="Snippet1"::: - - The following code illustrates how to use the binding on the service programmatically: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_msmqtowcf/vb/service.vb" id="Snippet1"::: + + The following code illustrates how to use the binding on the service programmatically: + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_msmqtowcf/cs/service.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_msmqtowcf/vb/service.vb" id="Snippet2"::: - - The following code illustrates how to use the binding on the client programmatically: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_msmqtowcf/vb/service.vb" id="Snippet2"::: + + The following code illustrates how to use the binding on the client programmatically: + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_wcftomsmq/cs/snippets.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_wcftomsmq/vb/snippets.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_wcftomsmq/vb/snippets.vb" id="Snippet2"::: + ]]> @@ -98,19 +94,19 @@ The security mode supported by the Message Queuing (MSMQ) integration channel. Initializes a new instance of the class by using the specified . - and pass in a security mode. - - - -## Examples - The following code illustrates how to instantiate an instance of the binding, specifying the : - + and pass in a security mode. + + + +## Examples + The following code illustrates how to instantiate an instance of the binding, specifying the : + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_wcftomsmq/cs/snippets.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_wcftomsmq/vb/snippets.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_wcftomsmq/vb/snippets.vb" id="Snippet5"::: + ]]> The value is not within the range of values. @@ -136,19 +132,19 @@ The value of the attribute that identifies the element whose settings are used to initialize the binding. Initializes a new instance of the class from the settings of a specified configuration binding element. - binding and initialize it by passing in the name of the binding element: - + binding and initialize it by passing in the name of the binding element: + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_wcftomsmq/cs/snippets.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_wcftomsmq/vb/snippets.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_wcftomsmq/vb/snippets.vb" id="Snippet3"::: + ]]> @@ -210,11 +206,11 @@ Gets the that is associated with this binding. The that is associated with this binding. - encapsulates Message Queuing (MSMQ) transport security settings. - + encapsulates Message Queuing (MSMQ) transport security settings. + ]]> @@ -245,18 +241,18 @@ Gets or sets the serialization format to be used to serialize or deserialize the message. A object that represents the type of serialization to use. - . - - - -## Examples - The following code illustrates how to set the serialization format on an instance of the class: - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_wcftomsmq/cs/client.cs" id="Snippet4"::: - + . + + + +## Examples + The following code illustrates how to set the serialization format on an instance of the class: + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_wcftomsmq/cs/client.cs" id="Snippet4"::: + ]]> diff --git a/xml/System.ServiceModel/ChannelFactory.xml b/xml/System.ServiceModel/ChannelFactory.xml index cb4ef286262..648fe15a4ad 100644 --- a/xml/System.ServiceModel/ChannelFactory.xml +++ b/xml/System.ServiceModel/ChannelFactory.xml @@ -64,36 +64,31 @@ Creates and manages the channels that are used by clients to send messages to service endpoints. - interface and their associated channels are generally used by the initiators of a communication pattern. Listener factories that implement the interface and their associated listeners provide the mechanisms with which channels are accepted for communications. - - This class is not part of the channel model, but of the service model. The method provides the means to create an for a service endpoint. Use it to construct a client that hooks up to an interface contract on the service without using metadata or policy. - + interface and their associated channels are generally used by the initiators of a communication pattern. Listener factories that implement the interface and their associated listeners provide the mechanisms with which channels are accepted for communications. + + This class is not part of the channel model, but of the service model. The method provides the means to create an for a service endpoint. Use it to construct a client that hooks up to an interface contract on the service without using metadata or policy. + > [!NOTE] -> Setting `ChannelFactory.Credentials.Windows.AllowedImpersonationLevel` to `TokenImpersonationLevel.Anonymous` always results in an anonymous logon regardless of impersonation level. - - Special note for Managed C++ users deriving from this class: - -- Put your cleanup code in (On)(Begin)Close (and/or OnAbort), not in a destructor. - -- Avoid destructors; they cause the compiler to auto-generate . - -- Avoid non-reference members; they can cause the compiler to auto-generate . - -- Avoid using a finalizer; but if you include one, you should suppress the build warning and call and the finalizer itself from (On)(Begin)Close (and/or OnAbort) to emulate what would have been the auto-generated behavior. - - When adding behaviors programmatically, the behavior is added to the appropriate `Behaviors` property on the prior to the creation of any channel. See the example section for a code sample. - - - -## Examples - The following code example shows how to insert programmatically a client behavior prior to the creation of the channel object by the factory. - +> Setting `ChannelFactory.Credentials.Windows.AllowedImpersonationLevel` to `TokenImpersonationLevel.Anonymous` always results in an anonymous logon regardless of impersonation level. + + Special note for Managed C++ users deriving from this class: + +- Put your cleanup code in (On)(Begin)Close (and/or OnAbort), not in a destructor. +- Avoid destructors; they cause the compiler to auto-generate . +- Avoid non-reference members; they can cause the compiler to auto-generate . +- Avoid using a finalizer; but if you include one, you should suppress the build warning and call and the finalizer itself from (On)(Begin)Close (and/or OnAbort) to emulate what would have been the auto-generated behavior. + + When adding behaviors programmatically, the behavior is added to the appropriate `Behaviors` property on the prior to the creation of any channel. See the example section for a code sample. + +## Examples + The following code example shows how to insert programmatically a client behavior prior to the creation of the channel object by the factory. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/channelfactorybehaviors/cs/client.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/channelfactorybehaviors/vb/client.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/channelfactorybehaviors/vb/client.vb" id="Snippet10"::: + ]]> @@ -168,11 +163,11 @@ The name of the configuration file. Initializes the channel factory with the behaviors provided by a specified configuration file and with those in the service endpoint of the channel factory. - The service endpoint of the channel factory is . @@ -281,18 +276,18 @@ Gets the credentials used by clients to communicate a service endpoint over the channels produced by the factory. The used by clients if they are configured for the factory or if the endpoint is non- and is in either the created or opening communication state; otherwise . - object is stored as a type of endpoint behavior and can be accessed through the property. - - The method initializes a read-only copy of the object for the factory. - - The object is used by the class (or a class that derives from this class) to create the proxy objects that can call services. The object is also accessible through the property. - + object is stored as a type of endpoint behavior and can be accessed through the property. + + The method initializes a read-only copy of the object for the factory. + + The object is used by the class (or a class that derives from this class) to create the proxy objects that can call services. The object is also accessible through the property. + > [!NOTE] -> Setting `ChannelFactory.Credentials.Windows.AllowedImpersonationLevel` to `TokenImpersonationLevel.Anonymous` always results in an anonymous logon regardless of impersonation level. - +> Setting `ChannelFactory.Credentials.Windows.AllowedImpersonationLevel` to `TokenImpersonationLevel.Anonymous` always results in an anonymous logon regardless of impersonation level. + ]]> @@ -329,11 +324,11 @@ Gets the default interval of time provided for a close operation to complete. The default that specifies how long the close operation has to complete before timing out. - and are `null`. The default value for the service model close time-out is 1 minute. Otherwise, the value is set to the value associated with the . - + and are `null`. The default value for the service model close time-out is 1 minute. Otherwise, the value is set to the value associated with the . + ]]> @@ -370,11 +365,11 @@ Gets the default interval of time provided for an open operation to complete. The default that specifies how long the open operation has to complete before timing out. - and are `null`. The default value for the service model open time-out is 1 minute. Otherwise, the value is set to the value associated with the . - + and are `null`. The default value for the service model open time-out is 1 minute. Otherwise, the value is set to the value associated with the . + ]]> @@ -455,11 +450,11 @@ Opens the current channel factory if it is not yet opened. - , , or . - + , , or . + ]]> The current factory is either closing or closed and so cannot be opened. @@ -509,13 +504,13 @@ Returns the typed object requested, if present, from the appropriate layer in the channel stack, or if not present. The typed object requested if it is present or if it is not. - ` is called on a duplex channel factory, it returns the underlying listener. - + ` is called on a duplex channel factory, it returns the underlying listener. + ]]> @@ -529,11 +524,11 @@ Initializes the service endpoint of the channel factory. - @@ -573,11 +568,11 @@ The to initialize the channel factory with. Initializes the service endpoint of the channel factory with a specified endpoint. - if you have just the binding. Use if you have the configuration. - + if you have just the binding. Use if you have the configuration. + ]]> @@ -621,11 +616,11 @@ The with which to initialize the channel factory. Initializes the service endpoint of the channel factory with a specified binding and address. - if you have the configuration. - + if you have the configuration. + ]]> @@ -666,11 +661,11 @@ The with which to initialize the channel factory. Initializes the service endpoint of the channel factory with a specified address and configuration. - if you have just the binding. - + if you have just the binding. + ]]> @@ -707,11 +702,11 @@ Terminates the inner channel factory of the current channel factory. - method is called on a factory after it transitions to the closing state if the method is invoked. - + method is called on a factory after it transitions to the closing state if the method is invoked. + ]]> @@ -756,11 +751,11 @@ Begins an asynchronous close operation on the inner channel factory of the current channel factory that has a state object associated with it. The that references the asynchronous operation. - @@ -805,11 +800,11 @@ Begins an asynchronous open operation on the inner channel factory of the current channel factory that has a state object associated with it. The that references the asynchronous operation. - @@ -995,11 +990,11 @@ Initializes a read-only copy of the object for the channel factory. - method, which is called during the transition of an object into the opened state. The object is stored as a type of endpoint behavior and can be accessed through the property. - + method, which is called during the transition of an object into the opened state. The object is stored as a type of endpoint behavior and can be accessed through the property. + ]]> diff --git a/xml/System.ServiceModel/ClientBase`1.xml b/xml/System.ServiceModel/ClientBase`1.xml index ccb40267419..71ac9c06de5 100644 --- a/xml/System.ServiceModel/ClientBase`1.xml +++ b/xml/System.ServiceModel/ClientBase`1.xml @@ -85,15 +85,10 @@ Special note for Managed C++ users deriving from this class: -- Put your clean-up code in (On)(Begin)Close (and/or OnAbort), not in a destructor. - -- Avoid destructors: they cause the compiler to auto-generate . - -- Avoid non-reference members: they can cause the compiler to auto-generate . - -- Avoid finalizers; but if you include one, you should suppress the build warning and call and the finalizer itself from (On)(Begin)Close (and/or OnAbort) to emulate what would have been the auto-generated behavior. - - +- Put your clean-up code in (On)(Begin)Close (and/or OnAbort), not in a destructor. +- Avoid destructors: they cause the compiler to auto-generate . +- Avoid non-reference members: they can cause the compiler to auto-generate . +- Avoid finalizers; but if you include one, you should suppress the build warning and call and the finalizer itself from (On)(Begin)Close (and/or OnAbort) to emulate what would have been the auto-generated behavior. ## Examples The following code example shows how the [ServiceModel Metadata Utility Tool (Svcutil.exe)](/dotnet/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe) extends the class to create a WCF client class. diff --git a/xml/System.ServiceModel/DuplexClientBase`1.xml b/xml/System.ServiceModel/DuplexClientBase`1.xml index 2fc73c54fe6..32693f91375 100644 --- a/xml/System.ServiceModel/DuplexClientBase`1.xml +++ b/xml/System.ServiceModel/DuplexClientBase`1.xml @@ -69,15 +69,10 @@ Special note for Managed C++ users deriving from this class: -- Put your cleanup code in (On)(Begin)Close (and/or OnAbort), not in a destructor. - -- Avoid destructors: they cause the compiler to auto-generate - -- Avoid non-reference members: they can cause the compiler to auto-generate - -- Avoid finalizers; but if you include one, you should suppress the build warning and call and the finalizer itself from (On)(Begin)Close (and/or OnAbort) in order to emulate what would have been the auto-generated behavior. - - +- Put your cleanup code in (On)(Begin)Close (and/or OnAbort), not in a destructor. +- Avoid destructors: they cause the compiler to auto-generate . +- Avoid non-reference members: they can cause the compiler to auto-generate . +- Avoid finalizers; but if you include one, you should suppress the build warning and call and the finalizer itself from (On)(Begin)Close (and/or OnAbort) in order to emulate what would have been the auto-generated behavior. ## Examples The following example shows the use in the client of a duplex WCF client type, the `SampleDuplexHelloClient`, to pass a new object with the callback object to listen for callbacks. diff --git a/xml/System.ServiceModel/ServiceHostBase.xml b/xml/System.ServiceModel/ServiceHostBase.xml index 570d1e78f0d..26ef2bfdf29 100644 --- a/xml/System.ServiceModel/ServiceHostBase.xml +++ b/xml/System.ServiceModel/ServiceHostBase.xml @@ -24,29 +24,24 @@ Extends the class to implement hosts that expose custom programming models. - class to create hosts that provide a custom programming model. The Windows Communication Foundation (WCF) service programming model uses the class. - - Special note for Managed C++ users deriving from this class: - -- Put your cleanup code in (On)(Begin)Close (and/or OnAbort), not in a destructor. - -- Avoid destructors; they cause the compiler to auto-generate . - -- Avoid non-reference members; they can cause the compiler to auto-generate . - -- Avoid finalizers; but if you include one, you should suppress the build warning and call and the finalizer itself from (On)(Begin)Close (and/or OnAbort) to emulate what would have been the auto-generated behavior. - - - -## Examples - This sample uses the class, which is derived from . - + class to create hosts that provide a custom programming model. The Windows Communication Foundation (WCF) service programming model uses the class. + + Special note for Managed C++ users deriving from this class: + +- Put your cleanup code in (On)(Begin)Close (and/or OnAbort), not in a destructor. +- Avoid destructors; they cause the compiler to auto-generate . +- Avoid non-reference members; they can cause the compiler to auto-generate . +- Avoid finalizers; but if you include one, you should suppress the build warning and call and the finalizer itself from (On)(Begin)Close (and/or OnAbort) to emulate what would have been the auto-generated behavior. + +## Examples + This sample uses the class, which is derived from . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_selfhost/cs/wholeenchilada.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_selfhost/vb/wholeenchilada.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_selfhost/vb/wholeenchilada.vb" id="Snippet1"::: + ]]> @@ -67,11 +62,11 @@ Initializes a new instance of the class. - @@ -99,11 +94,11 @@ A that contains the base address for services hosted on the current host. Adds a base address to the service host. - to provide the base address after the host is constructed. can be used to add base addresses to an existing host, but throws an exception if the description is already initialized. - + to provide the base address after the host is constructed. can be used to add base addresses to an existing host, but throws an exception if the description is already initialized. + ]]> The cannot be called. @@ -162,15 +157,15 @@ The service endpoint. Adds the specified service endpoint to the hosted service. - exists in the list of configuration names of the service contracts implemented by the service. If the validation passes, the description in the is used as it is, even if the reflected from the service is different. - - As an example, assume that the description in the ServiceEndpoint and the contract description reflected from the service have the same name, but different operation behaviors. The implication of only "by-configuration-name" validation is that there is no validation that the behaviors are the same and there are one updates to one description because of another description. - - If the `address` is a relative URI, one of the base addresses of the (depending on the binding protocol) is used as the endpoint's base address. - + exists in the list of configuration names of the service contracts implemented by the service. If the validation passes, the description in the is used as it is, even if the reflected from the service is different. + + As an example, assume that the description in the ServiceEndpoint and the contract description reflected from the service have the same name, but different operation behaviors. The implication of only "by-configuration-name" validation is that there is no validation that the behaviors are the same and there are one updates to one description because of another description. + + If the `address` is a relative URI, one of the base addresses of the (depending on the binding protocol) is used as the endpoint's base address. + ]]> @@ -213,11 +208,11 @@ Adds a service endpoint to the hosted service with a specified contract, binding, and endpoint address. The added to the hosted service. - @@ -294,11 +289,11 @@ Adds a service endpoint to the hosted service with a specified contract, binding, endpoint address and URI that contains the address at which it listens. The added to the hosted service. - (depending on the binding protocol) is used as the endpoint's base address. - + (depending on the binding protocol) is used as the endpoint's base address. + ]]> @@ -405,11 +400,11 @@ Gets the authorization behavior for the service hosted. The for the service hosted. - @@ -490,11 +485,11 @@ Gets or sets the interval of time allowed for the service host to close. The that specifies the interval of time allowed for the service host to close. - The value, in milliseconds, is less than zero or is larger than Int32.MaxValue (2,147,483,647 or, in hexadecimal notation, 0X7FFFFFFF). @@ -527,11 +522,11 @@ When implemented in a derived class, creates the description of the hosted service. The for the hosted service. - @@ -556,11 +551,11 @@ Gets the credential for the service hosted. The for the service hosted. - @@ -619,11 +614,11 @@ Gets the default interval of time allowed for the service host to open. The that specifies the default interval of time allowed for the service host to open. - @@ -654,11 +649,11 @@ Gets the description of the service hosted. The for the hosted service. - @@ -749,16 +744,16 @@ Increases the limit on the flow rate of messages to the hosted service by a specified increment. The new limit after the increment is added. - property. - - - -## Examples - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_selfhost/cs/wholeenchilada.cs" id="Snippet42"::: - + property. + + + +## Examples + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_selfhost/cs/wholeenchilada.cs" id="Snippet42"::: + ]]> The value is less than zero. @@ -860,16 +855,16 @@ Gets or sets the flow control limit for messages received by the service hosted. The flow control limit for messages received by the service hosted. - method. - - - -## Examples - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_selfhost/cs/wholeenchilada.cs" id="Snippet39"::: - + method. + + + +## Examples + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_selfhost/cs/wholeenchilada.cs" id="Snippet39"::: + ]]> The value is less than zero. @@ -986,19 +981,19 @@ The that specifies how long the on-close operation has to complete before timing out. Closes down the hosted service, including their channel dispatchers and associated instance contexts and listeners. - does the following: - -- Closes all input to , which also closes their associated instances. This stops any new channels from being accepting. - -- Calls on all objects, which mean they stop accepting new messages. - -- Waits for all objects to close down, which happens when their associated channels finish sending all pending messages. - -- Closes the objects associated with the host. - + does the following: + +- Closes all input to , which also closes their associated instances. This stops any new channels from being accepting. + +- Calls on all objects, which mean they stop accepting new messages. + +- Waits for all objects to close down, which happens when their associated channels finish sending all pending messages. + +- Closes the objects associated with the host. + ]]> @@ -1123,11 +1118,11 @@ Gets the service credentials,service authentication and authorization behavior for the hosted service. - @@ -1184,13 +1179,13 @@ Releases the service and channel dispatcher performance counters for the hosted service. - and - - . - + and + + . + ]]> @@ -1274,13 +1269,13 @@ This member is an explicit interface member implementation. It can be used only Occurs when an unknown message is received. - [!WARNING] -> When using , exposing a hosting endpoint, and a exception is thrown, the host passes the message to the event handler. If an attempt is made to read this message an is thrown. The description of the exception will say "This message cannot support the operation because it has been read." The WCF infrastructure reads the message while extracting the message parameters. This message is then passed to the event handler and any attempt to read it causes an exception. If you need to access message parameters in your handler from a hosting endpoint, define the hosting endpoint contract using MessageContract and place the needed data into a message header. For more information about hosting endpoints, see [Workflow Service Host Extensibility](/dotnet/framework/wcf/feature-details/workflow-service-host-extensibility) - +> When using , exposing a hosting endpoint, and a exception is thrown, the host passes the message to the event handler. If an attempt is made to read this message an is thrown. The description of the exception will say "This message cannot support the operation because it has been read." The WCF infrastructure reads the message while extracting the message parameters. This message is then passed to the event handler and any attempt to read it causes an exception. If you need to access message parameters in your handler from a hosting endpoint, define the hosting endpoint contract using MessageContract and place the needed data into a message header. For more information about hosting endpoints, see [Workflow Service Host Extensibility](/dotnet/framework/wcf/feature-details/workflow-service-host-extensibility) + ]]> diff --git a/xml/System.Text/SpanRuneEnumerator.xml b/xml/System.Text/SpanRuneEnumerator.xml index e45e9b64629..29f48783705 100644 --- a/xml/System.Text/SpanRuneEnumerator.xml +++ b/xml/System.Text/SpanRuneEnumerator.xml @@ -33,14 +33,14 @@ Provides an enumerator for the values represented by a span containing UTF-16 text. - method along with language-specific enumeration constructs to enumerate values within spans. -The `foreach` statement of the C# language (`for each` in C++, `For Each` in Visual Basic) hides the complexity of enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. - +The `foreach` statement of the C# language (`For Each` in Visual Basic) hides the complexity of enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. + ]]> diff --git a/xml/System.Text/StringRuneEnumerator.xml b/xml/System.Text/StringRuneEnumerator.xml index 2f1b848c07c..e232b7de589 100644 --- a/xml/System.Text/StringRuneEnumerator.xml +++ b/xml/System.Text/StringRuneEnumerator.xml @@ -39,14 +39,14 @@ Provides an enumerator for the values represented by a string. - method along with language-specific enumeration constructs to enumerate values within strings. -The `foreach` statement of the C# language (`for each` in C++, `For Each` in Visual Basic) hides the complexity of enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. - +The `foreach` statement of the C# language (`For Each` in Visual Basic) hides the complexity of enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. + ]]> @@ -174,13 +174,13 @@ The `foreach` statement of the C# language (`for each` in C++, `For Each` in Vis Returns the current enumerator instance. The current enumerator instance. - instance is cast to an interface. -This member is an explicit interface member implementation. -It can be used only when the instance is cast to an interface. - ]]> @@ -215,13 +215,13 @@ It can be used only when the instance is Returns the current enumerator instance. The current enumerator instance. - instance is cast to an interface. - + ]]> @@ -261,13 +261,13 @@ It can be used only when the instance is Gets the at the current position of the enumerator. The at the current position of the enumerator. - instance is cast to an interface. - + ]]> @@ -301,13 +301,13 @@ It can be used only when the instance is Resets the current instance to the beginning of the string. - instance is cast to an interface. - + ]]> diff --git a/xml/System.Threading/ParameterizedThreadStart.xml b/xml/System.Threading/ParameterizedThreadStart.xml index 4e0e5d84210..f821ca9a38d 100644 --- a/xml/System.Threading/ParameterizedThreadStart.xml +++ b/xml/System.Threading/ParameterizedThreadStart.xml @@ -57,45 +57,41 @@ An object that contains data for the thread procedure. Represents the method that executes on a . - delegate that is passed to the constructor. Any method that has no parameters and that returns `void` in C# or is a `Sub` procedure in Visual Basic can represent the delegate. - -- A delegate that is passed to the constructor. Any method that has a single parameter of type and that returns void in C# or is a Sub procedure in Visual Basic can represent the delegate. - - The thread does not begin executing until the method is called. The or delegate is invoked on the thread, and execution begins at the first line of the method represented by the delegate. In the case of the delegate, the object that is passed to the method is passed to the delegate. - + delegate that is passed to the constructor. Any method that has no parameters and that returns `void` in C# or is a `Sub` procedure in Visual Basic can represent the delegate. + +- A delegate that is passed to the constructor. Any method that has a single parameter of type and that returns void in C# or is a Sub procedure in Visual Basic can represent the delegate. + + The thread does not begin executing until the method is called. The or delegate is invoked on the thread, and execution begins at the first line of the method represented by the delegate. In the case of the delegate, the object that is passed to the method is passed to the delegate. + > [!NOTE] -> Visual Basic and C# users can omit the or delegate constructor when creating a thread. In Visual Basic, use the `AddressOf` operator when passing your method to the constructor; for example, `Dim t As New Thread(AddressOf ThreadProc)`. In C#, simply specify the name of the thread procedure. The compiler selects the correct delegate constructor. - +> Visual Basic and C# users can omit the or delegate constructor when creating a thread. In Visual Basic, use the `AddressOf` operator when passing your method to the constructor; for example, `Dim t As New Thread(AddressOf ThreadProc)`. In C#, simply specify the name of the thread procedure. The compiler selects the correct delegate constructor. + > [!NOTE] -> When you create a delegate for an instance method in C++, the first parameter of the constructor is the instance variable. For a static method, the first parameter of the constructor is zero. For a static method, the delegate constructor requires only one parameter: the address of the callback method, qualified by the class name. - - The delegate and the method overload make it easy to pass data to a thread procedure, but this technique is not type safe because any object can be passed to . A more robust way to pass data to a thread procedure is to put both the thread procedure and the data fields into a worker object. For more information, see [Creating Threads and Passing Data at Start Time](/dotnet/standard/threading/creating-threads-and-passing-data-at-start-time). - - The delegate supports only a single parameter. You can pass multiple data items to the by making that parameter one of the following: - -- An array. - -- A collection type, if all of the data items are of the same type. - -- A tuple type, such as or . - - - -## Examples - The following code example uses a delegate to execute a static method and an instance method. The first delegate is represented by the static `DoWork` method and the second is represented by the instance `DoMoreWork` method. Both methods match the delegate signature; that is, they have a single parameter of type and don't return a value. - +> When you create a delegate for an instance method in C++, the first parameter of the constructor is the instance variable. For a static method, the first parameter of the constructor is zero. For a static method, the delegate constructor requires only one parameter: the address of the callback method, qualified by the class name. + + The delegate and the method overload make it easy to pass data to a thread procedure, but this technique is not type safe because any object can be passed to . A more robust way to pass data to a thread procedure is to put both the thread procedure and the data fields into a worker object. For more information, see [Creating Threads and Passing Data at Start Time](/dotnet/standard/threading/creating-threads-and-passing-data-at-start-time). + + The delegate supports only a single parameter. You can pass multiple data items to the by making that parameter one of the following: + +- An array. +- A collection type, if all of the data items are of the same type. +- A tuple type, such as or . + +## Examples + The following code example uses a delegate to execute a static method and an instance method. The first delegate is represented by the static `DoWork` method and the second is represented by the instance `DoMoreWork` method. Both methods match the delegate signature; that is, they have a single parameter of type and don't return a value. + > [!NOTE] -> The Visual Basic and C# compilers infer the delegate from the signatures of the `DoWork` and `DoMoreWork` methods, and call the correct constructor. Thus, there is no explicit constructor call in the code. - +> The Visual Basic and C# compilers infer the delegate from the signatures of the `DoWork` and `DoMoreWork` methods, and call the correct constructor. Thus, there is no explicit constructor call in the code. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ParameterizedThreadStart/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/ParameterizedThreadStart/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ParameterizedThreadStart/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ParameterizedThreadStart/VB/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Threading/Thread.xml b/xml/System.Threading/Thread.xml index 35e0dbcad5b..bfdf373abc4 100644 --- a/xml/System.Threading/Thread.xml +++ b/xml/System.Threading/Thread.xml @@ -847,16 +847,12 @@ This method is obsolete. On .NET 5 and later versions, calling this method produ property is obsolete.** The non-obsolete alternatives are the method to retrieve the apartment state and the method to set the apartment state. - - In .NET Framework versions 1.0 and 1.1, the `ApartmentState` property marks a thread to indicate that it will execute in a single-threaded or multithreaded apartment. This property can be set when the thread is in the `Unstarted` or `Running` thread state; however, it can be set only once for a thread. If the property has not been set, it returns `Unknown`. - - An attempt to use the property to set the apartment state of a thread whose apartment state has already been set is ignored. However, the method throws a in this case. + **The property is obsolete.** The non-obsolete alternatives are the method to retrieve the apartment state and the method to set the apartment state. > [!IMPORTANT] -> In .NET Framework version 2.0, new threads are initialized as if their apartment state has not been set before they are started. The main application thread is initialized to by default. You can no longer set the main application thread to by setting the property on the first line of code. Use the instead. +> New threads are initialized as if their apartment state has not been set before they're started. The main application thread is initialized to by default. - In .NET Framework version 2.0, you can specify the COM threading model for a C++ application using the [/CLRTHREADATTRIBUTE (Set CLR Thread Attribute)](/cpp/build/reference/clrthreadattribute-set-clr-thread-attribute) linker option. +You can specify the COM threading model for a C++ application using the [/CLRTHREADATTRIBUTE (Set CLR Thread Attribute)](/cpp/build/reference/clrthreadattribute-set-clr-thread-attribute) linker option. ## Examples The following code example demonstrates how to set the apartment state of a thread. diff --git a/xml/System.Threading/ThreadStart.xml b/xml/System.Threading/ThreadStart.xml index b49b5d0e59b..368c6388176 100644 --- a/xml/System.Threading/ThreadStart.xml +++ b/xml/System.Threading/ThreadStart.xml @@ -54,27 +54,23 @@ Represents the method that executes on a . - delegate or a delegate that is passed to the constructor. The thread does not begin executing until the method is called. Execution begins at the first line of the method represented by the or delegate. - + delegate or a delegate that is passed to the constructor. The thread does not begin executing until the method is called. Execution begins at the first line of the method represented by the or delegate. + > [!NOTE] -> Visual Basic and C# users can omit the or delegate constructor when creating a thread. In Visual Basic, use the `AddressOf` operator when passing your method to the constructor; for example, `Dim t As New Thread(AddressOf ThreadProc)`. In C#, simply specify the name of the thread procedure. The compiler selects the correct delegate constructor. -> -> For C++, starting with .NET Framework 2.0, creating a delegate for a static method requires only one parameter: the address of the callback method, qualified by the class name. In earlier versions two parameters were required when creating a delegate for a static method: zero (null) and the method address. For an instance method, all versions require two parameters: the instance variable and the method address. - - - -## Examples - The following code example shows the syntax for creating and using a delegate with an instance method and with a static method. - - For another simple example that demonstrates how to create a delegate, see the method overload. For more information about thread creation, see [Creating Threads and Passing Data at Start Time](/dotnet/standard/threading/creating-threads-and-passing-data-at-start-time). - +> Visual Basic and C# users can omit the or delegate constructor when creating a thread. In Visual Basic, use the `AddressOf` operator when passing your method to the constructor; for example, `Dim t As New Thread(AddressOf ThreadProc)`. In C#, simply specify the name of the thread procedure. The compiler selects the correct delegate constructor. + +## Examples + The following code example shows the syntax for creating and using a delegate with an instance method and with a static method. + + For another simple example that demonstrates how to create a delegate, see the method overload. For more information about thread creation, see [Creating Threads and Passing Data at Start Time](/dotnet/standard/threading/creating-threads-and-passing-data-at-start-time). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ThreadStart2/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/ThreadStart/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ThreadStart2/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ThreadStart2/VB/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Windows.Forms/Control.xml b/xml/System.Windows.Forms/Control.xml index 85b21b56a24..76b850351fd 100644 --- a/xml/System.Windows.Forms/Control.xml +++ b/xml/System.Windows.Forms/Control.xml @@ -11292,9 +11292,7 @@ MyControl.Font = New Font(MyControl.Font, _ property can be used at run time to evaluate the object by name rather than type and programmatic name. Because the property returns a type, it can be evaluated in case-style logic statements (`Select` statement in Visual Basic, `switch` statement in Visual C# and Visual C++). - - + The property can be used at run time to evaluate the object by name rather than type and programmatic name. Because the property returns a type, it can be evaluated in case-style logic statements (`Select` statement in Visual Basic, `switch` statement in C#). ## Examples The following code example displays the of a control in a when the control is added or removed from a form. diff --git a/xml/System.Workflow.ComponentModel/ActivityCollection.xml b/xml/System.Workflow.ComponentModel/ActivityCollection.xml index f5c5e0f7ffe..1be440f31ad 100644 --- a/xml/System.Workflow.ComponentModel/ActivityCollection.xml +++ b/xml/System.Workflow.ComponentModel/ActivityCollection.xml @@ -56,26 +56,26 @@ Models a strongly typed of type . - [!NOTE] -> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] - - This class is used to represent the list of child activities for a . - +> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] + + This class is used to represent the list of child activities for a . + > [!NOTE] -> Only call methods derived from and not , such as using to add activities instead of . Calling methods derived from will have unexpected consequences. - - - -## Examples - The following example shows access of the which is the member of a composite activity class containing all child activities. This code example is part of the Using Throw SDK Sample and is from the ThrowWorkflow.cs file. For more information, see [Using the ThrowActivity Activity](https://msdn.microsoft.com/library/82bc0fef-d78a-4750-82b4-e4cb397a10f1). - +> Only call methods derived from and not , such as using to add activities instead of . Calling methods derived from will have unexpected consequences. + + + +## Examples + The following example shows access of the which is the member of a composite activity class containing all child activities. This code example is part of the Using Throw SDK Sample and is from the ThrowWorkflow.cs file. For more information, see [Using the ThrowActivity Activity](https://msdn.microsoft.com/library/82bc0fef-d78a-4750-82b4-e4cb397a10f1). + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wf_samples/cs/snippets11.cs" id="Snippet179"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/wf_samples/vb/snippets11.vb" id="Snippet179"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/wf_samples/vb/snippets11.vb" id="Snippet179"::: + ]]> @@ -100,11 +100,11 @@ The designated as owning this instance. Initializes a new instance of the class, initializing an owner . - @@ -139,14 +139,14 @@ The to be added to the . Adds the to the . - which is the member of a composite activity class containing all child activities. This example illustrates the use of . This code example is part of the Throw SDK sample and is from the ThrowWorkflow.cs file. For more information, see [Using the ThrowActivity Activity](https://msdn.microsoft.com/library/82bc0fef-d78a-4750-82b4-e4cb397a10f1). - + which is the member of a composite activity class containing all child activities. This example illustrates the use of . This code example is part of the Throw SDK sample and is from the ThrowWorkflow.cs file. For more information, see [Using the ThrowActivity Activity](https://msdn.microsoft.com/library/82bc0fef-d78a-4750-82b4-e4cb397a10f1). + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wf_samples/cs/snippets11.cs" id="Snippet179"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/wf_samples/vb/snippets11.vb" id="Snippet179"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/wf_samples/vb/snippets11.vb" id="Snippet179"::: + ]]> @@ -204,11 +204,11 @@ if the belongs to the ; otherwise, . - is type-safe. A run-time exception is raised if the item is not of type . - + is type-safe. A run-time exception is raised if the item is not of type . + ]]> @@ -262,23 +262,23 @@ Implements an enumeration interface to the . An enumerator that can iterate through the instance. - also brings the enumerator back to this position. At this position, calling raises an exception. Therefore, you must call to advance the enumerator to the first element of the collection before reading the value of . - - returns the same object until either or is called. sets to the next element. - - After the end of the collection is passed, the enumerator is positioned after the last element in the collection, and calling returns `false`. If the last call to returned `false`, calling raises an exception. - - To set `Current` to the first element of the collection again, you can call `Reset` followed by . - - An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying or deleting elements, the enumerator is irreversibly invalidated and the next call to or `Reset` raises an . If the collection is modified between and , will return the element that it is set to, even if the enumerator is already invalidated. - - The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads could still modify the collection. This causes the enumerator to raise an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - + also brings the enumerator back to this position. At this position, calling raises an exception. Therefore, you must call to advance the enumerator to the first element of the collection before reading the value of . + + returns the same object until either or is called. sets to the next element. + + After the end of the collection is passed, the enumerator is positioned after the last element in the collection, and calling returns `false`. If the last call to returned `false`, calling raises an exception. + + To set `Current` to the first element of the collection again, you can call `Reset` followed by . + + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying or deleting elements, the enumerator is irreversibly invalidated and the next call to or `Reset` raises an . If the collection is modified between and , will return the element that it is set to, even if the enumerator is already invalidated. + + The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads could still modify the collection. This causes the enumerator to raise an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. + ]]> @@ -310,11 +310,11 @@ Gets the index of the in the . The index of the in the . Otherwise -1 (if is not in the ). - . - + . + ]]> @@ -347,11 +347,11 @@ The to be inserted into the collection. Inserts the item at the index in the . - is type safe. A run-time exception is raised if an item is not of type . - + is type safe. A run-time exception is raised if an item is not of type . + ]]> @@ -422,11 +422,11 @@ Gets the activity in the based on the string which is a unique key. A member of the ; the key in the which was specified in the call. - in the with specified key, an exception is raised. - + in the with specified key, an exception is raised. + ]]> @@ -451,13 +451,13 @@ Raised whenever a change is made to the contents of this . - delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Handling and Raising Events](/dotnet/standard/events/). - + delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Handling and Raising Events](/dotnet/standard/events/). + ]]> @@ -490,11 +490,11 @@ if the operation succeeded; otherwise, . - is type safe. A run-time exception is raised if an item is not of type . - + is type safe. A run-time exception is raised if an item is not of type . + ]]> @@ -526,11 +526,11 @@ Position in a zero-based index to remove the activity from the collection. Removes the in the at the specified . - @@ -561,11 +561,11 @@ The to add to the . Adds an object to the at the end of the . - is not of type . - + is not of type . + ]]> @@ -593,11 +593,11 @@ Clears all activities from the . - property is zero after this operation is finished. - + property is zero after this operation is finished. + ]]> @@ -630,11 +630,11 @@ if value is in the collection; otherwise, . - is not of type . - + is not of type . + ]]> @@ -672,10 +672,10 @@ is less than zero. - is multidimensional. - - is equal to or greater than the length of . - + is multidimensional. + + is equal to or greater than the length of . + The number of elements in the source is greater than the available space from to the end of the destination array. The type cannot be cast automatically to the type of the destination . @@ -729,11 +729,11 @@ if the is read-only; otherwise, . - @@ -766,13 +766,13 @@ if was successfully removed from the ; otherwise, . This method also returns if is not found in the original . - uses , whereas, allows the user to specify the implementation to use for comparing keys. - - In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. - + uses , whereas, allows the user to specify the implementation to use for comparing keys. + + In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. + ]]> The is read-only. @@ -802,25 +802,25 @@ Returns an enumerator that iterates through the collection. An that can be used to iterate through the collection. - is undefined. Therefore, you must call to advance the enumerator to the first element of the collection before reading the value of . - - returns the same object until is called. sets to the next element. - - If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns false. When the enumerator is at this position, subsequent calls to also return false. If the last call to returned false, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. - - An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and its behavior is undefined. - - The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - Default implementations of collections in the namespace are not synchronized. - + is undefined. Therefore, you must call to advance the enumerator to the first element of the collection before reading the value of . + + returns the same object until is called. sets to the next element. + + If passes the end of the collection, the enumerator is positioned after the last element in the collection and returns false. When the enumerator is at this position, subsequent calls to also return false. If the last call to returned false, is undefined. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. + + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and its behavior is undefined. + + The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + Default implementations of collections in the namespace are not synchronized. + ]]> @@ -852,11 +852,11 @@ Determines the index of a specific item in the . The index of if found in the list; otherwise, -1. - @@ -889,11 +889,11 @@ The object to insert. It must be of type . Inserts an into the at the zero-based index specified. - cannot be cast to an , a custom is raised. - + cannot be cast to an , a custom is raised. + ]]> @@ -925,13 +925,13 @@ Gets or sets the element at the specified index. The at the specified index. - @@ -965,11 +965,11 @@ The zero-based index of the item to remove. Removes the item at the specified index. - @@ -1031,15 +1031,15 @@ if access to the is synchronized, that is, thread-safe; otherwise, . - returns an object, which can be used to synchronize access to the . - - Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. - - Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - + returns an object, which can be used to synchronize access to the . + + Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. + + Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. + ]]> @@ -1067,13 +1067,13 @@ Gets an object that can be used to synchronize access to the . An object that can be used to synchronize access to the . - property. - - Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. - + property. + + Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. + ]]> @@ -1102,11 +1102,11 @@ Returns an that iterates through the underlying . An that can be used to iterate through the collection. - only allows for reading the data in the collection. You cannot use an to modify the underlying collection. - + only allows for reading the data in the collection. You cannot use an to modify the underlying collection. + ]]> @@ -1287,11 +1287,11 @@ This member is an explicit interface member implementation. It can be used only if the has a fixed size; otherwise, . - @@ -1385,15 +1385,15 @@ This member is an explicit interface member implementation. It can be used only The to remove from the . Removes the first occurrence of a specific object from the . - - The is read-only. - + The is read-only. + has a fixed size. diff --git a/xml/System/Activator.xml b/xml/System/Activator.xml index c53417e1b0b..e1832e60c4d 100644 --- a/xml/System/Activator.xml +++ b/xml/System/Activator.xml @@ -1905,14 +1905,14 @@ An error occurred when attempting remote activation in a target specified in generic method is used by compilers to implement the instantiation of types specified by type parameters. For example, in the following generic method, the implementation of `new T()` (`gcnew T()` in C++) uses the generic method. + The generic method is used by compilers to implement the instantiation of types specified by type parameters. For example, in the following generic method, the implementation of `new T()` uses the generic method. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.activation.createinstance~~1/cpp/remarks.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Activator/CreateInstanceT/remarks.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.activation.createinstance~~1/fs/remarks.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.activation.createinstance~~1/vb/remarks.vb" id="Snippet1"::: - In general, there is no use for the generic method in application code, because the type must be known at compile time. If the type is known at compile time, normal instantiation syntax can be used (`new` operator in C#, `New` in Visual Basic, `gcnew` in C++). If the type is not known at compile time, you can call a non-generic overload of . + In general, there is no use for the generic method in application code, because the type must be known at compile time. If the type is known at compile time, normal instantiation syntax can be used (`new` operator in C#, `New` in Visual Basic). If the type is not known at compile time, you can call a non-generic overload of . There are no overloads of the generic method that take argument lists, because the non-generic overloads of already provide late-bound constructor resolution. diff --git a/xml/System/Array.xml b/xml/System/Array.xml index 1918ee348d9..b3812d3e062 100644 --- a/xml/System/Array.xml +++ b/xml/System/Array.xml @@ -320,14 +320,14 @@ Either `value` or every element of `array` must implement the interface, which is used for comparisons. The elements of `array` must already be sorted in increasing value according to the sort order defined by the implementation; otherwise, the result might be incorrect. > [!NOTE] -> If`value` does not implement the interface, the elements of `array` are not tested for before the search begins. An exception is thrown if the search encounters an element that does not implement . +> If`value` does not implement the interface, the elements of `array` are not tested for before the search begins. An exception is thrown if the search encounters an element that does not implement . Duplicate elements are allowed. If the contains more than one element equal to `value`, the method returns the index of only one of the occurrences, and not necessarily the first one. `null` can always be compared with any other reference type; therefore, comparisons with `null` do not generate an exception. > [!NOTE] -> For every element tested, `value` is passed to the appropriate implementation, even if `value` is `null`. That is, the implementation determines how a given element compares to `null`. +> For every element tested, `value` is passed to the appropriate implementation, even if `value` is `null`. That is, the implementation determines how a given element compares to `null`. This method is an O(log `n`) operation, where `n` is the of `array`. @@ -337,7 +337,7 @@ The following code example shows how to use to locate a specific object in an . > [!NOTE] -> The array is created with its elements in ascending sort order. The method requires the array to be sorted in ascending order. +> The array is created with its elements in ascending sort order. The method requires the array to be sorted in ascending order. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Array.BinarySearch Example/CPP/source.cpp" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_Classic/classic Array.BinarySearch Example/FS/source.fs" id="Snippet1"::: @@ -442,14 +442,14 @@ If`comparer` is `null`, the comparison is done using the implementation provided by the element itself or by the specified value. The elements of `array` must already be sorted in increasing value according to the sort order defined by the implementation; otherwise, the result might be incorrect. > [!NOTE] -> If `comparer` is `null` and `value` does not implement the interface, the elements of `array` are not tested for before the search begins. An exception is thrown if the search encounters an element that does not implement . +> If `comparer` is `null` and `value` does not implement the interface, the elements of `array` are not tested for before the search begins. An exception is thrown if the search encounters an element that does not implement . Duplicate elements are allowed. If the contains more than one element equal to `value`, the method returns the index of only one of the occurrences, and not necessarily the first one. `null` can always be compared with any other reference type; therefore, comparisons with `null` do not generate an exception. > [!NOTE] -> For every element tested, `value` is passed to the appropriate implementation, even if `value` is `null`. That is, the implementation determines how a given element compares to `null`. +> For every element tested, `value` is passed to the appropriate implementation, even if `value` is `null`. That is, the implementation determines how a given element compares to `null`. This method is an O(log `n`) operation, where `n` is the of `array`. @@ -546,14 +546,14 @@ Either `value` or every element of `array` must implement the interface, which is used for comparisons. The elements of `array` must already be sorted in increasing value according to the sort order defined by the implementation; otherwise, the result might be incorrect. > [!NOTE] -> If `value` does not implement the interface, the elements of `array` are not tested for before the search begins. An exception is thrown if the search encounters an element that does not implement . +> If `value` does not implement the interface, the elements of `array` are not tested for before the search begins. An exception is thrown if the search encounters an element that does not implement . Duplicate elements are allowed. If the contains more than one element equal to `value`, the method returns the index of only one of the occurrences, and not necessarily the first one. `null` can always be compared with any other reference type; therefore, comparisons with `null` do not generate an exception. > [!NOTE] -> For every element tested, `value` is passed to the appropriate implementation, even if `value` is `null`. That is, the implementation determines how a given element compares to `null`. +> For every element tested, `value` is passed to the appropriate implementation, even if `value` is `null`. That is, the implementation determines how a given element compares to `null`. This method is an O(log `n`) operation, where `n` is `length`. @@ -673,14 +673,14 @@ If `comparer` is `null`, the comparison is done using the implementation provided by the element itself or by the specified value. The elements of `array` must already be sorted in increasing value according to the sort order defined by the implementation; otherwise, the result might be incorrect. > [!NOTE] -> If `comparer` is `null` and `value` does not implement the interface, the elements of `array` are not tested for before the search begins. An exception is thrown if the search encounters an element that does not implement . +> If `comparer` is `null` and `value` does not implement the interface, the elements of `array` are not tested for before the search begins. An exception is thrown if the search encounters an element that does not implement . Duplicate elements are allowed. If the contains more than one element equal to `value`, the method returns the index of only one of the occurrences, and not necessarily the first one. `null` can always be compared with any other reference type; therefore, comparisons with `null` do not generate an exception when using . > [!NOTE] -> For every element tested, `value` is passed to the appropriate implementation, even if `value` is `null`. That is, the implementation determines how a given element compares to `null`. +> For every element tested, `value` is passed to the appropriate implementation, even if `value` is `null`. That is, the implementation determines how a given element compares to `null`. This method is an O(log `n`) operation, where `n` is `length`. @@ -789,7 +789,7 @@ `null` can always be compared with any other reference type; therefore, comparisons with `null` do not generate an exception. > [!NOTE] -> For every element tested, `value` is passed to the appropriate implementation, even if `value` is `null`. That is, the implementation determines how a given element compares to `null`. +> For every element tested, `value` is passed to the appropriate implementation, even if `value` is `null`. That is, the implementation determines how a given element compares to `null`. This method is an O(log `n`) operation, where `n` is the of `array`. @@ -801,9 +801,9 @@ The array is displayed, sorted, and displayed again. Arrays must be sorted in order to use the method. > [!NOTE] -> The calls to the and generic methods do not look any different from calls to their nongeneric counterparts, because Visual Basic, F#, C#, and C++ infer the type of the generic type parameter from the type of the first argument. If you use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to examine the Microsoft intermediate language (MSIL), you can see that the generic methods are being called. +> The calls to the and generic methods do not look any different from calls to their nongeneric counterparts, because Visual Basic, F#, C#, and C++ infer the type of the generic type parameter from the type of the first argument. If you use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to examine the Microsoft intermediate language (MSIL), you can see that the generic methods are being called. - The generic method overload is then used to search for two strings, one that is not in the array and one that is. The array and the return value of the method are passed to the `ShowWhere` generic method (the `showWhere` function in the F# example), which displays the index value if the string is found, and otherwise the elements the search string would fall between if it were in the array. The index is negative if the string is not in the array, so the `ShowWhere` method takes the bitwise complement (the ~ operator in C# and Visual C++, the ~~~ operator in F#, `Xor`-1 in Visual Basic) to obtain the index of the first element in the list that is larger than the search string. + The generic method overload is then used to search for two strings, one that is not in the array and one that is. The array and the return value of the method are passed to the `ShowWhere` generic method (the `showWhere` function in the F# example), which displays the index value if the string is found, and otherwise the elements the search string would fall between if it were in the array. The index is negative if the string is not in the array, so the `ShowWhere` method takes the bitwise complement (the ~ operator in C#, the ~~~ operator in F#, `Xor`-1 in Visual Basic) to obtain the index of the first element in the list that is larger than the search string. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Array_SortSearch/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Array/BinarySearchT/source.cs" interactive="try-dotnet" id="Snippet1"::: @@ -914,30 +914,28 @@ If `comparer` is `null`, the comparison is done using the generic interface implementation provided by `T`. The elements of `array` must already be sorted in increasing value according to the sort order defined by the implementation; otherwise, the result might be incorrect. > [!NOTE] -> If `comparer` is `null` and `value` does not implement the generic interface, the elements of `array` are not tested for before the search begins. An exception is thrown if the search encounters an element that does not implement . +> If `comparer` is `null` and `value` does not implement the generic interface, the elements of `array` are not tested for before the search begins. An exception is thrown if the search encounters an element that does not implement . Duplicate elements are allowed. If the contains more than one element equal to `value`, the method returns the index of only one of the occurrences, and not necessarily the first one. `null` can always be compared with any other reference type; therefore, comparisons with `null` do not generate an exception. > [!NOTE] -> For every element tested, `value` is passed to the appropriate implementation, even if `value` is `null`. That is, the implementation determines how a given element compares to `null`. +> For every element tested, `value` is passed to the appropriate implementation, even if `value` is `null`. That is, the implementation determines how a given element compares to `null`. This method is an O(log `n`) operation, where `n` is the of `array`. - - ## Examples The following example demonstrates the generic method overload and the generic method overload. - The code example defines an alternative comparer for strings, named `ReverseCompare`, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic, `IComparer` in Visual C++) generic interface. The comparer calls the method, reversing the order of the comparands so that the strings sort high-to-low instead of low-to-high. + The code example defines an alternative comparer for strings, named `ReverseCompare`, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic) generic interface. The comparer calls the method, reversing the order of the comparands so that the strings sort high-to-low instead of low-to-high. The array is displayed, sorted, and displayed again. Arrays must be sorted in order to use the method. > [!NOTE] -> The calls to the and generic methods do not look any different from calls to their nongeneric counterparts, because Visual Basic, C#, and C++ infer the type of the generic type parameter from the type of the first argument. If you use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to examine the Microsoft intermediate language (MSIL), you can see that the generic methods are being called. +> The calls to the and generic methods do not look any different from calls to their nongeneric counterparts, because Visual Basic, C#, and C++ infer the type of the generic type parameter from the type of the first argument. If you use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to examine the Microsoft intermediate language (MSIL), you can see that the generic methods are being called. - The generic method overload is then used to search for two strings, one that is not in the array and one that is. The array and the return value of the method are passed to the `ShowWhere` generic method (the `showWhere` function in the F# example), which displays the index value if the string is found, and otherwise the elements the search string would fall between if it were in the array. The index is negative if the string is not n the array, so the `ShowWhere` method takes the bitwise complement (the ~ operator in C# and Visual C++, the ~~~ operator in F#, `Xor` -1 in Visual Basic) to obtain the index of the first element in the list that is larger than the search string. + The generic method overload is then used to search for two strings, one that is not in the array and one that is. The array and the return value of the method are passed to the `ShowWhere` generic method (the `showWhere` function in the F# example), which displays the index value if the string is found, and otherwise the elements the search string would fall between if it were in the array. The index is negative if the string is not n the array, so the `ShowWhere` method takes the bitwise complement (the ~ operator in C#, the ~~~ operator in F#, `Xor` -1 in Visual Basic) to obtain the index of the first element in the list that is larger than the search string. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Array_SortSearchComparer/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Array/BinarySearchT/source1.cs" interactive="try-dotnet" id="Snippet1"::: @@ -1041,7 +1039,7 @@ `null` can always be compared with any other reference type; therefore, comparisons with `null` do not generate an exception. > [!NOTE] -> For every element tested, `value` is passed to the appropriate implementation, even if `value` is `null`. That is, the implementation determines how a given element compares to `null`. +> For every element tested, `value` is passed to the appropriate implementation, even if `value` is `null`. That is, the implementation determines how a given element compares to `null`. This method is an O(log `n`) operation, where `n` is `length`. @@ -1173,7 +1171,7 @@ `null` can always be compared with any other reference type; therefore, comparisons with `null` do not generate an exception when using . > [!NOTE] -> For every element tested, `value` is passed to the appropriate implementation, even if `value` is `null`. That is, the implementation determines how a given element compares to `null`. +> For every element tested, `value` is passed to the appropriate implementation, even if `value` is `null`. That is, the implementation determines how a given element compares to `null`. This method is an O(log `n`) operation, where `n` is `length`. @@ -1741,23 +1739,23 @@ The arrays can be reference-type arrays or value-type arrays. Type downcasting is performed, as required. -- When copying from a reference-type array to a value-type array, each element is unboxed and then copied. When copying from a value-type array to a reference-type array, each element is boxed and then copied. +- When copying from a reference-type array to a value-type array, each element is unboxed and then copied. When copying from a value-type array to a reference-type array, each element is boxed and then copied. -- When copying from a reference-type or value-type array to an array, an is created to hold each value or reference and then copied. When copying from an array to a reference-type or value-type array and the assignment is not possible, an is thrown. +- When copying from a reference-type or value-type array to an array, an is created to hold each value or reference and then copied. When copying from an array to a reference-type or value-type array and the assignment is not possible, an is thrown. -- If `sourceArray` and `destinationArray` are both reference-type arrays or are both arrays of type , a shallow copy is performed. A shallow copy of an is a new containing references to the same elements as the original . The elements themselves or anything referenced by the elements are not copied. In contrast, a deep copy of an copies the elements and everything directly or indirectly referenced by the elements. +- If `sourceArray` and `destinationArray` are both reference-type arrays or are both arrays of type , a shallow copy is performed. A shallow copy of an is a new containing references to the same elements as the original . The elements themselves or anything referenced by the elements are not copied. In contrast, a deep copy of an copies the elements and everything directly or indirectly referenced by the elements. An is thrown if the arrays are of incompatible types. Type compatibility is defined as follows: -- A type is compatible with itself. +- A type is compatible with itself. -- A value type is compatible with and with an interface type implemented by that value type. A value type is considered connected to an interface only if it implements that interface directly. Disconnected types are not compatible. +- A value type is compatible with and with an interface type implemented by that value type. A value type is considered connected to an interface only if it implements that interface directly. Disconnected types are not compatible. -- Two intrinsic (predefined) value types are compatible if copying from the source type to the destination type is a widening conversion. A widening conversion never loses information, whereas a narrowing conversion can lose information. For example, converting a 32-bit signed integer to a 64-bit signed integer is a widening conversion, and converting a 64-bit signed integer to a 32-bit signed integer is a narrowing conversion. For more information about conversions, see . +- Two intrinsic (predefined) value types are compatible if copying from the source type to the destination type is a widening conversion. A widening conversion never loses information, whereas a narrowing conversion can lose information. For example, converting a 32-bit signed integer to a 64-bit signed integer is a widening conversion, and converting a 64-bit signed integer to a 32-bit signed integer is a narrowing conversion. For more information about conversions, see . -- A nonintrinsic (user-defined) value type is compatible only with itself. +- A nonintrinsic (user-defined) value type is compatible only with itself. -- Enumerations have an implicit conversion to and to their underlying type. +- Enumerations have an implicit conversion to and to their underlying type. If every element in `sourceArray` requires a downcast (for example, from a base class to a derived class or from an interface to an object) and one or more elements cannot be cast to the corresponding type in `destinationArray`, an is thrown. @@ -1857,23 +1855,23 @@ The arrays can be reference-type arrays or value-type arrays. Type downcasting is performed, as required. -- When copying from a reference-type array to a value-type array, each element is unboxed and then copied. When copying from a value-type array to a reference-type array, each element is boxed and then copied. +- When copying from a reference-type array to a value-type array, each element is unboxed and then copied. When copying from a value-type array to a reference-type array, each element is boxed and then copied. -- When copying from a reference-type or value-type array to an array, an is created to hold each value or reference and then copied. When copying from an array to a reference-type or value-type array and the assignment is not possible, an is thrown. +- When copying from a reference-type or value-type array to an array, an is created to hold each value or reference and then copied. When copying from an array to a reference-type or value-type array and the assignment is not possible, an is thrown. -- If `sourceArray` and `destinationArray` are both reference-type arrays or are both arrays of type , a shallow copy is performed. A shallow copy of an is a new containing references to the same elements as the original . The elements themselves or anything referenced by the elements are not copied. In contrast, a deep copy of an copies the elements and everything directly or indirectly referenced by the elements. +- If `sourceArray` and `destinationArray` are both reference-type arrays or are both arrays of type , a shallow copy is performed. A shallow copy of an is a new containing references to the same elements as the original . The elements themselves or anything referenced by the elements are not copied. In contrast, a deep copy of an copies the elements and everything directly or indirectly referenced by the elements. An is thrown if the arrays are of incompatible types. Type compatibility is defined as follows: -- A type is compatible with itself. +- A type is compatible with itself. -- A value type is compatible with and with an interface type implemented by that value type. A value type is considered connected to an interface only if it implements that interface directly. Disconnected types are not compatible. +- A value type is compatible with and with an interface type implemented by that value type. A value type is considered connected to an interface only if it implements that interface directly. Disconnected types are not compatible. -- Two intrinsic (predefined) value types are compatible if copying from the source type to the destination type is a widening conversion. A widening conversion never loses information, whereas a narrowing conversion can lose information. For example, converting a 32-bit signed integer to a 64-bit signed integer is a widening conversion, and converting a 64-bit signed integer to a 32-bit signed integer is a narrowing conversion. For more information about conversions, see . +- Two intrinsic (predefined) value types are compatible if copying from the source type to the destination type is a widening conversion. A widening conversion never loses information, whereas a narrowing conversion can lose information. For example, converting a 32-bit signed integer to a 64-bit signed integer is a widening conversion, and converting a 64-bit signed integer to a 32-bit signed integer is a narrowing conversion. For more information about conversions, see . -- A nonintrinsic (user-defined) value type is compatible only with itself. +- A nonintrinsic (user-defined) value type is compatible only with itself. -- Enumerations have an implicit conversion to and to their underlying type. +- Enumerations have an implicit conversion to and to their underlying type. If every element in `sourceArray` requires a downcast (for example, from a base class to a derived class or from an interface to an object) and one or more elements cannot be cast to the corresponding type in `destinationArray`, an is thrown. @@ -1985,23 +1983,23 @@ The arrays can be reference-type arrays or value-type arrays. Type downcasting is performed, as required. -- When copying from a reference-type array to a value-type array, each element is unboxed and then copied. When copying from a value-type array to a reference-type array, each element is boxed and then copied. +- When copying from a reference-type array to a value-type array, each element is unboxed and then copied. When copying from a value-type array to a reference-type array, each element is boxed and then copied. -- When copying from a reference-type or value-type array to an array, an is created to hold each value or reference and then copied. When copying from an array to a reference-type or value-type array and the assignment is not possible, an is thrown. +- When copying from a reference-type or value-type array to an array, an is created to hold each value or reference and then copied. When copying from an array to a reference-type or value-type array and the assignment is not possible, an is thrown. -- If `sourceArray` and `destinationArray` are both reference-type arrays or are both arrays of type , a shallow copy is performed. A shallow copy of an is a new containing references to the same elements as the original . The elements themselves or anything referenced by the elements are not copied. In contrast, a deep copy of an copies the elements and everything directly or indirectly referenced by the elements. +- If `sourceArray` and `destinationArray` are both reference-type arrays or are both arrays of type , a shallow copy is performed. A shallow copy of an is a new containing references to the same elements as the original . The elements themselves or anything referenced by the elements are not copied. In contrast, a deep copy of an copies the elements and everything directly or indirectly referenced by the elements. An is thrown if the arrays are of incompatible types. Type compatibility is defined as follows: -- A type is compatible with itself. +- A type is compatible with itself. -- A value type is compatible with and with an interface type implemented by that value type. A value type is considered connected to an interface only if it implements that interface directly. Disconnected types are not compatible. +- A value type is compatible with and with an interface type implemented by that value type. A value type is considered connected to an interface only if it implements that interface directly. Disconnected types are not compatible. -- Two intrinsic (predefined) value types are compatible if copying from the source type to the destination type is a widening conversion. A widening conversion never loses information, whereas a narrowing conversion can lose information. For example, converting a 32-bit signed integer to a 64-bit signed integer is a widening conversion, and converting a 64-bit signed integer to a 32-bit signed integer is a narrowing conversion. For more information about conversions, see . +- Two intrinsic (predefined) value types are compatible if copying from the source type to the destination type is a widening conversion. A widening conversion never loses information, whereas a narrowing conversion can lose information. For example, converting a 32-bit signed integer to a 64-bit signed integer is a widening conversion, and converting a 64-bit signed integer to a 32-bit signed integer is a narrowing conversion. For more information about conversions, see . -- A nonintrinsic (user-defined) value type is compatible only with itself. +- A nonintrinsic (user-defined) value type is compatible only with itself. -- Enumerations have an implicit conversion to and to their underlying type. +- Enumerations have an implicit conversion to and to their underlying type. If every element in `sourceArray` requires a downcast (for example, from a base class to a derived class or from an interface to an object) and one or more elements cannot be cast to the corresponding type in `destinationArray`, an is thrown. @@ -2113,23 +2111,23 @@ The arrays can be reference-type arrays or value-type arrays. Type downcasting is performed, as required. -- When copying from a reference-type array to a value-type array, each element is unboxed and then copied. When copying from a value-type array to a reference-type array, each element is boxed and then copied. +- When copying from a reference-type array to a value-type array, each element is unboxed and then copied. When copying from a value-type array to a reference-type array, each element is boxed and then copied. -- When copying from a reference-type or value-type array to an array, an is created to hold each value or reference and then copied. When copying from an array to a reference-type or value-type array and the assignment is not possible, an is thrown. +- When copying from a reference-type or value-type array to an array, an is created to hold each value or reference and then copied. When copying from an array to a reference-type or value-type array and the assignment is not possible, an is thrown. -- If `sourceArray` and `destinationArray` are both reference-type arrays or are both arrays of type , a shallow copy is performed. A shallow copy of an is a new containing references to the same elements as the original . The elements themselves or anything referenced by the elements are not copied. In contrast, a deep copy of an copies the elements and everything directly or indirectly referenced by the elements. +- If `sourceArray` and `destinationArray` are both reference-type arrays or are both arrays of type , a shallow copy is performed. A shallow copy of an is a new containing references to the same elements as the original . The elements themselves or anything referenced by the elements are not copied. In contrast, a deep copy of an copies the elements and everything directly or indirectly referenced by the elements. An is thrown if the arrays are of incompatible types. Type compatibility is defined as follows: -- A type is compatible with itself. +- A type is compatible with itself. -- A value type is compatible with and with an interface type implemented by that value type. A value type is considered connected to an interface only if it implements that interface directly. Disconnected types are not compatible. +- A value type is compatible with and with an interface type implemented by that value type. A value type is considered connected to an interface only if it implements that interface directly. Disconnected types are not compatible. -- Two intrinsic (predefined) value types are compatible if copying from the source type to the destination type is a widening conversion. A widening conversion never loses information, whereas a narrowing conversion can lose information. For example, converting a 32-bit signed integer to a 64-bit signed integer is a widening conversion, and converting a 64-bit signed integer to a 32-bit signed integer is a narrowing conversion. For more information about conversions, see . +- Two intrinsic (predefined) value types are compatible if copying from the source type to the destination type is a widening conversion. A widening conversion never loses information, whereas a narrowing conversion can lose information. For example, converting a 32-bit signed integer to a 64-bit signed integer is a widening conversion, and converting a 64-bit signed integer to a 32-bit signed integer is a narrowing conversion. For more information about conversions, see . -- A nonintrinsic (user-defined) value type is compatible only with itself. +- A nonintrinsic (user-defined) value type is compatible only with itself. -- Enumerations have an implicit conversion to and to their underlying type. +- Enumerations have an implicit conversion to and to their underlying type. If every element in `sourceArray` requires a downcast (for example, from a base class to a derived class or from an interface to an object) and one or more elements cannot be cast to the corresponding type in `destinationArray`, an is thrown. @@ -3285,7 +3283,7 @@ The is a delegate to a method that returns `true` if the object passed to it matches the conditions defined in the delegate. The elements of `array` are individually passed to the , and processing is stopped when a match is found. > [!NOTE] -> In C# and Visual Basic, it is not necessary to create the delegate explicitly. These languages infer the correct delegate from context and create it automatically. In F#, functions and lambda expressions are implicitly converted. +> In C# and Visual Basic, it is not necessary to create the delegate explicitly. These languages infer the correct delegate from context and create it automatically. In F#, functions and lambda expressions are implicitly converted. This method is an O(`n`) operation, where `n` is the of `array`. @@ -3512,7 +3510,7 @@ The following example uses a delegate with the generic method to search an array of structures. The method the delegate represents, `ProductGT10`, returns `true` if the product of the X and Y fields is greater than 100,000. The method calls the delegate for each element of the array, returning the first point that meets the test condition. > [!NOTE] -> Visual Basic, C#, and F# users do not have to create the delegate explicitly or specify the type argument of the generic method. The compilers determine the necessary types from the method arguments you supply. +> Visual Basic, C#, and F# users do not have to create the delegate explicitly or specify the type argument of the generic method. The compilers determine the necessary types from the method arguments you supply. :::code language="csharp" source="~/snippets/csharp/System/Array/FindT/source.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.array.find/fs/source.fs" id="Snippet1"::: @@ -3623,7 +3621,7 @@ The generic method traverses the array from the beginning, passing each element in turn to the `EndsWithSaurus` method. The search stops when the `EndsWithSaurus` method returns `true` for the element "Amargasaurus". > [!NOTE] -> In C#, F#, and Visual Basic, it is not necessary to create the `Predicate` delegate (`Predicate(Of String)` in Visual Basic) explicitly. These languages infer the correct delegate from context and create it automatically. +> In C#, F#, and Visual Basic, it is not necessary to create the `Predicate` delegate (`Predicate(Of String)` in Visual Basic) explicitly. These languages infer the correct delegate from context and create it automatically. The generic method is used to search the array backward from the end. It finds the element "Dilophosaurus" at position 5. The generic method is used to return an array containing all the elements that end in "saurus". The elements are displayed. @@ -3671,7 +3669,7 @@ The method overload traverses the array from the beginning, passing each element in turn to the `EndsWithSaurus` method. The search stops when the `EndsWithSaurus` method returns `true` for the element at position 1. > [!NOTE] -> In C#, F#, and Visual Basic, it is not necessary to create the `Predicate` delegate (`Predicate(Of String)` in Visual Basic) explicitly. These languages infer the correct delegate from context and create it automatically. +> In C#, F#, and Visual Basic, it is not necessary to create the `Predicate` delegate (`Predicate(Of String)` in Visual Basic) explicitly. These languages infer the correct delegate from context and create it automatically. The method overload is used to search the array beginning at position 2 and continuing to the end of the array. It finds the element at position 5. Finally, the method overload is used to search the range of three elements beginning at position 2. It returns -1 because there are no dinosaur names in that range that end with "saurus". @@ -4035,7 +4033,7 @@ The generic method traverses the array from the beginning, passing each element in turn to the `EndsWithSaurus` method. The search stops when the `EndsWithSaurus` method returns `true` for the element "Amargasaurus". > [!NOTE] -> In C# and Visual Basic, it is not necessary to create the`Predicate` delegate (`Predicate(Of String)` in Visual Basic) explicitly. These languages infer the correct delegate from context and create it automatically. +> In C# and Visual Basic, it is not necessary to create the`Predicate` delegate (`Predicate(Of String)` in Visual Basic) explicitly. These languages infer the correct delegate from context and create it automatically. The generic method is used to search the array backward from the end. It finds the element "Dilophosaurus" at position 5. The generic method is used to return an array containing all the elements that end in "saurus". The elements are displayed. @@ -4083,7 +4081,7 @@ The method overload traverses the array backward from the end, passing each element in turn to the `EndsWithSaurus` method. The search stops when the `EndsWithSaurus` method returns `true` for the element at position 5. > [!NOTE] -> In C#, F# and Visual Basic, it is not necessary to create the `Predicate` delegate (`Predicate(Of String)` in Visual Basic) explicitly. These languages infer the correct delegate from context and create it automatically. +> In C#, F# and Visual Basic, it is not necessary to create the `Predicate` delegate (`Predicate(Of String)` in Visual Basic) explicitly. These languages infer the correct delegate from context and create it automatically. The method overload is used to search the array beginning at position 4 and continuing backward to the beginning of the array. It finds the element at position 1. Finally, the method overload is used to search the range of three elements beginning at position 4 and working backward (that is, elements 4, 3, and 2). It returns -1 because there are no dinosaur names in that range that end with "saurus". @@ -4507,7 +4505,7 @@ ## Remarks - The `foreach` statement of the C# language (`for each` in C++, `For Each` in Visual Basic) hides the complexity of the enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. + The `foreach` statement of the C# language (`For Each` in Visual Basic) hides the complexity of the enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. @@ -5558,11 +5556,11 @@ ## Examples The example calls the following three overloads of the method to find the index of a string in a string array: -- , to determine the first occurrence of the string "the" in a string array. +- , to determine the first occurrence of the string "the" in a string array. -- , to determine the first occurrence of the string "the" in the fourth to the last elements of a string array. +- , to determine the first occurrence of the string "the" in the fourth to the last elements of a string array. -- , to determine the first occurrence of the string "the" in a string array from the element that follows the last successful match to the end of the array. +- , to determine the first occurrence of the string "the" in a string array from the element that follows the last successful match to the end of the array. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Array.IndexOf Example/CPP/source.cpp" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_Classic/classic Array.IndexOf Example/FS/source.fs" id="Snippet1"::: @@ -5659,11 +5657,11 @@ ## Examples The example calls the following three overloads of the method to find the index of a string in a string array: -- , to determine the first occurrence of the string "the" in a string array. +- , to determine the first occurrence of the string "the" in a string array. -- , to determine the first occurrence of the string "the" in the fourth to the last elements of a string array. +- , to determine the first occurrence of the string "the" in the fourth to the last elements of a string array. -- , to determine the first occurrence of the string "the" in a string array from the element that follows the last successful match to the end of the array. +- , to determine the first occurrence of the string "the" in a string array from the element that follows the last successful match to the end of the array. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Array.IndexOf Example/CPP/source.cpp" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_Classic/classic Array.IndexOf Example/FS/source.fs" id="Snippet1"::: @@ -5769,11 +5767,11 @@ ## Examples The example calls the following three overloads of the method to find the index of a string in a string array: -- , to determine the first occurrence of the string "the" in a string array. +- , to determine the first occurrence of the string "the" in a string array. -- , to determine the first occurrence of the string "the" in the fourth to the last elements of a string array. +- , to determine the first occurrence of the string "the" in the fourth to the last elements of a string array. -- , to determine the first occurrence of the string "the" in a string array from the element that follows the last successful match to the end of the array. To determine the value of the `count` argument, it subtracts the upper bound of the array from the starting index and adds one. +- , to determine the first occurrence of the string "the" in a string array from the element that follows the last successful match to the end of the array. To determine the value of the `count` argument, it subtracts the upper bound of the array from the starting index and adds one. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Array.IndexOf Example/CPP/source.cpp" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_Classic/classic Array.IndexOf Example/FS/source.fs" id="Snippet1"::: @@ -7709,7 +7707,7 @@ int[,,] TDArray = new int[1,1,1]; This method is an O(1) operation. > [!NOTE] -> If is used to assign `null` to an element of an array of value types, all fields of the element are initialized to zero. The value of the element is not a null reference, and cannot be found by searching for a null reference. +> If is used to assign `null` to an element of an array of value types, all fields of the element are initialized to zero. The value of the element is not a null reference, and cannot be found by searching for a null reference. @@ -7806,7 +7804,7 @@ int[,,] TDArray = new int[1,1,1]; This method is an O(1) operation. > [!NOTE] -> If is used to assign `null` to an element of an array of value types, all fields of the element are initialized to zero. The value of the element is not a null reference, and cannot be found by searching for a null reference. +> If is used to assign `null` to an element of an array of value types, all fields of the element are initialized to zero. The value of the element is not a null reference, and cannot be found by searching for a null reference. @@ -7884,7 +7882,7 @@ int[,,] TDArray = new int[1,1,1]; This method is an O(1) operation. > [!NOTE] -> If is used to assign `null` to an element of an array of value types, all fields of the element are initialized to zero. The value of the element is not a null reference, and cannot be found by searching for a null reference. +> If is used to assign `null` to an element of an array of value types, all fields of the element are initialized to zero. The value of the element is not a null reference, and cannot be found by searching for a null reference. @@ -7977,7 +7975,7 @@ int[,,] TDArray = new int[1,1,1]; This method is an O(1) operation. > [!NOTE] -> If is used to assign `null` to an element of an array of value types, all fields of the element are initialized to zero. The value of the element is not a null reference, and cannot be found by searching for a null reference. +> If is used to assign `null` to an element of an array of value types, all fields of the element are initialized to zero. The value of the element is not a null reference, and cannot be found by searching for a null reference. @@ -8057,7 +8055,7 @@ int[,,] TDArray = new int[1,1,1]; This method is an O(1) operation. > [!NOTE] -> If is used to assign `null` to an element of an array of value types, all fields of the element are initialized to zero. The value of the element is not a null reference, and cannot be found by searching for a null reference. +> If is used to assign `null` to an element of an array of value types, all fields of the element are initialized to zero. The value of the element is not a null reference, and cannot be found by searching for a null reference. @@ -8135,7 +8133,7 @@ int[,,] TDArray = new int[1,1,1]; This method is an O(1) operation. > [!NOTE] -> If is used to assign `null` to an element of an array of value types, all fields of the element are initialized to zero. The value of the element is not a null reference, and cannot be found by searching for a null reference. +> If is used to assign `null` to an element of an array of value types, all fields of the element are initialized to zero. The value of the element is not a null reference, and cannot be found by searching for a null reference. @@ -8215,7 +8213,7 @@ int[,,] TDArray = new int[1,1,1]; This method is an O(1) operation. > [!NOTE] -> If is used to assign `null` to an element of an array of value types, all fields of the element are initialized to zero. The value of the element is not a null reference, and cannot be found by searching for a null reference. +> If is used to assign `null` to an element of an array of value types, all fields of the element are initialized to zero. The value of the element is not a null reference, and cannot be found by searching for a null reference. ]]> @@ -8295,7 +8293,7 @@ int[,,] TDArray = new int[1,1,1]; This method is an O(1) operation. > [!NOTE] -> If is used to assign `null` to an element of an array of value types, all fields of the element are initialized to zero. The value of the element is not a null reference, and cannot be found by searching for a null reference. +> If is used to assign `null` to an element of an array of value types, all fields of the element are initialized to zero. The value of the element is not a null reference, and cannot be found by searching for a null reference. @@ -8385,11 +8383,11 @@ int[,,] TDArray = new int[1,1,1]; This method uses the introspective sort ([introsort](https://en.wikipedia.org/wiki/Introsort)) algorithm as follows: -- If the partition size is less than or equal to 16 elements, it uses an [insertion sort](https://en.wikipedia.org/wiki/Insertion_sort) algorithm. +- If the partition size is less than or equal to 16 elements, it uses an [insertion sort](https://en.wikipedia.org/wiki/Insertion_sort) algorithm. -- If the number of partitions exceeds 2 * LogN, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. +- If the number of partitions exceeds 2 * LogN, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. -- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. +- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. This implementation performs an unstable sort; that is, if two elements are equal, their order might not be preserved. In contrast, a stable sort preserves the order of elements that are equal. @@ -8494,11 +8492,11 @@ int[,,] TDArray = new int[1,1,1]; This method uses the introspective sort ([introsort](https://en.wikipedia.org/wiki/Introsort)) algorithm as follows: -- If the partition size is less than or equal to 16 elements, it uses an [insertion sort](https://en.wikipedia.org/wiki/Insertion_sort) algorithm. +- If the partition size is less than or equal to 16 elements, it uses an [insertion sort](https://en.wikipedia.org/wiki/Insertion_sort) algorithm. -- If the number of partitions exceeds 2 * LogN, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. +- If the number of partitions exceeds 2 * LogN, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. -- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. +- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. This implementation performs an unstable sort; that is, if two elements are equal, their order might not be preserved. In contrast, a stable sort preserves the order of elements that are equal. @@ -8607,11 +8605,11 @@ int[,,] TDArray = new int[1,1,1]; This method uses the introspective sort ([introsort](https://en.wikipedia.org/wiki/Introsort)) algorithm as follows: -- If the partition size is less than or equal to 16 elements, it uses an [insertion sort](https://en.wikipedia.org/wiki/Insertion_sort) algorithm. +- If the partition size is less than or equal to 16 elements, it uses an [insertion sort](https://en.wikipedia.org/wiki/Insertion_sort) algorithm. -- If the number of partitions exceeds 2 * LogN, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. +- If the number of partitions exceeds 2 * LogN, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. -- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. +- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. This implementation performs an unstable sort; that is, if two elements are equal, their order might not be preserved. In contrast, a stable sort preserves the order of elements that are equal. @@ -8750,11 +8748,11 @@ This method is an O(`n` log `n`) operation, where `n` is the N, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. +- If the number of partitions exceeds 2 * LogN, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. -- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. +- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. This implementation performs an unstable sort; that is, if two elements are equal, their order might not be preserved. In contrast, a stable sort preserves the order of elements that are equal. @@ -8861,11 +8859,11 @@ This method is an O(`n` log `n`) operation, where `n` is the N, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. +- If the number of partitions exceeds 2 * LogN, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. -- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. +- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. This implementation performs an unstable sort; that is, if two elements are equal, their order might not be preserved. In contrast, a stable sort preserves the order of elements that are equal. @@ -8982,11 +8980,11 @@ This method is an O(`n` log `n`) operation, where `n` is the N, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. +- If the number of partitions exceeds 2 * LogN, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. -- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. +- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. This implementation performs an unstable sort; that is, if two elements are equal, their order might not be preserved. In contrast, a stable sort preserves the order of elements that are equal. @@ -9123,11 +9121,11 @@ This method is an O(`n` log `n`) operation, where `n` is the N, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. +- If the number of partitions exceeds 2 * LogN, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. -- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. +- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. This implementation performs an unstable sort; that is, if two elements are equal, their order might not be preserved. In contrast, a stable sort preserves the order of elements that are equal. @@ -9274,11 +9272,11 @@ This method is an O(`n` log `n`) operation, where `n` is the N, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. +- If the number of partitions exceeds 2 * LogN, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. -- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. +- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. This implementation performs an unstable sort; that is, if two elements are equal, their order might not be preserved. In contrast, a stable sort preserves the order of elements that are equal. @@ -9409,11 +9407,11 @@ This method is an O(`n` log `n`) operation, where `n` is the N, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. +- If the number of partitions exceeds 2 * LogN, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. -- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. +- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. This implementation performs an unstable sort; that is, if two elements are equal, their order might not be preserved. In contrast, a stable sort preserves the order of elements that are equal. @@ -9427,9 +9425,9 @@ This method is an O(`n` log `n`) operation, where `n` is the [!NOTE] -> The calls to the and generic methods do not look any different from calls to their nongeneric counterparts, because Visual Basic, C#, and C++ infer the type of the generic type parameter from the type of the first argument. If you use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to examine the Microsoft intermediate language (MSIL), you can see that the generic methods are being called. +> The calls to the and generic methods do not look any different from calls to their nongeneric counterparts, because Visual Basic, C#, and C++ infer the type of the generic type parameter from the type of the first argument. If you use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to examine the Microsoft intermediate language (MSIL), you can see that the generic methods are being called. - The generic method overload is then used to search for two strings, one that is not in the array and one that is. The array and the return value of the method are passed to the `ShowWhere` generic method, which displays the index value if the string is found, and otherwise the elements the search string would fall between if it were in the array. The index is negative if the string is not n the array, so the `ShowWhere` method takes the bitwise complement (the ~ operator in C# and Visual C++, `Xor` -1 in Visual Basic) to obtain the index of the first element in the list that is larger than the search string. + The generic method overload is then used to search for two strings, one that is not in the array and one that is. The array and the return value of the method are passed to the `ShowWhere` generic method, which displays the index value if the string is found, and otherwise the elements the search string would fall between if it were in the array. The index is negative if the string is not n the array, so the `ShowWhere` method takes the bitwise complement (the ~ operator in C#, `Xor` -1 in Visual Basic) to obtain the index of the first element in the list that is larger than the search string. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Array_SortSearch/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Array/BinarySearchT/source.cs" interactive="try-dotnet" id="Snippet1"::: @@ -9527,11 +9525,11 @@ This method is an O(`n` log `n`) operation, where `n` is the N, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. +- If the number of partitions exceeds 2 * LogN, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. -- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. +- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. This implementation performs an unstable sort; that is, if two elements are equal, their order might not be preserved. In contrast, a stable sort preserves the order of elements that are equal. @@ -9542,14 +9540,14 @@ This method is an O(`n` log `n`) operation, where `n` is the generic method overload and the generic method overload. - The code example defines an alternative comparer for strings, named `ReverseCompare`, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic, `IComparer` in Visual C++) generic interface. The comparer calls the method, reversing the order of the comparands so that the strings sort high-to-low instead of low-to-high. + The code example defines an alternative comparer for strings, named `ReverseCompare`, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic,) generic interface. The comparer calls the method, reversing the order of the comparands so that the strings sort high-to-low instead of low-to-high. The array is displayed, sorted, and displayed again. Arrays must be sorted in order to use the method. > [!NOTE] -> The calls to the and generic methods do not look any different from calls to their nongeneric counterparts, because Visual Basic, C#, and C++ infer the type of the generic type parameter from the type of the first argument. If you use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to examine the Microsoft intermediate language (MSIL), you can see that the generic methods are being called. +> The calls to the and generic methods do not look any different from calls to their nongeneric counterparts, because Visual Basic, C#, and C++ infer the type of the generic type parameter from the type of the first argument. If you use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to examine the Microsoft intermediate language (MSIL), you can see that the generic methods are being called. - The generic method overload is then used to search for two strings, one that is not in the array and one that is. The array and the return value of the method are passed to the `ShowWhere` generic method, which displays the index value if the string is found, and otherwise the elements the search string would fall between if it were in the array. The index is negative if the string is not n the array, so the `ShowWhere` method takes the bitwise complement (the ~ operator in C# and Visual C++, `Xor` -1 in Visual Basic) to obtain the index of the first element in the list that is larger than the search string. + The generic method overload is then used to search for two strings, one that is not in the array and one that is. The array and the return value of the method are passed to the `ShowWhere` generic method, which displays the index value if the string is found, and otherwise the elements the search string would fall between if it were in the array. The index is negative if the string is not n the array, so the `ShowWhere` method takes the bitwise complement (the ~ operator in C#, `Xor` -1 in Visual Basic) to obtain the index of the first element in the list that is larger than the search string. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Array_SortSearchComparer/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Array/BinarySearchT/source1.cs" interactive="try-dotnet" id="Snippet1"::: @@ -9637,11 +9635,11 @@ This method is an O(`n` log `n`) operation, where `n` is the N, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. +- If the number of partitions exceeds 2 * LogN, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. -- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. +- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. This implementation performs an unstable sort; that is, if two elements are equal, their order might not be preserved. In contrast, a stable sort preserves the order of elements that are equal. @@ -9753,11 +9751,11 @@ This method is an O(`n` log `n`) operation, where `n` is the N, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. +- If the number of partitions exceeds 2 * LogN, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. -- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. +- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. This implementation performs an unstable sort; that is, if two elements are equal, their order might not be preserved. In contrast, a stable sort preserves the order of elements that are equal. @@ -9768,12 +9766,12 @@ This method is an O(`n` log `n`) operation, where `n` is the generic method overload and the generic method overload for sorting a range in an array. - The code example defines an alternative comparer for strings, named `ReverseCompare`, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic, `IComparer` in Visual C++) generic interface. The comparer calls the method, reversing the order of the comparands so that the strings sort high-to-low instead of low-to-high. + The code example defines an alternative comparer for strings, named `ReverseCompare`, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic) generic interface. The comparer calls the method, reversing the order of the comparands so that the strings sort high-to-low instead of low-to-high. The code example creates and displays an array of dinosaur names, consisting of three herbivores followed by three carnivores (tyrannosaurids, to be precise). The generic method overload is used to sort the last three elements of the array, which is then displayed. The generic method overload is used with `ReverseCompare` to sort the last three elements in reverse order. The thoroughly confused dinosaurs are displayed again. > [!NOTE] -> The calls to the and generic methods do not look any different from calls to their nongeneric counterparts, because Visual Basic, C#, and C++ infer the type of the generic type parameter from the type of the first argument. If you use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to examine the Microsoft intermediate language (MSIL), you can see that the generic methods are being called. +> The calls to the and generic methods do not look any different from calls to their nongeneric counterparts, because Visual Basic, C#, and C++ infer the type of the generic type parameter from the type of the first argument. If you use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to examine the Microsoft intermediate language (MSIL), you can see that the generic methods are being called. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Array_SortIntIntIComparer/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Array/SortT/source1.cs" interactive="try-dotnet" id="Snippet1"::: @@ -9887,11 +9885,11 @@ This method is an O(`n` log `n`) operation, where `n` is the N, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. +- If the number of partitions exceeds 2 * LogN, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. -- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. +- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. This implementation performs an unstable sort; that is, if two elements are equal, their order might not be preserved. In contrast, a stable sort preserves the order of elements that are equal. @@ -9902,12 +9900,12 @@ This method is an O(`n` log `n`) operation, where `n` is the generic method overload and the generic method overload for sorting a range in an array. - The code example defines an alternative comparer for strings, named `ReverseCompare`, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic, `IComparer` in Visual C++) generic interface. The comparer calls the method, reversing the order of the comparands so that the strings sort high-to-low instead of low-to-high. + The code example defines an alternative comparer for strings, named `ReverseCompare`, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic) generic interface. The comparer calls the method, reversing the order of the comparands so that the strings sort high-to-low instead of low-to-high. The code example creates and displays an array of dinosaur names, consisting of three herbivores followed by three carnivores (tyrannosaurids, to be precise). The generic method overload is used to sort the last three elements of the array, which is then displayed. The generic method overload is used with `ReverseCompare` to sort the last three elements in reverse order. The thoroughly confused dinosaurs are displayed again. > [!NOTE] -> The calls to the and generic methods do not look any different from calls to their nongeneric counterparts, because Visual Basic, C#, and C++ infer the type of the generic type parameter from the type of the first argument. If you use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to examine the Microsoft intermediate language (MSIL), you can see that the generic methods are being called. +> The calls to the and generic methods do not look any different from calls to their nongeneric counterparts, because Visual Basic, C#, and C++ infer the type of the generic type parameter from the type of the first argument. If you use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to examine the Microsoft intermediate language (MSIL), you can see that the generic methods are being called. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Array_SortIntIntIComparer/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Array/SortT/source1.cs" interactive="try-dotnet" id="Snippet1"::: @@ -10026,11 +10024,11 @@ This method is an O(`n` log `n`) operation, where `n` is the N, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. +- If the number of partitions exceeds 2 * LogN, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. -- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. +- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. This implementation performs an unstable sort; that is, if two elements are equal, their order might not be preserved. In contrast, a stable sort preserves the order of elements that are equal. @@ -10041,20 +10039,17 @@ This method is an O(`n` log `n`) operation, where `n` is the , , , and generic method overloads, for sorting pairs of arrays that represent keys and values. - The code example defines an alternative comparer for strings, named `ReverseCompare`, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic, `IComparer` in Visual C++) generic interface. The comparer calls the method, reversing the order of the comparands so that the strings sort high-to-low instead of low-to-high. + The code example defines an alternative comparer for strings, named `ReverseCompare`, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic) generic interface. The comparer calls the method, reversing the order of the comparands so that the strings sort high-to-low instead of low-to-high. The code example creates and displays an array of dinosaur names (the keys) and an array of integers representing the maximum length of each dinosaur in meters (the values). The arrays are then sorted and displayed several times: -- The overload is used to sort both arrays in order of the dinosaur names in the first array. - -- The overload and an instance of `ReverseCompare` are used to reverse the sort order of the paired arrays. - -- The overload is used to sort the last three elements of both arrays. - -- The overload is used to sort the last three elements of both arrays in reverse order. +- The overload is used to sort both arrays in order of the dinosaur names in the first array. +- The overload and an instance of `ReverseCompare` are used to reverse the sort order of the paired arrays. +- The overload is used to sort the last three elements of both arrays. +- The overload is used to sort the last three elements of both arrays in reverse order. > [!NOTE] -> The calls to the generic methods do not look any different from calls to their nongeneric counterparts, because Visual Basic, C#, and C++ infer the type of the generic type parameter from the type of the first two arguments. If you use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to examine the Microsoft intermediate language (MSIL), you can see that the generic methods are being called. +> The calls to the generic methods do not look any different from calls to their nongeneric counterparts, because Visual Basic, C#, and C++ infer the type of the generic type parameter from the type of the first two arguments. If you use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to examine the Microsoft intermediate language (MSIL), you can see that the generic methods are being called. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Array_Sort2IntIntIComparer/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Array/SortTKey,TValue/source.cs" interactive="try-dotnet" id="Snippet1"::: @@ -10172,11 +10167,11 @@ This method is an O(`n` log `n`) operation, where `n` is the N, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. +- If the number of partitions exceeds 2 * LogN, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. -- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. +- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. This implementation performs an unstable sort; that is, if two elements are equal, their order might not be preserved. In contrast, a stable sort preserves the order of elements that are equal. @@ -10185,20 +10180,17 @@ This method is an O(`n` log `n`) operation, where `n` is the , [\], , , and generic method overloads, for sorting pairs of arrays that represent keys and values. - The code example defines an alternative comparer for strings, named `ReverseCompare`, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic, `IComparer` in Visual C++) generic interface. The comparer calls the method, reversing the order of the comparands so that the strings sort high-to-low instead of low-to-high. + The code example defines an alternative comparer for strings, named `ReverseCompare`, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic) generic interface. The comparer calls the method, reversing the order of the comparands so that the strings sort high-to-low instead of low-to-high. The code example creates and displays an array of dinosaur names (the keys) and an array of integers representing the maximum length of each dinosaur in meters (the values). The arrays are then sorted and displayed several times: -- The overload is used to sort both arrays in order of the dinosaur names in the first array. - -- The overload and an instance of `ReverseCompare` are used to reverse the sort order of the paired arrays. - -- The overload is used to sort the last three elements of both arrays. - -- The overload is used to sort the last three elements of both arrays in reverse order. +- The overload is used to sort both arrays in order of the dinosaur names in the first array. +- The overload and an instance of `ReverseCompare` are used to reverse the sort order of the paired arrays. +- The overload is used to sort the last three elements of both arrays. +- The overload is used to sort the last three elements of both arrays in reverse order. > [!NOTE] -> The calls to the generic methods do not look any different from calls to their nongeneric counterparts, because Visual Basic, C#, and C++ infer the type of the generic type parameter from the type of the first two arguments. If you use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to examine the Microsoft intermediate language (MSIL), you can see that the generic methods are being called. +> The calls to the generic methods do not look any different from calls to their nongeneric counterparts, because Visual Basic, C#, and C++ infer the type of the generic type parameter from the type of the first two arguments. If you use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to examine the Microsoft intermediate language (MSIL), you can see that the generic methods are being called. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Array_Sort2IntIntIComparer/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Array/SortTKey,TValue/source.cs" interactive="try-dotnet" id="Snippet1"::: @@ -10319,11 +10311,11 @@ This method is an O(`n` log `n`) operation, where `n` is the N, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. +- If the number of partitions exceeds 2 * LogN, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. -- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. +- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. This implementation performs an unstable sort; that is, if two elements are equal, their order might not be preserved. In contrast, a stable sort preserves the order of elements that are equal. @@ -10332,17 +10324,14 @@ This method is an O(`n` log `n`) operation, where `n` is the , , , and generic method overloads, for sorting pairs of arrays that represent keys and values. - The code example defines an alternative comparer for strings, named `ReverseCompare`, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic, `IComparer` in Visual C++) generic interface. The comparer calls the method, reversing the order of the comparands so that the strings sort high-to-low instead of low-to-high. + The code example defines an alternative comparer for strings, named `ReverseCompare`, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic) generic interface. The comparer calls the method, reversing the order of the comparands so that the strings sort high-to-low instead of low-to-high. The code example creates and displays an array of dinosaur names (the keys) and an array of integers representing the maximum length of each dinosaur in meters (the values). The arrays are then sorted and displayed several times: -- The overload is used to sort both arrays in order of the dinosaur names in the first array. - -- The overload and an instance of `ReverseCompare` are used to reverse the sort order of the paired arrays. - -- The overload is used to sort the last three elements of both arrays. - -- The overload is used to sort the last three elements of both arrays in reverse order. +- The overload is used to sort both arrays in order of the dinosaur names in the first array. +- The overload and an instance of `ReverseCompare` are used to reverse the sort order of the paired arrays. +- The overload is used to sort the last three elements of both arrays. +- The overload is used to sort the last three elements of both arrays in reverse order. > [!NOTE] > The calls to the generic methods do not look any different from calls to their nongeneric counterparts, because Visual Basic, C#, and C++ infer the type of the generic type parameter from the type of the first two arguments. If you use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to examine the Microsoft intermediate language (MSIL), you can see that the generic methods are being called. @@ -10484,11 +10473,11 @@ This method is an O(`n` log `n`) operation, where `n` is the N, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. +- If the number of partitions exceeds 2 * LogN, where *N* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. -- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. +- Otherwise, it uses a [Quicksort](https://en.wikipedia.org/wiki/Quicksort) algorithm. This implementation performs an unstable sort; that is, if two elements are equal, their order might not be preserved. In contrast, a stable sort preserves the order of elements that are equal. @@ -10497,17 +10486,14 @@ This method is an O(`n` log `n`) operation, where `n` is the , , , and generic method overloads, for sorting pairs of arrays that represent keys and values. - The code example defines an alternative comparer for strings, named `ReverseCompare`, which implements the `IComparer`(`IComparer(Of String)` in Visual Basic, `IComparer` in Visual C++) generic interface. The comparer calls the method, reversing the order of the comparands so that the strings sort high-to-low instead of low-to-high. + The code example defines an alternative comparer for strings, named `ReverseCompare`, which implements the `IComparer`(`IComparer(Of String)` in Visual Basic) generic interface. The comparer calls the method, reversing the order of the comparands so that the strings sort high-to-low instead of low-to-high. The code example creates and displays an array of dinosaur names (the keys) and an array of integers representing the maximum length of each dinosaur in meters (the values). The arrays are then sorted and displayed several times: -- The overload is used to sort both arrays in order of the dinosaur names in the first array. - -- The overload and an instance of `ReverseCompare` are used to reverse the sort order of the paired arrays. - -- The overload is used to sort the last three elements of both arrays. - -- The overload is used to sort the last three elements of both arrays in reverse order. +- The overload is used to sort both arrays in order of the dinosaur names in the first array. +- The overload and an instance of `ReverseCompare` are used to reverse the sort order of the paired arrays. +- The overload is used to sort the last three elements of both arrays. +- The overload is used to sort the last three elements of both arrays in reverse order. > [!NOTE] > The calls to the generic methods do not look any different from calls to their nongeneric counterparts, because Visual Basic, C#, and C++ infer the type of the generic type parameter from the type of the first two arguments. If you use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to examine the Microsoft intermediate language (MSIL), you can see that the generic methods are being called. @@ -11634,7 +11620,7 @@ This member is an explicit interface member implementation. It can be used only In both cases, the method returns `false` as soon as it encounters the first array element that does not end in a number. Otherwise, it returns `true` after iterating all the elements in the array. > [!NOTE] -> As both examples show, in C# and Visual Basic, it is not necessary to create the `Predicate` delegate (`Predicate(Of String)` in Visual Basic) explicitly. These languages infer the correct delegate from context and create it automatically. +> As both examples show, in C# and Visual Basic, it is not necessary to create the `Predicate` delegate (`Predicate(Of String)` in Visual Basic) explicitly. These languages infer the correct delegate from context and create it automatically. ]]> diff --git a/xml/System/AttributeTargets.xml b/xml/System/AttributeTargets.xml index cddbd938d66..de7f4fa7266 100644 --- a/xml/System/AttributeTargets.xml +++ b/xml/System/AttributeTargets.xml @@ -64,26 +64,24 @@ Specifies the application elements on which it is valid to apply an attribute. - class uses this enumeration to specify the kind of element on which it is valid to apply an attribute. - - enumeration values can be combined with a bitwise OR operation to get the preferred combination. - - - -## Examples - The following example illustrates the application of attributes to various targets. - + class uses this enumeration to specify the kind of element on which it's valid to apply an attribute. + + enumeration values can be combined with a bitwise OR operation to get the preferred combination. + +## Examples + The following example illustrates the application of attributes to various targets. + > [!NOTE] -> Visual Basic and Visual C++ syntax currently do not support the application of attributes to type parameters. - +> Visual Basic doesn't support the application of attributes to type parameters. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AttrTargs/CPP/attrtargs.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/AttributeTargets/Overview/attrtargs.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/AttrTargs/FS/attrtargs.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AttrTargs/VB/AttrTargs.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AttrTargs/VB/AttrTargs.vb" id="Snippet1"::: + ]]> diff --git a/xml/System/BadImageFormatException.xml b/xml/System/BadImageFormatException.xml index 96696e6fba8..65f457d1132 100644 --- a/xml/System/BadImageFormatException.xml +++ b/xml/System/BadImageFormatException.xml @@ -117,7 +117,7 @@ :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.badimageformatexception.class/fs/targetplatform1.fs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.badimageformatexception.class/vb/targetplatform1.vb" id="Snippet4"::: -- Reflecting on C++ executable files may throw this exception. This is most likely caused by the C++ compiler stripping the relocation addresses or the .Reloc section from the executable file. To preserve the .relocation address in a C++ executable file, specify /fixed:no when linking. +- Reflecting on C++ executable files might throw this exception. This is most likely caused by the C++ compiler stripping the relocation addresses or the .Reloc section from the executable file. To preserve the .relocation address in a C++ executable file, specify /fixed:no when linking. uses the HRESULT `COR_E_BADIMAGEFORMAT`, which has the value 0x8007000B. diff --git a/xml/System/CrossAppDomainDelegate.xml b/xml/System/CrossAppDomainDelegate.xml index 72822815b07..80b9acadf40 100644 --- a/xml/System/CrossAppDomainDelegate.xml +++ b/xml/System/CrossAppDomainDelegate.xml @@ -28,11 +28,10 @@ Used by for cross-application domain calls. - and has a constructor and an `Invoke` method. See the C++ code example given in the description for . - + and has a constructor and an `Invoke` method. + ]]> diff --git a/xml/System/Decimal.xml b/xml/System/Decimal.xml index e3e2bc3a8c5..6fc654d3158 100644 --- a/xml/System/Decimal.xml +++ b/xml/System/Decimal.xml @@ -3634,8 +3634,7 @@ For , this method matches the IE to a . The syntax for such explicit conversions is language-dependent, and individual language compilers can provide different implementations and return different results. The example illustrates the different return values when you explicitly convert a value to a value by using C#, C++, and Visual Basic. To perform a conversion that is independent of language, you can call the or the method. - + This operator supports the explicit conversion of a to a . The syntax for such explicit conversions is language-dependent, and individual language compilers can provide different implementations and return different results. The example illustrates the different return values when you explicitly convert a value to a value. To perform a conversion that is independent of language, you can call the or the method. ## Examples The following example converts numbers to values by using the explicit to conversion operator. @@ -3704,7 +3703,6 @@ For , this method matches the IE ## Remarks This operator supports the explicit conversion of a to a . The syntax for such explicit conversions is language-dependent, and individual language compilers can provide different implementations and return different results, or might not support the conversion at all. For example, the Visual Basic and C++ compilers do not support an explicit to a conversion. - ## Examples The following example converts numbers to values (Unicode characters) by using the explicit to conversion operator. @@ -3771,8 +3769,7 @@ For , this method matches the IE ## Remarks This operation can result in a loss of precision, because a double-precision floating-point number has fewer significant digits than a . - This operator supports the explicit conversion of a to a . The syntax for such explicit conversions is language-dependent, and individual language compilers can provide different implementations and return different results. The example illustrates the different return values when you explicitly convert a value to a value by using C#, C++, and Visual Basic. To perform a conversion that is independent of language, you can call the or the method. - + This operator supports the explicit conversion of a to a . The syntax for such explicit conversions is language-dependent, and individual language compilers can provide different implementations and return different results. The example illustrates the different return values when you explicitly convert a value to a value. To perform a conversion that is independent of language, you can call the or the method. ## Examples The following example converts numbers to values by using the explicit to conversion operator. @@ -3838,8 +3835,7 @@ For , this method matches the IE ## Remarks - This operator supports the explicit conversion of a to an . The syntax for such explicit conversions is language-dependent, and individual language compilers can provide different implementations and return different results. The example illustrates the different return values when you explicitly convert a value to an value by using C#, Visual Basic, and C++. To perform a conversion that is independent of language, you can call the or the method. - + This operator supports the explicit conversion of a to an . The syntax for such explicit conversions is language-dependent, and individual language compilers can provide different implementations and return different results. The example illustrates the different return values when you explicitly convert a value to an value. To perform a conversion that is independent of language, you can call the or the method. ## Examples The following example converts numbers to values by using the explicit to conversion operator. @@ -3906,8 +3902,7 @@ For , this method matches the IE to an . The syntax for such explicit conversions is language-dependent, and individual language compilers can provide different implementations and return different results. The example illustrates the different return values when you explicitly convert a value to an value by using C#, C++, and Visual Basic. To perform a conversion that is independent of language, you can call the or the method. - + This operator supports the explicit conversion of a to an . The syntax for such explicit conversions is language-dependent, and individual language compilers can provide different implementations and return different results. The example illustrates the different return values when you explicitly convert a value to an value. To perform a conversion that is independent of language, you can call the or the method. ## Examples The following example converts numbers to values by using the explicit to conversion operator. @@ -4796,7 +4791,7 @@ For , this method matches the IE The overloads of the method define the types from which the compiler can automatically convert a value without an explicit casting operator (in C#) or a call to a conversion function (in Visual Basic). They are widening conversions that do not involve data loss and do not throw an exception. ## Examples - The following example converts values (Unicode characters) to numbers. This conversion requires the op_Implicit operator in Visual Basic, but not in C# and C++. + The following example converts values (Unicode characters) to numbers. This conversion requires the op_Implicit operator in Visual Basic, but not in C#. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/System.Decimal.ConvFrom.Others/CPP/cfromchar.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Decimal/op_Explicit/cfromchar.cs" interactive="try-dotnet" id="Snippet1"::: @@ -4861,7 +4856,7 @@ For , this method matches the IE The overloads of the method define the types from which the compiler can automatically convert a value without an explicit casting operator (in C#) or a call to a conversion function (in Visual Basic). They are widening conversions that do not involve data loss and do not throw an exception. ## Examples - The following example converts values to numbers. This conversion requires the op_Implicit operator in Visual Basic, but not in C# and C++. + The following example converts values to numbers. This conversion requires the op_Implicit operator in Visual Basic, but not in C#. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/System.Decimal.ConvFrom.SInts/CPP/cfromint16.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System/Decimal/op_Implicit/cfromint16.cs" interactive="try-dotnet" id="Snippet3"::: diff --git a/xml/System/Delegate.xml b/xml/System/Delegate.xml index c12ad95f42d..6872224f1be 100644 --- a/xml/System/Delegate.xml +++ b/xml/System/Delegate.xml @@ -89,19 +89,16 @@ Most languages implement a `delegate` keyword, and compilers for those languages are able to derive from the class; therefore, users should use the `delegate` keyword provided by the language. > [!NOTE] -> The common language runtime provides an `Invoke` method for each delegate type, with the same signature as the delegate. You do not have to call this method explicitly from C#, Visual Basic, or Visual C++, because the compilers call it automatically. The `Invoke` method is useful in [reflection](/dotnet/framework/reflection-and-codedom/reflection) when you want to find the signature of the delegate type. +> The common language runtime provides an `Invoke` method for each delegate type, with the same signature as the delegate. You don't have to call this method explicitly from C# or Visual Basic because the compilers call it automatically. The `Invoke` method is useful in [reflection](/dotnet/framework/reflection-and-codedom/reflection) when you want to find the signature of the delegate type. The common language runtime provides each delegate type with `BeginInvoke` and `EndInvoke` methods, to enable asynchronous invocation of the delegate. For more information about these methods, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). The declaration of a delegate type establishes a contract that specifies the signature of one or more methods. A delegate is an instance of a delegate type that has references to: -- An instance method of a type and a target object assignable to that type. - -- An instance method of a type, with the hidden `this` parameter exposed in the formal parameter list. The delegate is said to be an open instance delegate. - -- A static method. - -- A static method and a target object assignable to the first parameter of the method. The delegate is said to be closed over its first argument. +- An instance method of a type and a target object assignable to that type. +- An instance method of a type, with the hidden `this` parameter exposed in the formal parameter list. The delegate is said to be an open instance delegate. +- A static method. +- A static method and a target object assignable to the first parameter of the method. The delegate is said to be closed over its first argument. For more information on delegate binding, see the method overload. @@ -116,12 +113,12 @@ Combining operations, such as and , do not alter existing delegates. Instead, such an operation returns a new delegate that contains the results of the operation, an unchanged delegate, or `null`. A combining operation returns `null` when the result of the operation is a delegate that does not reference at least one method. A combining operation returns an unchanged delegate when the requested operation has no effect. > [!NOTE] -> Managed languages use the and methods to implement delegate operations. Examples include the `AddHandler` and `RemoveHandler` statements in Visual Basic and the += and -= operators on delegate types in C#. +> Managed languages use the and methods to implement delegate operations. Examples include the `AddHandler` and `RemoveHandler` statements in Visual Basic and the += and -= operators on delegate types in C#. - Starting with the .NET Framework 4, generic delegate types can have variant type parameters. Contravariant type parameters can be used as parameter types of the delegate, and a covariant type parameter can be used as the return type. This feature allows generic delegate types that are constructed from the same generic type definition to be assignment-compatible if their type arguments are reference types with an inheritance relationship, as explained in [Covariance and Contravariance](/dotnet/standard/generics/covariance-and-contravariance). +Generic delegate types can have variant type parameters. Contravariant type parameters can be used as parameter types of the delegate, and a covariant type parameter can be used as the return type. This feature allows generic delegate types that are constructed from the same generic type definition to be assignment-compatible if their type arguments are reference types with an inheritance relationship, as explained in [Covariance and Contravariance](/dotnet/standard/generics/covariance-and-contravariance). > [!NOTE] -> Generic delegates that are assignment-compatible because of variance are not necessarily combinable. To be combinable, the types must match exactly. For example, suppose that a class named `Derived` is derived from a class named `Base`. A delegate of type `Action` (`Action(Of Base)` in Visual Basic) can be assigned to a variable of type `Action`, but the two delegates cannot be combined because the types do not match exactly. +> Generic delegates that are assignment-compatible because of variance are not necessarily combinable. To be combinable, the types must match exactly. For example, suppose that a class named `Derived` is derived from a class named `Base`. A delegate of type `Action` (`Action(Of Base)` in Visual Basic) can be assigned to a variable of type `Action`, but the two delegates cannot be combined because the types do not match exactly. If an invoked method throws an exception, the method stops executing, the exception is passed back to the caller of the delegate, and remaining methods in the invocation list are not invoked. Catching the exception in the caller does not alter this behavior. @@ -450,7 +447,7 @@ For examples, see [Supplemental API remarks for System.Delegate.CreateDelegate]( The invocation list can contain duplicate entries; that is, entries that refer to the same method on the same object. > [!NOTE] -> Generic delegates that are assignment-compatible because of variance are not necessarily combinable. To be combinable, the types must match exactly. For example, suppose that a class named `Derived` is derived from a class named `Base`. A delegate of type `Action` (`Action(Of Base)` in Visual Basic) can be assigned to a variable of type `Action`, as explained in [Covariance and Contravariance](/dotnet/standard/generics/covariance-and-contravariance), but the two delegates cannot be combined because the types do not match exactly. +> Generic delegates that are assignment-compatible because of variance are not necessarily combinable. To be combinable, the types must match exactly. For example, suppose that a class named `Derived` is derived from a class named `Base`. A delegate of type `Action` (`Action(Of Base)` in Visual Basic) can be assigned to a variable of type `Action`, as explained in [Covariance and Contravariance](/dotnet/standard/generics/covariance-and-contravariance), but the two delegates cannot be combined because the types do not match exactly. is useful for creating event handlers that call multiple methods each time an event occurs. @@ -575,7 +572,7 @@ For examples, see [Supplemental API remarks for System.Delegate.CreateDelegate]( The invocation list can contain duplicate entries; that is, entries that refer to the same method on the same object. > [!NOTE] -> Generic delegates that are assignment-compatible because of variance are not necessarily combinable. To be combinable, the types must match exactly. For example, suppose that a class named `Derived` is derived from a class named `Base`. A delegate of type `Action` (`Action(Of Base)` in Visual Basic) can be assigned to a variable of type `Action`, as explained in [Covariance and Contravariance](/dotnet/standard/generics/covariance-and-contravariance), but the two delegates cannot be combined because the types do not match exactly. +> Generic delegates that are assignment-compatible because of variance are not necessarily combinable. To be combinable, the types must match exactly. For example, suppose that a class named `Derived` is derived from a class named `Base`. A delegate of type `Action` (`Action(Of Base)` in Visual Basic) can be assigned to a variable of type `Action`, as explained in [Covariance and Contravariance](/dotnet/standard/generics/covariance-and-contravariance), but the two delegates cannot be combined because the types do not match exactly. is useful for creating event handlers that call multiple methods each time an event occurs. @@ -1217,7 +1214,7 @@ For examples, see [Supplemental API remarks for System.Delegate.CreateDelegate]( This method overload and the method overload, which always throws on failure to bind, provide the most flexible way to create delegates. You can use them to create delegates for either static or instance methods, with or without a first argument. > [!NOTE] -> If you do not supply a first argument, use the method overload for better performance. +> If you do not supply a first argument, use the method overload for better performance. For more information and examples, see [Supplemental API remarks for System.Delegate.CreateDelegate](/dotnet/fundamentals/runtime-libraries/system-delegate-createdelegate). @@ -1984,11 +1981,11 @@ The number, order, or type of parameters listed in is i The methods and targets are compared for equality as follows: -- If the two methods being compared are both static and are the same method on the same class, the methods are considered equal and the targets are also considered equal. +- If the two methods being compared are both static and are the same method on the same class, the methods are considered equal and the targets are also considered equal. -- If the two methods being compared are instance methods and are the same method on the same object, the methods are considered equal and the targets are also considered equal. +- If the two methods being compared are instance methods and are the same method on the same object, the methods are considered equal and the targets are also considered equal. -- Otherwise, the methods are not considered to be equal and the targets are also not considered to be equal. +- Otherwise, the methods are not considered to be equal and the targets are also not considered to be equal. Two invocation lists are considered identical only if they have the same order and the corresponding elements from the two lists represent the same method and target. @@ -2386,11 +2383,11 @@ The number, order, or type of parameters listed in is i The methods and targets are compared for equality as follows: -- If the two methods being compared are both static and are the same method on the same class, the methods are considered equal and the targets are also considered equal. +- If the two methods being compared are both static and are the same method on the same class, the methods are considered equal and the targets are also considered equal. -- If the two methods being compared are instance methods and are the same method on the same object, the methods are considered equal and the targets are also considered equal. +- If the two methods being compared are instance methods and are the same method on the same object, the methods are considered equal and the targets are also considered equal. -- Otherwise, the methods are not considered to be equal and the targets are also not considered to be equal. +- Otherwise, the methods are not considered to be equal and the targets are also not considered to be equal. Two invocation lists are considered identical if they have the same order and the corresponding elements from the two lists represent the same method and target. @@ -2459,11 +2456,11 @@ The number, order, or type of parameters listed in is i The methods and targets are compared for equality as follows: -- If the two methods being compared are both static and are the same method on the same class, the methods are considered equal and the targets are also considered equal. +- If the two methods being compared are both static and are the same method on the same class, the methods are considered equal and the targets are also considered equal. -- If the two methods being compared are instance methods and are the same method on the same object, the methods are considered equal and the targets are also considered equal. +- If the two methods being compared are instance methods and are the same method on the same object, the methods are considered equal and the targets are also considered equal. -- Otherwise, the methods are not considered to be equal and the targets are also not considered to be equal. +- Otherwise, the methods are not considered to be equal and the targets are also not considered to be equal. Two invocation lists are not equal if they have different sizes, if they are ordered differently, or if at least one element from one list represents a method or target that is different from that represented by its corresponding element in the other list. diff --git a/xml/System/EntryPointNotFoundException.xml b/xml/System/EntryPointNotFoundException.xml index a0370d64052..019a2954bda 100644 --- a/xml/System/EntryPointNotFoundException.xml +++ b/xml/System/EntryPointNotFoundException.xml @@ -59,65 +59,65 @@ The exception that is thrown when an attempt to load a class fails due to the absence of an entry method. - exception is thrown when the common language runtime is unable to load an assembly because it cannot identify the assembly's entry point. This exception can be thrown under the following conditions: - -- The common language runtime is unable to locate an application entry point (typically a `Main` method) in an executable assembly. The application entry point must be a global or `static` method that has either no parameters or a string array as its only parameter. The entry point can return `void`, or it can return an or exit code. An application assembly cannot define more than one entry point. - -- The call to a function in a Windows DLL cannot be resolved because the function cannot be found. In the following example, an exception is thrown because User32.dll does not include a function named `GetMyNumber`. - + exception is thrown when the common language runtime is unable to load an assembly because it cannot identify the assembly's entry point. This exception can be thrown under the following conditions: + +- The common language runtime is unable to locate an application entry point (typically a `Main` method) in an executable assembly. The application entry point must be a global or `static` method that has either no parameters or a string array as its only parameter. The entry point can return `void`, or it can return an or exit code. An application assembly cannot define more than one entry point. + +- The call to a function in a Windows DLL cannot be resolved because the function cannot be found. In the following example, an exception is thrown because User32.dll does not include a function named `GetMyNumber`. + :::code language="csharp" source="~/snippets/csharp/System/EntryPointNotFoundException/Overview/nofunction1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/EntryPointNotFoundException/Overview/nofunction1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.entrypointnotfoundexception.class/vb/nofunction1.vb" id="Snippet1"::: - -- The call to a function in a Windows DLL cannot be resolved because the name used in the method call does not match a name found in the assembly. Frequently, this occurs because the field is either implicitly or explicitly set to `true`, the called method includes one or more string parameters and has both an ANSI and a Unicode version, and the name used in the method call does not correspond to the name of this ANSI or Unicode version. The following example provides an illustration by attempting to call the Windows `MessageBox` function in User32.dll. Because the first method definition specifies for string marshaling, the common language looks for the wide-character version of the function, `MessageBoxW`, instead of the name used in the method call, `MessageBox`. The second method definition corrects this problem by calling the `MessageBoxW` instead of the `MessageBox` function. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.entrypointnotfoundexception.class/vb/nofunction1.vb" id="Snippet1"::: + +- The call to a function in a Windows DLL cannot be resolved because the name used in the method call does not match a name found in the assembly. Frequently, this occurs because the field is either implicitly or explicitly set to `true`, the called method includes one or more string parameters and has both an ANSI and a Unicode version, and the name used in the method call does not correspond to the name of this ANSI or Unicode version. The following example provides an illustration by attempting to call the Windows `MessageBox` function in User32.dll. Because the first method definition specifies for string marshaling, the common language looks for the wide-character version of the function, `MessageBoxW`, instead of the name used in the method call, `MessageBox`. The second method definition corrects this problem by calling the `MessageBoxW` instead of the `MessageBox` function. + :::code language="csharp" source="~/snippets/csharp/System/EntryPointNotFoundException/Overview/badcall1.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System/EntryPointNotFoundException/Overview/badcall1.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.entrypointnotfoundexception.class/vb/badcall1.vb" id="Snippet2"::: - -- You are trying to call a function in a dynamic link library by its simple name rather than its decorated name. Typically, the C++ compiler generates a decorated name for DLL functions. For example, the following C++ code defines a function named `Double` in a library named TestDll.dll. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.entrypointnotfoundexception.class/cpp/testdll.cpp" id="Snippet6"::: - - When the code in the following example tries to call the function, an exception is thrown because the `Double` function cannot be found. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.entrypointnotfoundexception.class/vb/badcall1.vb" id="Snippet2"::: + +- You're trying to call a function in a dynamic link library by its simple name rather than its decorated name. Typically, the C++ compiler generates a decorated name for DLL functions. For example, the following C++ code defines a function named `Double` in a library named TestDll.dll. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.entrypointnotfoundexception.class/cpp/testdll.cpp" id="Snippet6"::: + + When the code in the following example tries to call the function, an exception is thrown because the `Double` function cannot be found. + :::code language="csharp" source="~/snippets/csharp/System/EntryPointNotFoundException/Overview/mangle1.cs" id="Snippet7"::: :::code language="fsharp" source="~/snippets/fsharp/System/EntryPointNotFoundException/Overview/mangle1.fs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.entrypointnotfoundexception.class/vb/mangle1.vb" id="Snippet7"::: - - However, if the function is called by using its decorated name (in this case, `?Double@@YAHH@Z`), the function call succeeds, as the following example shows. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.entrypointnotfoundexception.class/vb/mangle1.vb" id="Snippet7"::: + + However, if the function is called by using its decorated name (in this case, `?Double@@YAHH@Z`), the function call succeeds, as the following example shows. + :::code language="csharp" source="~/snippets/csharp/System/EntryPointNotFoundException/Overview/mangle2.cs" id="Snippet8"::: :::code language="fsharp" source="~/snippets/fsharp/System/EntryPointNotFoundException/Overview/mangle2.fs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.entrypointnotfoundexception.class/vb/mangle2.vb" id="Snippet8"::: - - You can find the decorated names of functions exported by a DLL by using a utility such as Dumpbin.exe. - -- You are attempting to call a method in a managed assembly as if it were an unmanaged dynamic link library. To see this in action, compile the following example to an assembly named StringUtilities.dll. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.entrypointnotfoundexception.class/vb/mangle2.vb" id="Snippet8"::: + + You can find the decorated names of functions exported by a DLL by using a utility such as Dumpbin.exe. + +- You are attempting to call a method in a managed assembly as if it were an unmanaged dynamic link library. To see this in action, compile the following example to an assembly named StringUtilities.dll. + :::code language="csharp" source="~/snippets/csharp/System/EntryPointNotFoundException/Overview/stringutilities.cs" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System/EntryPointNotFoundException/Overview/stringutilities.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.entrypointnotfoundexception.class/vb/stringutilities.vb" id="Snippet3"::: - - Then compile and execute the following example, which attempts to call the `StringUtilities.SayGoodMorning` method in the StringUtilities.dll dynamic link library as if it were unmanaged code. The result is an exception. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.entrypointnotfoundexception.class/vb/stringutilities.vb" id="Snippet3"::: + + Then compile and execute the following example, which attempts to call the `StringUtilities.SayGoodMorning` method in the StringUtilities.dll dynamic link library as if it were unmanaged code. The result is an exception. + :::code language="csharp" source="~/snippets/csharp/System/EntryPointNotFoundException/Overview/importassembly1.cs" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System/EntryPointNotFoundException/Overview/importassembly1.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.entrypointnotfoundexception.class/vb/importassembly1.vb" id="Snippet4"::: - - To eliminate the exception, add a reference to the managed assembly and access the `StringUtilities.SayGoodMorning` method just as you would access any other method in managed code, as the following example does. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.entrypointnotfoundexception.class/vb/importassembly1.vb" id="Snippet4"::: + + To eliminate the exception, add a reference to the managed assembly and access the `StringUtilities.SayGoodMorning` method just as you would access any other method in managed code, as the following example does. + :::code language="csharp" source="~/snippets/csharp/System/EntryPointNotFoundException/Overview/fiximportassembly1.cs" id="Snippet5"::: :::code language="fsharp" source="~/snippets/fsharp/System/EntryPointNotFoundException/Overview/fiximportassembly1.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.entrypointnotfoundexception.class/vb/fiximportassembly1.vb" id="Snippet5"::: - -- You are trying to call a method in a COM DLL as if it were a Windows DLL. To access a COM DLL, select the **Add Reference** option in Visual Studio to add a reference to the project, and then select the type library from the **COM** tab. - - For a list of initial property values for an instance of , see the constructors. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.entrypointnotfoundexception.class/vb/fiximportassembly1.vb" id="Snippet5"::: + +- You are trying to call a method in a COM DLL as if it were a Windows DLL. To access a COM DLL, select the **Add Reference** option in Visual Studio to add a reference to the project, and then select the type library from the **COM** tab. + + For a list of initial property values for an instance of , see the constructors. + ]]> @@ -169,18 +169,18 @@ Initializes a new instance of the class. - property of the new instance to a system-supplied message that describes the error, such as "Entry point was not found." This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "Entry point was not found." This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The localized error message string.| + ]]> @@ -225,18 +225,18 @@ The error message that explains the reason for the exception. Initializes a new instance of the class with a specified error message. - . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The error message string.| - + . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The error message string.| + ]]> @@ -296,11 +296,11 @@ The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - @@ -347,18 +347,18 @@ The exception that is the cause of the current exception. If the parameter is not a null reference ( in Visual Basic), the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing` in Visual Basic) if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing` in Visual Basic) if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System/IDisposable.xml b/xml/System/IDisposable.xml index bfa05e20f35..e3c73103f17 100644 --- a/xml/System/IDisposable.xml +++ b/xml/System/IDisposable.xml @@ -122,7 +122,7 @@ When implementing this method, ensure that all held resources are freed by propagating the call through the containment hierarchy. For example, if an object A allocates an object B, and object B allocates an object C, then A's implementation must call on B, which must in turn call on C. > [!IMPORTANT] -> The C++ compiler supports deterministic disposal of resources and does not allow direct implementation of the method. +> The C++ compiler supports deterministic disposal of resources and doesn't allow direct implementation of the method. An object must also call the method of its base class if the base class implements . For more information about implementing on a base class and its subclasses, see the "IDisposable and the inheritance hierarchy" section in the topic. diff --git a/xml/System/IntPtr.xml b/xml/System/IntPtr.xml index ca7987b3b28..81bd4b8b7bf 100644 --- a/xml/System/IntPtr.xml +++ b/xml/System/IntPtr.xml @@ -285,23 +285,23 @@ The following example uses managed pointers to reverse the characters in an array. After it initializes a object and gets its length, it does the following: -1. Calls the method to copy the Unicode string to unmanaged memory as an ANSI (one-byte) character. The method returns an object that points to the beginning of the unmanaged string. The Visual Basic example uses this pointer directly; in the C++, F# and C# examples, it is cast to a pointer to a byte. +1. Calls the method to copy the Unicode string to unmanaged memory as an ANSI (one-byte) character. The method returns an object that points to the beginning of the unmanaged string. The Visual Basic example uses this pointer directly; in the C++, F# and C# examples, it is cast to a pointer to a byte. -2. Calls the method to allocate the same number of bytes as the unmanaged string occupies. The method returns an object that points to the beginning of the unmanaged block of memory. The Visual Basic example uses this pointer directly; in the C++, F# and C# examples, it is cast to a pointer to a byte. +2. Calls the method to allocate the same number of bytes as the unmanaged string occupies. The method returns an object that points to the beginning of the unmanaged block of memory. The Visual Basic example uses this pointer directly; in the C++, F# and C# examples, it is cast to a pointer to a byte. -3. The Visual Basic example defines a variable named `offset` that is equal to the length of the ANSI string. It is used to determine the offset into unmanaged memory to which the next character in the ANSI string is copied. Because its starting value is the length of the string, the copy operation will copy a character from the start of the string to the end of the memory block. +3. The Visual Basic example defines a variable named `offset` that is equal to the length of the ANSI string. It is used to determine the offset into unmanaged memory to which the next character in the ANSI string is copied. Because its starting value is the length of the string, the copy operation will copy a character from the start of the string to the end of the memory block. The C#, F# and C++ examples call the method to get an unmanaged pointer to the starting address of the string and the unmanaged block of memory, and they add one less than the length of the string to the starting address of the ANSI string. Because the unmanaged string pointer now points to the end of the string, the copy operation will copy a character from the end of the string to the start of the memory block. -4. Uses a loop to copy each character from the string to the unmanaged block of memory. +4. Uses a loop to copy each character from the string to the unmanaged block of memory. The Visual Basic example calls the method to read the byte (or one-byte character) at a specified offset from the managed pointer to the ANSI string. The offset is incremented with each iteration of the loop. It then calls the method to write the byte to the memory address defined by the starting address of the unmanaged block of memory plus `offset`. It then decrements `offset`. The C#, F# and C++ examples perform the copy operation, then decrement the pointer to the address of the next location in the unmanaged ANSI string and increment the pointer to the next address in the unmanaged block. -5. All examples call the to convert the unmanaged memory block containing the copied ANSI string to a managed Unicode object. +5. All examples call the to convert the unmanaged memory block containing the copied ANSI string to a managed Unicode object. -6. After displaying the original and reversed strings, all examples call the method to free the memory allocated for the unmanaged ANSI string and the unmanaged block of memory. +6. After displaying the original and reversed strings, all examples call the method to free the memory allocated for the unmanaged ANSI string and the unmanaged block of memory. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.intptr/cpp/topointer.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/IntPtr/ToPointer/topointer.cs" id="Snippet1"::: diff --git a/xml/System/MTAThreadAttribute.xml b/xml/System/MTAThreadAttribute.xml index 6f427a53914..1bd7ac360bd 100644 --- a/xml/System/MTAThreadAttribute.xml +++ b/xml/System/MTAThreadAttribute.xml @@ -60,32 +60,31 @@ Indicates that the COM threading model for an application is multithreaded apartment (MTA). - or method before starting the thread. - + or method before starting the thread. + > [!NOTE] -> For an overview of COM threading models, see [Understanding and Using COM Threading Models](https://learn.microsoft.com/previous-versions/ms809971(v=msdn.10)). - - COM threading models only apply to applications that use COM interop. The COM threading model can be set to single-threaded apartment or multithreaded apartment. The application thread is only initialized for COM interop if the thread actually makes a call to a COM component. If COM interop is not used, then the thread is not initialized, and the attribute, if it is present, has no effect. - - Starting with the .NET Framework version 2.0, the default threading model for COM interop depends on the language in which you are developing your application, as the following table shows. - -|Language|COM apartment model| -|--------------|-------------------------| -|C#|Multithreaded apartment| -|C++|Multithreaded apartment| -|Visual Basic|Single-threaded apartment| - - To change these defaults, you use the attribute to set the threading model for the application, or call the or method before starting the thread to set the threading model for a particular thread. In C++, you can also use the [/CLRTHREADATTRIBUTE (Set CLR Thread Attribute)](/cpp/build/reference/clrthreadattribute-set-clr-thread-attribute) linker option to specify the apartment model. - - Some of the cases in which you want to use the attribute to explicitly set the threading model to multithreaded apartment include the following: - -- You're developing a Visual Basic app that calls to a C# library that in turn relies on COM interop. Because the multithreaded apartment model is the default for C#, you should change your app's threading model to multithreaded by using the attribute. - -- Your application makes calls to COM components that use the multithreaded apartment model. - +> For an overview of COM threading models, see [Understanding and Using COM Threading Models](https://learn.microsoft.com/previous-versions/ms809971(v=msdn.10)). + + COM threading models only apply to applications that use COM interop. The COM threading model can be set to single-threaded apartment or multithreaded apartment. The application thread is only initialized for COM interop if the thread actually makes a call to a COM component. If COM interop is not used, then the thread is not initialized, and the attribute, if it is present, has no effect. + + Starting with the .NET Framework version 2.0, the default threading model for COM interop depends on the language in which you are developing your application, as the following table shows. + +|Language|COM apartment model| +|--------------|-------------------------| +|C#|Multithreaded apartment| +|C++|Multithreaded apartment| +|Visual Basic|Single-threaded apartment| + + To change these defaults, you use the attribute to set the threading model for the application, or call the or method before starting the thread to set the threading model for a particular thread. In C++, you can also use the [/CLRTHREADATTRIBUTE (Set CLR Thread Attribute)](/cpp/build/reference/clrthreadattribute-set-clr-thread-attribute) linker option to specify the apartment model. + +Use the attribute to explicitly set the threading model to multithreaded apartment in the following cases: + +- You're developing a Visual Basic app that calls to a C# library that in turn relies on COM interop. Because the multithreaded apartment model is the default for C#, you should change your app's threading model to multithreaded by using the attribute. +- Your application makes calls to COM components that use the multithreaded apartment model. + ]]> diff --git a/xml/System/ResolveEventHandler.xml b/xml/System/ResolveEventHandler.xml index 5fa07435b4a..84b98232489 100644 --- a/xml/System/ResolveEventHandler.xml +++ b/xml/System/ResolveEventHandler.xml @@ -81,16 +81,16 @@ Represents a method that handles the , , or event of an . The assembly that resolves the type, assembly, or resource; or if the assembly cannot be resolved. - to return the assembly that resolves the type, assembly, or resource, or to return null if the assembly is not recognized. For more information, see [Resolving Assembly Loads](/dotnet/standard/assembly/resolve-loads) and the , , and events. - + to return the assembly that resolves the type, assembly, or resource, or to return null if the assembly is not recognized. For more information, see [Resolving Assembly Loads](/dotnet/standard/assembly/resolve-loads) and the , , and events. + > [!IMPORTANT] -> Beginning with the .NET Framework 4, the event is raised for all assemblies, including resource assemblies. In earlier versions, the event was not raised for resource assemblies. If the operating system is localized, the handler might be called multiple times: once for each culture in the fallback chain. - - Every derived class of and has a constructor and an `Invoke` method. See the C++ code example in the description for the class. - +> Beginning with .NET Framework 4, the event is raised for all assemblies, including resource assemblies. In earlier versions, the event was not raised for resource assemblies. If the operating system is localized, the handler might be called multiple times: once for each culture in the fallback chain. + + Every derived class of and has a constructor and an `Invoke` method. + ]]> diff --git a/xml/System/String.xml b/xml/System/String.xml index 2bbfc51f2d7..da411ef590b 100644 --- a/xml/System/String.xml +++ b/xml/System/String.xml @@ -6587,7 +6587,7 @@ The index of a format item is less than zero, or greater than two. ## Remarks > [!TIP] -> Rather than calling the method to retrieve a object that you then use to enumerate a string, you should instead use your language's iteration construct (in C#, in F#, in C++/CLR, and in Visual Basic). [foreach](/dotnet/csharp/language-reference/keywords/foreach-in) in C#, [for..in](/dotnet/fsharp/language-reference/loops-for-in-expression) in F#, [for each](/cpp/dotnet/for-each-in) in C++/CLR, and [For Each](/dotnet/visual-basic/language-reference/statements/for-each-next-statement) in Visual Basic). +> Rather than calling the method to retrieve a object that you then use to enumerate a string, you should instead use your language's iteration construct. Examples include [foreach](/dotnet/csharp/language-reference/keywords/foreach-in) in C#, [for..in](/dotnet/fsharp/language-reference/loops-for-in-expression) in F#, and [For Each](/dotnet/visual-basic/language-reference/statements/for-each-next-statement) in Visual Basic). This method enables you to iterate the individual characters in a string. For example, the Visual Basic `For Each`, the F# `for..in` expression, and C# `foreach` statements invoke this method to return a object that can provide read-only access to the characters in this string instance. diff --git a/xml/System/Type.xml b/xml/System/Type.xml index b44d441489a..d51987f302c 100644 --- a/xml/System/Type.xml +++ b/xml/System/Type.xml @@ -241,7 +241,7 @@ The code example uses the to invoke the object represents a constructed generic type, this property returns the assembly that contains the generic type definition. For example, suppose you create an assembly named MyGenerics.dll that contains the generic type definition `MyGenericStack` (`MyGenericStack(Of T)` in Visual Basic, `generic ref class MyGenericStack` in C++). If you create an instance of `MyGenericStack` (`MyGenericStack(Of Integer)` in Visual Basic) in another assembly, the property for the constructed type returns an object that represents MyGenerics.dll. + If the current object represents a constructed generic type, this property returns the assembly that contains the generic type definition. For example, suppose you create an assembly named MyGenerics.dll that contains the generic type definition `MyGenericStack` (`MyGenericStack(Of T)` in Visual Basic). If you create an instance of `MyGenericStack` (`MyGenericStack(Of Integer)` in Visual Basic) in another assembly, the property for the constructed type returns an object that represents MyGenerics.dll. Similarly, if the current object represents an unassigned generic parameter `T`, this property returns the assembly that contains the generic type that defines `T`. @@ -4444,7 +4444,7 @@ In .NET 6 and earlier versions, the method does ` (expressed in C# syntax; `G(Of T)` in Visual Basic or `generic ref class G` in C++) you can construct and instantiate the type `G` (`G(Of Integer)` in Visual Basic). Given a object representing this constructed type, the method returns the generic type definition. + A generic type definition is a template from which other types can be constructed. For example, from the C# generic type definition `G`, you can construct and instantiate the type `G`. Given a object representing this constructed type, the method returns the generic type definition. If two constructed types are created from the same generic type definition, using the same type arguments, the method returns the same object for both types. @@ -4455,8 +4455,6 @@ In .NET 6 and earlier versions, the method does For a list of the invariant conditions for terms used in generic reflection, see the property remarks. - - ## Examples The following code example creates an instance of a constructed type by using ordinary instance creation and then uses the and methods to retrieve the constructed type and the generic type definition. This example uses the generic type; the constructed type represents a of `Test` objects with string keys. @@ -9182,7 +9180,7 @@ Type.GetType("System.Collections.Generic.Dictionary`2[System.String,[MyType,MyAs Nullable types are a special case of generic types. For example, a nullable is represented by the string "System.Nullable`1[System.Int32]". > [!NOTE] -> In C#, C++, and Visual Basic you can also get nullable types using type operators. For example, the nullable type is returned by `typeof(Nullable)` in C#, by `Nullable::typeid` in C++, and by `GetType(Nullable(Of Boolean))` in Visual Basic. +> You can also get nullable types using type operators. For example, the nullable type is returned by `typeof(Nullable)` in C# and by `GetType(Nullable(Of Boolean))` in Visual Basic. The following table shows the syntax you use with `GetType` for various types. @@ -9393,7 +9391,7 @@ Type.GetType("System.Collections.Generic.Dictionary`2[System.String,[MyType,MyAs Nullable types are a special case of generic types. For example, a nullable is represented by the string "System.Nullable`1[System.Int32]". > [!NOTE] -> In C#, C++, and Visual Basic you can also get nullable types using type operators. For example, the nullable type is returned by `typeof(Nullable)` in C#, by `Nullable::typeid` in C++, and by `GetType(Nullable(Of Boolean))` in Visual Basic. +> You can also get nullable types using type operators. For example, the nullable type is returned by `typeof(Nullable)` in C# and by `GetType(Nullable(Of Boolean))` in Visual Basic. The following table shows the syntax you use with `GetType` for various types. @@ -9629,7 +9627,7 @@ Type.GetType("System.Collections.Generic.Dictionary`2[System.String,[MyType,MyAs Nullable types are a special case of generic types. For example, a nullable is represented by the string "System.Nullable`1[System.Int32]". > [!NOTE] -> In C#, C++, and Visual Basic you can also get nullable types using type operators. For example, the nullable type is returned by `typeof(Nullable)` in C#, by `Nullable::typeid` in C++, and by `GetType(Nullable(Of Boolean))` in Visual Basic. +> You can also get nullable types using type operators. For example, the nullable type is returned by `typeof(Nullable)` in C# and by `GetType(Nullable(Of Boolean))` in Visual Basic. The following table shows the syntax you use with `GetType` for various types. @@ -13774,7 +13772,7 @@ Byref-like structures are declared using `ref struct` keyword in C#. An instance ` (expressed in C# syntax; `G(Of T)` in Visual Basic or `generic ref class G` in C++) you can construct and instantiate the type `G` (`G(Of Integer)` in Visual Basic), by calling the method with a generic argument list containing the type. Given a object representing this constructed type, the method gets the generic type definition back again. + A generic type definition is a template from which other types can be constructed. For example, from the C# generic type definition `G`, you can construct and instantiate the type `G` (`G(Of Integer)` in Visual Basic), by calling the method with a generic argument list containing the type. Given a object representing this constructed type, the method gets the generic type definition back again. Use the property to determine whether you can create new types from the current type. If the property returns `true`, you can call the method to create new generic types. diff --git a/xml/ns-System.xml b/xml/ns-System.xml index 19a3a390e4c..9c8080c8870 100644 --- a/xml/ns-System.xml +++ b/xml/ns-System.xml @@ -1,6 +1,6 @@ - Contains fundamental classes and base classes that define commonly-used value and reference data types, events and event handlers, interfaces, attributes, and processing exceptions. + Contains fundamental classes and base classes that define commonly used value and reference data types, events and event handlers, interfaces, attributes, and processing exceptions.