diff --git a/add/media/aboutgdip05-art10.gif b/add/media/aboutgdip05-art10.gif deleted file mode 100644 index 5853ca9cbb3..00000000000 Binary files a/add/media/aboutgdip05-art10.gif and /dev/null differ diff --git a/add/media/aboutgdip05-art12.gif b/add/media/aboutgdip05-art12.gif deleted file mode 100644 index 140c14f3cca..00000000000 Binary files a/add/media/aboutgdip05-art12.gif and /dev/null differ diff --git a/xml/System.Collections.Generic/HashSet`1.xml b/xml/System.Collections.Generic/HashSet`1.xml index 7a320edfb99..7a863c08386 100644 --- a/xml/System.Collections.Generic/HashSet`1.xml +++ b/xml/System.Collections.Generic/HashSet`1.xml @@ -127,69 +127,15 @@ The type of elements in the hash set. Represents a set of values. - - class provides high-performance set operations. A set is a collection that contains no duplicate elements, and whose elements are in no particular order. - -> [!NOTE] -> implements the interface starting with the .NET Framework 4.6; in previous versions of the .NET Framework, the class did not implement this interface. - - The capacity of a object is the number of elements that the object can hold. A object's capacity automatically increases as elements are added to the object. - - The class is based on the model of mathematical sets and provides high-performance set operations similar to accessing the keys of the or collections. In simple terms, the class can be thought of as a collection without values. - - A collection is not sorted and cannot contain duplicate elements. If order or element duplication is more important than performance for your application, consider using the class together with the method. - - provides many mathematical set operations, such as set addition (unions) and set subtraction. The following table lists the provided operations and their mathematical equivalents. - -|HashSet operation|Mathematical equivalent| -|-------------------------------|-----------------------------| -||Union or set addition| -||Intersection| -||Set subtraction| -||Symmetric difference| - - In addition to the listed set operations, the class also provides methods for determining set equality, overlap of sets, and whether a set is a subset or superset of another set. - -**.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. - - Starting with the .NET Framework 4, the class implements the interface. - -## HashSet and LINQ Set Operations - LINQ provides access to the `Distinct`, `Union`, `Intersect` and `Except` set operations on any data source that implements the or interfaces. provides a larger and more robust collection of set operations. For example, provides comparisons such as and . - - The primary difference between LINQ set operations and operations is that LINQ set operations always return a new collection, whereas the equivalent methods modify the current collection. - - Typically, if you must create a new set or if your application needs access only to the provided set operations, using LINQ set operations on any collection or array will be sufficient. However, if your application requires access to additional set operations, or if it is not desirable or necessary to create a new collection, use the class. - - The following table shows the operations and their equivalent LINQ set operations. - -|HashSet operation|LINQ equivalent| -|-------------------------------|---------------------| -||| -||| -||| -|Not provided.|| -||Not provided.| -||Not provided.| -||Not provided.| -||Not provided.| -||Not provided.| -||Not provided.| -||Not provided.| - - - -## Examples - The following example demonstrates how to merge two disparate sets. This example creates two objects, and populates them with even and odd numbers, respectively. A third object is created from the set that contains the even numbers. The example then calls the method, which adds the odd number set to the third set. - + For more information about this API, see Supplemental API remarks for HashSet<T>. + + objects and populates them with even and odd numbers, respectively. A third object is created from the set that contains the even numbers. The example then calls the method, which adds the odd number set to the third set. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/HashSetT/Overview/Program.cs" interactive="try-dotnet-method" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_UnionWith/vb/Program.vb" id="Snippet01"::: - - ]]> - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_UnionWith/vb/Program.vb" id="Snippet01"::: + ]]> + @@ -239,21 +185,21 @@ Initializes a new instance of the class that is empty and uses the default equality comparer for the set type. - object is the number of elements that the object can hold. A object's capacity automatically increases as elements are added to the object. - - This constructor is an O(1) operation. - - - -## Examples - The following example demonstrates how to create and populate two objects. This example is part of a larger example provided for the method. - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/HashSetT/Overview/Program.cs" id="Snippet03"::: + object is the number of elements that the object can hold. A object's capacity automatically increases as elements are added to the object. + + This constructor is an O(1) operation. + + + +## Examples + The following example demonstrates how to create and populate two objects. This example is part of a larger example provided for the method. + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/HashSetT/Overview/Program.cs" id="Snippet03"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_UnionWith/vb/Program.vb" id="Snippet03"::: - + ]]> @@ -296,23 +242,23 @@ The collection whose elements are copied to the new set. Initializes a new instance of the class that uses the default equality comparer for the set type, contains elements copied from the specified collection, and has sufficient capacity to accommodate the number of elements copied. - object is the number of elements that the object can hold. A object's capacity automatically increases as elements are added to the object. - - If `collection` contains duplicates, the set will contain one of each unique element. No exception will be thrown. Therefore, the size of the resulting set is not identical to the size of `collection`. - - This constructor is an O(`n`) operation, where `n` is the number of elements in the `collection` parameter. - - - -## Examples - The following example shows how to create a collection from an existing set. In this example, two sets are created with even and odd integers, respectively. A third object is then created from the even integer set. - + object is the number of elements that the object can hold. A object's capacity automatically increases as elements are added to the object. + + If `collection` contains duplicates, the set will contain one of each unique element. No exception will be thrown. Therefore, the size of the resulting set is not identical to the size of `collection`. + + This constructor is an O(`n`) operation, where `n` is the number of elements in the `collection` parameter. + + + +## Examples + The following example shows how to create a collection from an existing set. In this example, two sets are created with even and odd integers, respectively. A third object is then created from the even integer set. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/HashSetT/Overview/Program.cs" interactive="try-dotnet-method" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_UnionWith/vb/Program.vb" id="Snippet02"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_UnionWith/vb/Program.vb" id="Snippet02"::: + ]]> @@ -365,13 +311,13 @@ The implementation to use when comparing values in the set, or to use the default implementation for the set type. Initializes a new instance of the class that is empty and uses the specified equality comparer for the set type. - object is the number of elements that the object can hold. A object's capacity automatically increases as elements are added to the object. - - This constructor is an O(1) operation. - + object is the number of elements that the object can hold. A object's capacity automatically increases as elements are added to the object. + + This constructor is an O(1) operation. + ]]> @@ -409,11 +355,11 @@ The initial size of the . Initializes a new instance of the class that is empty, but has reserved space for items and uses the default equality comparer for the set type. - @@ -466,24 +412,24 @@ The implementation to use when comparing values in the set, or to use the default implementation for the set type. Initializes a new instance of the class that uses the specified equality comparer for the set type, contains elements copied from the specified collection, and has sufficient capacity to accommodate the number of elements copied. - object is the number of elements that the object can hold. A object's capacity automatically increases as elements are added to the object. - - If `collection` contains duplicates, the set will contain one of each unique element. No exception will be thrown. Therefore, the size of the resulting set is not identical to the size of `collection`. - - This constructor is an O(`n`) operation, where `n` is the number of elements in the `collection` parameter. - - - -## Examples - The following example uses a supplied to allow case-insensitive comparisons on the elements of a collection of vehicle types. - + object is the number of elements that the object can hold. A object's capacity automatically increases as elements are added to the object. + + If `collection` contains duplicates, the set will contain one of each unique element. No exception will be thrown. Therefore, the size of the resulting set is not identical to the size of `collection`. + + This constructor is an O(`n`) operation, where `n` is the number of elements in the `collection` parameter. + + + +## Examples + The following example uses a supplied to allow case-insensitive comparisons on the elements of a collection of vehicle types. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_ExceptWith/cpp/source2.cpp" id="Snippet03"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/HashSetT/.ctor/source2.cs" interactive="try-dotnet-method" id="Snippet03"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_ExceptWith/vb/source2.vb" id="Snippet03"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_ExceptWith/vb/source2.vb" id="Snippet03"::: + ]]> @@ -533,11 +479,11 @@ The implementation to use when comparing values in the set, or null (Nothing in Visual Basic) to use the default implementation for the set type. Initializes a new instance of the class that uses the specified equality comparer for the set type, and has sufficient capacity to accommodate elements. - @@ -594,11 +540,11 @@ A structure that contains the source and destination of the serialized stream associated with the object. Initializes a new instance of the class with serialized data. - @@ -658,20 +604,20 @@ if the element is added to the object; if the element is already present. - already equals the capacity of the object, the capacity is automatically adjusted to accommodate the new item. - - If is less than the capacity of the internal array, this method is an O(1) operation. If the object must be resized, this method becomes an O(`n`) operation, where `n` is . - - - -## Examples - The following example demonstrates how to create and populate two objects. This example is part of a larger example provided for the method. - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/HashSetT/Overview/Program.cs" id="Snippet03"::: - + already equals the capacity of the object, the capacity is automatically adjusted to accommodate the new item. + + If is less than the capacity of the internal array, this method is an O(1) operation. If the object must be resized, this method becomes an O(`n`) operation, where `n` is . + + + +## Examples + The following example demonstrates how to create and populate two objects. This example is part of a larger example provided for the method. + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/HashSetT/Overview/Program.cs" id="Snippet03"::: + ]]> @@ -717,21 +663,21 @@ Removes all elements from a object. - is set to zero and references to other objects from elements of the collection are also released. The capacity remains unchanged until a call to is made. - - This method is an O(`n`) operation, where `n` is . - - - -## Examples - The following example creates and populates a collection, then clears it and releases the memory referenced by the collection. - + is set to zero and references to other objects from elements of the collection are also released. The capacity remains unchanged until a call to is made. + + This method is an O(`n`) operation, where `n` is . + + + +## Examples + The following example creates and populates a collection, then clears it and releases the memory referenced by the collection. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/HashSetT/Clear/Program.cs" interactive="try-dotnet-method" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_Clear/vb/Program.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_Clear/vb/Program.vb" id="Snippet01"::: + ]]> @@ -780,11 +726,11 @@ Gets the object that is used to determine equality for the values in the set. The object that is used to determine equality for the values in the set. - @@ -836,19 +782,19 @@ if the object contains the specified element; otherwise, . - collection using the method. In this example, the method verifies that the set contains a value before removing it. - + collection using the method. In this example, the method verifies that the set contains a value before removing it. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/HashSetT/Contains/Program.cs" interactive="try-dotnet-method" id="Snippet02"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_RemoveWhere/vb/Program.vb" id="Snippet02"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_RemoveWhere/vb/Program.vb" id="Snippet02"::: + ]]> @@ -905,11 +851,11 @@ The one-dimensional array that is the destination of the elements copied from the object. The array must have zero-based indexing. Copies the elements of a object to an array. - . - + . + ]]> @@ -962,11 +908,11 @@ The zero-based index in at which copying begins. Copies the elements of a object to an array, starting at the specified array index. - . - + . + ]]> @@ -1022,26 +968,26 @@ The number of elements to copy to . Copies the specified number of elements of a object to an array, starting at the specified array index. - is . - is less than 0. - - -or- - + is less than 0. + + -or- + is less than 0. - is greater than the length of the destination . - - -or- - + is greater than the length of the destination . + + -or- + is greater than the available space from the to the end of the destination . @@ -1093,23 +1039,23 @@ Gets the number of elements that are contained in a set. The number of elements that are contained in the set. - object is the number of elements that the object can hold. A object's capacity automatically increases as elements are added to the object. - - The capacity is always greater than or equal to . If exceeds the capacity while adding elements, the capacity is set to the first prime number that is greater than double the previous capacity. - - Retrieving the value of this property is an O(1) operation. - - - -## Examples - The following example demonstrates how to create, populate, and manipulate two objects. In this example, both the contents of the set and display to the console. - + object is the number of elements that the object can hold. A object's capacity automatically increases as elements are added to the object. + + The capacity is always greater than or equal to . If exceeds the capacity while adding elements, the capacity is set to the first prime number that is greater than double the previous capacity. + + Retrieving the value of this property is an O(1) operation. + + + +## Examples + The following example demonstrates how to create, populate, and manipulate two objects. In this example, both the contents of the set and display to the console. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/HashSetT/Overview/Program.cs" interactive="try-dotnet-method" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_UnionWith/vb/Program.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_UnionWith/vb/Program.vb" id="Snippet01"::: + ]]> @@ -1151,13 +1097,13 @@ Returns an object that can be used for equality testing of a object. An object that can be used for deep equality testing of the object. - object checks for equality at only one level; however, you can chain together comparers at additional levels to perform deeper equality testing. - - Calling this method is an O(1) operation. - + object checks for equality at only one level; however, you can chain together comparers at additional levels to perform deeper equality testing. + + Calling this method is an O(1) operation. + ]]> @@ -1248,22 +1194,22 @@ The collection of items to remove from the object. Removes all elements in the specified collection from the current object. - method is the equivalent of mathematical set subtraction. - - This method is an O(`n`) operation, where `n` is the number of elements in the `other` parameter. - - - -## Examples - The following example creates two collections with overlapping sets of data. The lower range of values is then removed from the larger set using the method. - + method is the equivalent of mathematical set subtraction. + + This method is an O(`n`) operation, where `n` is the number of elements in the `other` parameter. + + + +## Examples + The following example creates two collections with overlapping sets of data. The lower range of values is then removed from the larger set using the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_ExceptWith/cpp/program.cpp" id="Snippet02"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/HashSetT/.ctor/Program.cs" interactive="try-dotnet-method" id="Snippet02"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_ExceptWith/vb/Program.vb" id="Snippet02"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_ExceptWith/vb/Program.vb" id="Snippet02"::: + ]]> @@ -1309,27 +1255,27 @@ Returns an enumerator that iterates through a object. A object for the 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 . - - 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 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. - - This method is an O(1) operation. - + 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 . + + 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 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. + + This method is an O(1) operation. + ]]> @@ -1392,11 +1338,11 @@ A structure that contains the source and destination of the serialized stream associated with the object. Implements the interface and returns the data needed to serialize a object. - . - + . + ]]> @@ -1456,11 +1402,11 @@ The collection to compare to the current object. Modifies the current object to contain only elements that are present in that object and in the specified collection. - collection with the same equality comparer as the current object, this method is an O(`n`) operation. Otherwise, this method is an O(`n` + `m`) operation, where `n` is and `m` is the number of elements in `other`. - + collection with the same equality comparer as the current object, this method is an O(`n`) operation. Otherwise, this method is an O(`n` + `m`) operation, where `n` is and `m` is the number of elements in `other`. + ]]> @@ -1523,23 +1469,23 @@ if the object is a proper subset of ; otherwise, . - object is empty unless the `other` parameter is also an empty set. - - This method always returns `false` if is greater than or equal to the number of elements in `other`. - - If the collection represented by `other` is a collection with the same equality comparer as the current object, then this method is an O(`n`) operation. Otherwise, this method is an O(`n` + `m`) operation, where `n` is and `m` is the number of elements in `other`. - - - -## Examples - The following example creates two disparate objects and compares them to each other. In this example, `lowNumbers` is both a subset and a proper subset of `allNumbers` until `allNumbers` is modified, using the method, to contain only values that are present in both sets. Once `allNumbers` and `lowNumbers` are identical, `lowNumbers` is still a subset of `allNumbers` but is no longer a proper subset. - + object is empty unless the `other` parameter is also an empty set. + + This method always returns `false` if is greater than or equal to the number of elements in `other`. + + If the collection represented by `other` is a collection with the same equality comparer as the current object, then this method is an O(`n`) operation. Otherwise, this method is an O(`n` + `m`) operation, where `n` is and `m` is the number of elements in `other`. + + + +## Examples + The following example creates two disparate objects and compares them to each other. In this example, `lowNumbers` is both a subset and a proper subset of `allNumbers` until `allNumbers` is modified, using the method, to contain only values that are present in both sets. Once `allNumbers` and `lowNumbers` are identical, `lowNumbers` is still a subset of `allNumbers` but is no longer a proper subset. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/HashSetT/IsProperSubsetOf/Program.cs" interactive="try-dotnet-method" id="Snippet02"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_boolMethods/vb/Program.vb" id="Snippet02"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_boolMethods/vb/Program.vb" id="Snippet02"::: + ]]> @@ -1602,23 +1548,23 @@ if the object is a proper superset of ; otherwise, . - collection is also empty. - - This method always returns `false` if is less than or equal to the number of elements in `other`. - - If the collection represented by `other` is a collection with the same equality comparer as the current object, this method is an O(`n`) operation. Otherwise, this method is an O(`n` + `m`) operation, where `n` is the number of elements in `other` and `m` is . - - - -## Examples - The following example creates two disparate objects and compares them to each other. In this example, `allNumbers` is both a superset and a proper superset of `lowNumbers` until `allNumbers` is modified, using the method, to contain only values that are present in both sets. Once `allNumbers` and `lowNumbers` are identical, `allNumbers` is still a superset of `lowNumbers` but is no longer a proper superset. - + collection is also empty. + + This method always returns `false` if is less than or equal to the number of elements in `other`. + + If the collection represented by `other` is a collection with the same equality comparer as the current object, this method is an O(`n`) operation. Otherwise, this method is an O(`n` + `m`) operation, where `n` is the number of elements in `other` and `m` is . + + + +## Examples + The following example creates two disparate objects and compares them to each other. In this example, `allNumbers` is both a superset and a proper superset of `lowNumbers` until `allNumbers` is modified, using the method, to contain only values that are present in both sets. Once `allNumbers` and `lowNumbers` are identical, `allNumbers` is still a superset of `lowNumbers` but is no longer a proper superset. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/HashSetT/IsProperSubsetOf/Program.cs" interactive="try-dotnet-method" id="Snippet02"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_boolMethods/vb/Program.vb" id="Snippet02"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_boolMethods/vb/Program.vb" id="Snippet02"::: + ]]> @@ -1681,23 +1627,23 @@ if the object is a subset of ; otherwise, . - object is empty, even if the `other` parameter is an empty set. - - This method always returns `false` if is greater than the number of elements in `other`. - - If the collection represented by `other` is a collection with the same equality comparer as the current object, this method is an O(`n`) operation. Otherwise, this method is an O(`n` + `m`) operation, where `n` is and `m` is the number of elements in `other`. - - - -## Examples - The following example creates two disparate objects and compares them to each other. In this example, `lowNumbers` is both a subset and a proper subset of `allNumbers` until `allNumbers` is modified, using the method, to contain only values that are present in both sets. Once `allNumbers` and `lowNumbers` are identical, `lowNumbers` is still a subset of `allNumbers` but is no longer a proper subset. - + object is empty, even if the `other` parameter is an empty set. + + This method always returns `false` if is greater than the number of elements in `other`. + + If the collection represented by `other` is a collection with the same equality comparer as the current object, this method is an O(`n`) operation. Otherwise, this method is an O(`n` + `m`) operation, where `n` is and `m` is the number of elements in `other`. + + + +## Examples + The following example creates two disparate objects and compares them to each other. In this example, `lowNumbers` is both a subset and a proper subset of `allNumbers` until `allNumbers` is modified, using the method, to contain only values that are present in both sets. Once `allNumbers` and `lowNumbers` are identical, `lowNumbers` is still a subset of `allNumbers` but is no longer a proper subset. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/HashSetT/IsProperSubsetOf/Program.cs" interactive="try-dotnet-method" id="Snippet02"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_boolMethods/vb/Program.vb" id="Snippet02"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_boolMethods/vb/Program.vb" id="Snippet02"::: + ]]> @@ -1754,23 +1700,23 @@ if the object is a superset of ; otherwise, . - object is empty. - - This method always returns `false` if is less than the number of elements in `other`. - - If the collection represented by `other` is a collection with the same equality comparer as the current object, this method is an O(`n`) operation. Otherwise, this method is an O(`n` + `m`) operation, where `n` is the number of elements in `other` and `m` is . - - - -## Examples - The following example creates two disparate objects and compares them to each other. In this example, `allNumbers` is both a superset and a proper superset of `lowNumbers` until `allNumbers` is modified, using the method, to contain only values that are present in both sets. Once `allNumbers` and `lowNumbers` are identical, `allNumbers` is still a superset of `lowNumbers` but is no longer a proper superset. - + object is empty. + + This method always returns `false` if is less than the number of elements in `other`. + + If the collection represented by `other` is a collection with the same equality comparer as the current object, this method is an O(`n`) operation. Otherwise, this method is an O(`n` + `m`) operation, where `n` is the number of elements in `other` and `m` is . + + + +## Examples + The following example creates two disparate objects and compares them to each other. In this example, `allNumbers` is both a superset and a proper superset of `lowNumbers` until `allNumbers` is modified, using the method, to contain only values that are present in both sets. Once `allNumbers` and `lowNumbers` are identical, `allNumbers` is still a superset of `lowNumbers` but is no longer a proper superset. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/HashSetT/IsProperSubsetOf/Program.cs" interactive="try-dotnet-method" id="Snippet02"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_boolMethods/vb/Program.vb" id="Snippet02"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_boolMethods/vb/Program.vb" id="Snippet02"::: + ]]> @@ -1826,11 +1772,11 @@ The source of the deserialization event. Implements the interface and raises the deserialization event when the deserialization is complete. - . - + . + ]]> The object associated with the current object is invalid. @@ -1886,19 +1832,19 @@ if the object and share at least one common element; otherwise, . - objects and compares them to each another. In this example, `allNumbers` and `lowNumbers` are shown to share common elements using the method. - + objects and compares them to each another. In this example, `allNumbers` and `lowNumbers` are shown to share common elements using the method. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/HashSetT/IsProperSubsetOf/Program.cs" interactive="try-dotnet-method" id="Snippet02"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_boolMethods/vb/Program.vb" id="Snippet02"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_boolMethods/vb/Program.vb" id="Snippet02"::: + ]]> @@ -1951,21 +1897,21 @@ if the element is successfully found and removed; otherwise, . This method returns if is not found in the object. - object does not contain the specified element, the object remains unchanged. No exception is thrown. - - This method is an O(1) operation. - - - -## Examples - The following example demonstrates how to remove values from a collection using the method. In this example, zero is arbitrarily removed from the collection. - + object does not contain the specified element, the object remains unchanged. No exception is thrown. + + This method is an O(1) operation. + + + +## Examples + The following example demonstrates how to remove values from a collection using the method. In this example, zero is arbitrarily removed from the collection. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/HashSetT/Contains/Program.cs" interactive="try-dotnet-method" id="Snippet02"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_RemoveWhere/vb/Program.vb" id="Snippet02"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_RemoveWhere/vb/Program.vb" id="Snippet02"::: + ]]> @@ -2012,19 +1958,19 @@ Removes all elements that match the conditions defined by the specified predicate from a collection. The number of elements that were removed from the collection. - . - - - -## Examples - The following example demonstrates how to remove values from a collection using the method. In this example, all odd integers are removed from the collection as specified by the `match` delegate. - + . + + + +## Examples + The following example demonstrates how to remove values from a collection using the method. In this example, all odd integers are removed from the collection as specified by the `match` delegate. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/HashSetT/Contains/Program.cs" interactive="try-dotnet-method" id="Snippet02"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_RemoveWhere/vb/Program.vb" id="Snippet02"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_RemoveWhere/vb/Program.vb" id="Snippet02"::: + ]]> @@ -2087,21 +2033,21 @@ if the object is equal to ; otherwise, . - method ignores duplicate entries and the order of elements in the `other` parameter. - - If the collection represented by `other` is a collection with the same equality comparer as the current object, this method is an O(`n`) operation. Otherwise, this method is an O(`n` + `m`) operation, where `n` is the number of elements in `other` and `m` is . - - - -## Examples - The following example creates two disparate objects and compares them to each another. Initially, the two sets are not equal, which is demonstrated by using the method. The `allNumbers` object is then modified, after which the sets are equal. - + method ignores duplicate entries and the order of elements in the `other` parameter. + + If the collection represented by `other` is a collection with the same equality comparer as the current object, this method is an O(`n`) operation. Otherwise, this method is an O(`n` + `m`) operation, where `n` is the number of elements in `other` and `m` is . + + + +## Examples + The following example creates two disparate objects and compares them to each another. Initially, the two sets are not equal, which is demonstrated by using the method. The `allNumbers` object is then modified, after which the sets are equal. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/HashSetT/IsProperSubsetOf/Program.cs" interactive="try-dotnet-method" id="Snippet02"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_boolMethods/vb/Program.vb" id="Snippet02"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_boolMethods/vb/Program.vb" id="Snippet02"::: + ]]> @@ -2161,19 +2107,19 @@ The collection to compare to the current object. Modifies the current object to contain only elements that are present either in that object or in the specified collection, but not both. - collection with the same equality comparer as the current object, this method is an O(`n`) operation. Otherwise, this method is an O(`n` + `m`) operation, where `n` is the number of elements in `other` and `m` is . - - - -## Examples - The following example creates two collections with overlapping sets of data. The set that contains the lower values is then modified, using the method, to contain only the values that are not present in both sets. - + collection with the same equality comparer as the current object, this method is an O(`n`) operation. Otherwise, this method is an O(`n` + `m`) operation, where `n` is the number of elements in `other` and `m` is . + + + +## Examples + The following example creates two collections with overlapping sets of data. The set that contains the lower values is then modified, using the method, to contain only the values that are not present in both sets. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/HashSetT/SymmetricExceptWith/Program.cs" interactive="try-dotnet-method" id="Snippet02"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_SymmetricExceptWith/vb/Program.vb" id="Snippet02"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_SymmetricExceptWith/vb/Program.vb" id="Snippet02"::: + ]]> @@ -2224,11 +2170,11 @@ The object to add to the object. Adds an item to an object. - is less than , this method is an O(1) operation. If the capacity must be increased to accommodate the new element, this method becomes an O(`n`) operation, where `n` is . - + is less than , this method is an O(1) operation. If the capacity must be increased to accommodate the new element, this method becomes an O(`n`) operation, where `n` is . + ]]> The is read-only. @@ -2276,11 +2222,11 @@ if the collection is read-only; otherwise, . - @@ -2327,27 +2273,27 @@ Returns an enumerator that iterates through a collection. An object that can be used to iterate through the collection. - 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 . - - 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 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 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. - - This method is an O(1) operation. - + 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 . + + 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 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 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. + + This method is an O(1) operation. + ]]> @@ -2395,27 +2341,27 @@ Returns an enumerator that iterates through a collection. An object that can be used to iterate through the collection. - also brings the enumerator back to this position. At this position, the 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 . - - The property returns the same object until either or 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. To set to the first element of the collection again, you can call 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 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. - - This method is an O(1) operation. - + also brings the enumerator back to this position. At this position, the 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 . + + The property returns the same object until either or 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. To set to the first element of the collection again, you can call 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 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. + + This method is an O(1) operation. + ]]> @@ -2459,21 +2405,21 @@ Sets the capacity of a object to the actual number of elements it contains, rounded up to a nearby, implementation-specific value. - method to minimize a object's memory overhead once it is known that no new elements will be added. To completely clear a object and release all memory referenced by it, call this method after calling the method. - - This method is an O(`n`) operation, where `n` is . - - - -## Examples - The following example creates and populates a collection, and then clears the collection and releases the memory referenced by it. - + method to minimize a object's memory overhead once it is known that no new elements will be added. To completely clear a object and release all memory referenced by it, call this method after calling the method. + + This method is an O(`n`) operation, where `n` is . + + + +## Examples + The following example creates and populates a collection, and then clears the collection and releases the memory referenced by it. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/HashSetT/Clear/Program.cs" interactive="try-dotnet-method" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_Clear/vb/Program.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_Clear/vb/Program.vb" id="Snippet01"::: + ]]> @@ -2524,11 +2470,11 @@ Searches the set for a given value and returns the equal value it finds, if any. A value indicating whether the search was successful. - @@ -2580,19 +2526,19 @@ The collection to compare to the current object. Modifies the current object to contain all elements that are present in itself, the specified collection, or both. - objects, and populates them with even and odd numbers, respectively. A third object is created from the set that contains the even numbers. The example then calls the method, which adds the odd number set to the third set. - + objects, and populates them with even and odd numbers, respectively. A third object is created from the set that contains the even numbers. The example then calls the method, which adds the odd number set to the third set. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/HashSetT/Overview/Program.cs" interactive="try-dotnet-method" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_UnionWith/vb/Program.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.HashSet_UnionWith/vb/Program.vb" id="Snippet01"::: + ]]> diff --git a/xml/System.Collections.Generic/List`1.xml b/xml/System.Collections.Generic/List`1.xml index 967dc784a70..fb54935e8b4 100644 --- a/xml/System.Collections.Generic/List`1.xml +++ b/xml/System.Collections.Generic/List`1.xml @@ -1,5300 +1,5238 @@ - - - - - - - - - - - - - - - - - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - - - - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - System.Object - - - - System.Collections.Generic.ICollection<T> - - - System.Collections.Generic.IEnumerable<T> - - - System.Collections.Generic.IList<T> - - - System.Collections.Generic.IReadOnlyCollection<T> - - - System.Collections.Generic.IReadOnlyList<T> - - - System.Collections.ICollection - - - System.Collections.IEnumerable - - - System.Collections.IList - - - - - [System.Runtime.CompilerServices.Nullable(0)] - [<System.Runtime.CompilerServices.Nullable(0)>] - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - [System.Diagnostics.DebuggerDisplay("Count = {Count}")] - [<System.Diagnostics.DebuggerDisplay("Count = {Count}")>] - - - [System.Diagnostics.DebuggerTypeProxy(typeof(System.Collections.Generic.Mscorlib_CollectionDebugView<>))] - [<System.Diagnostics.DebuggerTypeProxy(typeof(System.Collections.Generic.Mscorlib_CollectionDebugView<>))>] - - - [System.Serializable] - [<System.Serializable>] - - - - The type of elements in the list. - Represents a strongly typed list of objects that can be accessed by index. Provides methods to search, sort, and manipulate lists. - - class is the generic equivalent of the class. It implements the generic interface by using an array whose size is dynamically increased as required. - - You can add items to a by using the or methods. - - The class uses both an equality comparer and an ordering comparer. - -- Methods such as , , , and use an equality comparer for the list elements. The default equality comparer for type `T` is determined as follows. If type `T` implements the generic interface, then the equality comparer is the method of that interface; otherwise, the default equality comparer is . - -- Methods such as and use an ordering comparer for the list elements. The default comparer for type `T` is determined as follows. If type `T` implements the generic interface, then the default comparer is the method of that interface; otherwise, if type `T` implements the nongeneric interface, then the default comparer is the method of that interface. If type `T` implements neither interface, then there is no default comparer, and a comparer or comparison delegate must be provided explicitly. - - The is not guaranteed to be sorted. You must sort the before performing operations (such as ) that require the to be sorted. - - Elements in this collection can be accessed using an integer index. Indexes in this collection are zero-based. - - **.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. - - accepts `null` as a valid value for reference types and allows duplicate elements. - - For an immutable version of the class, see . - -## Performance Considerations - In deciding whether to use the or class, both of which have similar functionality, remember that the class performs better in most cases and is type safe. If a reference type is used for type `T` of the class, the behavior of the two classes is identical. However, if a value type is used for type `T`, you need to consider implementation and boxing issues. - - If a value type is used for type `T`, the compiler generates an implementation of the class specifically for that value type. That means a list element of a object does not have to be boxed before the element can be used, and after about 500 list elements are created, the memory saved by not boxing list elements is greater than the memory used to generate the class implementation. - - Make certain the value type used for type `T` implements the generic interface. If not, methods such as must call the method, which boxes the affected list element. If the value type implements the interface and you own the source code, also implement the generic interface to prevent the and methods from boxing list elements. If you do not own the source code, pass an object to the and methods - - It is to your advantage to use the type-specific implementation of the class instead of using the class or writing a strongly typed wrapper collection yourself. That's because your implementation must do what the .NET Framework does for you already, and the common language runtime can share Microsoft intermediate language code and metadata, which your implementation cannot. - -## F# Considerations - The class is used infrequently in F# code. Instead, [Lists](/dotnet/fsharp/language-reference/lists), which are immutable, singly-linked lists, are typically preferred. An F# `List` provides an ordered, immutable series of values, and is supported for use in functional-style development. When used from F#, the class is typically referred to by the `ResizeArray<'T>` type abbreviation to avoid naming conflicts with F# Lists. - -## Examples - - The following example demonstrates how to add, remove, and insert a simple business object in a . - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/program.cs" interactive="try-dotnet" id="snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.addremoveinsert/vb/module1.vb" id="snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.collections.generic.list.addremoveinsert/fs/addremoveinsert.fs" id="snippet1"::: - - The following example demonstrates several properties and methods of the generic class of type string. (For an example of a of complex types, see the method.) - - The parameterless constructor is used to create a list of strings with the default capacity. The property is displayed and then the method is used to add several items. The items are listed, and the property is displayed again, along with the property, to show that the capacity has been increased as needed. - - The method is used to test for the presence of an item in the list, the method is used to insert a new item in the middle of the list, and the contents of the list are displayed again. - - The default property (the indexer in C#) is used to retrieve an item, the method is used to remove the first instance of the duplicate item added earlier, and the contents are displayed again. The method always removes the first instance it encounters. - - The method is used to reduce the capacity to match the count, and the and properties are displayed. If the unused capacity had been less than 10 percent of total capacity, the list would not have been resized. - - Finally, the method is used to remove all items from the list, and the and properties are displayed. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Class/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/List`1_Class/fs/listclass.fs" id="Snippet1"::: - - ]]> - - Public static ( in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe. - - It is safe to perform multiple read operations on a , but issues can occur if the collection is modified while it's being read. To ensure thread safety, lock the collection during a read or write operation. To enable a collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. For collections with built-in synchronization, see the classes in the namespace. For an inherently thread-safe alternative, see the class. - - - Performing Culture-Insensitive String Operations in Collections - Iterators (C#) - Iterators (Visual Basic) - - - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - - - Initializes a new instance of the class. - - - - - - - - - Constructor - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - - Initializes a new instance of the class that is empty and has the default initial capacity. - - is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. - - If the size of the collection can be estimated, using the constructor and specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . - - The capacity can be decreased by calling the method or by setting the property explicitly. Decreasing the capacity reallocates memory and copies all the elements in the . - + + + + + + + + + + + + + + + + + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + + + + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + System.Object + + + + System.Collections.Generic.ICollection<T> + + + System.Collections.Generic.IEnumerable<T> + + + System.Collections.Generic.IList<T> + + + System.Collections.Generic.IReadOnlyCollection<T> + + + System.Collections.Generic.IReadOnlyList<T> + + + System.Collections.ICollection + + + System.Collections.IEnumerable + + + System.Collections.IList + + + + + [System.Runtime.CompilerServices.Nullable(0)] + [<System.Runtime.CompilerServices.Nullable(0)>] + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + [System.Diagnostics.DebuggerDisplay("Count = {Count}")] + [<System.Diagnostics.DebuggerDisplay("Count = {Count}")>] + + + [System.Diagnostics.DebuggerTypeProxy(typeof(System.Collections.Generic.Mscorlib_CollectionDebugView<>))] + [<System.Diagnostics.DebuggerTypeProxy(typeof(System.Collections.Generic.Mscorlib_CollectionDebugView<>))>] + + + [System.Serializable] + [<System.Serializable>] + + + + The type of elements in the list. + Represents a strongly typed list of objects that can be accessed by index. Provides methods to search, sort, and manipulate lists. + For more information about this API, see Supplemental API remarks for List<T>. + Public static ( in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe. + + It is safe to perform multiple read operations on a , but issues can occur if the collection is modified while it's being read. To ensure thread safety, lock the collection during a read or write operation. To enable a collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. For collections with built-in synchronization, see the classes in the namespace. For an inherently thread-safe alternative, see the class. + + + Performing Culture-Insensitive String Operations in Collections + Iterators (C#) + Iterators (Visual Basic) + + + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + + + Initializes a new instance of the class. + + + + + + + + + Constructor + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + + Initializes a new instance of the class that is empty and has the default initial capacity. + + is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. + + If the size of the collection can be estimated, using the constructor and specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . + + The capacity can be decreased by calling the method or by setting the property explicitly. Decreasing the capacity reallocates memory and copies all the elements in the . + This constructor is an O(1) operation. - -## Examples - The following example demonstrates the parameterless constructor of the generic class. The parameterless constructor creates a list with the default capacity, as demonstrated by displaying the property. - - The example adds, inserts, and removes items, showing how the capacity changes as these methods are used. - +## Examples + + The following example demonstrates the parameterless constructor of the generic class. The parameterless constructor creates a list with the default capacity, as demonstrated by displaying the property. + + The example adds, inserts, and removes items, showing how the capacity changes as these methods are used. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Class/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/List`1_Class/fs/listclass.fs" id="Snippet1"::: - - ]]> - - - - - - - - - - - Constructor - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - - - The collection whose elements are copied to the new list. - Initializes a new instance of the class that contains elements copied from the specified collection and has sufficient capacity to accommodate the number of elements copied. - - in the same order they are read by the enumerator of the collection. - + + ]]> + + + + + + + + + + + Constructor + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + + + The collection whose elements are copied to the new list. + Initializes a new instance of the class that contains elements copied from the specified collection and has sufficient capacity to accommodate the number of elements copied. + + in the same order they are read by the enumerator of the collection. + This constructor is an O(*n*) operation, where *n* is the number of elements in `collection`. - -## Examples - The following example demonstrates the constructor and various methods of the class that act on ranges. An array of strings is created and passed to the constructor, populating the list with the elements of the array. The property is then displayed, to show that the initial capacity is exactly what is required to hold the input elements. - + +## Examples + The following example demonstrates the constructor and various methods of the class that act on ranges. An array of strings is created and passed to the constructor, populating the list with the elements of the array. The property is then displayed, to show that the initial capacity is exactly what is required to hold the input elements. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Ranges/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/.ctor/source1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Ranges/vb/source.vb" id="Snippet1"::: - - ]]> - - - is . - - - - - - - - - - - - Constructor - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - - - - The number of elements that the new list can initially store. - Initializes a new instance of the class that is empty and has the specified initial capacity. - - is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. - - If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . - - The capacity can be decreased by calling the method or by setting the property explicitly. Decreasing the capacity reallocates memory and copies all the elements in the . - + + ]]> + + + is . + + + + + + + + + + + + Constructor + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + + + + The number of elements that the new list can initially store. + Initializes a new instance of the class that is empty and has the specified initial capacity. + + is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. + + If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . + + The capacity can be decreased by calling the method or by setting the property explicitly. Decreasing the capacity reallocates memory and copies all the elements in the . + This constructor is an O(1) operation. - -## Examples - The following example demonstrates the constructor. A of strings with a capacity of 4 is created, because the ultimate size of the list is known to be exactly 4. The list is populated with four strings, and a read-only copy is created by using the method. - + +## Examples + The following example demonstrates the constructor. A of strings with a capacity of 4 is created, because the ultimate size of the list is known to be exactly 4. The list is populated with four strings, and a read-only copy is created by using the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_AsReadOnly/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/.ctor/source.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_AsReadOnly/vb/source.vb" id="Snippet1"::: - - ]]> - - - is less than 0. - - - - - - - - - - - Method - - M:System.Collections.Generic.ICollection`1.Add(`0) - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Void - - - - - - The object to be added to the end of the . The value can be for reference types. - Adds an object to the end of the . - - accepts `null` as a valid value for reference types and allows duplicate elements. - - If already equals , the capacity of the is increased by automatically reallocating the internal array, and the existing elements are copied to the new array before the new element is added. - + + ]]> + + + is less than 0. + + + + + + + + + + + Method + + M:System.Collections.Generic.ICollection`1.Add(`0) + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Void + + + + + + The object to be added to the end of the . The value can be for reference types. + Adds an object to the end of the . + + accepts `null` as a valid value for reference types and allows duplicate elements. + + If already equals , the capacity of the is increased by automatically reallocating the internal array, and the existing elements are copied to the new array before the new element is added. + If is less than , this method is an O(1) operation. If the capacity needs to be increased to accommodate the new element, this method becomes an O(*n*) operation, where *n* is . - -## Examples - The following example demonstrates how to add, remove, and insert a simple business object in a . - +## Examples + + The following example demonstrates how to add, remove, and insert a simple business object in a . + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/program.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.addremoveinsert/vb/module1.vb" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.collections.generic.list.addremoveinsert/fs/addremoveinsert.fs" id="Snippet1"::: - - The following example demonstrates several properties and methods of the generic class, including the method. The parameterless constructor is used to create a list of strings with a capacity of 0. The property is displayed, and then the method is used to add several items. The items are listed, and the property is displayed again, along with the property, to show that the capacity has been increased as needed. - - Other properties and methods are used to search for, insert, and remove elements from the list, and finally to clear the list. - + + The following example demonstrates several properties and methods of the generic class, including the method. The parameterless constructor is used to create a list of strings with a capacity of 0. The property is displayed, and then the method is used to add several items. The items are listed, and the property is displayed again, along with the property, to show that the capacity has been increased as needed. + + Other properties and methods are used to search for, insert, and remove elements from the list, and finally to clear the list. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Class/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/List`1_Class/fs/listclass.fs" id="Snippet1"::: - - ]]> - - - - - - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Void - - - - - - The collection whose elements should be added to the end of the . The collection itself cannot be , but it can contain elements that are , if type is a reference type. - Adds the elements of the specified collection to the end of the . - - . - - If the new (the current plus the size of the collection) will be greater than , the capacity of the is increased by automatically reallocating the internal array to accommodate the new elements, and the existing elements are copied to the new array before the new elements are added. - + + ]]> + + + + + + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Void + + + + + + The collection whose elements should be added to the end of the . The collection itself cannot be , but it can contain elements that are , if type is a reference type. + Adds the elements of the specified collection to the end of the . + + . + + If the new (the current plus the size of the collection) will be greater than , the capacity of the is increased by automatically reallocating the internal array to accommodate the new elements, and the existing elements are copied to the new array before the new elements are added. + If the can accommodate the new elements without increasing the , this method is an O(*n*) operation, where *n* is the number of elements to be added. If the capacity needs to be increased to accommodate the new elements, this method becomes an O(*n* + *m*) operation, where *n* is the number of elements to be added and *m* is . - -## Examples - The following example demonstrates the method and various other methods of the class that act on ranges. An array of strings is created and passed to the constructor, populating the list with the elements of the array. The method is called, with the list as its argument. The result is that the current elements of the list are added to the end of the list, duplicating all the elements. - + +## Examples + The following example demonstrates the method and various other methods of the class that act on ranges. An array of strings is created and passed to the constructor, populating the list with the elements of the array. The method is called, with the list as its argument. The result is that the current elements of the list are added to the end of the list, duplicating all the elements. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Ranges/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/.ctor/source1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Ranges/vb/source.vb" id="Snippet1"::: - - ]]> - - - is . - - - - - - - - - - - - - - - - - Method - - System.Collections - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Collections.ObjectModel.ReadOnlyCollection<T> - - - - Returns a read-only wrapper for the current collection. - An object that acts as a read-only wrapper around the current . - - object, expose it only through this wrapper. A object does not expose methods that modify the collection. However, if changes are made to the underlying object, the read-only collection reflects those changes. - + + ]]> + + + is . + + + + + + + + + + + + + + + + + Method + + System.Collections + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Collections.ObjectModel.ReadOnlyCollection<T> + + + + Returns a read-only wrapper for the current collection. + An object that acts as a read-only wrapper around the current . + + object, expose it only through this wrapper. A object does not expose methods that modify the collection. However, if changes are made to the underlying object, the read-only collection reflects those changes. + This method is an O(1) operation. - -## Examples - The following example demonstrates the method. A of strings with a capacity of 4 is created, because the ultimate size of the list is known to be exactly 4. The list is populated with four strings, and the method is used to get a read-only generic interface implementation that wraps the original list. - - An element of the original list is set to "Coelophysis" using the property (the indexer in C#), and the contents of the read-only list are displayed again to demonstrate that it is just a wrapper for the original list. - + +## Examples + The following example demonstrates the method. A of strings with a capacity of 4 is created, because the ultimate size of the list is known to be exactly 4. The list is populated with four strings, and the method is used to get a read-only generic interface implementation that wraps the original list. + + An element of the original list is set to "Coelophysis" using the property (the indexer in C#), and the contents of the read-only list are displayed again to demonstrate that it is just a wrapper for the original list. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_AsReadOnly/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/.ctor/source.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_AsReadOnly/vb/source.vb" id="Snippet1"::: - - ]]> - - - - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - - - Uses a binary search algorithm to locate a specific element in the sorted or a portion of it. - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Int32 - - - - - - The object to locate. The value can be for reference types. - Searches the entire sorted for an element using the default comparer and returns the zero-based index of the element. - The zero-based index of in the sorted , if is found; otherwise, a negative number that is the bitwise complement of the index of the next element that is larger than or, if there is no larger element, the bitwise complement of . - - for type `T` to determine the order of list elements. The property checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws an . - - The must already be sorted according to the comparer implementation; otherwise, the result is incorrect. - - Comparing `null` with any reference type is allowed and does not generate an exception when using the generic interface. When sorting, `null` is considered to be less than any other object. - - If the contains more than one element with the same value, the method returns only one of the occurrences, and it might return any one of the occurrences, not necessarily the first one. - - If the does not contain the specified value, the method returns a negative integer. You can apply the bitwise complement operation (~) to this negative integer to get the index of the first element that is larger than the search value. When inserting the value into the , this index should be used as the insertion point to maintain the sort order. - + + ]]> + + + + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + + + Uses a binary search algorithm to locate a specific element in the sorted or a portion of it. + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Int32 + + + + + + The object to locate. The value can be for reference types. + Searches the entire sorted for an element using the default comparer and returns the zero-based index of the element. + The zero-based index of in the sorted , if is found; otherwise, a negative number that is the bitwise complement of the index of the next element that is larger than or, if there is no larger element, the bitwise complement of . + + for type `T` to determine the order of list elements. The property checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws an . + + The must already be sorted according to the comparer implementation; otherwise, the result is incorrect. + + Comparing `null` with any reference type is allowed and does not generate an exception when using the generic interface. When sorting, `null` is considered to be less than any other object. + + If the contains more than one element with the same value, the method returns only one of the occurrences, and it might return any one of the occurrences, not necessarily the first one. + + If the does not contain the specified value, the method returns a negative integer. You can apply the bitwise complement operation (~) to this negative integer to get the index of the first element that is larger than the search value. When inserting the value into the , this index should be used as the insertion point to maintain the sort order. + This method is an O(log *n*) operation, where *n* is the number of elements in the range. - -## 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. - + +## 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. + :::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"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_SortSearch/vb/source.vb" id="Snippet1"::: - - ]]> - - The default comparer cannot find an implementation of the generic interface or the interface for type . - Performing Culture-Insensitive String Operations in Collections - - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Int32 - - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })>] - - - - - - The object to locate. The value can be for reference types. - The implementation to use when comparing elements. - - -or- - - to use the default comparer . - Searches the entire sorted for an element using the specified comparer and returns the zero-based index of the element. - The zero-based index of in the sorted , if is found; otherwise, a negative number that is the bitwise complement of the index of the next element that is larger than or, if there is no larger element, the bitwise complement of . - - instance as the comparer to perform case-insensitive string searches. - - If `comparer` is provided, the elements of the are compared to the specified value using the specified implementation. - - If `comparer` is `null`, the default comparer checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws . - - The must already be sorted according to the comparer implementation; otherwise, the result is incorrect. - - Comparing `null` with any reference type is allowed and does not generate an exception when using the generic interface. When sorting, `null` is considered to be less than any other object. - - If the contains more than one element with the same value, the method returns only one of the occurrences, and it might return any one of the occurrences, not necessarily the first one. - - If the does not contain the specified value, the method returns a negative integer. You can apply the bitwise complement operation (~) to this negative integer to get the index of the first element that is larger than the search value. When inserting the value into the , this index should be used as the insertion point to maintain the sort order. - + + ]]> + + The default comparer cannot find an implementation of the generic interface or the interface for type . + Performing Culture-Insensitive String Operations in Collections + + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Int32 + + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })>] + + + + + + The object to locate. The value can be for reference types. + The implementation to use when comparing elements. + + -or- + + to use the default comparer . + Searches the entire sorted for an element using the specified comparer and returns the zero-based index of the element. + The zero-based index of in the sorted , if is found; otherwise, a negative number that is the bitwise complement of the index of the next element that is larger than or, if there is no larger element, the bitwise complement of . + + instance as the comparer to perform case-insensitive string searches. + + If `comparer` is provided, the elements of the are compared to the specified value using the specified implementation. + + If `comparer` is `null`, the default comparer checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws . + + The must already be sorted according to the comparer implementation; otherwise, the result is incorrect. + + Comparing `null` with any reference type is allowed and does not generate an exception when using the generic interface. When sorting, `null` is considered to be less than any other object. + + If the contains more than one element with the same value, the method returns only one of the occurrences, and it might return any one of the occurrences, not necessarily the first one. + + If the does not contain the specified value, the method returns a negative integer. You can apply the bitwise complement operation (~) to this negative integer to get the index of the first element that is larger than the search value. When inserting the value into the , this index should be used as the insertion point to maintain the sort order. + This method is an O(log *n*) operation, where *n* is the number of elements in the range. - -## 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. - - 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. - + +## 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. + + 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. + :::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"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_SortSearchComparer/vb/source.vb" id="Snippet1"::: - - ]]> - - - is , and the default comparer cannot find an implementation of the generic interface or the interface for type . - Performing Culture-Insensitive String Operations in Collections - - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Int32 - - - - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })>] - - - - - - The zero-based starting index of the range to search. - The length of the range to search. - The object to locate. The value can be for reference types. - The implementation to use when comparing elements, or to use the default comparer . - Searches a range of elements in the sorted for an element using the specified comparer and returns the zero-based index of the element. - The zero-based index of in the sorted , if is found; otherwise, a negative number that is the bitwise complement of the index of the next element that is larger than or, if there is no larger element, the bitwise complement of . - - instance as the comparer to perform case-insensitive string searches. - - If `comparer` is provided, the elements of the are compared to the specified value using the specified implementation. - - If `comparer` is `null`, the default comparer checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws . - - The must already be sorted according to the comparer implementation; otherwise, the result is incorrect. - - Comparing `null` with any reference type is allowed and does not generate an exception when using the generic interface. When sorting, `null` is considered to be less than any other object. - - If the contains more than one element with the same value, the method returns only one of the occurrences, and it might return any one of the occurrences, not necessarily the first one. - - If the does not contain the specified value, the method returns a negative integer. You can apply the bitwise complement operation (~) to this negative integer to get the index of the first element that is larger than the search value. When inserting the value into the , this index should be used as the insertion point to maintain the sort order. - + + ]]> + + + is , and the default comparer cannot find an implementation of the generic interface or the interface for type . + Performing Culture-Insensitive String Operations in Collections + + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Int32 + + + + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })>] + + + + + + The zero-based starting index of the range to search. + The length of the range to search. + The object to locate. The value can be for reference types. + The implementation to use when comparing elements, or to use the default comparer . + Searches a range of elements in the sorted for an element using the specified comparer and returns the zero-based index of the element. + The zero-based index of in the sorted , if is found; otherwise, a negative number that is the bitwise complement of the index of the next element that is larger than or, if there is no larger element, the bitwise complement of . + + instance as the comparer to perform case-insensitive string searches. + + If `comparer` is provided, the elements of the are compared to the specified value using the specified implementation. + + If `comparer` is `null`, the default comparer checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws . + + The must already be sorted according to the comparer implementation; otherwise, the result is incorrect. + + Comparing `null` with any reference type is allowed and does not generate an exception when using the generic interface. When sorting, `null` is considered to be less than any other object. + + If the contains more than one element with the same value, the method returns only one of the occurrences, and it might return any one of the occurrences, not necessarily the first one. + + If the does not contain the specified value, the method returns a negative integer. You can apply the bitwise complement operation (~) to this negative integer to get the index of the first element that is larger than the search value. When inserting the value into the , this index should be used as the insertion point to maintain the sort order. + This method is an O(log *n*) operation, where *n* is the number of elements in the range. - -## 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. - - 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. - + +## 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. + + 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. + :::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"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_SortSearchComparerRange/vb/source.vb" id="Snippet1"::: - - ]]> - - - is less than 0. - - -or- - - is less than 0. - - and do not denote a valid range in the . - - is , and the default comparer cannot find an implementation of the generic interface or the interface for type . - - - Performing Culture-Insensitive String Operations in Collections - - - - - - - - - - Property - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Int32 - - - Gets or sets the total number of elements the internal data structure can hold without resizing. - The number of elements that the can contain before resizing is required. - - is the number of elements that the can store before resizing is required, whereas is the number of elements that are actually in the . - - is always greater than or equal to . If exceeds while adding elements, the capacity is increased by automatically reallocating the internal array before copying the old elements and adding the new elements. - - If the capacity is significantly larger than the count and you want to reduce the memory used by the , you can decrease capacity by calling the method or by setting the property explicitly to a lower value. When the value of is set explicitly, the internal array is also reallocated to accommodate the specified capacity, and all the elements are copied. - + + ]]> + + + is less than 0. + + -or- + + is less than 0. + + and do not denote a valid range in the . + + is , and the default comparer cannot find an implementation of the generic interface or the interface for type . + + + Performing Culture-Insensitive String Operations in Collections + + + + + + + + + + Property + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Int32 + + + Gets or sets the total number of elements the internal data structure can hold without resizing. + The number of elements that the can contain before resizing is required. + + is the number of elements that the can store before resizing is required, whereas is the number of elements that are actually in the . + + is always greater than or equal to . If exceeds while adding elements, the capacity is increased by automatically reallocating the internal array before copying the old elements and adding the new elements. + + If the capacity is significantly larger than the count and you want to reduce the memory used by the , you can decrease capacity by calling the method or by setting the property explicitly to a lower value. When the value of is set explicitly, the internal array is also reallocated to accommodate the specified capacity, and all the elements are copied. + Retrieving the value of this property is an O(1) operation; setting the property is an O(*n*) operation, where *n* is the new capacity. - -## Examples - - The following example demonstrates how to check the capacity and count of a that contains a simple business object, and illustrates using the method to remove extra capacity. - + +## Examples + + The following example demonstrates how to check the capacity and count of a that contains a simple business object, and illustrates using the method to remove extra capacity. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Capacity/program.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.capacitycount/vb/module1.vb" id="Snippet1"::: - - The following example shows the property at several points in the life of a list. The parameterless constructor is used to create a list of strings with a capacity of 0, and the property is displayed to demonstrate this. After the method has been used to add several items, the items are listed, and then the property is displayed again, along with the property, to show that the capacity has been increased as needed. - - The property is displayed again after the method is used to reduce the capacity to match the count. Finally, the method is used to remove all items from the list, and the and properties are displayed again. - + + The following example shows the property at several points in the life of a list. The parameterless constructor is used to create a list of strings with a capacity of 0, and the property is displayed to demonstrate this. After the method has been used to add several items, the items are listed, and then the property is displayed again, along with the property, to show that the capacity has been increased as needed. + + The property is displayed again after the method is used to reduce the capacity to match the count. Finally, the method is used to remove all items from the list, and the and properties are displayed again. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Class/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/List`1_Class/fs/listclass.fs" id="Snippet1"::: - - ]]> - - - is set to a value that is less than . - There is not enough memory available on the system. - - - - - - - - - - - Method - - M:System.Collections.Generic.ICollection`1.Clear - M:System.Collections.IList.Clear - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Void - - - - Removes all elements from the . - - is set to 0, and references to other objects from elements of the collection are also released. - - remains unchanged. To reset the capacity of the , call the method or set the property directly. Decreasing the capacity reallocates memory and copies all the elements in the . Trimming an empty sets the capacity of the to the default capacity. - + + ]]> + + + is set to a value that is less than . + There is not enough memory available on the system. + + + + + + + + + + + Method + + M:System.Collections.Generic.ICollection`1.Clear + M:System.Collections.IList.Clear + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Void + + + + Removes all elements from the . + + is set to 0, and references to other objects from elements of the collection are also released. + + remains unchanged. To reset the capacity of the , call the method or set the property directly. Decreasing the capacity reallocates memory and copies all the elements in the . Trimming an empty sets the capacity of the to the default capacity. + This method is an O(*n*) operation, where *n* is . - -## Examples - The following example demonstrates the method and various other properties and methods of the generic class. The method is used at the end of the program, to remove all items from the list, and the and properties are then displayed. - +## Examples + + The following example demonstrates the method and various other properties and methods of the generic class. The method is used at the end of the program, to remove all items from the list, and the and properties are then displayed. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Class/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/List`1_Class/fs/listclass.fs" id="Snippet1"::: - - ]]> - - - - - - - - - - - - - - Method - - M:System.Collections.Generic.ICollection`1.Contains(`0) - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Boolean - - - - - - The object to locate in the . The value can be for reference types. - Determines whether an element is in the . - - if is found in the ; otherwise, . - - method for `T` (the type of values in the list). - + + ]]> + + + + + + + + + + + + + + Method + + M:System.Collections.Generic.ICollection`1.Contains(`0) + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Boolean + + + + + + The object to locate in the . The value can be for reference types. + Determines whether an element is in the . + + if is found in the ; otherwise, . + + method for `T` (the type of values in the list). + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . - -## Examples - The following example demonstrates the and methods on a that contains a simple business object that implements . - + +## Examples + The following example demonstrates the and methods on a that contains a simple business object that implements . + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Contains/program1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.containsexists/vb/module1.vb" id="Snippet1"::: - - The following example contains a list of complex objects of type `Cube`. The `Cube` class implements the method so that two cubes are considered equal if their dimensions are the same. In this example, the method returns `true`, because a cube that has the specified dimensions is already in the collection. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.containsexists/vb/module1.vb" id="Snippet1"::: + + The following example contains a list of complex objects of type `Cube`. The `Cube` class implements the method so that two cubes are considered equal if their dimensions are the same. In this example, the method returns `true`, because a cube that has the specified dimensions is already in the collection. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Contains/program.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.contains/vb/program.vb" id="Snippet1"::: - - ]]> - - - - Performing Culture-Insensitive String Operations in Collections - - - - - - - - - - Method - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Collections - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Collections.Generic.List<TOutput> - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - The type of the elements of the target array. - A delegate that converts each element from one type to another type. - Converts the elements in the current to another type, and returns a list containing the converted elements. - A of the target type containing the converted elements from the current . - - is a delegate to a method that converts an object to the target type. The elements of the current are individually passed to the delegate, and the converted elements are saved in the new . - - The current remains unchanged. - + + ]]> + + + + Performing Culture-Insensitive String Operations in Collections + + + + + + + + + + Method + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Collections + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Collections.Generic.List<TOutput> + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + The type of the elements of the target array. + A delegate that converts each element from one type to another type. + Converts the elements in the current to another type, and returns a list containing the converted elements. + A of the target type containing the converted elements from the current . + + is a delegate to a method that converts an object to the target type. The elements of the current are individually passed to the delegate, and the converted elements are saved in the new . + + The current remains unchanged. + This method is an O(*n*) operation, where *n* is . - -## Examples - The following example defines a method named `PointFToPoint` that converts a structure to a structure. The example then creates a of structures, creates a `Converter\` delegate (`Converter(Of PointF, Point)` in Visual Basic) to represent the `PointFToPoint` method, and passes the delegate to the method. The method passes each element of the input list to the `PointFToPoint` method and puts the converted elements into a new list of structures. Both lists are displayed. - + +## Examples + The following example defines a method named `PointFToPoint` that converts a structure to a structure. The example then creates a of structures, creates a `Converter\` delegate (`Converter(Of PointF, Point)` in Visual Basic) to represent the `PointFToPoint` method, and passes the delegate to the method. The method passes each element of the input list to the `PointFToPoint` method and puts the converted elements into a new list of structures. Both lists are displayed. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_ConvertAll/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/ConverterTInput,TOutput/Overview/source.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_ConvertAll/vb/source.vb" id="Snippet1"::: - - ]]> - - - is . - - - - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - - - Copies the or a portion of it to an array. - - method. A of strings is created and populated with 5 strings. An empty string array of 15 elements is created, and the method overload is used to copy all the elements of the list to the array beginning at the first element of the array. The method overload is used to copy all the elements of the list to the array beginning at array index 6 (leaving index 5 empty). Finally, the method overload is used to copy 3 elements from the list, beginning with index 2, to the array beginning at array index 12 (leaving index 11 empty). The contents of the array are then displayed. - + + ]]> + + + is . + + + + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + + + Copies the or a portion of it to an array. + + method. A of strings is created and populated with 5 strings. An empty string array of 15 elements is created, and the method overload is used to copy all the elements of the list to the array beginning at the first element of the array. The method overload is used to copy all the elements of the list to the array beginning at array index 6 (leaving index 5 empty). Finally, the method overload is used to copy 3 elements from the list, beginning with index 2, to the array beginning at array index 12 (leaving index 11 empty). The contents of the array are then displayed. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_CopyTo/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/CopyTo/source.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_CopyTo/vb/source.vb" id="Snippet1"::: - - ]]> - - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Void - - - - - - The one-dimensional that is the destination of the elements copied from . The must have zero-based indexing. - Copies the entire to a compatible one-dimensional array, starting at the beginning of the target array. - - to copy the elements. - - The elements are copied to the in the same order in which the enumerator iterates through the . - + + ]]> + + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Void + + + + + + The one-dimensional that is the destination of the elements copied from . The must have zero-based indexing. + Copies the entire to a compatible one-dimensional array, starting at the beginning of the target array. + + to copy the elements. + + The elements are copied to the in the same order in which the enumerator iterates through the . + + This method is an O(*n*) operation, where *n* is . + + ]]> + + + is . + The number of elements in the source is greater than the number of elements that the destination can contain. + + + + + + + + + + Method + + M:System.Collections.Generic.ICollection`1.CopyTo(`0[],System.Int32) + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Void + + + + + + + The one-dimensional that is the destination of the elements copied from . The must have zero-based indexing. + The zero-based index in at which copying begins. + Copies the entire to a compatible one-dimensional array, starting at the specified index of the target array. + + to copy the elements. + + The elements are copied to the in the same order in which the enumerator iterates through the . + This method is an O(*n*) operation, where *n* is . - - ]]> - - - is . - The number of elements in the source is greater than the number of elements that the destination can contain. - - - - - - - - - - Method - - M:System.Collections.Generic.ICollection`1.CopyTo(`0[],System.Int32) - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Void - - - - - - - The one-dimensional that is the destination of the elements copied from . The must have zero-based indexing. - The zero-based index in at which copying begins. - Copies the entire to a compatible one-dimensional array, starting at the specified index of the target array. - - to copy the elements. - - The elements are copied to the in the same order in which the enumerator iterates through the . - - This method is an O(*n*) operation, where *n* is . - - ]]> - - - is . - - is less than 0. - The number of elements in the source is greater than the available space from to the end of the destination . - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Void - - - - - - - - - The zero-based index in the source at which copying begins. - The one-dimensional that is the destination of the elements copied from . The must have zero-based indexing. - The zero-based index in at which copying begins. - The number of elements to copy. - Copies a range of elements from the to a compatible one-dimensional array, starting at the specified index of the target array. - - to copy the elements. - - The elements are copied to the in the same order in which the enumerator iterates through the . - - This method is an O(*n*) operation, where *n* is `count`. - - ]]> - - - is . - - is less than 0. - - -or- - - is less than 0. - - -or- - - is less than 0. - - is equal to or greater than the of the source . - - -or- - - The number of elements from to the end of the source is greater than the available space from to the end of the destination . - - - - - - - - - - Property - - P:System.Collections.Generic.ICollection`1.Count - P:System.Collections.Generic.IReadOnlyCollection`1.Count - P:System.Collections.ICollection.Count - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Int32 - - - Gets the number of elements contained in the . - The number of elements contained in the . - - is the number of elements that the can store before resizing is required. is the number of elements that are actually in the . - - is always greater than or equal to . If exceeds while adding elements, the capacity is increased by automatically reallocating the internal array before copying the old elements and adding the new elements. - + + ]]> + + + is . + + is less than 0. + The number of elements in the source is greater than the available space from to the end of the destination . + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Void + + + + + + + + + The zero-based index in the source at which copying begins. + The one-dimensional that is the destination of the elements copied from . The must have zero-based indexing. + The zero-based index in at which copying begins. + The number of elements to copy. + Copies a range of elements from the to a compatible one-dimensional array, starting at the specified index of the target array. + + to copy the elements. + + The elements are copied to the in the same order in which the enumerator iterates through the . + + This method is an O(*n*) operation, where *n* is `count`. + + ]]> + + + is . + + is less than 0. + + -or- + + is less than 0. + + -or- + + is less than 0. + + is equal to or greater than the of the source . + + -or- + + The number of elements from to the end of the source is greater than the available space from to the end of the destination . + + + + + + + + + + Property + + P:System.Collections.Generic.ICollection`1.Count + P:System.Collections.Generic.IReadOnlyCollection`1.Count + P:System.Collections.ICollection.Count + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Int32 + + + Gets the number of elements contained in the . + The number of elements contained in the . + + is the number of elements that the can store before resizing is required. is the number of elements that are actually in the . + + is always greater than or equal to . If exceeds while adding elements, the capacity is increased by automatically reallocating the internal array before copying the old elements and adding the new elements. + Retrieving the value of this property is an O(1) operation. - -## Examples - The following example demonstrates how to check the capacity and count of a that contains a simple business object, and illustrates using the method to remove extra capacity. - +## Examples + + The following example demonstrates how to check the capacity and count of a that contains a simple business object, and illustrates using the method to remove extra capacity. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Capacity/program.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.capacitycount/vb/module1.vb" id="Snippet1"::: - - The following example shows the value of the property at various points in the life of a list. After the list has been created and populated and its elements displayed, the and properties are displayed. These properties are displayed again after the method has been called, and again after the contents of the list are cleared. + + The following example shows the value of the property at various points in the life of a list. After the list has been created and populated and its elements displayed, the and properties are displayed. These properties are displayed again after the method has been called, and again after the contents of the list are cleared. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Class/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/List`1_Class/fs/listclass.fs" id="Snippet1"::: - - ]]> - - - - - - - - - - - - Method - - System.Collections - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Int32 - - - - - - The minimum capacity to ensure. - Ensures that the capacity of this list is at least the specified . If the current capacity is less than , it is increased to at least the specified . - The new capacity of this list. - To be added. - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Boolean - - - - - - The delegate that defines the conditions of the elements to search for. - Determines whether the contains elements that match the conditions defined by the specified predicate. - - if the contains one or more elements that match the conditions defined by the specified predicate; otherwise, . - - 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, and processing is stopped when a match is found. - + + ]]> + + + + + + + + + + + + Method + + System.Collections + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Int32 + + + + + + The minimum capacity to ensure. + Ensures that the capacity of this list is at least the specified . If the current capacity is less than , it is increased to at least the specified . + The new capacity of this list. + To be added. + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Boolean + + + + + + The delegate that defines the conditions of the elements to search for. + Determines whether the contains elements that match the conditions defined by the specified predicate. + + if the contains one or more elements that match the conditions defined by the specified predicate; otherwise, . + + 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, and processing is stopped when a match is found. + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . - -## Examples - The following example demonstrates the and methods on a that contains a simple business object that implements . - + +## Examples + The following example demonstrates the and methods on a that contains a simple business object that implements . + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Contains/program1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.containsexists/vb/module1.vb" id="Snippet1"::: - - The following example demonstrates the method and several other methods that use the generic delegate. - - A of strings is created, containing 8 dinosaur names, two of which (at positions 1 and 5) end with "saurus". The example also defines a search predicate method named `EndsWithSaurus`, which accepts a string parameter and returns a Boolean value indicating whether the input string ends in "saurus". - - The , , and methods are used to search the list with the search predicate method, and then the method is used to remove all entries ending with "saurus". - - 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. - + + The following example demonstrates the method and several other methods that use the generic delegate. + + A of strings is created, containing 8 dinosaur names, two of which (at positions 1 and 5) end with "saurus". The example also defines a search predicate method named `EndsWithSaurus`, which accepts a string parameter and returns a Boolean value indicating whether the input string ends in "saurus". + + The , , and methods are used to search the list with the search predicate method, and then the method is used to remove all entries ending with "saurus". + + 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"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_FindEtAl/vb/source.vb" id="Snippet1"::: - - ]]> - - - is . - - - - - - - - - - - - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - T - - - - - - The delegate that defines the conditions of the element to search for. - Searches for an element that matches the conditions defined by the specified predicate, and returns the first occurrence within the entire . - The first element that matches the conditions defined by the specified predicate, if found; otherwise, the default value for type . - - 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. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_FindEtAl/vb/source.vb" id="Snippet1"::: + + ]]> + + + is . + + + + + + + + + + + + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + T + + + + + + The delegate that defines the conditions of the element to search for. + Searches for an element that matches the conditions defined by the specified predicate, and returns the first occurrence within the entire . + The first element that matches the conditions defined by the specified predicate, if found; otherwise, the default value for type . + + 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 . - -## Examples - The following example demonstrates the method on a that contains a simple complex object. - + +## Examples + The following example demonstrates the method on a that contains a simple complex object. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Contains/program1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.containsexists/vb/module1.vb" id="Snippet1"::: - - The following example demonstrates the find methods for the class. The example for the class contains `book` objects, of class `Book`, using the data from the [Sample XML File: Books (LINQ to XML)](/dotnet/standard/linq/sample-xml-file-books). The `FillList` method in the example uses [LINQ to XML](/dotnet/standard/linq/linq-xml-overview) to parse the values from the XML to property values of the `book` objects. - - The following table describes the examples provided for the find methods. - -|Method|Example| -|------------|-------------| -||Finds a book by an ID using the `IDToFind` predicate delegate.

C# example uses an anonymous delegate.| -||Find all books that whose `Genre` property is "Computer" using the `FindComputer` predicate delegate.| -||Finds the last book in the collection that has a publish date before 2001, using the `PubBefore2001` predicate delegate.

C# example uses an anonymous delegate.| -||Finds the index of first computer book using the `FindComputer` predicate delegate.| -||Finds the index of the last computer book using the `FindComputer` predicate delegate.| -||Finds the index of first computer book in the second half of the collection, using the `FindComputer` predicate delegate.| -||Finds the index of last computer book in the second half of the collection, using the `FindComputer` predicate delegate.| - + + The following example demonstrates the find methods for the class. The example for the class contains `book` objects, of class `Book`, using the data from the [Sample XML File: Books (LINQ to XML)](/dotnet/standard/linq/sample-xml-file-books). The `FillList` method in the example uses [LINQ to XML](/dotnet/standard/linq/linq-xml-overview) to parse the values from the XML to property values of the `book` objects. + + The following table describes the examples provided for the find methods. + +|Method|Example| +|------------|-------------| +||Finds a book by an ID using the `IDToFind` predicate delegate.

C# example uses an anonymous delegate.| +||Find all books that whose `Genre` property is "Computer" using the `FindComputer` predicate delegate.| +||Finds the last book in the collection that has a publish date before 2001, using the `PubBefore2001` predicate delegate.

C# example uses an anonymous delegate.| +||Finds the index of first computer book using the `FindComputer` predicate delegate.| +||Finds the index of the last computer book using the `FindComputer` predicate delegate.| +||Finds the index of first computer book in the second half of the collection, using the `FindComputer` predicate delegate.| +||Finds the index of last computer book in the second half of the collection, using the `FindComputer` predicate delegate.| + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Find/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/list`1_find_methods/vb/module1.vb" id="Snippet1"::: - - ]]> - - - is . - - - - - - - - - - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Collections.Generic.List<T> - - - - - - The delegate that defines the conditions of the elements to search for. - Retrieves all the elements that match the conditions defined by the specified predicate. - A containing all the elements that match the conditions defined by the specified predicate, if found; otherwise, an empty . - - 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, and the elements that match the conditions are saved in the returned . - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/list`1_find_methods/vb/module1.vb" id="Snippet1"::: + + ]]> + + + is . + + + + + + + + + + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Collections.Generic.List<T> + + + + + + The delegate that defines the conditions of the elements to search for. + Retrieves all the elements that match the conditions defined by the specified predicate. + A containing all the elements that match the conditions defined by the specified predicate, if found; otherwise, an empty . + + 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, and the elements that match the conditions are saved in the returned . + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . - -## Examples - The following example demonstrates the find methods for the class. The example for the class contains `book` objects, of class `Book`, using the data from the [Sample XML File: Books (LINQ to XML)](/dotnet/standard/linq/sample-xml-file-books). The `FillList` method in the example uses [LINQ to XML](/dotnet/standard/linq/linq-xml-overview) to parse the values from the XML to property values of the `book` objects. - - The following table describes the examples provided for the find methods. - -|Method|Example| -|------------|-------------| -||Finds a book by an ID using the `IDToFind` predicate delegate.

C# example uses an anonymous delegate.| -||Find all books that whose `Genre` property is "Computer" using the `FindComputer` predicate delegate.| -||Finds the last book in the collection that has a publish date before 2001, using the `PubBefore2001` predicate delegate.

C# example uses an anonymous delegate.| -||Finds the index of first computer book using the `FindComputer` predicate delegate.| -||Finds the index of the last computer book using the `FindComputer` predicate delegate.| -||Finds the index of first computer book in the second half of the collection, using the `FindComputer` predicate delegate.| -||Finds the index of last computer book in the second half of the collection, using the `FindComputer` predicate delegate.| - + +## Examples + The following example demonstrates the find methods for the class. The example for the class contains `book` objects, of class `Book`, using the data from the [Sample XML File: Books (LINQ to XML)](/dotnet/standard/linq/sample-xml-file-books). The `FillList` method in the example uses [LINQ to XML](/dotnet/standard/linq/linq-xml-overview) to parse the values from the XML to property values of the `book` objects. + + The following table describes the examples provided for the find methods. + +|Method|Example| +|------------|-------------| +||Finds a book by an ID using the `IDToFind` predicate delegate.

C# example uses an anonymous delegate.| +||Find all books that whose `Genre` property is "Computer" using the `FindComputer` predicate delegate.| +||Finds the last book in the collection that has a publish date before 2001, using the `PubBefore2001` predicate delegate.

C# example uses an anonymous delegate.| +||Finds the index of first computer book using the `FindComputer` predicate delegate.| +||Finds the index of the last computer book using the `FindComputer` predicate delegate.| +||Finds the index of first computer book in the second half of the collection, using the `FindComputer` predicate delegate.| +||Finds the index of last computer book in the second half of the collection, using the `FindComputer` predicate delegate.| + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Find/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/list`1_find_methods/vb/module1.vb" id="Snippet1"::: - - ]]> - - - is . - - - - - - - - - - - - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - - - Searches for an element that matches the conditions defined by a specified predicate, and returns the zero-based index of the first occurrence within the or a portion of it. This method returns -1 if an item that matches the conditions is not found. - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Int32 - - - - - - The delegate that defines the conditions of the element to search for. - Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the first occurrence within the entire . - The zero-based index of the first occurrence of an element that matches the conditions defined by , if found; otherwise, -1. - - is searched forward starting at the first element and ending at the last element. - - 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. The delegate has the signature: - -```csharp -public bool methodName(T obj) -``` - -```vb -Public Function methodName(obj As T) As Boolean -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/list`1_find_methods/vb/module1.vb" id="Snippet1"::: + + ]]> + + + is . + + + + + + + + + + + + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + + + Searches for an element that matches the conditions defined by a specified predicate, and returns the zero-based index of the first occurrence within the or a portion of it. This method returns -1 if an item that matches the conditions is not found. + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Int32 + + + + + + The delegate that defines the conditions of the element to search for. + Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the first occurrence within the entire . + The zero-based index of the first occurrence of an element that matches the conditions defined by , if found; otherwise, -1. + + is searched forward starting at the first element and ending at the last element. + + 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. The delegate has the signature: + +```csharp +public bool methodName(T obj) +``` + +```vb +Public Function methodName(obj As T) As Boolean +``` + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . - -## Examples - The following example defines an `Employee` class with two fields, `Name` and `Id`. It also defines an `EmployeeSearch` class with a single method, `StartsWith`, that indicates whether the `Employee.Name` field starts with a specified substring that is supplied to the `EmployeeSearch` class constructor. Note the signature of this method - -```csharp -public bool StartsWith(Employee e) -``` - -```vb -Public Function StartsWith(e As Employee) As Boolean -``` - - corresponds to the signature of the delegate that can be passed to the method. The example instantiates a `List` object, adds a number of `Employee` objects to it, and then calls the method twice to search the entire collection, the first time for the first `Employee` object whose `Name` field begins with "J", and the second time for the first `Employee` object whose `Name` field begins with "Ju". - + +## Examples + The following example defines an `Employee` class with two fields, `Name` and `Id`. It also defines an `EmployeeSearch` class with a single method, `StartsWith`, that indicates whether the `Employee.Name` field starts with a specified substring that is supplied to the `EmployeeSearch` class constructor. Note the signature of this method + +```csharp +public bool StartsWith(Employee e) +``` + +```vb +Public Function StartsWith(e As Employee) As Boolean +``` + + corresponds to the signature of the delegate that can be passed to the method. The example instantiates a `List` object, adds a number of `Employee` objects to it, and then calls the method twice to search the entire collection, the first time for the first `Employee` object whose `Name` field begins with "J", and the second time for the first `Employee` object whose `Name` field begins with "Ju". + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/FindIndex/FindIndex2.cs" interactive="try-dotnet" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.Collections.Generic.List.FindIndex/vb/FindIndex2.vb" id="Snippet2"::: - - ]]> - - - is . - - - - - - - - - - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Int32 - - - - - - - The zero-based starting index of the search. - The delegate that defines the conditions of the element to search for. - Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the first occurrence within the range of elements in the that extends from the specified index to the last element. - The zero-based index of the first occurrence of an element that matches the conditions defined by , if found; otherwise, -1. - - is searched forward starting at `startIndex` and ending at the last element. - - 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. The delegate has the signature: - -```csharp -public bool methodName(T obj) -``` - -```vb -Public Function methodName(obj As T) As Boolean -``` - + + ]]> + + + is . + + + + + + + + + + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Int32 + + + + + + + The zero-based starting index of the search. + The delegate that defines the conditions of the element to search for. + Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the first occurrence within the range of elements in the that extends from the specified index to the last element. + The zero-based index of the first occurrence of an element that matches the conditions defined by , if found; otherwise, -1. + + is searched forward starting at `startIndex` and ending at the last element. + + 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. The delegate has the signature: + +```csharp +public bool methodName(T obj) +``` + +```vb +Public Function methodName(obj As T) As Boolean +``` + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is the number of elements from `startIndex` to the end of the . - -## Examples - The following example defines an `Employee` class with two fields, `Name` and `Id`. It also defines an `EmployeeSearch` class with a single method, `StartsWith`, that indicates whether the `Employee.Name` field starts with a specified substring that is supplied to the `EmployeeSearch` class constructor. Note the signature of this method - -```csharp -public bool StartsWith(Employee e) -``` - -```vb -Public Function StartsWith(e As Employee) As Boolean -``` - - corresponds to the signature of the delegate that can be passed to the method. The example instantiates a `List` object, adds a number of `Employee` objects to it, and then calls the method twice to search the collection starting with its fifth member (that is, the member at index 4). The first time, it searches for the first `Employee` object whose `Name` field begins with "J"; the second time, it searches for the first `Employee` object whose `Name` field begins with "Ju". - + +## Examples + The following example defines an `Employee` class with two fields, `Name` and `Id`. It also defines an `EmployeeSearch` class with a single method, `StartsWith`, that indicates whether the `Employee.Name` field starts with a specified substring that is supplied to the `EmployeeSearch` class constructor. Note the signature of this method + +```csharp +public bool StartsWith(Employee e) +``` + +```vb +Public Function StartsWith(e As Employee) As Boolean +``` + + corresponds to the signature of the delegate that can be passed to the method. The example instantiates a `List` object, adds a number of `Employee` objects to it, and then calls the method twice to search the collection starting with its fifth member (that is, the member at index 4). The first time, it searches for the first `Employee` object whose `Name` field begins with "J"; the second time, it searches for the first `Employee` object whose `Name` field begins with "Ju". + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/FindIndex/FindIndex3.cs" interactive="try-dotnet" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.Collections.Generic.List.FindIndex/vb/FindIndex3.vb" id="Snippet3"::: - - ]]> - - - is . - - is outside the range of valid indexes for the . - - - - - - - - - - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Int32 - - - - - - - - The zero-based starting index of the search. - The number of elements in the section to search. - The delegate that defines the conditions of the element to search for. - Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the first occurrence within the range of elements in the that starts at the specified index and contains the specified number of elements. - The zero-based index of the first occurrence of an element that matches the conditions defined by , if found; otherwise, -1. - - is searched forward starting at `startIndex` and ending at `startIndex` plus `count` minus 1, if `count` is greater than 0. - - 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. The delegate has the signature: - -```csharp -public bool methodName(T obj) -``` - -```vb -Public Function methodName(obj As T) As Boolean -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.Collections.Generic.List.FindIndex/vb/FindIndex3.vb" id="Snippet3"::: + + ]]> + + + is . + + is outside the range of valid indexes for the . + + + + + + + + + + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Int32 + + + + + + + + The zero-based starting index of the search. + The number of elements in the section to search. + The delegate that defines the conditions of the element to search for. + Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the first occurrence within the range of elements in the that starts at the specified index and contains the specified number of elements. + The zero-based index of the first occurrence of an element that matches the conditions defined by , if found; otherwise, -1. + + is searched forward starting at `startIndex` and ending at `startIndex` plus `count` minus 1, if `count` is greater than 0. + + 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. The delegate has the signature: + +```csharp +public bool methodName(T obj) +``` + +```vb +Public Function methodName(obj As T) As Boolean +``` + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is `count`. - -## Examples - The following example defines an `Employee` class with two fields, `Name` and `Id`. It also defines an `EmployeeSearch` class with a single method, `StartsWith`, that indicates whether the `Employee.Name` field starts with a specified substring that is supplied to the `EmployeeSearch` class constructor. Note the signature of this method - -```csharp -public bool StartsWith(Employee e) -``` - -```vb -Public Function StartsWith(e As Employee) As Boolean -``` - - corresponds to the signature of the delegate that can be passed to the method. The example instantiates a `List` object, adds a number of `Employee` objects to it, and then calls the method twice to search the entire collection (that is, the members from index 0 to index - 1). The first time, it searches for the first `Employee` object whose `Name` field begins with "J"; the second time, it searches for the first `Employee` object whose `Name` field begins with "Ju". - + +## Examples + The following example defines an `Employee` class with two fields, `Name` and `Id`. It also defines an `EmployeeSearch` class with a single method, `StartsWith`, that indicates whether the `Employee.Name` field starts with a specified substring that is supplied to the `EmployeeSearch` class constructor. Note the signature of this method + +```csharp +public bool StartsWith(Employee e) +``` + +```vb +Public Function StartsWith(e As Employee) As Boolean +``` + + corresponds to the signature of the delegate that can be passed to the method. The example instantiates a `List` object, adds a number of `Employee` objects to it, and then calls the method twice to search the entire collection (that is, the members from index 0 to index - 1). The first time, it searches for the first `Employee` object whose `Name` field begins with "J"; the second time, it searches for the first `Employee` object whose `Name` field begins with "Ju". + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/FindIndex/FindIndex1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.Collections.Generic.List.FindIndex/vb/FindIndex1.vb" id="Snippet1"::: - - ]]> - - - is . - - is outside the range of valid indexes for the . - - -or- - - is less than 0. - - -or- - - and do not specify a valid section in the . - - - - - - - - - - - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - T - - - - - - The delegate that defines the conditions of the element to search for. - Searches for an element that matches the conditions defined by the specified predicate, and returns the last occurrence within the entire . - The last element that matches the conditions defined by the specified predicate, if found; otherwise, the default value for type . - - 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. - + + ]]> + + + is . + + is outside the range of valid indexes for the . + + -or- + + is less than 0. + + -or- + + and do not specify a valid section in the . + + + + + + + + + + + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + T + + + + + + The delegate that defines the conditions of the element to search for. + Searches for an element that matches the conditions defined by the specified predicate, and returns the last occurrence within the entire . + The last element that matches the conditions defined by the specified predicate, if found; otherwise, the default value for type . + + 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 . - -## Examples - The following example demonstrates the find methods for the class. The example for the class contains `book` objects, of class `Book`, using the data from the [Sample XML File: Books (LINQ to XML)](/dotnet/standard/linq/sample-xml-file-books). The `FillList` method in the example uses [LINQ to XML](/dotnet/standard/linq/linq-xml-overview) to parse the values from the XML to property values of the `book` objects. - - The following table describes the examples provided for the find methods. - -|Method|Example| -|------------|-------------| -||Finds a book by an ID using the `IDToFind` predicate delegate.

C# example uses an anonymous delegate.| -||Find all books that whose `Genre` property is "Computer" using the `FindComputer` predicate delegate.| -||Finds the last book in the collection that has a publish date before 2001, using the `PubBefore2001` predicate delegate.

C# example uses an anonymous delegate.| -||Finds the index of first computer book using the `FindComputer` predicate delegate.| -||Finds the index of the last computer book using the `FindComputer` predicate delegate.| -||Finds the index of first computer book in the second half of the collection, using the `FindComputer` predicate delegate.| -||Finds the index of last computer book in the second half of the collection, using the `FindComputer` predicate delegate.| - + +## Examples + The following example demonstrates the find methods for the class. The example for the class contains `book` objects, of class `Book`, using the data from the [Sample XML File: Books (LINQ to XML)](/dotnet/standard/linq/sample-xml-file-books). The `FillList` method in the example uses [LINQ to XML](/dotnet/standard/linq/linq-xml-overview) to parse the values from the XML to property values of the `book` objects. + + The following table describes the examples provided for the find methods. + +|Method|Example| +|------------|-------------| +||Finds a book by an ID using the `IDToFind` predicate delegate.

C# example uses an anonymous delegate.| +||Find all books that whose `Genre` property is "Computer" using the `FindComputer` predicate delegate.| +||Finds the last book in the collection that has a publish date before 2001, using the `PubBefore2001` predicate delegate.

C# example uses an anonymous delegate.| +||Finds the index of first computer book using the `FindComputer` predicate delegate.| +||Finds the index of the last computer book using the `FindComputer` predicate delegate.| +||Finds the index of first computer book in the second half of the collection, using the `FindComputer` predicate delegate.| +||Finds the index of last computer book in the second half of the collection, using the `FindComputer` predicate delegate.| + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Find/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/list`1_find_methods/vb/module1.vb" id="Snippet1"::: - - ]]> - - - is . - - - - - - - - - - - - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - - - Searches for an element that matches the conditions defined by a specified predicate, and returns the zero-based index of the last occurrence within the or a portion of it. - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Int32 - - - - - - The delegate that defines the conditions of the element to search for. - Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the last occurrence within the entire . - The zero-based index of the last occurrence of an element that matches the conditions defined by , if found; otherwise, -1. - - is searched backward starting at the last element and ending at the first element. - - 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. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/list`1_find_methods/vb/module1.vb" id="Snippet1"::: + + ]]> + + + is . + + + + + + + + + + + + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + + + Searches for an element that matches the conditions defined by a specified predicate, and returns the zero-based index of the last occurrence within the or a portion of it. + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Int32 + + + + + + The delegate that defines the conditions of the element to search for. + Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the last occurrence within the entire . + The zero-based index of the last occurrence of an element that matches the conditions defined by , if found; otherwise, -1. + + is searched backward starting at the last element and ending at the first element. + + 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. + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . - -## Examples - The following example demonstrates the find methods for the class. The example for the class contains `book` objects, of class `Book`, using the data from the [Sample XML File: Books (LINQ to XML)](/dotnet/standard/linq/sample-xml-file-books). The `FillList` method in the example uses [LINQ to XML](/dotnet/standard/linq/linq-xml-overview) to parse the values from the XML to property values of the `book` objects. - - The following table describes the examples provided for the find methods. - -|Method|Example| -|------------|-------------| -||Finds a book by an ID using the `IDToFind` predicate delegate.

C# example uses an anonymous delegate.| -||Find all books that whose `Genre` property is "Computer" using the `FindComputer` predicate delegate.| -||Finds the last book in the collection that has a publish date before 2001, using the `PubBefore2001` predicate delegate.

C# example uses an anonymous delegate.| -||Finds the index of first computer book using the `FindComputer` predicate delegate.| -||Finds the index of the last computer book using the `FindComputer` predicate delegate.| -||Finds the index of first computer book in the second half of the collection, using the `FindComputer` predicate delegate.| -||Finds the index of last computer book in the second half of the collection, using the `FindComputer` predicate delegate.| - + +## Examples + The following example demonstrates the find methods for the class. The example for the class contains `book` objects, of class `Book`, using the data from the [Sample XML File: Books (LINQ to XML)](/dotnet/standard/linq/sample-xml-file-books). The `FillList` method in the example uses [LINQ to XML](/dotnet/standard/linq/linq-xml-overview) to parse the values from the XML to property values of the `book` objects. + + The following table describes the examples provided for the find methods. + +|Method|Example| +|------------|-------------| +||Finds a book by an ID using the `IDToFind` predicate delegate.

C# example uses an anonymous delegate.| +||Find all books that whose `Genre` property is "Computer" using the `FindComputer` predicate delegate.| +||Finds the last book in the collection that has a publish date before 2001, using the `PubBefore2001` predicate delegate.

C# example uses an anonymous delegate.| +||Finds the index of first computer book using the `FindComputer` predicate delegate.| +||Finds the index of the last computer book using the `FindComputer` predicate delegate.| +||Finds the index of first computer book in the second half of the collection, using the `FindComputer` predicate delegate.| +||Finds the index of last computer book in the second half of the collection, using the `FindComputer` predicate delegate.| + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Find/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/list`1_find_methods/vb/module1.vb" id="Snippet1"::: - - ]]> - - - is . - - - - - - - - - - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Int32 - - - - - - - The zero-based starting index of the backward search. - The delegate that defines the conditions of the element to search for. - Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the last occurrence within the range of elements in the that extends from the first element to the specified index. - The zero-based index of the last occurrence of an element that matches the conditions defined by , if found; otherwise, -1. - - is searched backward starting at `startIndex` and ending at the first element. - - 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. - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is the number of elements from the beginning of the to `startIndex`. - - ]]> - - - is . - - is outside the range of valid indexes for the . - - - - - - - - - - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Int32 - - - - - - - - The zero-based starting index of the backward search. - The number of elements in the section to search. - The delegate that defines the conditions of the element to search for. - Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the last occurrence within the range of elements in the that contains the specified number of elements and ends at the specified index. - The zero-based index of the last occurrence of an element that matches the conditions defined by , if found; otherwise, -1. - - is searched backward starting at `startIndex` and ending at `startIndex` minus `count` plus 1, if `count` is greater than 0. - - 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. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/list`1_find_methods/vb/module1.vb" id="Snippet1"::: + + ]]> + + + is . + + + + + + + + + + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Int32 + + + + + + + The zero-based starting index of the backward search. + The delegate that defines the conditions of the element to search for. + Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the last occurrence within the range of elements in the that extends from the first element to the specified index. + The zero-based index of the last occurrence of an element that matches the conditions defined by , if found; otherwise, -1. + + is searched backward starting at `startIndex` and ending at the first element. + + 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. + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is the number of elements from the beginning of the to `startIndex`. + + ]]> + + + is . + + is outside the range of valid indexes for the . + + + + + + + + + + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Int32 + + + + + + + + The zero-based starting index of the backward search. + The number of elements in the section to search. + The delegate that defines the conditions of the element to search for. + Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the last occurrence within the range of elements in the that contains the specified number of elements and ends at the specified index. + The zero-based index of the last occurrence of an element that matches the conditions defined by , if found; otherwise, -1. + + is searched backward starting at `startIndex` and ending at `startIndex` minus `count` plus 1, if `count` is greater than 0. + + 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. + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is `count`. - -## Examples - The following example demonstrates the find methods for the class. The example for the class contains `book` objects, of class `Book`, using the data from the [Sample XML File: Books (LINQ to XML)](/dotnet/standard/linq/sample-xml-file-books). The `FillList` method in the example uses [LINQ to XML](/dotnet/standard/linq/linq-xml-overview) to parse the values from the XML to property values of the `book` objects. - - The following table describes the examples provided for the find methods. - -|Method|Example| -|------------|-------------| -||Finds a book by an ID using the `IDToFind` predicate delegate.

C# example uses an anonymous delegate.| -||Find all books that whose `Genre` property is "Computer" using the `FindComputer` predicate delegate.| -||Finds the last book in the collection that has a publish date before 2001, using the `PubBefore2001` predicate delegate.

C# example uses an anonymous delegate.| -||Finds the index of first computer book using the `FindComputer` predicate delegate.| -||Finds the index of the last computer book using the `FindComputer` predicate delegate.| -||Finds the index of first computer book in the second half of the collection, using the `FindComputer` predicate delegate.| -||Finds the index of last computer book in the second half of the collection, using the `FindComputer` predicate delegate.| - + +## Examples + The following example demonstrates the find methods for the class. The example for the class contains `book` objects, of class `Book`, using the data from the [Sample XML File: Books (LINQ to XML)](/dotnet/standard/linq/sample-xml-file-books). The `FillList` method in the example uses [LINQ to XML](/dotnet/standard/linq/linq-xml-overview) to parse the values from the XML to property values of the `book` objects. + + The following table describes the examples provided for the find methods. + +|Method|Example| +|------------|-------------| +||Finds a book by an ID using the `IDToFind` predicate delegate.

C# example uses an anonymous delegate.| +||Find all books that whose `Genre` property is "Computer" using the `FindComputer` predicate delegate.| +||Finds the last book in the collection that has a publish date before 2001, using the `PubBefore2001` predicate delegate.

C# example uses an anonymous delegate.| +||Finds the index of first computer book using the `FindComputer` predicate delegate.| +||Finds the index of the last computer book using the `FindComputer` predicate delegate.| +||Finds the index of first computer book in the second half of the collection, using the `FindComputer` predicate delegate.| +||Finds the index of last computer book in the second half of the collection, using the `FindComputer` predicate delegate.| + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Find/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/list`1_find_methods/vb/module1.vb" id="Snippet1"::: - - ]]> - - - is . - - is outside the range of valid indexes for the . - - -or- - - is less than 0. - - -or- - - and do not specify a valid section in the . - - - - - - - - - - - - - - - - - - - Method - - System.Collections - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Void - - - - - - The delegate to perform on each element of the . - Performs the specified action on each element of the . - - is a delegate to a method that performs an action on the object passed to it. The elements of the current are individually passed to the delegate. - - This method is an O(*n*) operation, where *n* is . - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/list`1_find_methods/vb/module1.vb" id="Snippet1"::: + + ]]> + + + is . + + is outside the range of valid indexes for the . + + -or- + + is less than 0. + + -or- + + and do not specify a valid section in the . + + + + + + + + + + + + + + + + + + + Method + + System.Collections + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Void + + + + + + The delegate to perform on each element of the . + Performs the specified action on each element of the . + + is a delegate to a method that performs an action on the object passed to it. The elements of the current are individually passed to the delegate. + + This method is an O(*n*) operation, where *n* is . + Modifying the underlying collection in the body of the delegate is not supported and causes undefined behavior. - -## Examples - 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. - + +## Examples + 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"::: - - ]]> - - - is . - An element in the collection has been modified. - - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Collections.Generic.List<T>+Enumerator - - - - Returns an enumerator that iterates through the . - A for the . - - 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 . - - 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. - - This method is an O(1) operation. - - ]]> - - - - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Collections.Generic.List<T> - - - - - - - The zero-based index at which the range starts. - The number of elements in the range. - Creates a shallow copy of a range of elements in the source . - A shallow copy of a range of elements in the source . - - + + + is . + An element in the collection has been modified. + + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Collections.Generic.List<T>+Enumerator + + + + Returns an enumerator that iterates through the . + A for the . + + 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 . + + 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. + + This method is an O(1) operation. + + ]]> + + + + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Collections.Generic.List<T> + + + + + + + The zero-based index at which the range starts. + The number of elements in the range. + Creates a shallow copy of a range of elements in the source . + A shallow copy of a range of elements in the source . + + method and other methods of the class that act on ranges. At the end of the example, the method is used to get three items from the list, beginning with index location 2. The method is called on the resulting , creating an array of three elements. The elements of the array are displayed. - + +## Examples + The following example demonstrates the method and other methods of the class that act on ranges. At the end of the example, the method is used to get three items from the list, beginning with index location 2. The method is called on the resulting , creating an array of three elements. The elements of the array are displayed. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Ranges/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/.ctor/source1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Ranges/vb/source.vb" id="Snippet1"::: - - ]]> - - - is less than 0. - - -or- - - is less than 0. - - and do not denote a valid range of elements in the . - - - - - - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - - - Returns the zero-based index of the first occurrence of a value in the or in a portion of it. - - method. A of strings is created, with one entry that appears twice, at index location 0 and index location 5. The method overload searches the list from the beginning, and finds the first occurrence of the string. The method overload is used to search the list beginning with index location 3 and continuing to the end of the list, and finds the second occurrence of the string. Finally, the method overload is used to search a range of two entries, beginning at index location two; it returns -1 because there are no instances of the search string in that range. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Ranges/vb/source.vb" id="Snippet1"::: + + ]]> + + + is less than 0. + + -or- + + is less than 0. + + and do not denote a valid range of elements in the . + + + + + + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + + + Returns the zero-based index of the first occurrence of a value in the or in a portion of it. + + method. A of strings is created, with one entry that appears twice, at index location 0 and index location 5. The method overload searches the list from the beginning, and finds the first occurrence of the string. The method overload is used to search the list beginning with index location 3 and continuing to the end of the list, and finds the second occurrence of the string. Finally, the method overload is used to search a range of two entries, beginning at index location two; it returns -1 because there are no instances of the search string in that range. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_IndexOf/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/IndexOf/source.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_IndexOf/vb/source.vb" id="Snippet1"::: - - ]]> - - - - - - - - - - - Method - - M:System.Collections.Generic.IList`1.IndexOf(`0) - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Int32 - - - - - - The object to locate in the . The value can be for reference types. - Searches for the specified object and returns the zero-based index of the first occurrence within the entire . - The zero-based index of the first occurrence of within the entire , if found; otherwise, -1. - - is searched forward starting at the first element and ending at the last element. - - This method determines equality using the default equality comparer for `T`, the type of values in the list. - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . - - ]]> - - - - Performing Culture-Insensitive String Operations in Collections - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Int32 - - - - - - - The object to locate in the . The value can be for reference types. - The zero-based starting index of the search. 0 (zero) is valid in an empty list. - Searches for the specified object and returns the zero-based index of the first occurrence within the range of elements in the that extends from the specified index to the last element. - The zero-based index of the first occurrence of within the range of elements in the that extends from to the last element, if found; otherwise, -1. - - is searched forward starting at `index` and ending at the last element. - - This method determines equality using the default equality comparer for `T`, the type of values in the list. - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is the number of elements from `index` to the end of the . - - ]]> - - - is outside the range of valid indexes for the . - - - Performing Culture-Insensitive String Operations in Collections - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Int32 - - - - - - - - The object to locate in the . The value can be for reference types. - The zero-based starting index of the search. 0 (zero) is valid in an empty list. - The number of elements in the section to search. - Searches for the specified object and returns the zero-based index of the first occurrence within the range of elements in the that starts at the specified index and contains the specified number of elements. - The zero-based index of the first occurrence of within the range of elements in the that starts at and contains number of elements, if found; otherwise, -1. - - is searched forward starting at `index` and ending at `index` plus `count` minus 1, if `count` is greater than 0. - - This method determines equality using the default equality comparer for `T`, the type of values in the list. - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is `count`. - - ]]> - - - is outside the range of valid indexes for the . - - -or- - - is less than 0. - - -or- - - and do not specify a valid section in the . - - - Performing Culture-Insensitive String Operations in Collections - - - - - - - - - - Method - - M:System.Collections.Generic.IList`1.Insert(System.Int32,`0) - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Void - - - - - - - The zero-based index at which should be inserted. - The object to insert. The value can be for reference types. - Inserts an element into the at the specified index. - - accepts `null` as a valid value for reference types and allows duplicate elements. - - If already equals , the capacity of the is increased by automatically reallocating the internal array, and the existing elements are copied to the new array before the new element is added. - - If `index` is equal to , `item` is added to the end of . - + + ]]> + + + + + + + + + + + Method + + M:System.Collections.Generic.IList`1.IndexOf(`0) + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Int32 + + + + + + The object to locate in the . The value can be for reference types. + Searches for the specified object and returns the zero-based index of the first occurrence within the entire . + The zero-based index of the first occurrence of within the entire , if found; otherwise, -1. + + is searched forward starting at the first element and ending at the last element. + + This method determines equality using the default equality comparer for `T`, the type of values in the list. + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . + + ]]> + + + + Performing Culture-Insensitive String Operations in Collections + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Int32 + + + + + + + The object to locate in the . The value can be for reference types. + The zero-based starting index of the search. 0 (zero) is valid in an empty list. + Searches for the specified object and returns the zero-based index of the first occurrence within the range of elements in the that extends from the specified index to the last element. + The zero-based index of the first occurrence of within the range of elements in the that extends from to the last element, if found; otherwise, -1. + + is searched forward starting at `index` and ending at the last element. + + This method determines equality using the default equality comparer for `T`, the type of values in the list. + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is the number of elements from `index` to the end of the . + + ]]> + + + is outside the range of valid indexes for the . + + + Performing Culture-Insensitive String Operations in Collections + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Int32 + + + + + + + + The object to locate in the . The value can be for reference types. + The zero-based starting index of the search. 0 (zero) is valid in an empty list. + The number of elements in the section to search. + Searches for the specified object and returns the zero-based index of the first occurrence within the range of elements in the that starts at the specified index and contains the specified number of elements. + The zero-based index of the first occurrence of within the range of elements in the that starts at and contains number of elements, if found; otherwise, -1. + + is searched forward starting at `index` and ending at `index` plus `count` minus 1, if `count` is greater than 0. + + This method determines equality using the default equality comparer for `T`, the type of values in the list. + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is `count`. + + ]]> + + + is outside the range of valid indexes for the . + + -or- + + is less than 0. + + -or- + + and do not specify a valid section in the . + + + Performing Culture-Insensitive String Operations in Collections + + + + + + + + + + Method + + M:System.Collections.Generic.IList`1.Insert(System.Int32,`0) + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Void + + + + + + + The zero-based index at which should be inserted. + The object to insert. The value can be for reference types. + Inserts an element into the at the specified index. + + accepts `null` as a valid value for reference types and allows duplicate elements. + + If already equals , the capacity of the is increased by automatically reallocating the internal array, and the existing elements are copied to the new array before the new element is added. + + If `index` is equal to , `item` is added to the end of . + This method is an O(*n*) operation, where *n* is . - -## Examples - The following example demonstrates how to add, remove, and insert a simple business object in a . - +## Examples + + The following example demonstrates how to add, remove, and insert a simple business object in a . + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/program.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.addremoveinsert/vb/module1.vb" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.collections.generic.list.addremoveinsert/fs/addremoveinsert.fs" id="Snippet1"::: - - The following example demonstrates the method, along with various other properties and methods of the generic class. After the list is created, elements are added. The method is used to insert an item into the middle of the list. The item inserted is a duplicate, which is later removed using the method. - + + The following example demonstrates the method, along with various other properties and methods of the generic class. After the list is created, elements are added. The method is used to insert an item into the middle of the list. The item inserted is a duplicate, which is later removed using the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Class/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/List`1_Class/fs/listclass.fs" id="Snippet1"::: - - ]]> - - - is less than 0. - - -or- - - is greater than . - - - - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Void - - - - - - - The zero-based index at which the new elements should be inserted. - The collection whose elements should be inserted into the . The collection itself cannot be , but it can contain elements that are , if type is a reference type. - Inserts the elements of a collection into the at the specified index. - - accepts `null` as a valid value for reference types and allows duplicate elements. - - If the new (the current plus the size of the collection) will be greater than , the capacity of the is increased by automatically reallocating the internal array to accommodate the new elements, and the existing elements are copied to the new array before the new elements are added. - - If `index` is equal to , the elements are added to the end of . - - The order of the elements in the collection is preserved in the . - + + ]]> + + + is less than 0. + + -or- + + is greater than . + + + + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Void + + + + + + + The zero-based index at which the new elements should be inserted. + The collection whose elements should be inserted into the . The collection itself cannot be , but it can contain elements that are , if type is a reference type. + Inserts the elements of a collection into the at the specified index. + + accepts `null` as a valid value for reference types and allows duplicate elements. + + If the new (the current plus the size of the collection) will be greater than , the capacity of the is increased by automatically reallocating the internal array to accommodate the new elements, and the existing elements are copied to the new array before the new elements are added. + + If `index` is equal to , the elements are added to the end of . + + The order of the elements in the collection is preserved in the . + This method is an O(*n* * *m*) operation, where *n* is the number of elements to be added and *m* is . - -## Examples - The following example demonstrates method and various other methods of the class that act on ranges. After the list has been created and populated with the names of several peaceful plant-eating dinosaurs, the method is used to insert an array of three ferocious meat-eating dinosaurs into the list, beginning at index location 3. - + +## Examples + The following example demonstrates method and various other methods of the class that act on ranges. After the list has been created and populated with the names of several peaceful plant-eating dinosaurs, the method is used to insert an array of three ferocious meat-eating dinosaurs into the list, beginning at index location 3. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Ranges/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/.ctor/source1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Ranges/vb/source.vb" id="Snippet1"::: - - ]]> - - - is . - - is less than 0. - - -or- - - is greater than . - - - - - - - - - - - - - - Property - - P:System.Collections.Generic.IList`1.Item(System.Int32) - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - [set: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<set: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - T - - - - - - The zero-based index of the element to get or set. - Gets or sets the element at the specified index. - The element at the specified index. - - accepts `null` as a valid value for reference types and allows duplicate elements. - - This property provides the ability to access a specific element in the collection by using the following syntax: `myCollection[index]`. - + + ]]> + + + is . + + is less than 0. + + -or- + + is greater than . + + + + + + + + + + + + + + Property + + P:System.Collections.Generic.IList`1.Item(System.Int32) + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + [set: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<set: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + T + + + + + + The zero-based index of the element to get or set. + Gets or sets the element at the specified index. + The element at the specified index. + + accepts `null` as a valid value for reference types and allows duplicate elements. + + This property provides the ability to access a specific element in the collection by using the following syntax: `myCollection[index]`. + Retrieving the value of this property is an O(1) operation; setting the property is also an O(1) operation. - -## Examples - The example in this section demonstrates the 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 .) - + +## Examples + The example in this section demonstrates the 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. - - 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. - +> 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. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet3"::: - - ]]> - - - is less than 0. - - -or- - - is equal to or greater than . - - - - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - - - Returns the zero-based index of the last occurrence of a value in the or in a portion of it. - - method. A of strings is created, with one entry that appears twice, at index location 0 and index location 5. The method overload searches the entire list from the end, and finds the second occurrence of the string. The method overload is used to search the list backward beginning with index location 3 and continuing to the beginning of the list, so it finds the first occurrence of the string in the list. Finally, the method overload is used to search a range of four entries, beginning at index location 4 and extending backward (that is, it searches the items at locations 4, 3, 2, and 1); this search returns -1 because there are no instances of the search string in that range. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet3"::: + + ]]> + + + is less than 0. + + -or- + + is equal to or greater than . + + + + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + + + Returns the zero-based index of the last occurrence of a value in the or in a portion of it. + + method. A of strings is created, with one entry that appears twice, at index location 0 and index location 5. The method overload searches the entire list from the end, and finds the second occurrence of the string. The method overload is used to search the list backward beginning with index location 3 and continuing to the beginning of the list, so it finds the first occurrence of the string in the list. Finally, the method overload is used to search a range of four entries, beginning at index location 4 and extending backward (that is, it searches the items at locations 4, 3, 2, and 1); this search returns -1 because there are no instances of the search string in that range. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_LastIndexOf/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/LastIndexOf/source.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_LastIndexOf/vb/source.vb" id="Snippet1"::: - - ]]> - - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Int32 - - - - - - The object to locate in the . The value can be for reference types. - Searches for the specified object and returns the zero-based index of the last occurrence within the entire . - The zero-based index of the last occurrence of within the entire the , if found; otherwise, -1. - - is searched backward starting at the last element and ending at the first element. - - This method determines equality using the default equality comparer for `T`, the type of values in the list. - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . - - ]]> - - - - Performing Culture-Insensitive String Operations in Collections - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Int32 - - - - - - - The object to locate in the . The value can be for reference types. - The zero-based starting index of the backward search. - Searches for the specified object and returns the zero-based index of the last occurrence within the range of elements in the that extends from the first element to the specified index. - The zero-based index of the last occurrence of within the range of elements in the that extends from the first element to , if found; otherwise, -1. - - is searched backward starting at `index` and ending at the first element. - - This method determines equality using the default equality comparer for `T`, the type of values in the list. - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is the number of elements from the beginning of the to `index`. - - ]]> - - - is outside the range of valid indexes for the . - - - Performing Culture-Insensitive String Operations in Collections - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Int32 - - - - - - - - The object to locate in the . The value can be for reference types. - The zero-based starting index of the backward search. - The number of elements in the section to search. - Searches for the specified object and returns the zero-based index of the last occurrence within the range of elements in the that contains the specified number of elements and ends at the specified index. - The zero-based index of the last occurrence of within the range of elements in the that contains number of elements and ends at , if found; otherwise, -1. - - is searched backward starting at `index` and ending at `index` minus `count` plus 1, if `count` is greater than 0. - - This method determines equality using the default equality comparer for `T`, the type of values in the list. - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is `count`. - - ]]> - - - is outside the range of valid indexes for the . - - -or- - - is less than 0. - - -or- - - and do not specify a valid section in the . - - - Performing Culture-Insensitive String Operations in Collections - - - - - - - - - - Method - - M:System.Collections.Generic.ICollection`1.Remove(`0) - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Boolean - - - - - - The object to remove from the . The value can be for reference types. - Removes the first occurrence of a specific object from the . - - if is successfully removed; otherwise, . This method also returns if was not found in the . - - generic interface, the equality comparer is the method of that interface; otherwise, the default equality comparer is . - + + ]]> + + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Int32 + + + + + + The object to locate in the . The value can be for reference types. + Searches for the specified object and returns the zero-based index of the last occurrence within the entire . + The zero-based index of the last occurrence of within the entire the , if found; otherwise, -1. + + is searched backward starting at the last element and ending at the first element. + + This method determines equality using the default equality comparer for `T`, the type of values in the list. + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . + + ]]> + + + + Performing Culture-Insensitive String Operations in Collections + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Int32 + + + + + + + The object to locate in the . The value can be for reference types. + The zero-based starting index of the backward search. + Searches for the specified object and returns the zero-based index of the last occurrence within the range of elements in the that extends from the first element to the specified index. + The zero-based index of the last occurrence of within the range of elements in the that extends from the first element to , if found; otherwise, -1. + + is searched backward starting at `index` and ending at the first element. + + This method determines equality using the default equality comparer for `T`, the type of values in the list. + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is the number of elements from the beginning of the to `index`. + + ]]> + + + is outside the range of valid indexes for the . + + + Performing Culture-Insensitive String Operations in Collections + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Int32 + + + + + + + + The object to locate in the . The value can be for reference types. + The zero-based starting index of the backward search. + The number of elements in the section to search. + Searches for the specified object and returns the zero-based index of the last occurrence within the range of elements in the that contains the specified number of elements and ends at the specified index. + The zero-based index of the last occurrence of within the range of elements in the that contains number of elements and ends at , if found; otherwise, -1. + + is searched backward starting at `index` and ending at `index` minus `count` plus 1, if `count` is greater than 0. + + This method determines equality using the default equality comparer for `T`, the type of values in the list. + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is `count`. + + ]]> + + + is outside the range of valid indexes for the . + + -or- + + is less than 0. + + -or- + + and do not specify a valid section in the . + + + Performing Culture-Insensitive String Operations in Collections + + + + + + + + + + Method + + M:System.Collections.Generic.ICollection`1.Remove(`0) + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Boolean + + + + + + The object to remove from the . The value can be for reference types. + Removes the first occurrence of a specific object from the . + + if is successfully removed; otherwise, . This method also returns if was not found in the . + + generic interface, the equality comparer is the method of that interface; otherwise, the default equality comparer is . + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . - -## Examples - The following example demonstrates how to add, remove, and insert a simple business object in a . - +## Examples + + The following example demonstrates how to add, remove, and insert a simple business object in a . + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/program.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.addremoveinsert/vb/module1.vb" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.collections.generic.list.addremoveinsert/fs/addremoveinsert.fs" id="Snippet1"::: - - The following example demonstrates method. Several properties and methods of the generic class are used to add, insert, and search the list. After these operations, the list contains a duplicate. The method is used to remove the first instance of the duplicate item, and the contents are displayed. The method always removes the first instance it encounters. - + + The following example demonstrates method. Several properties and methods of the generic class are used to add, insert, and search the list. After these operations, the list contains a duplicate. The method is used to remove the first instance of the duplicate item, and the contents are displayed. The method always removes the first instance it encounters. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Class/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/List`1_Class/fs/listclass.fs" id="Snippet1"::: - - ]]> - - - - - - Performing Culture-Insensitive String Operations in Collections - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Int32 - - - - - - The delegate that defines the conditions of the elements to remove. - Removes all the elements that match the conditions defined by the specified predicate. - The number of elements removed from 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, and the elements that match the conditions are removed from the . - + + ]]> + + + + + + Performing Culture-Insensitive String Operations in Collections + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Int32 + + + + + + The delegate that defines the conditions of the elements to remove. + Removes all the elements that match the conditions defined by the specified predicate. + The number of elements removed from 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, and the elements that match the conditions are removed from the . + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . - -## Examples - The following example demonstrates the method and several other methods that use the generic delegate. - - A of strings is created, containing 8 dinosaur names, two of which (at positions 1 and 5) end with "saurus". The example also defines a search predicate method named `EndsWithSaurus`, which accepts a string parameter and returns a Boolean value indicating whether the input string ends in "saurus". - - The , , and methods are used to search the list with the search predicate method. - - 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`. - + +## Examples + The following example demonstrates the method and several other methods that use the generic delegate. + + A of strings is created, containing 8 dinosaur names, two of which (at positions 1 and 5) end with "saurus". The example also defines a search predicate method named `EndsWithSaurus`, which accepts a string parameter and returns a Boolean value indicating whether the input string ends in "saurus". + + The , , and methods are used to search the list with the search predicate method. + + 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. - - Finally, the method verifies that there are no strings in the list that end with "saurus". - +> 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". + :::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"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_FindEtAl/vb/source.vb" id="Snippet1"::: - - ]]> - - - is . - - - - - - - - - - - - - - - Method - - M:System.Collections.Generic.IList`1.RemoveAt(System.Int32) - M:System.Collections.IList.RemoveAt(System.Int32) - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Void - - - - - - The zero-based index of the element to remove. - Removes the element at the specified index of the . - - to remove an item, the remaining items in the list are renumbered to replace the removed item. For example, if you remove the item at index 3, the item at index 4 is moved to the 3 position. In addition, the number of items in the list (as represented by the property) is reduced by 1. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_FindEtAl/vb/source.vb" id="Snippet1"::: + + ]]> + + + is . + + + + + + + + + + + + + + + Method + + M:System.Collections.Generic.IList`1.RemoveAt(System.Int32) + M:System.Collections.IList.RemoveAt(System.Int32) + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Void + + + + + + The zero-based index of the element to remove. + Removes the element at the specified index of the . + + to remove an item, the remaining items in the list are renumbered to replace the removed item. For example, if you remove the item at index 3, the item at index 4 is moved to the 3 position. In addition, the number of items in the list (as represented by the property) is reduced by 1. + This method is an O(*n*) operation, where *n* is ( - `index`). - -## Examples - The following example demonstrates how to add, remove, and insert a simple business object in a . - + +## Examples + The following example demonstrates how to add, remove, and insert a simple business object in a . + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/program.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.addremoveinsert/vb/module1.vb" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.collections.generic.list.addremoveinsert/fs/addremoveinsert.fs" id="Snippet1"::: - - ]]> - - - is less than 0. - - -or- - - is equal to or greater than . - - - - - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Void - - - - - - - The zero-based starting index of the range of elements to remove. - The number of elements to remove. - Removes a range of elements from the . - - have their indexes reduced by `count`. - + + ]]> + + + is less than 0. + + -or- + + is equal to or greater than . + + + + + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Void + + + + + + + The zero-based starting index of the range of elements to remove. + The number of elements to remove. + Removes a range of elements from the . + + have their indexes reduced by `count`. + This method is an O(*n*) operation, where *n* is . - -## Examples - The following example demonstrates the method and various other methods of the class that act on ranges. After the list has been created and modified, the method is used to remove two elements from the list, beginning at index location 2. - + +## Examples + The following example demonstrates the method and various other methods of the class that act on ranges. After the list has been created and modified, the method is used to remove two elements from the list, beginning at index location 2. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Ranges/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/.ctor/source1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Ranges/vb/source.vb" id="Snippet1"::: - - ]]> - - - is less than 0. - - -or- - - is less than 0. - - and do not denote a valid range of elements in the . - - - - - - - - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - - - Reverses the order of the elements in the or a portion of it. - - method. The example creates a of strings and adds six strings. The method overload is used to reverse the list, and then the method overload is used to reverse the middle of the list, beginning with element 1 and encompassing four elements. - + + ]]> + + + is less than 0. + + -or- + + is less than 0. + + and do not denote a valid range of elements in the . + + + + + + + + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + + + Reverses the order of the elements in the or a portion of it. + + method. The example creates a of strings and adds six strings. The method overload is used to reverse the list, and then the method overload is used to reverse the middle of the list, beginning with element 1 and encompassing four elements. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Reverse/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Reverse/source.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Reverse/vb/source.vb" id="Snippet1"::: - - ]]> - - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Void - - - - Reverses the order of the elements in the entire . - - to reverse the order of the elements. - + + ]]> + + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Void + + + + Reverses the order of the elements in the entire . + + to reverse the order of the elements. + This method is an O(*n*) operation, where *n* is . - ]]> - - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Void - - - - - - - The zero-based starting index of the range to reverse. - The number of elements in the range to reverse. - Reverses the order of the elements in the specified range. - - to reverse the order of the elements. - - This method is an O(*n*) operation, where *n* is . - - ]]> - - - is less than 0. - - -or- - - is less than 0. - - and do not denote a valid range of elements in the . - - - - - - - - - - Method - - System.Collections - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Collections.Generic.List<T> - - - - - - - The zero-based index at which the range starts. - The length of the range. - Creates a shallow copy of a range of elements in the source . - A shallow copy of a range of elements in the source . - To be added. - + ]]> + + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Void + + + + + + + The zero-based starting index of the range to reverse. + The number of elements in the range to reverse. + Reverses the order of the elements in the specified range. + + to reverse the order of the elements. + + This method is an O(*n*) operation, where *n* is . + + ]]> + + + is less than 0. + + -or- + + is less than 0. + + and do not denote a valid range of elements in the . + + + + + + + + + + Method + + System.Collections + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Collections.Generic.List<T> + + + + + + + The zero-based index at which the range starts. + The length of the range. + Creates a shallow copy of a range of elements in the source . + A shallow copy of a range of elements in the source . + To be added. + is less than 0. -or- - is less than 0. - - and do not denote a valid range of elements in the . - - - - - System.Collections - 4.0.0.0 - 4.0.10.0 - - - Sorts the elements or a portion of the elements in the using either the specified or default implementation or a provided delegate to compare list elements. - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Void - - - - Sorts the elements in the entire using the default comparer. - - for type `T` to determine the order of list elements. The property checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws an . - - This method uses the method, which applies the introspective sort as follows: - -- If the partition size is less than or equal to 16 elements, it uses an insertion sort algorithm. - -- If the number of partitions exceeds 2 log *n*, where *n* is the range of the input array, it uses a Heapsort algorithm. - -- Otherwise, it uses a 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. - + is less than 0. + + and do not denote a valid range of elements in the . + + + + + System.Collections + 4.0.0.0 + 4.0.10.0 + + + Sorts the elements or a portion of the elements in the using either the specified or default implementation or a provided delegate to compare list elements. + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Void + + + + Sorts the elements in the entire using the default comparer. + + for type `T` to determine the order of list elements. The property checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws an . + + This method uses the method, which applies the introspective sort as follows: + +- If the partition size is less than or equal to 16 elements, it uses an insertion sort algorithm. + +- If the number of partitions exceeds 2 log *n*, where *n* is the range of the input array, it uses a Heapsort algorithm. + +- Otherwise, it uses a 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. + This method is an O(*n* log *n*) operation, where *n* is . - -## Examples - The following example adds some names to a `List` object, displays the list in unsorted order, calls the method, and then displays the sorted list. - +## Examples + + The following example adds some names to a `List` object, displays the list in unsorted order, calls the method, and then displays the sorted list. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Sort/Sort1.cs" interactive="try-dotnet-method" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.sort/vb/Sort1.vb" id="Snippet2"::: - - The following code demonstrates the and method overloads on a simple business object. Calling the method results in the use of the default comparer for the Part type, and the method is implemented by using an anonymous method. - + + The following code demonstrates the and method overloads on a simple business object. Calling the method results in the use of the default comparer for the Part type, and the method is implemented by using an anonymous method. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Sort/program.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.sort/vb/module1.vb" id="Snippet1"::: - - 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. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.sort/vb/module1.vb" id="Snippet1"::: + + 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. + :::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"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_SortSearch/vb/source.vb" id="Snippet1"::: - - ]]> - - The default comparer cannot find an implementation of the generic interface or the interface for type . - Performing Culture-Insensitive String Operations in Collections - - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Void - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })>] - - - - - - The implementation to use when comparing elements, or to use the default comparer . - Sorts the elements in the entire using the specified comparer. - - are sorted using the specified implementation. - - If `comparer` is `null`, the default comparer checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws an . - - This method uses the method, which applies the introspective sort as follows: - -- If the partition size is less than or equal to 16 elements, it uses an insertion sort algorithm. - -- If the number of partitions exceeds 2 log *n*, where *n* is the range of the input array, it uses a Heapsort algorithm. - -- Otherwise, it uses a 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. - + + ]]> + + The default comparer cannot find an implementation of the generic interface or the interface for type . + Performing Culture-Insensitive String Operations in Collections + + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Void + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })>] + + + + + + The implementation to use when comparing elements, or to use the default comparer . + Sorts the elements in the entire using the specified comparer. + + are sorted using the specified implementation. + + If `comparer` is `null`, the default comparer checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws an . + + This method uses the method, which applies the introspective sort as follows: + +- If the partition size is less than or equal to 16 elements, it uses an insertion sort algorithm. + +- If the number of partitions exceeds 2 log *n*, where *n* is the range of the input array, it uses a Heapsort algorithm. + +- Otherwise, it uses a 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. + This method is an O(*n* log *n*) operation, where *n* is . - -## 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. - - 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. - + +## 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. + + 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. + :::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"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_SortSearchComparer/vb/source.vb" id="Snippet1"::: - - ]]> - - - is , and the default comparer cannot find implementation of the generic interface or the interface for type . - The implementation of caused an error during the sort. For example, might not return 0 when comparing an item with itself. - Performing Culture-Insensitive String Operations in Collections - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Void - - - - - - The to use when comparing elements. - Sorts the elements in the entire using the specified . - - are sorted using the method represented by the delegate. - - If `comparison` is `null`, an is thrown. - - This method uses , which applies the introspective sort as follows: - -- If the partition size is less than or equal to 16 elements, it uses an insertion sort algorithm - -- If the number of partitions exceeds 2 log *n*, 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 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. - + + ]]> + + + is , and the default comparer cannot find implementation of the generic interface or the interface for type . + The implementation of caused an error during the sort. For example, might not return 0 when comparing an item with itself. + Performing Culture-Insensitive String Operations in Collections + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Void + + + + + + The to use when comparing elements. + Sorts the elements in the entire using the specified . + + are sorted using the method represented by the delegate. + + If `comparison` is `null`, an is thrown. + + This method uses , which applies the introspective sort as follows: + +- If the partition size is less than or equal to 16 elements, it uses an insertion sort algorithm + +- If the number of partitions exceeds 2 log *n*, 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 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. + This method is an O(*n* log *n*) operation, where *n* is . - -## Examples - The following code demonstrates the and method overloads on a simple business object. Calling the method results in the use of the default comparer for the Part type, and the method is implemented using an anonymous method. - + +## Examples + The following code demonstrates the and method overloads on a simple business object. Calling the method results in the use of the default comparer for the Part type, and the method is implemented using an anonymous method. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Sort/program.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.sort/vb/module1.vb" id="Snippet1"::: - - The following example demonstrates the method overload. - - The example defines an alternative comparison method for strings, named `CompareDinosByLength`. This method 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 also includes an empty string and a null reference. The list is displayed, sorted using a generic delegate representing the `CompareDinosByLength` method, and displayed again. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.sort/vb/module1.vb" id="Snippet1"::: + + The following example demonstrates the method overload. + + The example defines an alternative comparison method for strings, named `CompareDinosByLength`. This method 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 also includes an empty string and a null reference. The list is displayed, sorted using a generic delegate representing the `CompareDinosByLength` method, and displayed again. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_SortComparison/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/ComparisonT/Overview/source.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_SortComparison/vb/source.vb" id="Snippet1"::: - - ]]> - - - is . - The implementation of caused an error during the sort. For example, might not return 0 when comparing an item with itself. - - Performing Culture-Insensitive String Operations in Collections - - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Void - - - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })>] - - - - - - The zero-based starting index of the range to sort. - The length of the range to sort. - The implementation to use when comparing elements, or to use the default comparer . - Sorts the elements in a range of elements in using the specified comparer. - - are sorted using the specified implementation. - - If `comparer` is `null`, the default comparer checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws an . - - This method uses , which applies the introspective sort as follows: - -- If the partition size is less than or equal to 16 elements, it uses an insertion sort algorithm - -- If the number of partitions exceeds 2 log *n*, 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 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. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_SortComparison/vb/source.vb" id="Snippet1"::: + + ]]> + + + is . + The implementation of caused an error during the sort. For example, might not return 0 when comparing an item with itself. + + Performing Culture-Insensitive String Operations in Collections + + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Void + + + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })>] + + + + + + The zero-based starting index of the range to sort. + The length of the range to sort. + The implementation to use when comparing elements, or to use the default comparer . + Sorts the elements in a range of elements in using the specified comparer. + + are sorted using the specified implementation. + + If `comparer` is `null`, the default comparer checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws an . + + This method uses , which applies the introspective sort as follows: + +- If the partition size is less than or equal to 16 elements, it uses an insertion sort algorithm + +- If the number of partitions exceeds 2 log *n*, 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 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. + This method is an O(*n* log *n*) operation, where *n* is . - -## 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. - - 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. - + +## 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. + + 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. + :::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"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_SortSearchComparerRange/vb/source.vb" id="Snippet1"::: - - ]]> - - - is less than 0. - - -or- - - is less than 0. - - and do not specify a valid range in the . - - -or- - - The implementation of caused an error during the sort. For example, might not return 0 when comparing an item with itself. - - is , and the default comparer cannot find implementation of the generic interface or the interface for type . - Performing Culture-Insensitive String Operations in Collections - - - - - - - - - - Property - - P:System.Collections.Generic.ICollection`1.IsReadOnly - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Boolean - - - Gets a value indicating whether the is read-only. - - if the is read-only; otherwise, . In the default implementation of , this property always returns . - - - - - - - - - - - - - Method - - M:System.Collections.Generic.IEnumerable`1.GetEnumerator - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Collections.Generic.IEnumerator<T> - - - - Returns an enumerator that iterates through a collection. - An that can be used to iterate through the collection. - - 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 . - - 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. - - This method is an O(1) operation. - - ]]> - - - - - - - - - - - - Method - - M:System.Collections.ICollection.CopyTo(System.Array,System.Int32) - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Void - - - - - - - The one-dimensional that is the destination of the elements copied from . The must have zero-based indexing. - The zero-based index in at which copying begins. - Copies the elements of the to an , starting at a particular index. - - + + + is less than 0. + + -or- + + is less than 0. + + and do not specify a valid range in the . + + -or- + + The implementation of caused an error during the sort. For example, might not return 0 when comparing an item with itself. + + is , and the default comparer cannot find implementation of the generic interface or the interface for type . + Performing Culture-Insensitive String Operations in Collections + + + + + + + + + + Property + + P:System.Collections.Generic.ICollection`1.IsReadOnly + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Boolean + + + Gets a value indicating whether the is read-only. + + if the is read-only; otherwise, . In the default implementation of , this property always returns . + + + + + + + + + + + + + Method + + M:System.Collections.Generic.IEnumerable`1.GetEnumerator + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Collections.Generic.IEnumerator<T> + + + + Returns an enumerator that iterates through a collection. + An that can be used to iterate through the collection. + + 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 . + + 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. + + This method is an O(1) operation. + + ]]> + + + + + + + + + + + + Method + + M:System.Collections.ICollection.CopyTo(System.Array,System.Int32) + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Void + + + + + + + The one-dimensional that is the destination of the elements copied from . The must have zero-based indexing. + The zero-based index in at which copying begins. + Copies the elements of the to an , starting at a particular index. + + [!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 . - - This method is an O(*n*) operation, where *n* is . - - ]]> - - - is . - - is less than 0. - - is multidimensional. - - -or- - - does not have zero-based indexing. - - -or- - - The number of elements in the source is greater than the available space from to the end of the destination . - - -or- - - The type of the source cannot be cast automatically to the type of the destination . - - - - - - - - - - Property - - P:System.Collections.ICollection.IsSynchronized - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Boolean - - - Gets a value indicating whether access to the is synchronized (thread safe). - - if access to the is synchronized (thread safe); otherwise, . In the default implementation of , this property always returns . - - namespace are not synchronized. - - Enumerating through a collection is intrinsically not a thread-safe procedure. In the rare case where enumeration contends with write accesses, 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. - - returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock this object before accessing the collection. - - Retrieving the value of this property is an O(1) operation. - - ]]> - - - - - - - - - - - - Property - - P:System.Collections.ICollection.SyncRoot - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Object - - - Gets an object that can be used to synchronize access to the . - An object that can be used to synchronize access to the . In the default implementation of , this property always returns the current instance. - - namespace are not synchronized. - - 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. - - returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock this object before accessing the collection. The following code shows the use of the property for C#, C++, and Visual Basic. - -```csharp -ICollection ic = ...; -lock (ic.SyncRoot) -{ - // Access the collection. -} -``` - -```vb -Dim ic As ICollection = ... -SyncLock ic.SyncRoot - ' Access the collection. -End SyncLock -``` - +> 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 . + + ]]> + + + is . + + is less than 0. + + is multidimensional. + + -or- + + does not have zero-based indexing. + + -or- + + The number of elements in the source is greater than the available space from to the end of the destination . + + -or- + + The type of the source cannot be cast automatically to the type of the destination . + + + + + + + + + + Property + + P:System.Collections.ICollection.IsSynchronized + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Boolean + + + Gets a value indicating whether access to the is synchronized (thread safe). + + if access to the is synchronized (thread safe); otherwise, . In the default implementation of , this property always returns . + + namespace are not synchronized. + + Enumerating through a collection is intrinsically not a thread-safe procedure. In the rare case where enumeration contends with write accesses, 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. + + returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock this object before accessing the collection. + + Retrieving the value of this property is an O(1) operation. + + ]]> + + + + + + + + + + + + Property + + P:System.Collections.ICollection.SyncRoot + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Object + + + Gets an object that can be used to synchronize access to the . + An object that can be used to synchronize access to the . In the default implementation of , this property always returns the current instance. + + namespace are not synchronized. + + 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. + + returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock this object before accessing the collection. The following code shows the use of the property for C#, C++, and Visual Basic. + +```csharp +ICollection ic = ...; +lock (ic.SyncRoot) +{ + // Access the collection. +} +``` + +```vb +Dim ic As ICollection = ... +SyncLock ic.SyncRoot + ' Access the collection. +End SyncLock +``` + ```cpp -ICollection^ ic = ...; -try -{ - Monitor::Enter(ic->SyncRoot); - // Access the collection. -} -finally -{ - Monitor::Exit(ic->SyncRoot); -} -``` - - Retrieving the value of this property is an O(1) operation. - - ]]> - - - - - - - - - - - - Method - - M:System.Collections.IEnumerable.GetEnumerator - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Collections.IEnumerator - - - - Returns an enumerator that iterates through a collection. - An that can be used to iterate through the collection. - - also brings the enumerator back to this position. At this position, the 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 . - - The property returns the same object until either or 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. To set to the first element of the collection again, you can call 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 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. - - This method is an O(1) operation. - - ]]> - - - - - - - - - - - - Method - - M:System.Collections.IList.Add(System.Object) - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Int32 - - - - - - The to add to the . - Adds an item to the . - The position into which the new element was inserted. - - is less than , this method is an O(1) operation. If the capacity needs to be increased to accommodate the new element, this method becomes an O(*n*) operation, where *n* is . - - ]]> - - - is of a type that is not assignable to the . - - - - - - - - - - Method - - M:System.Collections.IList.Contains(System.Object) - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Boolean - - - - - - The to locate in the . - Determines whether the contains a specific value. - - if is found in the ; otherwise, . - - for `T`, the type of values in the list. - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . - - ]]> - - - - - - - - - - - Method - - M:System.Collections.IList.IndexOf(System.Object) - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Int32 - - - - - - The object to locate in the . - Determines the index of a specific item in the . - The index of if found in the list; otherwise, -1. - - for `T`, the type of values in the list. - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . - - ]]> - - - is of a type that is not assignable to the . - - - - - - - - - - Method - - M:System.Collections.IList.Insert(System.Int32,System.Object) - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Void - - - - - - - The zero-based index at which should be inserted. - The object to insert into the . - Inserts an item to the at the specified index. - - , then `item` is appended to the end. - - This method is an O(*n*) operation, where *n* is . - - ]]> - - - is not a valid index in the . - - is of a type that is not assignable to the . - - - - - - - - - - Property - - P:System.Collections.IList.IsFixedSize - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Boolean - - - Gets a value indicating whether the has a fixed size. - - if the has a fixed size; otherwise, . In the default implementation of , this property always returns . - - - - - - - - - - - - - Property - - P:System.Collections.IList.IsReadOnly - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Boolean - - - Gets a value indicating whether the is read-only. - - if the is read-only; otherwise, . In the default implementation of , this property always returns . - - - - - - - - - - - - - - Property - - P:System.Collections.IList.Item(System.Int32) - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - System.Object - - - - - - The zero-based index of the element to get or set. - Gets or sets the element at the specified index. - The element at the specified index. - - property. Visual Basic implements as a default property, which provides the same indexing functionality. - - Retrieving the value of this property is an O(1) operation; setting the property is also an O(1) operation. - - ]]> - - - is not a valid index in the . - The property is set and is of a type that is not assignable to the . - - - - - - - - - - Method - - M:System.Collections.IList.Remove(System.Object) - - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - The object to remove from the . - Removes the first occurrence of a specific object from the . - - for `T`, the type of values in the list. - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . - - ]]> - - - is of a type that is not assignable to the . - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - T[] - - - - Copies the elements of the to a new array. - An array containing copies of the elements of the . - - , which is an O(*n*) operation, where *n* is . - +ICollection^ ic = ...; +try +{ + Monitor::Enter(ic->SyncRoot); + // Access the collection. +} +finally +{ + Monitor::Exit(ic->SyncRoot); +} +``` + + Retrieving the value of this property is an O(1) operation. + + ]]> + + + + + + + + + + + + Method + + M:System.Collections.IEnumerable.GetEnumerator + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Collections.IEnumerator + + + + Returns an enumerator that iterates through a collection. + An that can be used to iterate through the collection. + + also brings the enumerator back to this position. At this position, the 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 . + + The property returns the same object until either or 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. To set to the first element of the collection again, you can call 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 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. + + This method is an O(1) operation. + + ]]> + + + + + + + + + + + + Method + + M:System.Collections.IList.Add(System.Object) + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Int32 + + + + + + The to add to the . + Adds an item to the . + The position into which the new element was inserted. + + is less than , this method is an O(1) operation. If the capacity needs to be increased to accommodate the new element, this method becomes an O(*n*) operation, where *n* is . + + ]]> + + + is of a type that is not assignable to the . + + + + + + + + + + Method + + M:System.Collections.IList.Contains(System.Object) + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Boolean + + + + + + The to locate in the . + Determines whether the contains a specific value. + + if is found in the ; otherwise, . + + for `T`, the type of values in the list. + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . + + ]]> + + + + + + + + + + + Method + + M:System.Collections.IList.IndexOf(System.Object) + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Int32 + + + + + + The object to locate in the . + Determines the index of a specific item in the . + The index of if found in the list; otherwise, -1. + + for `T`, the type of values in the list. + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . + + ]]> + + + is of a type that is not assignable to the . + + + + + + + + + + Method + + M:System.Collections.IList.Insert(System.Int32,System.Object) + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Void + + + + + + + The zero-based index at which should be inserted. + The object to insert into the . + Inserts an item to the at the specified index. + + , then `item` is appended to the end. + + This method is an O(*n*) operation, where *n* is . + + ]]> + + + is not a valid index in the . + + is of a type that is not assignable to the . + + + + + + + + + + Property + + P:System.Collections.IList.IsFixedSize + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Boolean + + + Gets a value indicating whether the has a fixed size. + + if the has a fixed size; otherwise, . In the default implementation of , this property always returns . + + + + + + + + + + + + + Property + + P:System.Collections.IList.IsReadOnly + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Boolean + + + Gets a value indicating whether the is read-only. + + if the is read-only; otherwise, . In the default implementation of , this property always returns . + + + + + + + + + + + + + + Property + + P:System.Collections.IList.Item(System.Int32) + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + System.Object + + + + + + The zero-based index of the element to get or set. + Gets or sets the element at the specified index. + The element at the specified index. + + property. Visual Basic implements as a default property, which provides the same indexing functionality. + + Retrieving the value of this property is an O(1) operation; setting the property is also an O(1) operation. + + ]]> + + + is not a valid index in the . + The property is set and is of a type that is not assignable to the . + + + + + + + + + + Method + + M:System.Collections.IList.Remove(System.Object) + + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + The object to remove from the . + Removes the first occurrence of a specific object from the . + + for `T`, the type of values in the list. + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . + + ]]> + + + is of a type that is not assignable to the . + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + T[] + + + + Copies the elements of the to a new array. + An array containing copies of the elements of the . + + , which is an O(*n*) operation, where *n* is . + This method is an O(*n*) operation, where *n* is . - -## Examples - The following example demonstrates the method and other methods of the class that act on ranges. At the end of the example, the method is used to get three items from the list, beginning with index location 2. The method is called on the resulting , creating an array of three elements. The elements of the array are displayed. - + +## Examples + The following example demonstrates the method and other methods of the class that act on ranges. At the end of the example, the method is used to get three items from the list, beginning with index location 2. The method is called on the resulting , creating an array of three elements. The elements of the array are displayed. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Ranges/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/.ctor/source1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Ranges/vb/source.vb" id="Snippet1"::: - - ]]> - - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Void - - - - Sets the capacity to the actual number of elements in the , if that number is less than a threshold value. - - 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. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Ranges/vb/source.vb" id="Snippet1"::: + + ]]> + + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Void + + + + Sets the capacity to the actual number of elements in the , if that number is less than a threshold value. + + 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. - - This method is an O(*n*) operation, where *n* is . - - To reset a to its initial state, call the method before calling the method. Trimming an empty sets the capacity of the to the default capacity. - +> The current threshold of 90 percent might change in future releases. + + This method is an O(*n*) operation, where *n* is . + + To reset a to its initial state, call the method before calling the method. Trimming an empty sets the capacity of the to the default capacity. + The capacity can also be set using the property. - -## Examples - The following example demonstrates how to check the capacity and count of a that contains a simple business object, and illustrates using the method to remove extra capacity. - +## Examples + + The following example demonstrates how to check the capacity and count of a that contains a simple business object, and illustrates using the method to remove extra capacity. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Capacity/program.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.capacitycount/vb/module1.vb" id="Snippet1"::: - - The following example demonstrates the method. Several properties and methods of the class are used to add, insert, and remove items from a list of strings. Then the method is used to reduce the capacity to match the count, and the and properties are displayed. If the unused capacity had been less than 10 percent of total capacity, the list would not have been resized. Finally, the contents of the list are cleared. - + + The following example demonstrates the method. Several properties and methods of the class are used to add, insert, and remove items from a list of strings. Then the method is used to reduce the capacity to match the count, and the and properties are displayed. If the unused capacity had been less than 10 percent of total capacity, the list would not have been resized. Finally, the contents of the list are cleared. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Class/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/List`1_Class/fs/listclass.fs" id="Snippet1"::: - - ]]> - - - - - - - - - - - - - - Method - - System.Collections - 4.0.0.0 - 4.0.10.0 - 4.1.0.0 - 4.1.1.0 - 4.1.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Boolean - - - - - - The delegate that defines the conditions to check against the elements. - Determines whether every element in the matches the conditions defined by the specified predicate. - - if every element in the matches the conditions defined by the specified predicate; otherwise, . If the list has no elements, the return value is . - - 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, and processing is stopped when the delegate returns `false` for any element. The elements are processed in order, and all calls are made on a single thread. - + + ]]> + + + + + + + + + + + + + + Method + + System.Collections + 4.0.0.0 + 4.0.10.0 + 4.1.0.0 + 4.1.1.0 + 4.1.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Boolean + + + + + + The delegate that defines the conditions to check against the elements. + Determines whether every element in the matches the conditions defined by the specified predicate. + + if every element in the matches the conditions defined by the specified predicate; otherwise, . If the list has no elements, the return value is . + + 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, and processing is stopped when the delegate returns `false` for any element. The elements are processed in order, and all calls are made on a single thread. + This method is an O(*n*) operation, where *n* is . - -## Examples - The following example demonstrates the method and several other methods that use generic delegate. - - A of strings is created, containing 8 dinosaur names, two of which (at positions 1 and 5) end with "saurus". The example also defines a search predicate method named `EndsWithSaurus`, which accepts a string parameter and returns a Boolean value indicating whether the input string ends in "saurus". - - 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`. - + +## Examples + The following example demonstrates the method and several other methods that use generic delegate. + + A of strings is created, containing 8 dinosaur names, two of which (at positions 1 and 5) end with "saurus". The example also defines a search predicate method named `EndsWithSaurus`, which accepts a string parameter and returns a Boolean value indicating whether the input string ends in "saurus". + + 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"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_FindEtAl/vb/source.vb" id="Snippet1"::: - - ]]> - - - is . - - - - - - + + ]]> + + + is . + + + + + + diff --git a/xml/System.Collections.ObjectModel/ObservableCollection`1.xml b/xml/System.Collections.ObjectModel/ObservableCollection`1.xml index d719c842b94..cbf4aae60d9 100644 --- a/xml/System.Collections.ObjectModel/ObservableCollection`1.xml +++ b/xml/System.Collections.ObjectModel/ObservableCollection`1.xml @@ -89,38 +89,9 @@ The type of elements in the collection. Represents a dynamic data collection that provides notifications when items get added or removed, or when the whole list is refreshed. - - such as a , , or to display a collection of records. - - You can enumerate over any collection that implements the interface. However, to set up dynamic bindings so that insertions or deletions in the collection update the UI automatically, the collection must implement the interface. This interface exposes the event, an event that should be raised whenever the underlying collection changes. - - WPF provides the class, which is a built-in implementation of a data collection that implements the interface. - - Before implementing your own collection, consider using or one of the existing collection classes, such as , , and , among many others. If you have an advanced scenario and want to implement your own collection, consider using , which provides a non-generic collection of objects that can be individually accessed by index. Implementing provides the best performance with the data binding engine. - -> [!NOTE] -> To fully support transferring data values from binding source objects to binding targets, each object in your collection that supports bindable properties must implement an appropriate property changed notification mechanism such as the interface. - - For more information, see "Binding to Collections" in [Data Binding Overview](/dotnet/framework/wpf/data/data-binding-overview). - -## Notes on XAML Usage - can be used as a XAML object element in Windows Presentation Foundation (WPF), in versions 3.0 and 3.5. However, the usage has substantial limitations. - -- must be the root element, because the `x:TypeArguments` attribute that must be used to specify the constrained type of the generic is only supported on the object element for the root element. - -- You must declare an `x:Class` attribute (which entails that the build action for this XAML file must be `Page` or some other build action that compiles the XAML). - -- is in a namespace and assembly that are not initially mapped to the default XML namespace. You must map a prefix for the namespace and assembly, and then use that prefix on the object element tag for . - - A more straightforward way to use capabilities from XAML in an application is to declare your own non-generic custom collection class that derives from , and constrains it to a specific type. Then map the assembly that contains this class, and reference it as an object element in your XAML. - ]]> - + For more information about this API, see Supplemental API remarks for ObservableCollection<T>. - Data Binding Demo @@ -226,11 +197,11 @@ The collection from which the elements are copied. Initializes a new instance of the class that contains elements copied from the specified collection. - in the same order they are read by the enumerator of the collection. - + in the same order they are read by the enumerator of the collection. + ]]> The parameter cannot be . @@ -284,11 +255,11 @@ The list from which the elements are copied. Initializes a new instance of the class that contains elements copied from the specified list. - in the same order they are read by the enumerator of the list. - + in the same order they are read by the enumerator of the list. + ]]> The parameter cannot be . @@ -345,14 +316,14 @@ Disallows reentrant attempts to change this collection. An object that can be used to dispose of the object. - call within a `using` scope, as in the following example: - + call within a `using` scope, as in the following example: + :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/ObservableCollectionT/BlockReentrancy/DataSource.cs" id="Snippetblockreentrancy"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/ObservableCollection_snip/visualbasic/datasource.vb" id="Snippetblockreentrancy"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/ObservableCollection_snip/visualbasic/datasource.vb" id="Snippetblockreentrancy"::: + ]]> @@ -450,13 +421,13 @@ Removes all items from the collection. - event. - - For more information, see the method of the base class. - + event. + + For more information, see the method of the base class. + ]]> @@ -568,13 +539,13 @@ The object to insert. Inserts an item into the collection at the specified index. - event. - - For more information, see the method of the base class. - + event. + + For more information, see the method of the base class. + ]]> @@ -634,11 +605,11 @@ The zero-based index specifying the new location of the item. Moves the item at the specified index to a new location in the collection. - method to provide custom behavior for this method. - + method to provide custom behavior for this method. + ]]> @@ -692,13 +663,13 @@ The zero-based index specifying the new location of the item. Moves the item at the specified index to a new location in the collection. - event. - - Subclasses can override this protected method to provide custom behavior for the method. - + event. + + Subclasses can override this protected method to provide custom behavior for the method. + ]]> @@ -756,19 +727,19 @@ Arguments of the event being raised. Raises the event with the provided arguments. - event through this `virtual` method. - - - -## Examples - When overriding this method, either call the base implementation or use the method to handle reentrant collection changes, as in the following example: - + event through this `virtual` method. + + + +## Examples + When overriding this method, either call the base implementation or use the method to handle reentrant collection changes, as in the following example: + :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/ObservableCollectionT/BlockReentrancy/DataSource.cs" id="Snippetblockreentrancy"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/ObservableCollection_snip/visualbasic/datasource.vb" id="Snippetblockreentrancy"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/ObservableCollection_snip/visualbasic/datasource.vb" id="Snippetblockreentrancy"::: + ]]> @@ -926,13 +897,13 @@ The zero-based index of the element to remove. Removes the item at the specified index of the collection. - event. - - For more information, see the method of the base class. - + event. + + For more information, see the method of the base class. + ]]> @@ -992,13 +963,13 @@ The new value for the element at the specified index. Replaces the element at the specified index. - event. - - For more information, see the method of the base class. - + event. + + For more information, see the method of the base class. + ]]> diff --git a/xml/System.Data.Linq.Mapping/TableAttribute.xml b/xml/System.Data.Linq.Mapping/TableAttribute.xml index 3e4f9b8f3e8..3bf727f0eba 100644 --- a/xml/System.Data.Linq.Mapping/TableAttribute.xml +++ b/xml/System.Data.Linq.Mapping/TableAttribute.xml @@ -22,37 +22,7 @@ Designates a class as an entity class that is associated with a database table. - - attribute as persistent classes. - - LINQ to SQL supports only single-table mapping. That is, an entity class must be mapped to exactly one database table, and you cannot map a database table to multiple classes at the same time. - - You can use the property of the attribute to specify a name for the table, and you can optionally use the schema name to qualify a table name. If you do not specify a name by using the property, the table name is assumed to be the same as the class name. - -## Schema-qualified Names - You can optionally use the schema name to qualify a table name. By default, the token to the left of the first period in the string is considered to be the schema name. The remainder of the name is considered to be the table name. The provider quotes the table name as appropriate. For example, the LINQ to SQL provider for SQL Server makes sure that brackets are used at least where they are needed. - -> [!NOTE] -> In some cases, you must explicitly quote attributes because the SQL Server provider cannot auto-quote. The following table shows some examples. - -|Case|Example: Identifier Name|Example: Expected String in Attributes|Otherwise…| -|----------|------------------------------|--------------------------------------------|----------------| -|Schema name contains a period|Schema: "A.B"

Table: "C"|"[A.B].C"|The first period is assumed to separate the schema name from the table name.| -|Schema/Table name starts with `@`|"@SomeName"|"[@SomeName]"|Assumed to be a parameter name.| -|Schema starts with `[` and ends with `]`|"[Schema.Table]"|"[[Schema].[Table]]]"|The unquoted identifier resembles a quoted identifier.| -|Table starts with `[` and ends with `]`|"[Table]"|"[[Table]]]"|The unquoted identifier resembles a quoted identifier.| - - - -## Examples - :::code language="csharp" source="~/snippets/csharp/System.Data.Linq.Mapping/TableAttribute/Overview/Program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/DLinqCustomize/vb/Module1.vb" id="Snippet1"::: - - ]]> - + For more information about this API, see Supplemental API remarks for TableAttribute. @@ -109,22 +79,22 @@ Gets or sets the name of the table or view. By default, the value is the same as the name of the class. - , the table name is assumed to be the same as the class name. - + , the table name is assumed to be the same as the class name. + > [!NOTE] -> You can optionally use a schema name to qualify the table name (for example, Schema3.Table5). By default, the token to the left of the first period in the string is considered to be the schema name, and the rest to be the table name. - - In the following example, the default table name, `Customer`, is changed to `Customers`. - - - -## Examples +> You can optionally use a schema name to qualify the table name (for example, Schema3.Table5). By default, the token to the left of the first period in the string is considered to be the schema name, and the rest to be the table name. + + In the following example, the default table name, `Customer`, is changed to `Customers`. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/System.Data.Linq.Mapping/TableAttribute/Overview/Program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/DLinqCustomize/vb/Module1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/DLinqCustomize/vb/Module1.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Data.Linq/DataLoadOptions.xml b/xml/System.Data.Linq/DataLoadOptions.xml index 1cd112eae76..f0a38586ce7 100644 --- a/xml/System.Data.Linq/DataLoadOptions.xml +++ b/xml/System.Data.Linq/DataLoadOptions.xml @@ -16,73 +16,7 @@ Provides for immediate loading and filtering of related data. - - class provides two methods to achieve immediate loading of specified related data. The method allows for immediate loading of data related to the main target. The method allows for filtering related objects. - -## Rules - Note the following rules regarding usage: - -- Assigning a to a after the first query has been executed generates an exception. - -- Modifying a after it has been assigned to a generates an exception - -## Cycle Handling - and directives must not create cycles. The following represent examples of such graphs: - -- Example 1: Self recursive - - - `dlo.LoadWith(e => e.Reports);` - -- Example 2: Back-pointers - - - `dlo.LoadWith (c => C.Orders);` - - - `dlo.LoadWith (o => o.Customer);` - -- Example 3: Longer cycles - - Although this should not occur in a well-normalized model, it is possible. - - - `dlo.LoadWith (a => a.Bs);` - - - `dlo.LoadWith (b => b.Cs);` - - - `dlo.LoadWith (c => c.As);` - -- Example 4: Self recursive subQueries - - - `dlo.AssociateWith(a=>a.As.Where(a=>a.Id=33));` - -- Example 5: Longer recursive subqueries - - - `dlo.AssociateWith(a=>a.Bs.Where(b=>b.Id==3));` - - - `dlo.AssociateWith(b=>b.As.Where(a=>a.Id==3));` - - The following are some general rules that help you understand what occurs in these scenarios. - - **LoadWith** Each call to checks whether cycles have been introduced into the graph. If there are, as in Examples 1, 2, and 3, an exception is thrown. - - **AssociateWith** The engine at run time does not apply the existing SubQuery clauses to the relationship inside the expression. - -- In Example 4, the `Where` clause is executed against all `A`, not just the ones sub-filtered by the SubQuery expression itself (because that would be recursive) - -- In Example 5, the first `Where` clause is applied to all the `B`s, even though there are subqueries on `B`. The second `Where` clause is applied to all the `A`s even though there are subqueries on `A`. - - - -## Examples - When you retrieve `Customers` from the Northwind sample database, you can use to specify that `Orders` is also to be retrieved. You can even specify which subset of `Orders` to retrieve. - - ]]> - + For more information about this API, see Supplemental API remarks for DataLoadOptions. @@ -123,37 +57,37 @@ - Identifies the query to be used on a particular one-to-many field or property. Note the following: - - If the expression does not start with a field or property that represents a one-to-many relationship, an exception is thrown. - - If an operator other than a valid operator appears in the expression, an exception is thrown. Valid operators are as follows: - - Where - - OrderBy - - ThenBy - - OrderByDescending - - ThenByDescending - + Identifies the query to be used on a particular one-to-many field or property. Note the following: + + If the expression does not start with a field or property that represents a one-to-many relationship, an exception is thrown. + + If an operator other than a valid operator appears in the expression, an exception is thrown. Valid operators are as follows: + + Where + + OrderBy + + ThenBy + + OrderByDescending + + ThenByDescending + Take Filters the objects retrieved for a particular relationship. - @@ -181,42 +115,42 @@ - The type that is queried against. - + The type that is queried against. + If the type is unmapped, an exception is thrown. - Identifies the query to be used on a particular one-to-many field or property. Note the following: - - If the expression does not start with a field or property that represents a one-to-many relationship, an exception is thrown. - - If an operator other than a valid operator appears in the expression, an exception is thrown. Valid operators are as follows: - - Where - - OrderBy - - ThenBy - - OrderByDescending - - ThenByDescending - + Identifies the query to be used on a particular one-to-many field or property. Note the following: + + If the expression does not start with a field or property that represents a one-to-many relationship, an exception is thrown. + + If an operator other than a valid operator appears in the expression, an exception is thrown. Valid operators are as follows: + + Where + + OrderBy + + ThenBy + + OrderByDescending + + ThenByDescending + Take Filters objects retrieved for a particular relationship. - . - - - -## Examples - In the following example, the inner loop iterates only over those `Orders` that have not been shipped today. - + . + + + +## Examples + In the following example, the inner loop iterates only over those `Orders` that have not been shipped today. + :::code language="csharp" source="~/snippets/csharp/System.Data.Linq/DataLoadOptions/AssociateWith/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/system.data.linq.dataloadoptions/vb/module1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/system.data.linq.dataloadoptions/vb/module1.vb" id="Snippet1"::: + ]]> @@ -296,17 +230,17 @@ A lambda expression that identifies the related material. Retrieves specified data related to the main target by using a lambda expression. - @@ -334,29 +268,29 @@ - Type that is queried against. - + Type that is queried against. + If this type is unmapped, an exception is thrown. - Identifies the field or property to be retrieved. - + Identifies the field or property to be retrieved. + If the expression does not identify a field or property that represents a one-to-one or one-to-many relationship, an exception is thrown. Specifies which sub-objects to retrieve when a query is submitted for an object of type T. - methods. - - To avoid cycling, see Remarks section in . - - - -## Examples - In the following example, all the `Orders` for all the `Customers` who are located in London are retrieved when the query is executed. As a result, successive access to the `Orders` property on a `Customer` object does not trigger a new database query. - + methods. + + To avoid cycling, see Remarks section in . + + + +## Examples + In the following example, all the `Orders` for all the `Customers` who are located in London are retrieved when the query is executed. As a result, successive access to the `Orders` property on a `Customer` object does not trigger a new database query. + :::code language="csharp" source="~/snippets/csharp/System.Data.Linq/DataLoadOptions/AssociateWith/program.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/system.data.linq.dataloadoptions/vb/module1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/system.data.linq.dataloadoptions/vb/module1.vb" id="Snippet2"::: + ]]> diff --git a/xml/System.Data.Objects/MergeOption.xml b/xml/System.Data.Objects/MergeOption.xml index 92cb13fd5b4..6cfc6721672 100644 --- a/xml/System.Data.Objects/MergeOption.xml +++ b/xml/System.Data.Objects/MergeOption.xml @@ -16,25 +16,26 @@ Specifies how objects being loaded into the object context are merged with objects already in the object context. - objects are immutable objects that represent object's identity. Entity keys are used to perform identity resolution in the object context. For more information, see [Working with Entity Keys](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/dd283139(v=vs.100)). If an entity with the same identity is already being tracked, the data coming from the data source and the data already in the state manager are merged according to the of the query. + objects are immutable objects that represent object's identity. Entity keys are used to perform identity resolution in the object context. For more information, see [Working with Entity Keys](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/dd283139(v=vs.100)). If an entity with the same identity is already being tracked, the data coming from the data source and the data already in the state manager are merged according to the of the query. + +## Additional information on `MergeOption.PreserveChanges` + +If the state of the entity is , the current and original values in the entry are overwritten with data source values. The state of the entity remains and no properties are marked as modified. + +If the state of the entity is , the current values of modified properties are not overwritten with data source values. The original values of unmodified properties are overwritten with the values from the data source. + +In .NET Framework 4, Entity Framework compares the current values of unmodified properties with the values that were returned from the data source. If the values are not the same, the property is marked as modified. + +In .NET Framework 3.5 SP1, Entity Framework does not mark the property as modified even if the value in the data source is different. + +Only modified properties are persisted to the data source when you call . + +To preserve the .NET Framework 3.5 SP1 behavior, set to `true`. The `PreserveChanges` option can be used to resolve optimistic concurrency exceptions while preserving changes in the local context. For more information, see [Saving Changes and Managing Concurrency](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738618(v=vs.100)). - If the state of the entity is , the current and original values in the entry are overwritten with data source values. The state of the entity remains and no properties are marked as modified. - - If the state of the entity is , the current values of modified properties are not overwritten with data source values. The original values of unmodified properties are overwritten with the values from the data source. - - In .NET Framework 4, the Entity Framework compares the current values of unmodified properties with the values that were returned from the data source. If the values are not the same, the property is marked as modified. - - In .NET Framework 3.5 SP1, the Entity Framework does not mark the property as modified even if the value in the data source is different. - - Only modified properties are persisted to the data source when you call . - - To preserve the .NET Framework 3.5 SP1 behavior, set to `true`. The `PreserveChanges` option can be used to resolve optimistic concurrency exceptions while preserving changes in the local context. For more information, see [Saving Changes and Managing Concurrency](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738618(v=vs.100)). - ]]> diff --git a/xml/System.Data/CommandBehavior.xml b/xml/System.Data/CommandBehavior.xml index 5567fdaaa61..bb277d35e82 100644 --- a/xml/System.Data/CommandBehavior.xml +++ b/xml/System.Data/CommandBehavior.xml @@ -46,27 +46,7 @@ Provides a description of the results of the query and its effect on the database. - - method of and any implementing classes. - - A bitwise combination of these values may be used. - -`CommandBehavior` is ignored when used to define a or and should therefore not be used. Use the constructor that does not require a `CommandBehavior` parameter in these two cases. - -### Notes on individual enumeration members - -When using `KeyInfo`, the .NET Framework Data Provider for SQL Server precedes the statement being executed with `SET FMTONLY OFF` and `SET NO_BROWSETABLE ON`. The user should be aware of potential side effects, such as interference with the use of `SET FMTONLY ON` statements. For more information, see [SET FMTONLY (Transact-SQL)](/sql/t-sql/statements/set-fmtonly-transact-sql). - -> [!NOTE] -> Use `SequentialAccess` to retrieve large values and binary data. Otherwise, an might occur and the connection will be closed. - -When you specify `SequentialAccess`, you are required to read from the columns in the order they are returned, although you are not required to read each column. Once you have read past a location in the returned stream of data, data at or before that location can no longer be read from the `DataReader`. When using the , you can reread the current column value until reading past it. When using the , you can read a column value only once. - - ]]> - + For more information about this API, see Supplemental API remarks for CommandBehavior. diff --git a/xml/System.Data/DataSet.xml b/xml/System.Data/DataSet.xml index 054d86f63d2..46397da1d8b 100644 --- a/xml/System.Data/DataSet.xml +++ b/xml/System.Data/DataSet.xml @@ -136,48 +136,15 @@ Represents an in-memory cache of data. - - , which is an in-memory cache of data retrieved from a data source, is a major component of the ADO.NET architecture. The consists of a collection of objects that you can relate to each other with objects. You can also enforce data integrity in the by using the and objects. For further details about working with objects, see [DataSets, DataTables, and DataViews](/dotnet/framework/data/adonet/dataset-datatable-dataview/). - - Whereas objects contain the data, the allows you to navigate though the table hierarchy. The tables are contained in a accessed through the property. When accessing objects, note that they are conditionally case sensitive. For example, if one is named "mydatatable" and another is named "Mydatatable", a string used to search for one of the tables is regarded as case sensitive. However, if "mydatatable" exists and "Mydatatable" does not, the search string is regarded as case insensitive. For more information about working with objects, see [Creating a DataTable](/dotnet/framework/data/adonet/dataset-datatable-dataview/creating-a-datatable). - - A can read and write data and schema as XML documents. The data and schema can then be transported across HTTP and used by any application, on any platform that is XML-enabled. You can save the schema as an XML schema with the method, and both schema and data can be saved using the method. To read an XML document that includes both schema and data, use the method. - - In a typical multiple-tier implementation, the steps for creating and refreshing a , and in turn, updating the original data are to: - -1. Build and fill each in a with data from a data source using a . - -2. Change the data in individual objects by adding, updating, or deleting objects. - -3. Invoke the method to create a second that features only the changes to the data. - -4. Call the method of the , passing the second as an argument. - -5. Invoke the method to merge the changes from the second into the first. - -6. Invoke the on the . Alternatively, invoke to cancel the changes. - -> [!NOTE] -> The and objects inherit from , and support the interface for remoting. These are the only ADO.NET objects that can be remoted. - -> [!NOTE] -> Classes inherited from are not finalized by the garbage collector, because the finalizer has been suppressed in . The derived class can call the method in its constructor to allow the class to be finalized by the garbage collector. - -### Security considerations - -For information about DataSet and DataTable security, see [Security guidance](/dotnet/framework/data/adonet/dataset-datatable-dataview/security-guidance). - -## Examples - The following example consists of several methods that, combined, create and fill a from the **Northwind** database. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet Example/VB/source.vb" id="Snippet1"::: - - ]]> - + For more information about this API, see Supplemental API remarks for DataSet. + + from the **Northwind** database. + +:::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet Example/CS/source.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet Example/VB/source.vb" id="Snippet1"::: + ]]> + This type is safe for multithreaded read operations. You must synchronize any write operations. Using DataSets in ADO.NET @@ -226,20 +193,20 @@ For information about DataSet and DataTable security, see [Security guidance](/d Initializes a new instance of the class. - constructor takes no parameters, and creates a default name, "NewDataSet," for the new instance. - - A name for the is required to ensure that the XML representation of the always has a name for the document element, which is the highest-level element in a schema definition. - - - -## Examples - The following example creates a new , and adds two objects to it. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.DataSet Example/VB/source.vb" id="Snippet1"::: - + constructor takes no parameters, and creates a default name, "NewDataSet," for the new instance. + + A name for the is required to ensure that the XML representation of the always has a name for the document element, which is the highest-level element in a schema definition. + + + +## Examples + The following example creates a new , and adds two objects to it. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.DataSet Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -283,18 +250,18 @@ For information about DataSet and DataTable security, see [Security guidance](/d The name of the . Initializes a new instance of the class with the given name. - is required to ensure that the XML representation of the always has a name for the document element, which is the highest level element in a schema definition. - - - -## Examples - The following example creates a new , to which two objects are added. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.DataSet1 Example/VB/source.vb" id="Snippet1"::: - + is required to ensure that the XML representation of the always has a name for the document element, which is the highest level element in a schema definition. + + + +## Examples + The following example creates a new , to which two objects are added. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.DataSet1 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -359,12 +326,12 @@ For information about DataSet and DataTable security, see [Security guidance](/d Contextual information about the serialized stream. Initializes a new instance of the class with serialized data. - .NET 7 and later versions only: contains binary data. @@ -428,12 +395,12 @@ For information about DataSet and DataTable security, see [Security guidance](/d To be added. Initializes a new instance of the class with serialized data. - .NET 7 and later versions only: contains binary data. @@ -476,28 +443,28 @@ For information about DataSet and DataTable security, see [Security guidance](/d Commits all the changes made to this since it was loaded or since the last time was called. - and classes have methods. Calling at the level causes the method for each to be called. Similarly, invoking on the causes to be called on each table within the . In this manner, you have multiple levels at which the method can be invoked. Calling the of the enables you to invoke the method on all subordinate objects (for example, tables and rows) with one call. - - When you call `AcceptChanges` on the `DataSet`, any objects still in edit-mode end their edits successfully. The property of each also changes; `Added` and `Modified` rows become `Unchanged`, and `Deleted` rows are removed. - - If the `DataSet` contains objects, invoking the `AcceptChanges` method also causes the to be enforced. - + and classes have methods. Calling at the level causes the method for each to be called. Similarly, invoking on the causes to be called on each table within the . In this manner, you have multiple levels at which the method can be invoked. Calling the of the enables you to invoke the method on all subordinate objects (for example, tables and rows) with one call. + + When you call `AcceptChanges` on the `DataSet`, any objects still in edit-mode end their edits successfully. The property of each also changes; `Added` and `Modified` rows become `Unchanged`, and `Deleted` rows are removed. + + If the `DataSet` contains objects, invoking the `AcceptChanges` method also causes the to be enforced. + > [!NOTE] -> `AcceptChanges` and `RejectChanges` only apply to `DataRow` related changes (that is, Add, Remove, Delete, and Modify). They are not applicable to schema or structural changes. -> -> Calling AcceptChanges will not replicate these changes back to the data source if the DataSet was filled using a DataAdapter. In that situation, call instead. See [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters) for more information. - - - -## Examples - The following example adds a to a in a . The method is then called on the , which cascades to all objects that it contains. - +> `AcceptChanges` and `RejectChanges` only apply to `DataRow` related changes (that is, Add, Remove, Delete, and Modify). They are not applicable to schema or structural changes. +> +> Calling AcceptChanges will not replicate these changes back to the data source if the DataSet was filled using a DataAdapter. In that situation, call instead. See [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters) for more information. + + + +## Examples + The following example adds a to a in a . The method is then called on the , which cascades to all objects that it contains. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.AcceptChanges/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.AcceptChanges/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.AcceptChanges/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -543,11 +510,11 @@ For information about DataSet and DataTable security, see [Security guidance](/d Begins the initialization of a that is used on a form or used by another component. The initialization occurs at run time. - method ends the initialization. Using the and methods prevents the control from being used before it is fully initialized. - + method ends the initialization. Using the and methods prevents the control from being used before it is fully initialized. + ]]> Using DataSets in ADO.NET @@ -601,20 +568,20 @@ For information about DataSet and DataTable security, see [Security guidance](/d if string comparisons are case-sensitive; otherwise, . The default is . - property affects how sorting, searching, and filtering operations are performed on each object contained in a when using the method. - - By default, setting the property for a also sets the property of each associated to the same value. - - - -## Examples - The following example toggles the property. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.CaseSensitive Example/VB/source.vb" id="Snippet1"::: - + property affects how sorting, searching, and filtering operations are performed on each object contained in a when using the method. + + By default, setting the property for a also sets the property of each associated to the same value. + + + +## Examples + The following example toggles the property. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.CaseSensitive Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -657,19 +624,19 @@ For information about DataSet and DataTable security, see [Security guidance](/d Clears the of any data by removing all rows in all tables. - is bound to an , calling or raises the . To avoid this situation, traverse each table, removing each row one at a time. - - - -## Examples - The following example clears the of all rows in all tables. - + is bound to an , calling or raises the . To avoid this situation, traverse each table, removing each row one at a time. + + + +## Examples + The following example clears the of all rows in all tables. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.Clear Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.Clear Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.Clear Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -713,21 +680,21 @@ For information about DataSet and DataTable security, see [Security guidance](/d Copies the structure of the , including all schemas, relations, and constraints. Does not copy any data. A new with the same schema as the current , but none of the data. - [!NOTE] -> If these classes have been subclassed, the clone will also be of the same subclasses. - - - -## Examples - The following example creates a clone of a object's schema. - +> If these classes have been subclassed, the clone will also be of the same subclasses. + + + +## Examples + The following example creates a clone of a object's schema. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.Clone Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.Clone Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.Clone Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -777,13 +744,13 @@ For information about DataSet and DataTable security, see [Security guidance](/d ## Remarks If these classes have been subclassed, the copy will also be of the same subclasses. - -## Examples - The following example uses the method to create a copy of the original . - + +## Examples + The following example uses the method to create a copy of the original . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.Copy Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.Copy Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.Copy Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -799,24 +766,24 @@ If these classes have been subclassed, the copy will also be of the same subclas Returns a with one result set per , in the same sequence as the tables appear in the collection. - , if a within the is empty, it will be represented by an empty result set within the returned `DataTableReader`. - - - -## Examples - This example, a Console application, creates three instances and adds each to a . The example calls the method and displays the contents of the returned . Note that the order of the result sets in the `DataTableReader` is controlled by the order of the `DataTable` instances passed as parameters. - + , if a within the is empty, it will be represented by an empty result set within the returned `DataTableReader`. + + + +## Examples + This example, a Console application, creates three instances and adds each to a . The example calls the method and displays the contents of the returned . Note that the order of the result sets in the `DataTableReader` is controlled by the order of the `DataTable` instances passed as parameters. + > [!NOTE] -> This example shows how to use one of the overloaded versions of `CreateDataReader`. For other examples that might be available, see the individual overload topics. - +> This example shows how to use one of the overloaded versions of `CreateDataReader`. For other examples that might be available, see the individual overload topics. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataSet.CreateDataReader/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks DataSet.CreateDataReader/VB/source.vb" id="Snippet1"::: - - The example displays the following code in the Console window: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks DataSet.CreateDataReader/VB/source.vb" id="Snippet1"::: + + The example displays the following code in the Console window: + ]]> Using DataSets in ADO.NET @@ -859,19 +826,19 @@ If these classes have been subclassed, the copy will also be of the same subclas Returns a with one result set per , in the same sequence as the tables appear in the collection. A containing one or more result sets, corresponding to the instances contained within the source . - , if a within the is empty, it is represented by an empty result set within the returned `DataTableReader`. - - - -## Examples - The following example creates three instances, and adds each to a . The example then passes the filled `DataSet` to a procedure that calls the method, and proceeds to iterate through all the result sets contained within the . The example displays the results in the Console window. - + , if a within the is empty, it is represented by an empty result set within the returned `DataTableReader`. + + + +## Examples + The following example creates three instances, and adds each to a . The example then passes the filled `DataSet` to a procedure that calls the method, and proceeds to iterate through all the result sets contained within the . The example displays the results in the Console window. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataSet.DataTableReader/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks DataSet.DataTableReader/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks DataSet.DataTableReader/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -924,19 +891,19 @@ If these classes have been subclassed, the copy will also be of the same subclas Returns a with one result set per . A containing one or more result sets, corresponding to the instances contained within the source . The returned result sets are in the order specified by the parameter. - , if a within the is empty, it is represented by an empty result set within the returned `DataTableReader`. Because this overloaded version allows you to supply a list of `DataTable` instances as parameters, you can specify the order in which the result sets appear within the returned `DataTableReader`. - - - -## Examples - This example, a Console application, creates three instances and adds each to a . The example calls the method and displays the contents of the returned . Note that the order of the result sets in the `DataTableReader` is controlled by the order of the `DataTable` instances passed as parameters. The example displays the results in the Console window. - + , if a within the is empty, it is represented by an empty result set within the returned `DataTableReader`. Because this overloaded version allows you to supply a list of `DataTable` instances as parameters, you can specify the order in which the result sets appear within the returned `DataTableReader`. + + + +## Examples + This example, a Console application, creates three instances and adds each to a . The example calls the method and displays the contents of the returned . Note that the order of the result sets in the `DataTableReader` is controlled by the order of the `DataTable` instances passed as parameters. The example displays the results in the Console window. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataSet.DataTableReaderTables/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks DataSet.DataTableReaderTables/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks DataSet.DataTableReaderTables/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -989,14 +956,14 @@ If these classes have been subclassed, the copy will also be of the same subclas Gets or sets the name of the current . The name of the . - with the given . - + with the given . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.DataSetName Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.DataSetName Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.DataSetName Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -1049,20 +1016,20 @@ If these classes have been subclassed, the copy will also be of the same subclas Gets a custom view of the data contained in the to allow filtering, searching, and navigating using a custom . A object. - returned by the property allows you to create custom settings for each in the . - - When you obtain a from a , the sort order, filtering, and are configured according to the settings in the property. - - - -## Examples - The following example gets the default for a , and adds a to the . - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.DefaultViewManager Example/VB/source.vb" id="Snippet1"::: - + returned by the property allows you to create custom settings for each in the . + + When you obtain a from a , the sort order, filtering, and are configured according to the settings in the property. + + + +## Examples + The following example gets the default for a , and adds a to the . + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.DefaultViewManager Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -1077,11 +1044,11 @@ If these classes have been subclassed, the copy will also be of the same subclas Determines the for a . - to determine its . - + to determine its . + ]]> Using DataSets in ADO.NET @@ -1127,11 +1094,11 @@ If these classes have been subclassed, the copy will also be of the same subclas Determines the for a . An enumeration indicating whether schema information has been omitted from the payload. - to determine its . - + to determine its . + ]]> Using DataSets in ADO.NET @@ -1179,11 +1146,11 @@ If these classes have been subclassed, the copy will also be of the same subclas Determines the for a . An enumeration indicating whether schema information has been omitted from the payload. - to determine its . - + to determine its . + ]]> Using DataSets in ADO.NET @@ -1229,11 +1196,11 @@ If these classes have been subclassed, the copy will also be of the same subclas Ends the initialization of a that is used on a form or used by another component. The initialization occurs at run time. - method starts the initialization. Using the and methods prevents the control from being used before it is fully initialized. - + method starts the initialization. Using the and methods prevents the control from being used before it is fully initialized. + ]]> Using DataSets in ADO.NET @@ -1287,19 +1254,19 @@ If these classes have been subclassed, the copy will also be of the same subclas if rules are enforced; otherwise, . The default is . - level ( property). For more information about creating constraints, see [DataTable Constraints](/dotnet/framework/data/adonet/dataset-datatable-dataview/datatable-constraints). - - - -## Examples - The following example creates a with one table, one column, five rows, and one . The property is set to `false` and the values of each row are set to the same value. When the property is reset to `true`, a is generated. - + level ( property). For more information about creating constraints, see [DataTable Constraints](/dotnet/framework/data/adonet/dataset-datatable-dataview/datatable-constraints). + + + +## Examples + The following example creates a with one table, one column, five rows, and one . The property is set to `false` and the values of each row are set to the same value. When the property is reset to `true`, a is generated. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.EnforceConstraints Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.EnforceConstraints Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.EnforceConstraints Example/VB/source.vb" id="Snippet1"::: + ]]> One or more constraints cannot be enforced. @@ -1353,21 +1320,21 @@ If these classes have been subclassed, the copy will also be of the same subclas Gets the collection of customized user information associated with the . A with all custom user information. - property enables you to store custom information with the `DataSet`. For example, you might store a time when the data should be refreshed. - - Extended properties must be of type if you want them persisted when the is written as XML. - - - -## Examples - The following example adds a custom property to the returned by the property. The second example retrieves the custom property. - + property enables you to store custom information with the `DataSet`. For example, you might store a time when the data should be refreshed. + + Extended properties must be of type if you want them persisted when the is written as XML. + + + +## Examples + The following example adds a custom property to the returned by the property. The second example retrieves the custom property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.ExtendedProperties Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.ExtendedProperties Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.ExtendedProperties Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -1429,19 +1396,19 @@ If these classes have been subclassed, the copy will also be of the same subclas Gets a copy of the that contains all changes made to it since it was loaded or since was last called. A copy of the changes from this that can have actions performed on it and later be merged back in using . If no changed rows are found, the method returns . - that contains a copy of all rows in the original that have pending changes. Relationship constraints can cause additional unchanged rows to be added to the new if the unchanged rows contain primary keys corresponding to foreign keys in the changed rows. The method returns `null` if there are no rows in the original that have pending changes. - - - -## Examples - The following example creates a simple with one table, two columns, and ten rows. Two values are changed, and one row is added. A subset of the changed data is created using the method. After reconciling errors, a new column is added to the subset, changing the schema. When the method is called with the `missingSchemaAction` set to `MissingSchemaAction.Add`, the new column is added to the original object's schema. - + that contains a copy of all rows in the original that have pending changes. Relationship constraints can cause additional unchanged rows to be added to the new if the unchanged rows contain primary keys corresponding to foreign keys in the changed rows. The method returns `null` if there are no rows in the original that have pending changes. + + + +## Examples + The following example creates a simple with one table, two columns, and ten rows. Two values are changed, and one row is added. A subset of the changed data is created using the method. After reconciling errors, a new column is added to the subset, changing the schema. When the method is called with the `missingSchemaAction` set to `MissingSchemaAction.Add`, the new column is added to the original object's schema. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.GetChanges Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.GetChanges Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.GetChanges Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1496,21 +1463,21 @@ If these classes have been subclassed, the copy will also be of the same subclas Gets a copy of the containing all changes made to it since it was last loaded, or since was called, filtered by . A filtered copy of the that can have actions performed on it, and subsequently be merged back in using . If no rows of the desired are found, the method returns . - method is used to produce a second object that contains only the changes introduced into the original. Use the `rowStates` argument to specify the type of changes the new object should include. - - This returned copy is designed to be merged back in to this original . Relationship constraints may cause parent rows marked `Unchanged` to be included. If no rows of the desired are found, the method returns `null`. - - - -## Examples - The following example uses the method to create a second object, which is then used to update a data source. - + method is used to produce a second object that contains only the changes introduced into the original. Use the `rowStates` argument to specify the type of changes the new object should include. + + This returned copy is designed to be merged back in to this original . Relationship constraints may cause parent rows marked `Unchanged` to be included. If no rows of the desired are found, the method returns `null`. + + + +## Examples + The following example uses the method to create a second object, which is then used to update a data source. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.GetChanges1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.GetChanges1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.GetChanges1 Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -1769,344 +1736,344 @@ If these classes have been subclassed, the copy will also be of the same subclas Returns the XML representation of the data stored in the . A string that is a representation of the data stored in the . - with set to . - - returns XML as a string, and therefore requires more overhead than to write XML to a file. - - If you build a using schema inference and serialize it using XML or Web services, the column ordering may change. - - - -## Examples - The following example creates a and , adds sample data, and then displays the data in XML format. - + with set to . + + returns XML as a string, and therefore requires more overhead than to write XML to a file. + + If you build a using schema inference and serialize it using XML or Web services, the column ordering may change. + + + +## Examples + The following example creates a and , adds sample data, and then displays the data in XML format. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.GetXml Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.GetXml Example/VB/source.vb" id="Snippet1"::: - - This sample demonstrates how to write data into an XML file from a DataSet and read data into DataSet from XML. This sample will create one dataset with two tables, use two ways to export a dataset into the XML files (WriteXml and GetXml), and use two ways (ReadXml and InferXmlSchema) to import a dataset from the XML files. - - Before you compile and run the sample, you need to create four XML files in the sample directory. First, create ElementsWithAttributes.xml: - -```xml - - New - - - Cancelled - -``` - - Next, create ElementsWithChildElementsxml.xml: - -```xml - - - C1045 - 2012 - Calculus - 4 - 7 - - - C1061 - 2012 - Physics - 4 - 1 - - - C2021 - 2012 - Composition - 3 - 2 - - - C2042 - 2012 - Literature - 4 - 2 - - - 1 - Engineering - 350000 - 2007-09-01T00:00:00+08:00 - 2 - - - 2 - English - 120000 - 2007-09-01T00:00:00+08:00 - 6 - - - 4 - Economics - 200000 - 2007-09-01T00:00:00+08:00 - 4 - - - 7 - Mathematics - 250024 - 2007-09-01T00:00:00+08:00 - 3 - - -``` - - Now create ElementsWithOnlyAttributes.xml: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.GetXml Example/VB/source.vb" id="Snippet1"::: + + This sample demonstrates how to write data into an XML file from a DataSet and read data into DataSet from XML. This sample will create one dataset with two tables, use two ways to export a dataset into the XML files (WriteXml and GetXml), and use two ways (ReadXml and InferXmlSchema) to import a dataset from the XML files. + + Before you compile and run the sample, you need to create four XML files in the sample directory. First, create ElementsWithAttributes.xml: + ```xml - - - - - - -``` - - And finally, create RepeatingElements.xml: - + + New + + + Cancelled + +``` + + Next, create ElementsWithChildElementsxml.xml: + +```xml + + + C1045 + 2012 + Calculus + 4 + 7 + + + C1061 + 2012 + Physics + 4 + 1 + + + C2021 + 2012 + Composition + 3 + 2 + + + C2042 + 2012 + Literature + 4 + 2 + + + 1 + Engineering + 350000 + 2007-09-01T00:00:00+08:00 + 2 + + + 2 + English + 120000 + 2007-09-01T00:00:00+08:00 + 6 + + + 4 + Economics + 200000 + 2007-09-01T00:00:00+08:00 + 4 + + + 7 + Mathematics + 250024 + 2007-09-01T00:00:00+08:00 + 3 + + +``` + + Now create ElementsWithOnlyAttributes.xml: + +```xml + + + + + + +``` + + And finally, create RepeatingElements.xml: + ```xml - - C1045 - C1061 - Engineering - Mathematics - -``` - + + C1045 + C1061 + Engineering + Mathematics + +``` + Now you can compile and run the following source code. - + ```csharp -using System; -using System.Data; -using System.IO; -using System.Text; -using System.Xml; - -// Use WriteXml method to export the dataset. -static class DataTableHelper { - public static void WriteDataSetToXML(DataSet dataset, String xmlFileName) { - using (FileStream fsWriterStream = new FileStream(xmlFileName, FileMode.Create)) { - using (XmlTextWriter xmlWriter = new XmlTextWriter(fsWriterStream, Encoding.Unicode)) { - dataset.WriteXml(xmlWriter, XmlWriteMode.WriteSchema); - Console.WriteLine("Write {0} to the File {1}.", dataset.DataSetName, xmlFileName); - Console.WriteLine(); - } - } - } - - // Use GetXml method to get the XML data of the dataset and then export to the file. - public static void GetXMLFromDataSet(DataSet dataset, String xmlFileName) { - using (StreamWriter writer = new StreamWriter(xmlFileName)) { - writer.WriteLine(dataset.GetXml()); - Console.WriteLine("Get Xml data from {0} and write to the File {1}.", dataset.DataSetName, xmlFileName); - Console.WriteLine(); - } - } - - // Use ReadXml method to import the dataset from the dataset. - public static void ReadXmlIntoDataSet(DataSet newDataSet, String xmlFileName) { - using (FileStream fsReaderStream = new FileStream(xmlFileName, FileMode.Open)) { - using (XmlTextReader xmlReader = new XmlTextReader(fsReaderStream)) { - newDataSet.ReadXml(xmlReader, XmlReadMode.ReadSchema); - } - } - } - - // Display the columns and value of DataSet. - public static void ShowDataSet(DataSet dataset) { - foreach (DataTable table in dataset.Tables) { - Console.WriteLine("Table {0}:", table.TableName); - ShowDataTable(table); - } - } - - // Display the columns and value of DataTable. - private static void ShowDataTable(DataTable table) { - foreach (DataColumn col in table.Columns) { - Console.Write("{0,-14}", col.ColumnName); - } - Console.WriteLine("{0,-14}", ""); - - foreach (DataRow row in table.Rows) { - if (row.RowState == DataRowState.Deleted) { - foreach (DataColumn col in table.Columns) { - if (col.DataType.Equals(typeof(DateTime))) { - Console.Write("{0,-14:d}", row[col, DataRowVersion.Original]); - } - else if (col.DataType.Equals(typeof(Decimal))) { - Console.Write("{0,-14:C}", row[col, DataRowVersion.Original]); - } - else { - Console.Write("{0,-14}", row[col, DataRowVersion.Original]); - } - } - } - else { - foreach (DataColumn col in table.Columns) { - if (col.DataType.Equals(typeof(DateTime))) { - Console.Write("{0,-14:d}", row[col]); - } - else if (col.DataType.Equals(typeof(Decimal))) { - Console.Write("{0,-14:C}", row[col]); - } - else { - Console.Write("{0,-14}", row[col]); - } - } - } - Console.WriteLine("{0,-14}", ""); - } - } - - // Display the columns of DataSet. - public static void ShowDataSetSchema(DataSet dataSet) { - Console.WriteLine("{0} contains the following tables:", dataSet.DataSetName); - foreach (DataTable table in dataSet.Tables) { - Console.WriteLine(" Table {0} contains the following columns:", table.TableName); - ShowDataTableSchema(table); - } - } - - // Display the columns of DataTable - private static void ShowDataTableSchema(DataTable table) { - String columnString = ""; - foreach (DataColumn col in table.Columns) { - columnString += col.ColumnName + " "; - } - Console.WriteLine(columnString); - } -} - -class Program { - static void Main(string[] args) { - // Create the DataSet - DataSet school = new DataSet("MySchool"); - DataTable course = CreateCourse(); - DataTable department = CreateDepartment(); - school.Tables.Add(course); - school.Tables.Add(department); - - // Define the constraint between the tables. - ForeignKeyConstraint courseDepartFK = new ForeignKeyConstraint("CourseDepartFK", department.Columns["DepartmentID"], course.Columns["DepartmentID"]); - courseDepartFK.DeleteRule = Rule.Cascade; - courseDepartFK.UpdateRule = Rule.Cascade; - courseDepartFK.AcceptRejectRule = AcceptRejectRule.None; - course.Constraints.Add(courseDepartFK); - - InsertDepartments(department); - InsertCourses(course); - - // Export the dataset to the XML file. - Console.WriteLine("Data of the whole DataSet {0}", school.DataSetName); - DataTableHelper.ShowDataSet(school); - - String xmlWithSchemaFileName = "WriterXMLWithSchema.xml"; - String xmlGetDataFileName = "GetXML.xml"; - - // Use two ways to export the dataset to the Xml file. - DataTableHelper.WriteDataSetToXML(school, xmlWithSchemaFileName); - DataTableHelper.GetXMLFromDataSet(school, xmlGetDataFileName); - - // Import the dataset from the XML file. - // Use two ways to import the dataset from the Xml file. - Console.WriteLine("Read Xml document into a new DataSet:"); - DataSet newSchool = new DataSet("NewSchool"); - DataTableHelper.ReadXmlIntoDataSet(newSchool, xmlWithSchemaFileName); - DataTableHelper.ShowDataSetSchema(newSchool); - Console.WriteLine(); - - Console.WriteLine("Infer a schema for a DataSet from an XML document:"); - InferDataSetSchemaFromXml(); - - Console.WriteLine("Press any key to exit."); - Console.ReadKey(); - } - - static DataTable CreateCourse() { - DataTable course = new DataTable("Course"); - DataColumn[] cols ={ - new DataColumn("CourseID",typeof(String)), - new DataColumn("Year",typeof(Int32)), - new DataColumn("Title",typeof(String)), - new DataColumn("Credits",typeof(Int32)), - new DataColumn("DepartmentID",typeof(Int32))}; - course.Columns.AddRange(cols); - - course.PrimaryKey = new DataColumn[] { course.Columns["CourseID"], course.Columns["Year"] }; - - return course; - } - - static DataTable CreateDepartment() { - DataTable department = new DataTable("Department"); - DataColumn[] cols = { - new DataColumn("DepartmentID", typeof(Int32)), - new DataColumn("Name",typeof(String)), - new DataColumn("Budget",typeof(Decimal)), - new DataColumn("StartDate",typeof(DateTime)), - new DataColumn("Administrator",typeof(Int32))}; - department.Columns.AddRange(cols); - - department.PrimaryKey = new DataColumn[] { department.Columns["DepartmentID"] }; - - return department; - } - - static void InsertDepartments(DataTable department) { - Object[] rows = { - new Object[]{1,"Engineering",350000.00,new DateTime(2007,9,1),2}, - new Object[]{2,"English",120000.00,new DateTime(2007,9,1),6}, - new Object[]{4,"Economics",200000.00,new DateTime(2007,9,1),4}, - new Object[]{7,"Mathematics",250024.00,new DateTime(2007,9,1),3}}; - - foreach (Object[] row in rows) { - department.Rows.Add(row); - } - } - - static void InsertCourses(DataTable course) { - Object[] rows ={ - new Object[]{"C1045",2012,"Calculus",4,7}, - new Object[]{"C1061",2012,"Physics",4,1}, - new Object[]{"C2021",2012,"Composition",3,2}, - new Object[]{"C2042",2012,"Literature",4,2}}; - - foreach (Object[] row in rows) { - course.Rows.Add(row); - } - } - - // Display the results of inferring schema from four types of XML structures - private static void InferDataSetSchemaFromXml() { - String[] xmlFileNames = { - - @"ElementsWithOnlyAttributes.xml", - @"ElementsWithAttributes.xml", - @"RepeatingElements.xml", - @"ElementsWithChildElements.xml" }; - - foreach (String xmlFileName in xmlFileNames) { - Console.WriteLine("Result of {0}", Path.GetFileNameWithoutExtension(xmlFileName)); - DataSet newSchool = new DataSet(); - newSchool.InferXmlSchema(xmlFileName, null); - DataTableHelper.ShowDataSetSchema(newSchool); - Console.WriteLine(); - } - } -} -``` - +using System; +using System.Data; +using System.IO; +using System.Text; +using System.Xml; + +// Use WriteXml method to export the dataset. +static class DataTableHelper { + public static void WriteDataSetToXML(DataSet dataset, String xmlFileName) { + using (FileStream fsWriterStream = new FileStream(xmlFileName, FileMode.Create)) { + using (XmlTextWriter xmlWriter = new XmlTextWriter(fsWriterStream, Encoding.Unicode)) { + dataset.WriteXml(xmlWriter, XmlWriteMode.WriteSchema); + Console.WriteLine("Write {0} to the File {1}.", dataset.DataSetName, xmlFileName); + Console.WriteLine(); + } + } + } + + // Use GetXml method to get the XML data of the dataset and then export to the file. + public static void GetXMLFromDataSet(DataSet dataset, String xmlFileName) { + using (StreamWriter writer = new StreamWriter(xmlFileName)) { + writer.WriteLine(dataset.GetXml()); + Console.WriteLine("Get Xml data from {0} and write to the File {1}.", dataset.DataSetName, xmlFileName); + Console.WriteLine(); + } + } + + // Use ReadXml method to import the dataset from the dataset. + public static void ReadXmlIntoDataSet(DataSet newDataSet, String xmlFileName) { + using (FileStream fsReaderStream = new FileStream(xmlFileName, FileMode.Open)) { + using (XmlTextReader xmlReader = new XmlTextReader(fsReaderStream)) { + newDataSet.ReadXml(xmlReader, XmlReadMode.ReadSchema); + } + } + } + + // Display the columns and value of DataSet. + public static void ShowDataSet(DataSet dataset) { + foreach (DataTable table in dataset.Tables) { + Console.WriteLine("Table {0}:", table.TableName); + ShowDataTable(table); + } + } + + // Display the columns and value of DataTable. + private static void ShowDataTable(DataTable table) { + foreach (DataColumn col in table.Columns) { + Console.Write("{0,-14}", col.ColumnName); + } + Console.WriteLine("{0,-14}", ""); + + foreach (DataRow row in table.Rows) { + if (row.RowState == DataRowState.Deleted) { + foreach (DataColumn col in table.Columns) { + if (col.DataType.Equals(typeof(DateTime))) { + Console.Write("{0,-14:d}", row[col, DataRowVersion.Original]); + } + else if (col.DataType.Equals(typeof(Decimal))) { + Console.Write("{0,-14:C}", row[col, DataRowVersion.Original]); + } + else { + Console.Write("{0,-14}", row[col, DataRowVersion.Original]); + } + } + } + else { + foreach (DataColumn col in table.Columns) { + if (col.DataType.Equals(typeof(DateTime))) { + Console.Write("{0,-14:d}", row[col]); + } + else if (col.DataType.Equals(typeof(Decimal))) { + Console.Write("{0,-14:C}", row[col]); + } + else { + Console.Write("{0,-14}", row[col]); + } + } + } + Console.WriteLine("{0,-14}", ""); + } + } + + // Display the columns of DataSet. + public static void ShowDataSetSchema(DataSet dataSet) { + Console.WriteLine("{0} contains the following tables:", dataSet.DataSetName); + foreach (DataTable table in dataSet.Tables) { + Console.WriteLine(" Table {0} contains the following columns:", table.TableName); + ShowDataTableSchema(table); + } + } + + // Display the columns of DataTable + private static void ShowDataTableSchema(DataTable table) { + String columnString = ""; + foreach (DataColumn col in table.Columns) { + columnString += col.ColumnName + " "; + } + Console.WriteLine(columnString); + } +} + +class Program { + static void Main(string[] args) { + // Create the DataSet + DataSet school = new DataSet("MySchool"); + DataTable course = CreateCourse(); + DataTable department = CreateDepartment(); + school.Tables.Add(course); + school.Tables.Add(department); + + // Define the constraint between the tables. + ForeignKeyConstraint courseDepartFK = new ForeignKeyConstraint("CourseDepartFK", department.Columns["DepartmentID"], course.Columns["DepartmentID"]); + courseDepartFK.DeleteRule = Rule.Cascade; + courseDepartFK.UpdateRule = Rule.Cascade; + courseDepartFK.AcceptRejectRule = AcceptRejectRule.None; + course.Constraints.Add(courseDepartFK); + + InsertDepartments(department); + InsertCourses(course); + + // Export the dataset to the XML file. + Console.WriteLine("Data of the whole DataSet {0}", school.DataSetName); + DataTableHelper.ShowDataSet(school); + + String xmlWithSchemaFileName = "WriterXMLWithSchema.xml"; + String xmlGetDataFileName = "GetXML.xml"; + + // Use two ways to export the dataset to the Xml file. + DataTableHelper.WriteDataSetToXML(school, xmlWithSchemaFileName); + DataTableHelper.GetXMLFromDataSet(school, xmlGetDataFileName); + + // Import the dataset from the XML file. + // Use two ways to import the dataset from the Xml file. + Console.WriteLine("Read Xml document into a new DataSet:"); + DataSet newSchool = new DataSet("NewSchool"); + DataTableHelper.ReadXmlIntoDataSet(newSchool, xmlWithSchemaFileName); + DataTableHelper.ShowDataSetSchema(newSchool); + Console.WriteLine(); + + Console.WriteLine("Infer a schema for a DataSet from an XML document:"); + InferDataSetSchemaFromXml(); + + Console.WriteLine("Press any key to exit."); + Console.ReadKey(); + } + + static DataTable CreateCourse() { + DataTable course = new DataTable("Course"); + DataColumn[] cols ={ + new DataColumn("CourseID",typeof(String)), + new DataColumn("Year",typeof(Int32)), + new DataColumn("Title",typeof(String)), + new DataColumn("Credits",typeof(Int32)), + new DataColumn("DepartmentID",typeof(Int32))}; + course.Columns.AddRange(cols); + + course.PrimaryKey = new DataColumn[] { course.Columns["CourseID"], course.Columns["Year"] }; + + return course; + } + + static DataTable CreateDepartment() { + DataTable department = new DataTable("Department"); + DataColumn[] cols = { + new DataColumn("DepartmentID", typeof(Int32)), + new DataColumn("Name",typeof(String)), + new DataColumn("Budget",typeof(Decimal)), + new DataColumn("StartDate",typeof(DateTime)), + new DataColumn("Administrator",typeof(Int32))}; + department.Columns.AddRange(cols); + + department.PrimaryKey = new DataColumn[] { department.Columns["DepartmentID"] }; + + return department; + } + + static void InsertDepartments(DataTable department) { + Object[] rows = { + new Object[]{1,"Engineering",350000.00,new DateTime(2007,9,1),2}, + new Object[]{2,"English",120000.00,new DateTime(2007,9,1),6}, + new Object[]{4,"Economics",200000.00,new DateTime(2007,9,1),4}, + new Object[]{7,"Mathematics",250024.00,new DateTime(2007,9,1),3}}; + + foreach (Object[] row in rows) { + department.Rows.Add(row); + } + } + + static void InsertCourses(DataTable course) { + Object[] rows ={ + new Object[]{"C1045",2012,"Calculus",4,7}, + new Object[]{"C1061",2012,"Physics",4,1}, + new Object[]{"C2021",2012,"Composition",3,2}, + new Object[]{"C2042",2012,"Literature",4,2}}; + + foreach (Object[] row in rows) { + course.Rows.Add(row); + } + } + + // Display the results of inferring schema from four types of XML structures + private static void InferDataSetSchemaFromXml() { + String[] xmlFileNames = { + + @"ElementsWithOnlyAttributes.xml", + @"ElementsWithAttributes.xml", + @"RepeatingElements.xml", + @"ElementsWithChildElements.xml" }; + + foreach (String xmlFileName in xmlFileNames) { + Console.WriteLine("Result of {0}", Path.GetFileNameWithoutExtension(xmlFileName)); + DataSet newSchool = new DataSet(); + newSchool.InferXmlSchema(xmlFileName, null); + DataTableHelper.ShowDataSetSchema(newSchool); + Console.WriteLine(); + } + } +} +``` + ]]> Using DataSets in ADO.NET @@ -2156,23 +2123,23 @@ class Program { Returns the XML Schema for the XML representation of the data stored in the . String that is the XML Schema for the XML representation of the data stored in the . - , except that only the primary schema is written. - - returns XML as a string, and therefore requires more overhead than to write XML to a file. - - If you build a using schema inference and serialize it using XML or Web services, the column ordering may change. - - - -## Examples - The following example creates a and , and then displays the schema in XML format. - + , except that only the primary schema is written. + + returns XML as a string, and therefore requires more overhead than to write XML to a file. + + If you build a using schema inference and serialize it using XML or Web services, the column ordering may change. + + + +## Examples + The following example creates a and , and then displays the schema in XML format. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.GetXmlSchema Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.GetXmlSchema Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.GetXmlSchema Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -2228,14 +2195,14 @@ class Program { if the has changes; otherwise, . - method to create a second object that is then used to update a data source. - + method to create a second object that is then used to update a data source. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.HasChanges Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.HasChanges Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.HasChanges Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -2283,19 +2250,19 @@ class Program { if the has changes; otherwise, . - property of the `DataSet` before invoking the method. - - - -## Examples - The following example uses the method to create a second object, which is then used to update a data source. - + property of the `DataSet` before invoking the method. + + + +## Examples + The following example uses the method to create a second object, which is then used to update a data source. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.GetChanges1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.GetChanges1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.GetChanges1 Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -2349,19 +2316,19 @@ class Program { if any table contains an error; otherwise, . - in a also has a property. Use the `HasErrors` property of the `DataSet` first, to determine if any table has errors, before checking individual objects. If a `DataTable` has errors, the method returns an array of objects containing the errors. - - - -## Examples - The following example uses the property to determine whether a object contains errors. If so, the errors for each in each are printed. - + in a also has a property. Use the `HasErrors` property of the `DataSet` first, to determine if any table has errors, before checking individual objects. If a `DataTable` has errors, the method returns an array of objects containing the errors. + + + +## Examples + The following example uses the property to determine whether a object contains errors. If so, the errors for each in each are printed. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.HasErrors Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.HasErrors Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.HasErrors Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -2681,11 +2648,11 @@ class Program { Occurs after the is initialized. - . - + . + ]]> Using DataSets in ADO.NET @@ -2772,11 +2739,11 @@ class Program { if the specified represents a serialized in its binary format, otherwise. - @@ -2827,12 +2794,12 @@ class Program { to indicate the component has completed initialization; otherwise, . - while it's being constructed, for instance by Visual Studio. The method sets it to `false` and method sets it to `true`. - - ]]> + while it's being constructed, for instance by Visual Studio. The method sets it to `false` and method sets it to `true`. + + ]]> Using DataSets in ADO.NET @@ -2846,35 +2813,35 @@ class Program { Fills a with values from a data source using the supplied . - method provides a technique for filling a single with data, retrieved from an instance. This method provides the same functionality, but allows you to load multiple result sets from an `IDataReader` into multiple tables within a `DataSet`. - - If the `DataSet` already contains rows, the incoming data from the data source is merged with the existing rows. - - The `Load` method can be used in several common scenarios, all centered around getting data from a specified data source and adding it to the current data container (in this case, a `DataSet`). These scenarios describe standard usage for a `DataSet`, describing its update and merge behavior. - - A `DataSet` synchronizes or updates with a single primary data source. The `DataSet` tracks changes, allowing synchronization with the primary data source. In addition, a `DataSet` can accept incremental data from one or more secondary data sources. The `DataSet` isn't responsible for tracking changes in order to allow synchronization with the secondary data source. - - Given these two hypothetical data sources, a user is likely to require one of the following behaviors: - -- Initialize `DataSet` from a primary data source. In this scenario, the user wants to initialize an empty `DataSet` with values from the primary data source. One or more DataTable's contents are modified. Later the user intends to propagate changes back to the primary data source. - -- Preserve changes and re-synchronize from the primary data source. In this scenario, the user wants to take the `DataSet` filled in the previous scenario and perform an incremental synchronization with the primary data source, preserving modifications made in the `DataSet`. - -- Incremental data feed from secondary data sources. In this scenario, the user wants to merge changes from one or more secondary data sources, and propagate those changes back to the primary data source. - - The `Load` method makes all these scenarios possible. This method allows you to specify a load option parameter, indicating how rows already in a combine with rows being loaded. The following table describes the three load options provided by the enumeration. In each case, the description indicates the behavior when the primary key of a row in the incoming data matches the primary key of an existing row. - -|Load Option|Description| -|-----------------|-----------------| -|`PreserveChanges` (default)|Updates the original version of the row with the value of the incoming row.| -|`OverwriteChanges`|Updates the current and original versions of the row with the value of the incoming row.| -|`Upsert`|Updates the current version of the row with the value of the incoming row.| - - In general, the `PreserveChanges` and `OverwriteChanges` options are intended for scenarios in which the user needs to synchronize the `DataSet` and its changes with the primary data source. The `Upsert` option facilitates aggregating changes from one or more secondary data sources. - + method provides a technique for filling a single with data, retrieved from an instance. This method provides the same functionality, but allows you to load multiple result sets from an `IDataReader` into multiple tables within a `DataSet`. + + If the `DataSet` already contains rows, the incoming data from the data source is merged with the existing rows. + + The `Load` method can be used in several common scenarios, all centered around getting data from a specified data source and adding it to the current data container (in this case, a `DataSet`). These scenarios describe standard usage for a `DataSet`, describing its update and merge behavior. + + A `DataSet` synchronizes or updates with a single primary data source. The `DataSet` tracks changes, allowing synchronization with the primary data source. In addition, a `DataSet` can accept incremental data from one or more secondary data sources. The `DataSet` isn't responsible for tracking changes in order to allow synchronization with the secondary data source. + + Given these two hypothetical data sources, a user is likely to require one of the following behaviors: + +- Initialize `DataSet` from a primary data source. In this scenario, the user wants to initialize an empty `DataSet` with values from the primary data source. One or more DataTable's contents are modified. Later the user intends to propagate changes back to the primary data source. + +- Preserve changes and re-synchronize from the primary data source. In this scenario, the user wants to take the `DataSet` filled in the previous scenario and perform an incremental synchronization with the primary data source, preserving modifications made in the `DataSet`. + +- Incremental data feed from secondary data sources. In this scenario, the user wants to merge changes from one or more secondary data sources, and propagate those changes back to the primary data source. + + The `Load` method makes all these scenarios possible. This method allows you to specify a load option parameter, indicating how rows already in a combine with rows being loaded. The following table describes the three load options provided by the enumeration. In each case, the description indicates the behavior when the primary key of a row in the incoming data matches the primary key of an existing row. + +|Load Option|Description| +|-----------------|-----------------| +|`PreserveChanges` (default)|Updates the original version of the row with the value of the incoming row.| +|`OverwriteChanges`|Updates the current and original versions of the row with the value of the incoming row.| +|`Upsert`|Updates the current version of the row with the value of the incoming row.| + + In general, the `PreserveChanges` and `OverwriteChanges` options are intended for scenarios in which the user needs to synchronize the `DataSet` and its changes with the primary data source. The `Upsert` option facilitates aggregating changes from one or more secondary data sources. + ]]> Using DataSets in ADO.NET @@ -2936,28 +2903,28 @@ class Program { An array of instances, from which the method retrieves name and namespace information. Each of these tables must be a member of the contained by this . Fills a with values from a data source using the supplied , using an array of instances to supply the schema and namespace information. - method provides a technique for filling a single with data, retrieved from an instance. This method provides the same functionality, but allows you to load multiple result sets from an into multiple tables within a . - + method provides a technique for filling a single with data, retrieved from an instance. This method provides the same functionality, but allows you to load multiple result sets from an into multiple tables within a . + > [!NOTE] -> The load operation will fail with an if any of the source data columns in the incoming `reader` are computed columns. - - The `loadOption` parameter allows you to specify how you want the imported data to interact with existing data, and can be any of the values from the enumeration. See the documentation for the method for more information on using this parameter. - - The `tables` parameter allows you to specify an array of instances, indicating the order of the tables corresponding to each result set loaded from the reader. The method fills each supplied instance with data from a single result set from the source data reader. After each result set, the method moves on to the next result set within the reader, until there are no more result sets. - - The name resolution scheme for this method is the same as that followed by the method of the class. - - - -## Examples - The following example creates a new , adds two instances to the , and then fills the using the method, retrieving data from a that contains two result sets. Finally, the example displays the contents of the tables in the console window. - +> The load operation will fail with an if any of the source data columns in the incoming `reader` are computed columns. + + The `loadOption` parameter allows you to specify how you want the imported data to interact with existing data, and can be any of the values from the enumeration. See the documentation for the method for more information on using this parameter. + + The `tables` parameter allows you to specify an array of instances, indicating the order of the tables corresponding to each result set loaded from the reader. The method fills each supplied instance with data from a single result set from the source data reader. After each result set, the method moves on to the next result set within the reader, until there are no more result sets. + + The name resolution scheme for this method is the same as that followed by the method of the class. + + + +## Examples + The following example creates a new , adds two instances to the , and then fills the using the method, retrieving data from a that contains two result sets. Finally, the example displays the contents of the tables in the console window. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataSet.LoadTables/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks DataSet.LoadTables/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks DataSet.LoadTables/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -3019,28 +2986,28 @@ class Program { An array of strings, from which the method retrieves table name information. Fills a with values from a data source using the supplied , using an array of strings to supply the names for the tables within the . - method provides a technique for filling a single with data, retrieved from an instance. This method provides the same functionality, but allows you to load multiple result sets from an `IDataReader` into multiple tables within a `DataSet`. - + method provides a technique for filling a single with data, retrieved from an instance. This method provides the same functionality, but allows you to load multiple result sets from an `IDataReader` into multiple tables within a `DataSet`. + > [!NOTE] -> The load operation will fail with an if any of the source data columns in the incoming `reader` are computed columns. - - The `loadOption` parameter allows you to specify how you want the imported data to interact with existing data, and can be any of the values from the enumeration. See the documentation for the method for more information on using this parameter. - - The `tables` parameter allows you to specify an array of table names, indicating the order of the tables corresponding to each result set loaded from the reader. The `Load` method attempts to find a table within the `DataSet` matching the name found in the array of table names, in order. If a matching table is found, that table is loaded with the content of the current result set. If no matching table is found, a table is created using the name supplied in the array of table names, and the new table's schema is inferred from the result set. After each result set, the `Load` method moves on to the next result set within the reader, until there are no more result sets. - - The default namespace associated with `DataSet`, if any, is associated with each newly created `DataTable`. The name resolution scheme for this method is the same as that followed by the method of the class. - - - -## Examples - The following Console application example first creates tables and loads data from a reader into a , using the `Load` method. The example then adds tables to a and attempts to fill the tables with data from a . In this example, because the parameters passed to the `Load` method indicate a table name that does not exist, the `Load` method creates a new table to match the name passed as a parameter. Once the data has been loaded, the example displays the contents of all its tables in the Console window. - +> The load operation will fail with an if any of the source data columns in the incoming `reader` are computed columns. + + The `loadOption` parameter allows you to specify how you want the imported data to interact with existing data, and can be any of the values from the enumeration. See the documentation for the method for more information on using this parameter. + + The `tables` parameter allows you to specify an array of table names, indicating the order of the tables corresponding to each result set loaded from the reader. The `Load` method attempts to find a table within the `DataSet` matching the name found in the array of table names, in order. If a matching table is found, that table is loaded with the content of the current result set. If no matching table is found, a table is created using the name supplied in the array of table names, and the new table's schema is inferred from the result set. After each result set, the `Load` method moves on to the next result set within the reader, until there are no more result sets. + + The default namespace associated with `DataSet`, if any, is associated with each newly created `DataTable`. The name resolution scheme for this method is the same as that followed by the method of the class. + + + +## Examples + The following Console application example first creates tables and loads data from a reader into a , using the `Load` method. The example then adds tables to a and attempts to fill the tables with data from a . In this example, because the parameters passed to the `Load` method indicate a table name that does not exist, the `Load` method creates a new table to match the name passed as a parameter. Once the data has been loaded, the example displays the contents of all its tables in the Console window. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataSet.LoadString/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks DataSet.LoadString/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks DataSet.LoadString/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -3112,30 +3079,30 @@ class Program { An array of instances, from which the method retrieves name and namespace information. Fills a with values from a data source using the supplied , using an array of instances to supply the schema and namespace information. - method provides a technique for filling a single with data, retrieved from an instance. This method provides the same functionality, but allows you to load multiple result sets from an into multiple tables within a . - + method provides a technique for filling a single with data, retrieved from an instance. This method provides the same functionality, but allows you to load multiple result sets from an into multiple tables within a . + > [!NOTE] -> The load operation will fail with an if any of the source data columns in the incoming `reader` are computed columns. - - The `loadOption` parameter allows you to specify how you want the imported data to interact with existing data, and can be any of the values from the enumeration. See the documentation for the method for more information on using this parameter. - - The `errorHandler` parameter is a delegate that refers to a procedure that is called when an error occurs while loading data. The parameter passed to the procedure provides properties that allow you to retrieve information about the error that occurred, the current row of data, and the being filled. Using this delegate mechanism, rather than a simpler try/catch block, allows you to determine the error, handle the situation, and continue processing if you like. The parameter supplies a property: set this property to `true` to indicate that you have handled the error and wish to continue processing; set the property to `false` to indicate that you wish to halt processing. Be aware that setting the property to `false` causes the code that triggered the problem to throw an exception. - - The `tables` parameter allows you to specify an array of instances, indicating the order of the tables corresponding to each result set loaded from the reader. The method fills each supplied instance with data from a single result set from the source data reader. After each result set, the method moves on to the next result set within the reader, until there are no more result sets. - - The name resolution scheme for this method is the same as that followed by the method of the class. - - - -## Examples - The following example adds a table to a , and then attempts to use the method to load data from a that contains an incompatible schema. Rather than trapping the error, this example uses a delegate to investigate and handle the error. The output is displayed in the console window. - +> The load operation will fail with an if any of the source data columns in the incoming `reader` are computed columns. + + The `loadOption` parameter allows you to specify how you want the imported data to interact with existing data, and can be any of the values from the enumeration. See the documentation for the method for more information on using this parameter. + + The `errorHandler` parameter is a delegate that refers to a procedure that is called when an error occurs while loading data. The parameter passed to the procedure provides properties that allow you to retrieve information about the error that occurred, the current row of data, and the being filled. Using this delegate mechanism, rather than a simpler try/catch block, allows you to determine the error, handle the situation, and continue processing if you like. The parameter supplies a property: set this property to `true` to indicate that you have handled the error and wish to continue processing; set the property to `false` to indicate that you wish to halt processing. Be aware that setting the property to `false` causes the code that triggered the problem to throw an exception. + + The `tables` parameter allows you to specify an array of instances, indicating the order of the tables corresponding to each result set loaded from the reader. The method fills each supplied instance with data from a single result set from the source data reader. After each result set, the method moves on to the next result set within the reader, until there are no more result sets. + + The name resolution scheme for this method is the same as that followed by the method of the class. + + + +## Examples + The following example adds a table to a , and then attempts to use the method to load data from a that contains an incompatible schema. Rather than trapping the error, this example uses a delegate to investigate and handle the error. The output is displayed in the console window. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataSet.Load/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks DataSet.Load/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks DataSet.Load/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -3184,23 +3151,23 @@ class Program { Gets or sets the locale information used to compare strings within the table. A that contains data about the user's machine locale. The default is . - property specifies the locale for which sorting applies. - - By default, setting the for a also sets the for each object in that `DataSet` to the same value. - + property specifies the locale for which sorting applies. + + By default, setting the for a also sets the for each object in that `DataSet` to the same value. + > [!NOTE] -> In columns that contain expressions, the is used. The is ignored. - - - -## Examples - The following example gets the for a and prints the and properties. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.Locale Example/VB/source.vb" id="Snippet1"::: - +> In columns that contain expressions, the is used. The is ignored. + + + +## Examples + The following example gets the for a and prints the and properties. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.Locale Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -3257,23 +3224,23 @@ class Program { The array of objects to be merged into the . Merges an array of objects into the current . - method is used to merge two objects that have largely similar schemas. A merge is typically used on a client application to incorporate the latest changes from a data source into an existing . This allows the client application to have a refreshed with the latest data from the data source. - - The method is typically called at the end of a series of procedures that involve validating changes, reconciling errors, updating the data source with the changes, and finally refreshing the existing . - - In a client application, it is common to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle-tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller and thus more efficiently passed back to a middle-tier component. The middle-tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. - - When the method is called, the schemas of the two objects are compared because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. - - After merging schemas, the data is merged. - - When merging a new source into the target, any source rows with a value of `Unchanged`, `Modified`, or `Deleted` are matched to target rows with the same primary key values. Source rows with a value of `Added` are matched to new target rows with the same primary key values as the new source rows. - - During a merge, constraints are disabled. If any constraints cannot be enabled at the end of a merge, a is generated and the merged data is retained while the constraints are disabled. In this case, the property is set to `false`, and all rows that are invalid are marked in error. The errors must be resolved before attempting to reset the property to `true`. - + method is used to merge two objects that have largely similar schemas. A merge is typically used on a client application to incorporate the latest changes from a data source into an existing . This allows the client application to have a refreshed with the latest data from the data source. + + The method is typically called at the end of a series of procedures that involve validating changes, reconciling errors, updating the data source with the changes, and finally refreshing the existing . + + In a client application, it is common to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle-tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller and thus more efficiently passed back to a middle-tier component. The middle-tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. + + When the method is called, the schemas of the two objects are compared because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. + + After merging schemas, the data is merged. + + When merging a new source into the target, any source rows with a value of `Unchanged`, `Modified`, or `Deleted` are matched to target rows with the same primary key values. Source rows with a value of `Added` are matched to new target rows with the same primary key values as the new source rows. + + During a merge, constraints are disabled. If any constraints cannot be enabled at the end of a merge, a is generated and the merged data is retained while the constraints are disabled. In this case, the property is set to `false`, and all rows that are invalid are marked in error. The errors must be resolved before attempting to reset the property to `true`. + ]]> Using DataSets in ADO.NET @@ -3319,31 +3286,31 @@ class Program { The whose data and schema will be merged. Merges a specified and its schema into the current . - method is used to merge two objects that have largely similar schemas. A merge is typically used on a client application to incorporate the latest changes from a data source into an existing . This allows the client application to have a refreshed with the latest data from the data source. - - The method is typically called at the end of a series of procedures that involve validating changes, reconciling errors, updating the data source with the changes, and finally refreshing the existing . - - In a client application, it is common to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle-tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller, and thus more efficiently passed back to a middle-tier component. The middle-tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. - - When the method is called, the schemas of the two objects are compared because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. - - After merging schemas, the data is merged. - - When merging a new source into the target, any source rows with a value of `Unchanged`, `Modified`, or `Deleted` are matched to target rows with the same primary key values. Source rows with a `DataRowState` value of `Added` are matched to new target rows with the same primary key values as the new source rows. - - During a merge, constraints are disabled. If any constraints cannot be enabled at the end of merge, a is generated and the merged data is retained while the constraints are disabled. In this case, the property is set to `false`, and all rows that are invalid are marked in error. The errors must be resolved before attempting to reset the property to `true`. - - - -## Examples - The following example uses the , Update, and methods on a . - + method is used to merge two objects that have largely similar schemas. A merge is typically used on a client application to incorporate the latest changes from a data source into an existing . This allows the client application to have a refreshed with the latest data from the data source. + + The method is typically called at the end of a series of procedures that involve validating changes, reconciling errors, updating the data source with the changes, and finally refreshing the existing . + + In a client application, it is common to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle-tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller, and thus more efficiently passed back to a middle-tier component. The middle-tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. + + When the method is called, the schemas of the two objects are compared because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. + + After merging schemas, the data is merged. + + When merging a new source into the target, any source rows with a value of `Unchanged`, `Modified`, or `Deleted` are matched to target rows with the same primary key values. Source rows with a `DataRowState` value of `Added` are matched to new target rows with the same primary key values as the new source rows. + + During a merge, constraints are disabled. If any constraints cannot be enabled at the end of merge, a is generated and the merged data is retained while the constraints are disabled. In this case, the property is set to `false`, and all rows that are invalid are marked in error. The errors must be resolved before attempting to reset the property to `true`. + + + +## Examples + The following example uses the , Update, and methods on a . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.Merge Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.Merge Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.Merge Example/VB/source.vb" id="Snippet1"::: + ]]> One or more constraints cannot be enabled. @@ -3394,31 +3361,31 @@ class Program { The whose data and schema will be merged. Merges a specified and its schema into the current . - method is used to merge two objects that have largely similar schemas. A merge is typically used on a client application to incorporate the latest changes from a data source into an existing . This allows the client application to have a refreshed with the latest data from the data source. - - The method is typically called at the end of a series of procedures that involve validating changes, reconciling errors, updating the data source with the changes, and finally refreshing the existing . - - In a client application, it is common to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle-tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller, and thus more efficiently passed back to a middle-tier component. The middle-tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. - - When the method is called, the schemas of the two objects are compared because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. - - After merging schemas, the data is merged. - - When merging a new source into the target, any source rows with a value of `Unchanged`, `Modified`, or `Deleted` are matched to target rows with the same primary key values. Source rows with a `DataRowState` value of `Added` are matched to new target rows with the same primary key values as the new source rows. - - During a merge, constraints are disabled. If any constraints cannot be enabled at the end of merge, a is generated and the merged data is retained while the constraints are disabled. In this case, the property is set to `false`, and all rows that are invalid are marked in error. The errors must be resolved before attempting to reset the property to `true`. - - - -## Examples - The following example creates a simple with one table, two columns, and ten rows. A second is created that is identical to the first. Two rows are added to the second table, which is then merged into the . - + method is used to merge two objects that have largely similar schemas. A merge is typically used on a client application to incorporate the latest changes from a data source into an existing . This allows the client application to have a refreshed with the latest data from the data source. + + The method is typically called at the end of a series of procedures that involve validating changes, reconciling errors, updating the data source with the changes, and finally refreshing the existing . + + In a client application, it is common to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle-tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller, and thus more efficiently passed back to a middle-tier component. The middle-tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. + + When the method is called, the schemas of the two objects are compared because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. + + After merging schemas, the data is merged. + + When merging a new source into the target, any source rows with a value of `Unchanged`, `Modified`, or `Deleted` are matched to target rows with the same primary key values. Source rows with a `DataRowState` value of `Added` are matched to new target rows with the same primary key values as the new source rows. + + During a merge, constraints are disabled. If any constraints cannot be enabled at the end of merge, a is generated and the merged data is retained while the constraints are disabled. In this case, the property is set to `false`, and all rows that are invalid are marked in error. The errors must be resolved before attempting to reset the property to `true`. + + + +## Examples + The following example creates a simple with one table, two columns, and ten rows. A second is created that is identical to the first. Two rows are added to the second table, which is then merged into the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.Merge3 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.Merge3 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.Merge3 Example/VB/source.vb" id="Snippet1"::: + ]]> The is . @@ -3468,31 +3435,31 @@ class Program { to preserve changes in the current ; otherwise, . Merges a specified and its schema into the current , preserving or discarding any changes in this according to the given argument. - method is used to merge two objects that have largely similar schemas. A merge is typically used on a client application to incorporate the latest changes from a data source into an existing . This allows the client application to have a refreshed with the latest data from the data source. - - The method is typically called at the end of a series of procedures that involve validating changes, reconciling errors, updating the data source with the changes, and finally refreshing the existing . - - In a client application, it is common to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle-tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller, and thus more efficiently passed back to a middle-tier component. The middle-tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. - - When the method is called, the schemas of the two objects are compared because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. - - After merging schemas, the data is merged. - - When merging a new source into the target, any source rows with a value of `Unchanged`, `Modified`, or `Deleted` are matched to target rows with the same primary key values. Source rows with a `DataRowState` value of `Added` are matched to new target rows with the same primary key values as the new source rows. - - During a merge, constraints are disabled. If any constraints cannot be enabled at the end of merge, a is generated and the merged data is retained while the constraints are disabled. In this case, the property is set to `false`, and all rows that are invalid are marked in error. The errors must be resolved before attempting to reset the property to `true`. - - - -## Examples - The following example creates a simple with one table, two columns, and ten rows. After adding ten rows, two values are changed, and one row is added. A subset of the changed data is created using the method. After reconciling errors, the subset data is merged into the original . - + method is used to merge two objects that have largely similar schemas. A merge is typically used on a client application to incorporate the latest changes from a data source into an existing . This allows the client application to have a refreshed with the latest data from the data source. + + The method is typically called at the end of a series of procedures that involve validating changes, reconciling errors, updating the data source with the changes, and finally refreshing the existing . + + In a client application, it is common to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle-tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller, and thus more efficiently passed back to a middle-tier component. The middle-tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. + + When the method is called, the schemas of the two objects are compared because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. + + After merging schemas, the data is merged. + + When merging a new source into the target, any source rows with a value of `Unchanged`, `Modified`, or `Deleted` are matched to target rows with the same primary key values. Source rows with a `DataRowState` value of `Added` are matched to new target rows with the same primary key values as the new source rows. + + During a merge, constraints are disabled. If any constraints cannot be enabled at the end of merge, a is generated and the merged data is retained while the constraints are disabled. In this case, the property is set to `false`, and all rows that are invalid are marked in error. The errors must be resolved before attempting to reset the property to `true`. + + + +## Examples + The following example creates a simple with one table, two columns, and ten rows. After adding ten rows, two values are changed, and one row is added. A subset of the changed data is created using the method. After reconciling errors, the subset data is merged into the original . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.GetChanges Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.GetChanges Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.GetChanges Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -3545,25 +3512,25 @@ class Program { One of the values. Merges an array of objects into the current , preserving or discarding changes in the and handling an incompatible schema according to the given arguments. - method is used to merge two objects that have largely similar schemas. A merge is typically used on a client application to incorporate the latest changes from a data source into an existing . This allows the client application to have a refreshed with the latest data from the data source. - - The method is typically called at the end of a series of procedures that involve validating changes, reconciling errors, updating the data source with the changes, and finally refreshing the existing . - - In a client application, it is common to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle-tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller, and thus more efficiently passed back to a middle-tier component. The middle-tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. - - To facilitate explanation of the method, we use "target" to signify the current , and "source" to name the second (parameter) . The target is so named because it is the object upon which an action (the merge) occurs. The second is called a "source" because the information it contains does not change, but instead is merged into the current . - - When the method is called, the schemas of the two objects are compared because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. - - After merging schemas, the data is merged. - - When merging a new source into the target, any source rows with a value of `Unchanged`, `Modified`, or `Deleted` are matched to target rows with the same primary key values. Source rows with a `DataRowState` value of `Added` are matched to new target rows with the same primary key values as the new source rows. - - During a merge, constraints are disabled. If any constraints cannot be enabled at the end of merge, a is generated and the merged data is retained while the constraints are disabled. In this case, the property is set to `false`, and all rows that are invalid are marked in error. The errors must be resolved before attempting to reset the property to `true`. - + method is used to merge two objects that have largely similar schemas. A merge is typically used on a client application to incorporate the latest changes from a data source into an existing . This allows the client application to have a refreshed with the latest data from the data source. + + The method is typically called at the end of a series of procedures that involve validating changes, reconciling errors, updating the data source with the changes, and finally refreshing the existing . + + In a client application, it is common to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle-tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller, and thus more efficiently passed back to a middle-tier component. The middle-tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. + + To facilitate explanation of the method, we use "target" to signify the current , and "source" to name the second (parameter) . The target is so named because it is the object upon which an action (the merge) occurs. The second is called a "source" because the information it contains does not change, but instead is merged into the current . + + When the method is called, the schemas of the two objects are compared because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. + + After merging schemas, the data is merged. + + When merging a new source into the target, any source rows with a value of `Unchanged`, `Modified`, or `Deleted` are matched to target rows with the same primary key values. Source rows with a `DataRowState` value of `Added` are matched to new target rows with the same primary key values as the new source rows. + + During a merge, constraints are disabled. If any constraints cannot be enabled at the end of merge, a is generated and the merged data is retained while the constraints are disabled. In this case, the property is set to `false`, and all rows that are invalid are marked in error. The errors must be resolved before attempting to reset the property to `true`. + ]]> Using DataSets in ADO.NET @@ -3614,33 +3581,33 @@ class Program { One of the values. Merges a specified and its schema with the current , preserving or discarding changes in the current and handling an incompatible schema according to the given arguments. - method is used to merge two objects that have largely similar schemas. A merge is typically used on a client application to incorporate the latest changes from a data source into an existing . This allows the client application to have a refreshed with the latest data from the data source. - - The method is typically called at the end of a series of procedures that involve validating changes, reconciling errors, updating the data source with the changes, and finally refreshing the existing . - - In a client application, it is common to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle-tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller, and thus more efficiently passed back to a middle-tier component. The middle-tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. - - To facilitate explanation of the method, we use "target" to signify the current , and "source" to name the second (parameter) . The target is so named because it is the object upon which an action (the merge) occurs. The second is called a "source" because the information it contains does not change, but instead is merged into the current . - - When the method is called, the schemas of the two objects are compared because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. - - After merging schemas, the data is merged. - - When merging a new source into the target, any source rows with a value of `Unchanged`, `Modified`, or `Deleted` are matched to target rows with the same primary key values. Source rows with a `DataRowState` value of `Added` are matched to new target rows with the same primary key values as the new source rows. - - During a merge, constraints are disabled. If any constraints cannot be enabled at the end of merge, a is generated and the merged data is retained while the constraints are disabled. In this case, the property is set to `false`, and all rows that are invalid are marked in error. The errors must be resolved before attempting to reset the property to `true`. - - - -## Examples - The following example creates a simple with one table, two columns, and ten rows. Two values are changed, and one row is added. A subset of the changed data is created using the method. After reconciling errors, a new column is added to the subset, changing the schema. When the method is called with the `missingSchemaAction` set to `MissingSchemaAction.Add`, the new column is added to the original object's schema. - + method is used to merge two objects that have largely similar schemas. A merge is typically used on a client application to incorporate the latest changes from a data source into an existing . This allows the client application to have a refreshed with the latest data from the data source. + + The method is typically called at the end of a series of procedures that involve validating changes, reconciling errors, updating the data source with the changes, and finally refreshing the existing . + + In a client application, it is common to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle-tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller, and thus more efficiently passed back to a middle-tier component. The middle-tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. + + To facilitate explanation of the method, we use "target" to signify the current , and "source" to name the second (parameter) . The target is so named because it is the object upon which an action (the merge) occurs. The second is called a "source" because the information it contains does not change, but instead is merged into the current . + + When the method is called, the schemas of the two objects are compared because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. + + After merging schemas, the data is merged. + + When merging a new source into the target, any source rows with a value of `Unchanged`, `Modified`, or `Deleted` are matched to target rows with the same primary key values. Source rows with a `DataRowState` value of `Added` are matched to new target rows with the same primary key values as the new source rows. + + During a merge, constraints are disabled. If any constraints cannot be enabled at the end of merge, a is generated and the merged data is retained while the constraints are disabled. In this case, the property is set to `false`, and all rows that are invalid are marked in error. The errors must be resolved before attempting to reset the property to `true`. + + + +## Examples + The following example creates a simple with one table, two columns, and ten rows. Two values are changed, and one row is added. A subset of the changed data is created using the method. After reconciling errors, a new column is added to the subset, changing the schema. When the method is called with the `missingSchemaAction` set to `MissingSchemaAction.Add`, the new column is added to the original object's schema. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.Merge2 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.Merge2 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.Merge2 Example/VB/source.vb" id="Snippet1"::: + ]]> The is . @@ -3692,31 +3659,31 @@ class Program { to preserve changes in the ; otherwise, . Merges a specified and its schema into the current , preserving or discarding changes in the and handling an incompatible schema according to the given arguments. - method is used to merge two objects that have largely similar schemas. A merge is typically used on a client application to incorporate the latest changes from a data source into an existing . This allows the client application to have a refreshed with the latest data from the data source. - - The method is typically called at the end of a series of procedures that involve validating changes, reconciling errors, updating the data source with the changes, and finally refreshing the existing . - - iOn a client application, it is common to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle-tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller, and thus more efficiently passed back to a middle-tier component. The middle-tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. - - When the method is called, the schemas of the two objects are compared because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. - - After merging schemas, the data is merged. - - When merging a new source into the target, any source rows with a value of `Unchanged`, `Modified`, or `Deleted` are matched to target rows with the same primary key values. Source rows with a `DataRowState` value of `Added` are matched to new target rows with the same primary key values as the new source rows. - - During a merge, constraints are disabled. If any constraints cannot be enabled at the end of merge, a is generated and the merged data is retained while the constraints are disabled. In this case, the property is set to `false`, and all rows that are invalid are marked in error. The errors must be resolved before attempting to reset the property to `true`. - - - -## Examples - The following example creates a simple with one table, two columns, and ten rows. A second is created that is nearly identical to the first except that a new `DataColumn` is added to the table. Two rows are added to the second table, which is then merged into the with the `preserveChanges` argument set to `false`, and the `missingSchemaAction` argument set to `MissingSchemaAction.Add`. - + method is used to merge two objects that have largely similar schemas. A merge is typically used on a client application to incorporate the latest changes from a data source into an existing . This allows the client application to have a refreshed with the latest data from the data source. + + The method is typically called at the end of a series of procedures that involve validating changes, reconciling errors, updating the data source with the changes, and finally refreshing the existing . + + iOn a client application, it is common to have a single button that the user can click that gathers the changed data and validates it before sending it back to a middle-tier component. In this scenario, the method is first invoked. That method returns a second optimized for validating and merging. This second object contains only the and objects that were changed, resulting in a subset of the original . This subset is generally smaller, and thus more efficiently passed back to a middle-tier component. The middle-tier component then updates the original data source with the changes through stored procedures. The middle tier can then send back either a new that includes original data and the latest data from the data source (by running the original query again), or it can send back the subset with any changes that have been made to it from the data source. (For example, if the data source automatically creates unique primary key values, these values can be propagated back to the client application.) In either case, the returned can be merged back into the client application's original with the method. + + When the method is called, the schemas of the two objects are compared because it is possible that the schemas may have been changed. For example, in a business-to-business scenario, new columns may have been added to an XML schema by an automated process. If the source contains schema elements (added objects) that are missing in the target, the schema elements can be added to the target by setting the `missingSchemaAction` argument to `MissingSchemaAction.Add`. In that case, the merged contains the added schema and data. + + After merging schemas, the data is merged. + + When merging a new source into the target, any source rows with a value of `Unchanged`, `Modified`, or `Deleted` are matched to target rows with the same primary key values. Source rows with a `DataRowState` value of `Added` are matched to new target rows with the same primary key values as the new source rows. + + During a merge, constraints are disabled. If any constraints cannot be enabled at the end of merge, a is generated and the merged data is retained while the constraints are disabled. In this case, the property is set to `false`, and all rows that are invalid are marked in error. The errors must be resolved before attempting to reset the property to `true`. + + + +## Examples + The following example creates a simple with one table, two columns, and ten rows. A second is created that is nearly identical to the first except that a new `DataColumn` is added to the table. Two rows are added to the second table, which is then merged into the with the `preserveChanges` argument set to `false`, and the `missingSchemaAction` argument set to `MissingSchemaAction.Add`. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.Merge4 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.Merge4 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.Merge4 Example/VB/source.vb" id="Snippet1"::: + ]]> The is . @@ -3778,19 +3745,19 @@ class Program { Occurs when a target and source have the same primary key value, and is set to true. - event. - + event. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.MergeFailed Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.MergeFailed Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.MergeFailed Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -3843,21 +3810,21 @@ class Program { Gets or sets the namespace of the . The namespace of the . - property is used when reading and writing an XML document into the using the , , , or methods. - - The namespace of an XML document is used to scope XML attributes and elements when read into a . For example, if a contains a schema that was read from a document with the namespace "myCompany," and an attempt is made to read data only from a document with a different namespace, any data that does not correspond to the existing schema is ignored. - - - -## Examples - The following example sets the before calling the method. - + property is used when reading and writing an XML document into the using the , , , or methods. + + The namespace of an XML document is used to scope XML attributes and elements when read into a . For example, if a contains a schema that was read from a document with the namespace "myCompany," and an attempt is made to read data only from a document with a different namespace, any data that does not correspond to the existing schema is ignored. + + + +## Examples + The following example sets the before calling the method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.Namespace Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.Namespace Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.Namespace Example/VB/source.vb" id="Snippet1"::: + ]]> The namespace already has data. @@ -3908,11 +3875,11 @@ class Program { A that contains the event data. Raises the event. - @@ -3961,11 +3928,11 @@ class Program { The being removed. Occurs when a object is removed from a . - Using DataSets in ADO.NET @@ -4015,19 +3982,19 @@ class Program { The being removed. Occurs when a is removed from a . - with the method overridden. - + with the method overridden. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.OnRemoveTable Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.OnRemoveTable Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.OnRemoveTable Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -4080,19 +4047,19 @@ class Program { Gets or sets an XML prefix that aliases the namespace of the . The XML prefix for the namespace. - property is used throughout an XML document to identify elements which belong to the namespace of the object (as set by the property). - - - -## Examples - The following example sets the before calling the method. - + property is used throughout an XML document to identify elements which belong to the namespace of the object (as set by the property). + + + +## Examples + The following example sets the before calling the method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.Namespace Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.Namespace Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.Namespace Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -4204,46 +4171,46 @@ class Program { Reads XML schema and data into the using the specified . The used to read the data. - method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. - - Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. - + method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. + + Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. + > [!NOTE] -> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . - - If an in-line schema is specified, the in-line schema is used to extend the existing relational structure prior to loading the data. If there are any conflicts (for example, the same column in the same table defined with different data types) an exception is raised. - - If no in-line schema is specified, the relational structure is extended through inference, as necessary, according to the structure of the XML document. If the schema cannot be extended through inference in order to expose all data, an exception is raised. - +> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . + + If an in-line schema is specified, the in-line schema is used to extend the existing relational structure prior to loading the data. If there are any conflicts (for example, the same column in the same table defined with different data types) an exception is raised. + + If no in-line schema is specified, the relational structure is extended through inference, as necessary, according to the structure of the XML document. If the schema cannot be extended through inference in order to expose all data, an exception is raised. + > [!NOTE] -> The `DataSet` does not associate an XML element with its corresponding `DataColumn` or `DataTable` when legal XML characters like ("_") are escaped in the serialized XML. The `DataSet` itself only escapes illegal XML characters in XML element names and hence can only consume the same. When legal characters in XML element name are escaped, the element is ignored while processing. - - If the XML Schema for a includes `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema, as the following example demonstrates. - -``` - - -``` - +> The `DataSet` does not associate an XML element with its corresponding `DataColumn` or `DataTable` when legal XML characters like ("_") are escaped in the serialized XML. The `DataSet` itself only escapes illegal XML characters in XML element names and hence can only consume the same. When legal characters in XML element name are escaped, the element is ignored while processing. + + If the XML Schema for a includes `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema, as the following example demonstrates. + +``` + + +``` + > [!NOTE] -> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. - - - -## Examples - The following example first creates a simple with one , two columns, and ten rows. The schema and data are written to disk by invoking the method. A second is created and the method is used to fill it with schema and data. - +> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. + + + +## Examples + The following example first creates a simple with one , two columns, and ten rows. The schema and data are written to disk by invoking the method. A second is created and the method is used to fill it with schema and data. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXml1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXml1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXml1 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -4304,48 +4271,48 @@ class Program { Reads XML schema and data into the using the specified . The used to read the data. - method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. - - Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. - + method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. + + Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. + > [!NOTE] -> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . - - If an in-line schema is specified, the in-line schema is used to extend the existing relational structure prior to loading the data. If there are any conflicts (for example, the same column in the same table defined with different data types) an exception is raised. - - If no in-line schema is specified, the relational structure is extended through inference, as necessary, according to the structure of the XML document. If the schema cannot be extended through inference in order to expose all data, an exception is raised. - +> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . + + If an in-line schema is specified, the in-line schema is used to extend the existing relational structure prior to loading the data. If there are any conflicts (for example, the same column in the same table defined with different data types) an exception is raised. + + If no in-line schema is specified, the relational structure is extended through inference, as necessary, according to the structure of the XML document. If the schema cannot be extended through inference in order to expose all data, an exception is raised. + > [!NOTE] -> The `DataSet` does not associate an XML element with its corresponding `DataColumn` or `DataTable` when legal XML characters like ("_") are escaped in the serialized XML. The `DataSet` itself only escapes illegal XML characters in XML element names and hence can only consume the same. When legal characters in XML element name are escaped, the element is ignored while processing. - - If the XML Schema for a includes `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema as the following example demonstrates. - -``` - - -``` - - Classes that inherit from the class include the and classes. - +> The `DataSet` does not associate an XML element with its corresponding `DataColumn` or `DataTable` when legal XML characters like ("_") are escaped in the serialized XML. The `DataSet` itself only escapes illegal XML characters in XML element names and hence can only consume the same. When legal characters in XML element name are escaped, the element is ignored while processing. + + If the XML Schema for a includes `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema as the following example demonstrates. + +``` + + +``` + + Classes that inherit from the class include the and classes. + > [!NOTE] -> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. - - - -## Examples - The following example first creates a simple with one , two columns, and ten rows. The schema and data are written to disk by invoking the method. A second is created and the method is used to fill it with schema and data. - +> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. + + + +## Examples + The following example first creates a simple with one , two columns, and ten rows. The schema and data are written to disk by invoking the method. A second is created and the method is used to fill it with schema and data. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXml2 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXml2 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXml2 Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -4398,46 +4365,46 @@ class Program { Reads XML schema and data into the using the specified file. The used to read the data. - method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. - - Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. - + method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. + + Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. + > [!NOTE] -> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . - - If an in-line schema is specified, the in-line schema is used to extend the existing relational structure prior to loading the data. If there are any conflicts (for example, the same column in the same table defined with different data types) an exception is raised. - - If no in-line schema is specified, the relational structure is extended through inference, as necessary, according to the structure of the XML document. If the schema cannot be extended through inference in order to expose all data, an exception is raised. - +> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . + + If an in-line schema is specified, the in-line schema is used to extend the existing relational structure prior to loading the data. If there are any conflicts (for example, the same column in the same table defined with different data types) an exception is raised. + + If no in-line schema is specified, the relational structure is extended through inference, as necessary, according to the structure of the XML document. If the schema cannot be extended through inference in order to expose all data, an exception is raised. + > [!NOTE] -> The `DataSet` does not associate an XML element with its corresponding `DataColumn` or `DataTable` when legal XML characters like ("_") are escaped in the serialized XML. The `DataSet` itself only escapes illegal XML characters in XML element names and hence can only consume the same. When legal characters in XML element name are escaped, the element is ignored while processing. - - If the XML Schema for a includes a `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema as the following example demonstrates. - -``` - - -``` - +> The `DataSet` does not associate an XML element with its corresponding `DataColumn` or `DataTable` when legal XML characters like ("_") are escaped in the serialized XML. The `DataSet` itself only escapes illegal XML characters in XML element names and hence can only consume the same. When legal characters in XML element name are escaped, the element is ignored while processing. + + If the XML Schema for a includes a `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema as the following example demonstrates. + +``` + + +``` + > [!NOTE] -> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. - - - -## Examples - The following example first creates a simple with one , two columns, and ten rows. The schema and data are written to disk by invoking the method. A second is created and the method is used to fill it with schema and data. - +> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. + + + +## Examples + The following example first creates a simple with one , two columns, and ten rows. The schema and data are written to disk by invoking the method. A second is created and the method is used to fill it with schema and data. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXml3 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXml3 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXml3 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -4497,48 +4464,48 @@ class Program { Reads XML schema and data into the using the specified . The used to read the data. - method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. - - Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. - + method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. + + Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. + > [!NOTE] -> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . - - If an in-line schema is specified, the in-line schema is used to extend the existing relational structure prior to loading the data. If there are any conflicts (for example, the same column in the same table defined with different data types) an exception is raised. - - If no in-line schema is specified, the relational structure is extended through inference, as necessary, according to the structure of the XML document. If the schema cannot be extended through inference in order to expose all data, an exception is raised. - +> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . + + If an in-line schema is specified, the in-line schema is used to extend the existing relational structure prior to loading the data. If there are any conflicts (for example, the same column in the same table defined with different data types) an exception is raised. + + If no in-line schema is specified, the relational structure is extended through inference, as necessary, according to the structure of the XML document. If the schema cannot be extended through inference in order to expose all data, an exception is raised. + > [!NOTE] -> The `DataSet` does not associate an XML element with its corresponding `DataColumn` or `DataTable` when legal XML characters like ("_") are escaped in the serialized XML. The `DataSet` itself only escapes illegal XML characters in XML element names and hence can only consume the same. When legal characters in XML element name are escaped, the element is ignored while processing. - - If the XML Schema for a includes a `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema as the following example demonstrates. - -``` - - -``` - - inherits from . - +> The `DataSet` does not associate an XML element with its corresponding `DataColumn` or `DataTable` when legal XML characters like ("_") are escaped in the serialized XML. The `DataSet` itself only escapes illegal XML characters in XML element names and hence can only consume the same. When legal characters in XML element name are escaped, the element is ignored while processing. + + If the XML Schema for a includes a `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema as the following example demonstrates. + +``` + + +``` + + inherits from . + > [!NOTE] -> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. - - - -## Examples - The following example first creates a simple with one , two columns, and ten rows. The schema and data are written to disk by invoking the method. A second is created and the method is used to fill it with schema and data. - +> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. + + + +## Examples + The following example first creates a simple with one , two columns, and ten rows. The schema and data are written to disk by invoking the method. A second is created and the method is used to fill it with schema and data. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXml Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXml Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXml Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -4598,41 +4565,41 @@ class Program { Reads XML schema and data into the using the specified and . The used to read the data. - method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. - - The same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. - + method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. + + The same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. + > [!NOTE] -> When you use and you set to `Diffgram`, the content of the target `DataSet` and the original `DataSet` may differ because of how the diffgram is generated and processed. For more information on diffgrams, see [DiffGrams](/dotnet/framework/data/adonet/dataset-datatable-dataview/diffgrams). - +> When you use and you set to `Diffgram`, the content of the target `DataSet` and the original `DataSet` may differ because of how the diffgram is generated and processed. For more information on diffgrams, see [DiffGrams](/dotnet/framework/data/adonet/dataset-datatable-dataview/diffgrams). + > [!NOTE] -> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . - - If an in-line schema is specified, the in-line schema is used to extend the existing relational structure prior to loading the data. If there are any conflicts (for example, the same column in the same table defined with different data types) an exception is raised. - - If no in-line schema is specified, the relational structure is extended through inference, as necessary, according to the structure of the XML document. If the schema cannot be extended through inference in order to expose all data, an exception is raised. - +> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . + + If an in-line schema is specified, the in-line schema is used to extend the existing relational structure prior to loading the data. If there are any conflicts (for example, the same column in the same table defined with different data types) an exception is raised. + + If no in-line schema is specified, the relational structure is extended through inference, as necessary, according to the structure of the XML document. If the schema cannot be extended through inference in order to expose all data, an exception is raised. + > [!NOTE] -> The `DataSet` does not associate an XML element with its corresponding `DataColumn` or `DataTable` when legal XML characters like ("_") are escaped in the serialized XML. The `DataSet` itself only escapes illegal XML characters in XML element names and hence can only consume the same. When legal characters in XML element name are escaped, the element is ignored while processing. - - If the XML Schema for a includes `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema as the following example demonstrates. - -``` - - -``` - +> The `DataSet` does not associate an XML element with its corresponding `DataColumn` or `DataTable` when legal XML characters like ("_") are escaped in the serialized XML. The `DataSet` itself only escapes illegal XML characters in XML element names and hence can only consume the same. When legal characters in XML element name are escaped, the element is ignored while processing. + + If the XML Schema for a includes `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema as the following example demonstrates. + +``` + + +``` + > [!NOTE] -> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. - +> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. + ]]> Using DataSets in ADO.NET @@ -4692,38 +4659,38 @@ class Program { Reads XML schema and data into the using the specified and . The used to read the data. - method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. - - Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. - + method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. + + Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. + > [!NOTE] -> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . - - If an in-line schema is specified, the in-line schema is used to extend the existing relational structure prior to loading the data. If there are any conflicts (for example, the same column in the same table defined with different data types) an exception is raised. - - If no in-line schema is specified, the relational structure is extended through inference, as necessary, according to the structure of the XML document. If the schema cannot be extended through inference in order to expose all data, an exception is raised. - +> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . + + If an in-line schema is specified, the in-line schema is used to extend the existing relational structure prior to loading the data. If there are any conflicts (for example, the same column in the same table defined with different data types) an exception is raised. + + If no in-line schema is specified, the relational structure is extended through inference, as necessary, according to the structure of the XML document. If the schema cannot be extended through inference in order to expose all data, an exception is raised. + > [!NOTE] -> The `DataSet` does not associate an XML element with its corresponding `DataColumn` or `DataTable` when legal XML characters like ("_") are escaped in the serialized XML. The `DataSet` itself only escapes illegal XML characters in XML element names and hence can only consume the same. When legal characters in XML element name are escaped, the element is ignored while processing. - - If the XML Schema for a includes `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema as the following example demonstrates. - -``` - - -``` - +> The `DataSet` does not associate an XML element with its corresponding `DataColumn` or `DataTable` when legal XML characters like ("_") are escaped in the serialized XML. The `DataSet` itself only escapes illegal XML characters in XML element names and hence can only consume the same. When legal characters in XML element name are escaped, the element is ignored while processing. + + If the XML Schema for a includes `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema as the following example demonstrates. + +``` + + +``` + > [!NOTE] -> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. - +> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. + ]]> Using DataSets in ADO.NET @@ -4778,38 +4745,38 @@ class Program { Reads XML schema and data into the using the specified file and . The used to read the data. - method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. - - Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. - + method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. + + Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. + > [!NOTE] -> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . - - If an in-line schema is specified, the in-line schema is used to extend the existing relational structure prior to loading the data. If there are any conflicts (for example, the same column in the same table defined with different data types) an exception is raised. - - If no in-line schema is specified, the relational structure is extended through inference, as necessary, according to the structure of the XML document. If the schema cannot be extended through inference in order to expose all data, an exception is raised. - +> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . + + If an in-line schema is specified, the in-line schema is used to extend the existing relational structure prior to loading the data. If there are any conflicts (for example, the same column in the same table defined with different data types) an exception is raised. + + If no in-line schema is specified, the relational structure is extended through inference, as necessary, according to the structure of the XML document. If the schema cannot be extended through inference in order to expose all data, an exception is raised. + > [!NOTE] -> The `DataSet` does not associate an XML element with its corresponding `DataColumn` or `DataTable` when legal XML characters like ("_") are escaped in the serialized XML. The `DataSet` itself only escapes illegal XML characters in XML element names and hence can only consume the same. When legal characters in XML element name are escaped, the element is ignored while processing. - - If the XML Schema for a includes a `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema as the following example demonstrates. - -``` - - -``` - +> The `DataSet` does not associate an XML element with its corresponding `DataColumn` or `DataTable` when legal XML characters like ("_") are escaped in the serialized XML. The `DataSet` itself only escapes illegal XML characters in XML element names and hence can only consume the same. When legal characters in XML element name are escaped, the element is ignored while processing. + + If the XML Schema for a includes a `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema as the following example demonstrates. + +``` + + +``` + > [!NOTE] -> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. - +> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. + ]]> @@ -4871,38 +4838,38 @@ class Program { Reads XML schema and data into the using the specified and . The used to read the data. - method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. - - Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. - + method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. To read both data and schema, use one of the `ReadXML` overloads that includes the `mode` parameter, and set its value to `ReadSchema`. + + Note that the same is true for the and methods, respectively. To write XML data, or both schema and data from the `DataSet`, use the `WriteXml` method. To write just the schema, use the `WriteXmlSchema` method. + > [!NOTE] -> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . - - If an in-line schema is specified, the in-line schema is used to extend the existing relational structure prior to loading the data. If there are any conflicts (for example, the same column in the same table defined with different data types) an exception is raised. - - If no in-line schema is specified, the relational structure is extended through inference, as necessary, according to the structure of the XML document. If the schema cannot be extended through inference in order to expose all data, an exception is raised. - +> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . + + If an in-line schema is specified, the in-line schema is used to extend the existing relational structure prior to loading the data. If there are any conflicts (for example, the same column in the same table defined with different data types) an exception is raised. + + If no in-line schema is specified, the relational structure is extended through inference, as necessary, according to the structure of the XML document. If the schema cannot be extended through inference in order to expose all data, an exception is raised. + > [!NOTE] -> The `DataSet` does not associate an XML element with its corresponding `DataColumn` or `DataTable` when legal XML characters like ("_") are escaped in the serialized XML. The `DataSet` itself only escapes illegal XML characters in XML element names and hence can only consume the same. When legal characters in XML element name are escaped, the element is ignored while processing. - - If the XML Schema for a includes a `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema as the following example demonstrates. - -``` - - -``` - +> The `DataSet` does not associate an XML element with its corresponding `DataColumn` or `DataTable` when legal XML characters like ("_") are escaped in the serialized XML. The `DataSet` itself only escapes illegal XML characters in XML element names and hence can only consume the same. When legal characters in XML element name are escaped, the element is ignored while processing. + + If the XML Schema for a includes a `targetNamespace`, data may not be read, and you may encounter exceptions when calling to load the with XML that contains elements with no qualifying namespace. To read unqualified elements, set `elementFormDefault` equal to "qualified" in your XML Schema as the following example demonstrates. + +``` + + +``` + > [!NOTE] -> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. - +> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. + ]]> Using DataSets in ADO.NET @@ -4970,31 +4937,31 @@ class Program { The from which to read. Reads the XML schema from the specified into the . - method to create the schema for a . The schema includes table, relation, and constraint definitions. To write a schema to an XML document, use the method. - - The XML schema is written using the XSD standard. - + method to create the schema for a . The schema includes table, relation, and constraint definitions. To write a schema to an XML document, use the method. + + The XML schema is written using the XSD standard. + > [!NOTE] -> Data corruption can occur if the msdata:DataType and the xs:type types do not match. No exception will be thrown. - - The method is generally invoked before invoking the method which is used to fill the . - - Classes that derive from the class include , , , and . - +> Data corruption can occur if the msdata:DataType and the xs:type types do not match. No exception will be thrown. + + The method is generally invoked before invoking the method which is used to fill the . + + Classes that derive from the class include , , , and . + > [!NOTE] -> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is be thrown when you attempt to read the schema into the with . This exception does not occur if you are using .NET Framework version 1.0. - - - -## Examples - The following example creates a object to read an XML schema with, and invokes the method with the object. - +> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is be thrown when you attempt to read the schema into the with . This exception does not occur if you are using .NET Framework version 1.0. + + + +## Examples + The following example creates a object to read an XML schema with, and invokes the method with the object. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXmlSchema1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXmlSchema1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXmlSchema1 Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -5051,31 +5018,31 @@ class Program { The from which to read. Reads the XML schema from the specified into the . - method to create the schema for a . The schema includes table, relation, and constraint definitions. To write a schema to an XML document, use the method. - - The XML schema is written using the XSD standard. - + method to create the schema for a . The schema includes table, relation, and constraint definitions. To write a schema to an XML document, use the method. + + The XML schema is written using the XSD standard. + > [!NOTE] -> Data corruption can occur if the msdata:DataType and the xs:type types do not match. No exception will be thrown. - - The method is generally invoked before invoking the method which is used to fill the . - - Classes that inherit from the class include the and classes. - +> Data corruption can occur if the msdata:DataType and the xs:type types do not match. No exception will be thrown. + + The method is generally invoked before invoking the method which is used to fill the . + + Classes that inherit from the class include the and classes. + > [!NOTE] -> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is be thrown when you attempt to read the schema into the with . This exception does not occur if you are using .NET Framework version 1.0. - - - -## Examples - The following example creates a object to read a schema with, and invokes the method with the object. - +> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is be thrown when you attempt to read the schema into the with . This exception does not occur if you are using .NET Framework version 1.0. + + + +## Examples + The following example creates a object to read a schema with, and invokes the method with the object. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXmlSchema2 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXmlSchema2 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXmlSchema2 Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -5127,27 +5094,27 @@ class Program { The file name (including the path) from which to read. Reads the XML schema from the specified file into the . - method to create the schema for a . The schema includes table, relation, and constraint definitions. To write a schema to an XML document, use the method. - - The XML schema is written using the XSD standard. - + method to create the schema for a . The schema includes table, relation, and constraint definitions. To write a schema to an XML document, use the method. + + The XML schema is written using the XSD standard. + > [!NOTE] -> Data corruption can occur if the msdata:DataType and the xs:type types do not match. No exception will be thrown. - - The method is generally invoked before invoking the method which is used to fill the . - +> Data corruption can occur if the msdata:DataType and the xs:type types do not match. No exception will be thrown. + + The method is generally invoked before invoking the method which is used to fill the . + > [!NOTE] -> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with . This exception does not occur if you are using .NET Framework version 1.0. - - - -## Examples +> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with . This exception does not occur if you are using .NET Framework version 1.0. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXmlSchema3 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXmlSchema3 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXmlSchema3 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -5206,31 +5173,31 @@ class Program { The from which to read. Reads the XML schema from the specified into the . - method to create the schema for a . The schema includes table, relation, and constraint definitions. - - The XML schema is written using the XSD standard. - + method to create the schema for a . The schema includes table, relation, and constraint definitions. + + The XML schema is written using the XSD standard. + > [!NOTE] -> Data corruption can occur if the msdata:DataType and the xs:type types do not match. No exception will be thrown. - - The method is generally invoked before invoking the method which is used to fill the . - - The class is abstract. A class that inherits from the `XmlReader` is the class. - +> Data corruption can occur if the msdata:DataType and the xs:type types do not match. No exception will be thrown. + + The method is generally invoked before invoking the method which is used to fill the . + + The class is abstract. A class that inherits from the `XmlReader` is the class. + > [!NOTE] -> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is be thrown when you attempt to read the schema into the with . This exception does not occur if you are using .NET Framework version 1.0. - - - -## Examples - The following example creates a new and object. The object, created with a file path and file name, is used to create an that is passed as an argument to the method. - +> If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is be thrown when you attempt to read the schema into the with . This exception does not occur if you are using .NET Framework version 1.0. + + + +## Examples + The following example creates a new and object. The object, created with a file path and file name, is used to create an that is passed as an argument to the method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXmlSchema Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXmlSchema Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXmlSchema Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -5321,25 +5288,25 @@ class Program { Rolls back all the changes made to the since it was created, or since the last time was called. - to call the method on all objects contained by the . - - objects contained by the can each be set into edit mode by invoking the method. After invoking the method, changes can be rejected by calling the on the to which the objects belong. - - When the method is called, any rows still in edit-mode cancel their edits. New rows are removed. Modified and deleted rows return back to their original state (`DataRowState.Unchanged`). - - AcceptChanges and RejectChanges only apply to related changes (that is, `Add`, `Remove`, `Delete`, and `Modify`). They are not applicable to schema or structural changes. - - - -## Examples - The following example shows a class derived from the class. The event is invoked from within a function. - + to call the method on all objects contained by the . + + objects contained by the can each be set into edit mode by invoking the method. After invoking the method, changes can be rejected by calling the on the to which the objects belong. + + When the method is called, any rows still in edit-mode cancel their edits. New rows are removed. Modified and deleted rows return back to their original state (`DataRowState.Unchanged`). + + AcceptChanges and RejectChanges only apply to related changes (that is, `Add`, `Remove`, `Delete`, and `Modify`). They are not applicable to schema or structural changes. + + + +## Examples + The following example shows a class derived from the class. The event is invoked from within a function. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.RejectChanges Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.RejectChanges Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.RejectChanges Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -5392,13 +5359,13 @@ class Program { Gets the collection of relations that link tables and allow navigation from parent tables to child tables. A that contains a collection of objects. An empty collection is returned if no objects exist. - property. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.Relations Example/VB/source.vb" id="Snippet1"::: - + property. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.Relations Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -5536,19 +5503,19 @@ class Program { Gets or sets a for a . A for a . - serializes its schema and instance data by default in Web services and remoting scenarios. Setting the property of a typed `DataSet` to causes schema information to be excluded from the serialization payload. - - is supported only for a typed `DataSet`. For an un-typed `DataSet` this property can only be set to . - - should only be used in cases where the schema information of the underlying typed `DataTables`, `DataRelations` and `Constraints` has not been modified. If modifications have occurred, complete schema information should be serialized with . - - is supported in version 2.0 of the .NET Framework or later. - - When is set, only the top level runtime properties present on the are serialized. In addition, they are serialized only if they happen to be different from the default values. None of the `Tables`, `Relations` or `Constraints` are serialized. The serialized runtime properties include , , , , , and . These properties are serialized to make sure that overall runtime data integrity is preserved. - + serializes its schema and instance data by default in Web services and remoting scenarios. Setting the property of a typed `DataSet` to causes schema information to be excluded from the serialization payload. + + is supported only for a typed `DataSet`. For an un-typed `DataSet` this property can only be set to . + + should only be used in cases where the schema information of the underlying typed `DataTables`, `DataRelations` and `Constraints` has not been modified. If modifications have occurred, complete schema information should be serialized with . + + is supported in version 2.0 of the .NET Framework or later. + + When is set, only the top level runtime properties present on the are serialized. In addition, they are serialized only if they happen to be different from the default values. None of the `Tables`, `Relations` or `Constraints` are serialized. The serialized runtime properties include , , , , , and . These properties are serialized to make sure that overall runtime data integrity is preserved. + ]]> Using DataSets in ADO.NET @@ -5593,19 +5560,19 @@ class Program { if the property value has been changed from its default; otherwise, . - , or creating your own control incorporating the . - - - -## Examples - The following examples show a class derived from the class. The and methods are invoked from within functions in the derived class. - + , or creating your own control incorporating the . + + + +## Examples + The following examples show a class derived from the class. The and methods are invoked from within functions in the derived class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.ShouldSerializeRelations Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.ShouldSerializeRelations Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.ShouldSerializeRelations Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -5650,19 +5617,19 @@ class Program { if the property value has been changed from its default; otherwise, . - , or creating your own control incorporating the . - - - -## Examples - The following example shows a class derived from the class. The method is called from within functions in the derived class. - + , or creating your own control incorporating the . + + + +## Examples + The following example shows a class derived from the class. The method is called from within functions in the derived class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.ShouldSerializeTables Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.ShouldSerializeTables Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.ShouldSerializeTables Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -5728,11 +5695,11 @@ class Program { Gets or sets an for the . An for the . - to a and enable communication between them, as well as provide a way for the container to manage its components. - + to a and enable communication between them, as well as provide a way for the container to manage its components. + ]]> Using DataSets in ADO.NET @@ -5777,11 +5744,11 @@ class Program { For a description of this member, see . For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -5827,11 +5794,11 @@ class Program { For a description of this member, see . For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -5912,11 +5879,11 @@ class Program { For a description of this member, see . For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -5964,11 +5931,11 @@ class Program { A . For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -6016,11 +5983,11 @@ class Program { A . For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -6072,19 +6039,19 @@ class Program { Gets the collection of tables contained in the . The contained by this . An empty collection is returned if no objects exist. - method of the . To remove tables, use the method. - - - -## Examples - The following example returns the object's , and prints the columns and rows in each table. - + method of the . To remove tables, use the method. + + + +## Examples + The following example returns the object's , and prints the columns and rows in each table. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.Tables Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.Tables Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.Tables Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -6152,24 +6119,24 @@ class Program { A object used to write to a file. Writes the current data for the using the specified . - into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the `mode` parameter, and set its value to `WriteSchema`. - - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. - + into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the `mode` parameter, and set its value to `WriteSchema`. + + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + > [!NOTE] -> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . - - - -## Examples - The following example creates a object. The object is then used with the method to write an XML document. - +> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . + + + +## Examples + The following example creates a object. The object is then used with the method to write an XML document. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXml Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXml Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXml Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -6226,16 +6193,16 @@ class Program { The object with which to write. Writes the current data for the using the specified . - into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the `mode` parameter, and set its value to `WriteSchema`. - - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. - + into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the `mode` parameter, and set its value to `WriteSchema`. + + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + > [!NOTE] -> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . - +> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . + ]]> Using DataSets in ADO.NET @@ -6287,16 +6254,16 @@ class Program { The file name (including the path) to which to write. Writes the current data for the to the specified file. - into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the `mode` parameter, and set its value to `WriteSchema`. - - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. - + into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the `mode` parameter, and set its value to `WriteSchema`. + + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + > [!NOTE] -> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . - +> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . + ]]> @@ -6355,16 +6322,16 @@ class Program { The with which to write. Writes the current data for the to the specified . - into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the `mode` parameter, and set its value to `WriteSchema`. - - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. - + into an XML document, whereas the method writes only the schema. To write both data and schema, use one of the overloads that includes the `mode` parameter, and set its value to `WriteSchema`. + + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + > [!NOTE] -> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . - +> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . + ]]> Using DataSets in ADO.NET @@ -6423,16 +6390,16 @@ class Program { One of the values. Writes the current data, and optionally the schema, for the using the specified and . To write the schema, set the value for the parameter to . - into an XML document, whereas the method writes only the schema. To write both data and schema, set the `mode` parameter to `WriteSchema`. - - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. - + into an XML document, whereas the method writes only the schema. To write both data and schema, set the `mode` parameter to `WriteSchema`. + + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + > [!NOTE] -> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . - +> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . + ]]> Using DataSets in ADO.NET @@ -6491,24 +6458,24 @@ class Program { One of the values. Writes the current data, and optionally the schema, for the using the specified and . To write the schema, set the value for the parameter to . - into an XML document, whereas the method writes only the schema. To write both data and schema, set the `mode` parameter to `WriteSchema`. - - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. - + into an XML document, whereas the method writes only the schema. To write both data and schema, set the `mode` parameter to `WriteSchema`. + + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + > [!NOTE] -> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . - - - -## Examples - The following example first creates a simple with one , two columns, and ten rows. The schema and data are written to disk by invoking the method. A second is created and the method is used to fill it with schema and data. - +> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . + + + +## Examples + The following example first creates a simple with one , two columns, and ten rows. The schema and data are written to disk by invoking the method. A second is created and the method is used to fill it with schema and data. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXml2 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXml2 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXml2 Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -6562,24 +6529,24 @@ class Program { One of the values. Writes the current data, and optionally the schema, for the to the specified file using the specified . To write the schema, set the value for the parameter to . - into an XML document, whereas the method writes only the schema. To write both data and schema, set the `mode` parameter to `WriteSchema`. - - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. - + into an XML document, whereas the method writes only the schema. To write both data and schema, set the `mode` parameter to `WriteSchema`. + + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + > [!NOTE] -> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . - - - -## Examples - The following example uses the method to write an XML document. - +> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . + + + +## Examples + The following example uses the method to write an XML document. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXml7 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXml7 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXml7 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -6640,24 +6607,24 @@ class Program { One of the values. Writes the current data, and optionally the schema, for the using the specified and . To write the schema, set the value for the parameter to . - into an XML document, whereas the method writes only the schema. To write both data and schema, set the `mode` parameter to `WriteSchema`. - - Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. - + into an XML document, whereas the method writes only the schema. To write both data and schema, set the `mode` parameter to `WriteSchema`. + + Note that the same is true for the and methods, respectively. To read XML data, or both schema and data into the `DataSet`, use the `ReadXml` method. To read just the schema, use the `ReadXmlSchema` method. + > [!NOTE] -> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . - - - -## Examples - The following example creates a object that is used to create a new . The object is used with the method to write an XML document. - +> An will be thrown if a column type in the `DataRow` being read from or written to implements and does not implement . + + + +## Examples + The following example creates a object that is used to create a new . The object is used with the method to write an XML document. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXml6 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXml6 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXml6 Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -6725,25 +6692,25 @@ class Program { A object used to write to a file. Writes the structure as an XML schema to the specified object. - method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. To write a schema to an XML document, use the method. - - The XML schema is written using the XSD standard. - - To write the data to an XML document, use the method. - - Classes that derive from the class include , , , and . - - - -## Examples - The following example creates a new object that is passed to the method to write the schema to disk. - + method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. To write a schema to an XML document, use the method. + + The XML schema is written using the XSD standard. + + To write the data to an XML document, use the method. + + Classes that derive from the class include , , , and . + + + +## Examples + The following example creates a new object that is passed to the method to write the schema to disk. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXmlSchema Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXmlSchema Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXmlSchema Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -6800,25 +6767,25 @@ class Program { The object with which to write. Writes the structure as an XML schema to the specified object. - method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. To write a schema to an XML document, use the method. - - The XML schema is written using the XSD standard. - - To write the data to an XML document, use the method. - - Classes the derive from the class include the , , , , and . - - - -## Examples - The following example creates a object to that is used to create a new . The is passed to the method, and the resulting string is printed to the console window. - + method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. To write a schema to an XML document, use the method. + + The XML schema is written using the XSD standard. + + To write the data to an XML document, use the method. + + Classes the derive from the class include the , , , , and . + + + +## Examples + The following example creates a object to that is used to create a new . The is passed to the method, and the resulting string is printed to the console window. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXmlSchema1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXmlSchema1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXmlSchema1 Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -6870,21 +6837,21 @@ class Program { The file name (including the path) to which to write. Writes the structure as an XML schema to a file. - method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. To write a schema to an XML document, use the method. - - The XML schema is written using the XSD standard. - - To write the data to an XML document, use the method. - - - -## Examples + method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. To write a schema to an XML document, use the method. + + The XML schema is written using the XSD standard. + + To write the data to an XML document, use the method. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXmlSchema3 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXmlSchema3 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXmlSchema3 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -6943,25 +6910,25 @@ class Program { The to write to. Writes the structure as an XML schema to an object. - method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. To write a schema to an XML document, use the method. - - The XML schema is written using the XSD standard. - - To write the data to an XML document, use the method. - - One class that inherits from the class is the class. - - - -## Examples - The following example creates a new object with the specified path. The object is used to create an object. The method is then invoked with the object to write the schema to the disk. - + method to write the schema for a to an XML document. The schema includes table, relation, and constraint definitions. To write a schema to an XML document, use the method. + + The XML schema is written using the XSD standard. + + To write the data to an XML document, use the method. + + One class that inherits from the class is the class. + + + +## Examples + The following example creates a new object with the specified path. The object is used to create an object. The method is then invoked with the object to write the schema to the disk. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXmlSchema2 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXmlSchema2 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXmlSchema2 Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET diff --git a/xml/System.Data/DataTable.xml b/xml/System.Data/DataTable.xml index 64b86e6abd4..f085fd131ac 100644 --- a/xml/System.Data/DataTable.xml +++ b/xml/System.Data/DataTable.xml @@ -131,53 +131,15 @@ Represents one table of in-memory data. - + For more information about this API, see Supplemental API remarks for DataTable. + objects and one object, and adds the new objects to a . The tables are then displayed in a control. -## Remarks - - The is a central object in the ADO.NET library. Other objects that use the include the and the . - - When accessing objects, note that they are conditionally case sensitive. For example, if one is named "mydatatable" and another is named "Mydatatable", a string used to search for one of the tables is regarded as case sensitive. However, if "mydatatable" exists and "Mydatatable" does not, the search string is regarded as case insensitive. A can contain two objects that have the same property value but different property values. For more information about working with objects, see [Creating a DataTable](/dotnet/framework/data/adonet/dataset-datatable-dataview/creating-a-datatable). - - If you are creating a programmatically, you must first define its schema by adding objects to the (accessed through the property). For more information about adding objects, see [Adding Columns to a DataTable](/dotnet/framework/data/adonet/dataset-datatable-dataview/adding-columns-to-a-datatable). - - To add rows to a , you must first use the method to return a new object. The method returns a row with the schema of the , as it is defined by the table's . The maximum number of rows that a can store is 16,777,216. For more information, see [Adding Data to a DataTable](/dotnet/framework/data/adonet/dataset-datatable-dataview/adding-data-to-a-datatable). - - The also contains a collection of objects that can be used to ensure the integrity of the data. For more information, see [DataTable Constraints](/dotnet/framework/data/adonet/dataset-datatable-dataview/datatable-constraints). - - There are many events that can be used to determine when changes are made to a table. These include , , , and . For more information about the events that can be used with a , see [Handling DataTable Events](/dotnet/framework/data/adonet/dataset-datatable-dataview/handling-datatable-events). - - When an instance of is created, some of the read/write properties are set to initial values. For a list of these values, see the constructor topic. - -> [!NOTE] -> The and objects inherit from and support the interface for .NET Framework remoting. These are the only ADO.NET objects that you can use for .NET Framework remoting. - -### Security considerations - -For information about DataSet and DataTable security, see [Security guidance](/dotnet/framework/data/adonet/dataset-datatable-dataview/security-guidance). - -## Examples - The following example creates two objects and one object, and adds the new objects to a . The tables are then displayed in a control. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTable Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataTable Example/VB/source.vb" id="Snippet1"::: - - This sample demonstrates how to create a DataTable manually with specific schema definitions: - -- Create multiple DataTables and define the initial columns. - -- Create the table constraints. - -- Insert the values and display the tables. - -- Create the expression columns and display the tables. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/classic webdata datatable example2/cs/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/classic webdata datatable example2/vb/source.vb" id="Snippet1"::: - - ]]> - +:::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTable Example/CS/source.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataTable Example/VB/source.vb" id="Snippet1"::: + ]]> + This type is safe for multithreaded read operations. You must synchronize any write operations. DataTables diff --git a/xml/System.Diagnostics.Tracing/EventSource.xml b/xml/System.Diagnostics.Tracing/EventSource.xml index 0cc9e59f901..b813ec6fcdc 100644 --- a/xml/System.Diagnostics.Tracing/EventSource.xml +++ b/xml/System.Diagnostics.Tracing/EventSource.xml @@ -1,380 +1,315 @@ - - - - - - - - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - - - - - - - - - System.Object - - - - System.IDisposable - - - - - [System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.All)] - [<System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.All)>] - - - [System.Runtime.CompilerServices.Nullable(0)] - [<System.Runtime.CompilerServices.Nullable(0)>] - - - [System.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - - Provides the ability to create events for event tracing across platforms. - - methods are called to log the events. - - The basic functionality of is sufficient for most applications. If you want more control over the event metadata that's created, you can apply the attribute to the methods. For advanced event source applications, it is possible to intercept the commands being sent to the derived event source and change the filtering, or to cause actions (such as dumping a data structure) to be performed by the inheritor. An event source can be activated in-process using and out-of-process using EventPipe-based tools such as `dotnet-trace` or Event Tracing for Windows (ETW) based tools like `PerfView` or `Logman`. It is also possible to programmatically control and intercept the data dispatcher. The class provides additional functionality. - -### Conventions - -derived classes should follow the following conventions: - - - User-defined classes should implement a singleton pattern. The singleton instance is traditionally named `Log`. By extension, users should not call `IDisposable.Dispose` manually and allow the runtime to clean up the singleton instance at the end of managed code execution. - - A user-defined, derived class should be marked as `sealed` unless it implements the advanced "Utility EventSource" configuration discussed in the Advanced Usage section. - - Call before performing any resource intensive work related to firing an event. - - You can implicitly create objects by declaring two event methods with subsequent event IDs that have the naming pattern `Start` and `Stop`. These events _must_ be declared next to each other in the class definition and the `Start` method _must_ come first. - - Attempt to keep objects backwards compatible and version them appropriately. The default version for an event is `0`. The version can be can be changed by setting . Change the version of an event whenever you change properties of the payload. Always add new payload properties to the end of the event declaration. If this is not possible, create a new event with a new ID to replace the old one. - - When declaring event methods, specify fixed-size payload properties before variably sized properties. - - are used as a bit mask for specifying specific events when subscribing to a provider. You can specify keywords by defining a `public static class Keywords` member class that has `public const EventKeywords` members. - - Associate expensive events with an using . This pattern allows users of your to opt out of these expensive operations. - -### Self-describing (tracelogging) vs. manifest event formats - can be configured into to two different modes based on the constructor used or what flags are set on . - - Historically, these two formats are derived from two formats that Event Tracing for Windows (ETW) used. While these two modes don't affect your ability to use Event Tracing for Windows (ETW) or EventPipe-based listeners, they do generate the metadata for events differently. - - The default event format is , which is set if not specified on . Manifest-based objects generate an XML document representing the events defined on the class upon initialization. This requires the to reflect over itself to generate the provider and event metadata. - - To use self-describing (tracelogging) event format, construct your using the constructor, the constructor, or by setting the `EtwSelfDescribingEventFormat` flag on . Self-describing sources generate minimal provider metadata on initialization and only generate event metadata when is called. - - In practice, these event format settings only affect usage with readers based on Event Tracing for Windows (ETW). They can, however, have a small effect on initialization time and per-event write times due to the time required for reflection and generating the metadata. - -### Examples - The following example shows a simple implementation of the class. - - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventSource/Overview/program1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/etwtracesmall/vb/program.vb" id="Snippet1"::: - - The following example shows a more complex implementation of the class. - - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/etwtrace/vb/program.vb" id="Snippet1"::: - - -### Advanced Usage - Traditionally, user-defined objects expect to inherit directly from . For advanced scenarios, however, you can create `abstract` objects, called *Utility Sources*, and implement interfaces. Using one or both of these techniques allows you to share code between different derived sources. - -> [!IMPORTANT] -> Abstract objects cannot define keywords, tasks, opcodes, channels, or events. - -> [!IMPORTANT] -> To avoid name collisions at run time when generating event metadata, don't explicitly implement interface methods when using interfaces with . - -The following example shows an implementation of that uses an interface. - - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventSource/Overview/program.cs" id="InterfaceSource"::: - -The following example shows an implementation of that uses the Utility EventSource pattern. - - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventSource/Overview/program.cs" id="UtilitySource"::: - -The following example shows an implementation of for tracing information about a component in a library. - - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventSource/Overview/program.cs" id="ComplexSource"::: - - ]]> - - This type is thread safe. - - - - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - - - Creates a new instance of the class. - - - - - - - - - Constructor - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - Creates a new instance of the class. - To be added. - - - - - - - - - - Constructor - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - - - - to throw an exception when an error occurs in the underlying Windows code; otherwise, . - Creates a new instance of the class and specifies whether to throw an exception when an error occurs in the underlying Windows code. - To be added. - - - - - - - - - - Constructor - - System.Diagnostics.Tracing - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - - - A bitwise combination of the enumeration values that specify the configuration settings to apply to the event source. - Creates a new instance of the class with the specified configuration settings. - + + + + + + + + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + + + + + + + + + System.Object + + + + System.IDisposable + + + + + [System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.All)] + [<System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.All)>] + + + [System.Runtime.CompilerServices.Nullable(0)] + [<System.Runtime.CompilerServices.Nullable(0)>] + + + [System.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + + Provides the ability to create events for event tracing across platforms. + For more information about this API, see Supplemental API remarks for EventSource. + This type is thread safe. + + + + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + + + Creates a new instance of the class. + + + + + + + + + Constructor + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + Creates a new instance of the class. + To be added. + + + + + + + + + + Constructor + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + + + + to throw an exception when an error occurs in the underlying Windows code; otherwise, . + Creates a new instance of the class and specifies whether to throw an exception when an error occurs in the underlying Windows code. + To be added. + + + + + + + + + + Constructor + + System.Diagnostics.Tracing + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + + + A bitwise combination of the enumeration values that specify the configuration settings to apply to the event source. + Creates a new instance of the class with the specified configuration settings. + is constructed enables you to specify whether the event is written in a manifest-based or a self-describing format. In addition, you can specify that an exception should be raised when an error occurs during the event-writing process. - ]]> - - - - - - - - - - - Constructor - - System.Diagnostics.Tracing - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - - - - The name to apply to the event source. Must not be . - Creates a new instance of the class with the specified name. - + ]]> + + + + + + + + + + + Constructor + + System.Diagnostics.Tracing + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + + + + The name to apply to the event source. Must not be . + Creates a new instance of the class with the specified name. + attribute on that type. Otherwise, the GUIDs returned by the property and the method will be different. If the event source names differ, the property returns the GUID used to register this EventSource with ETW. - ]]> - - - is . - - - - - - - - - - - Constructor - - System.Diagnostics.Tracing - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - - - - [System.ParamArray] - [<System.ParamArray>] - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })>] - - - - - - A bitwise combination of the enumeration values that specify the configuration settings to apply to the event source. - The key-value pairs that specify traits for the event source. - Initializes a new instance of the to be used with non-contract events that contains the specified settings and traits. - + ]]> + + + is . + + + + + + + + + + + Constructor + + System.Diagnostics.Tracing + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + + + + [System.ParamArray] + [<System.ParamArray>] + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })>] + + + + + + A bitwise combination of the enumeration values that specify the configuration settings to apply to the event source. + The key-value pairs that specify traits for the event source. + Initializes a new instance of the to be used with non-contract events that contains the specified settings and traits. + is constructed enables you to specify whether the event is written in a manifest-based or a self-describing format. In addition, you can specify that an exception should be raised when an error occurs during the event-writing process. - ]]> - - - is not specified in key-value pairs. - - - - - - - - - - - Constructor - - System.Diagnostics.Tracing - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - - - - - The name to apply to the event source. Must not be . - A bitwise combination of the enumeration values that specify the configuration settings to apply to the event source. - Creates a new instance of the class with the specified name and settings. - + ]]> + + + is not specified in key-value pairs. + + + + + + + + + + + Constructor + + System.Diagnostics.Tracing + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + + + + + The name to apply to the event source. Must not be . + A bitwise combination of the enumeration values that specify the configuration settings to apply to the event source. + Creates a new instance of the class with the specified name and settings. + property returns the GUID used to register this EventSource with ETW. - ]]> - - - is . - - - - - - - - - - - Constructor - - System.Diagnostics.Tracing - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - - - - - - [System.ParamArray] - [<System.ParamArray>] - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })>] - - - - - - The name to apply to the event source. Must not be . - A bitwise combination of the enumeration values that specify the configuration settings to apply to the event source. - The key-value pairs that specify traits for the event source. - Creates a new instance of the class with the specified configuration settings. - + ]]> + + + is . + + + + + + + + + + + Constructor + + System.Diagnostics.Tracing + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + + + + + + [System.ParamArray] + [<System.ParamArray>] + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })>] + + + + + + The name to apply to the event source. Must not be . + A bitwise combination of the enumeration values that specify the configuration settings to apply to the event source. + The key-value pairs that specify traits for the event source. + Creates a new instance of the class with the specified configuration settings. + attribute on that type. Otherwise, the GUIDs returned by the property and the method will be different. In such cases, the GUID used to register this EventSource with ETW is the one returned by . - ]]> - - - is . - - is not specified in key-value pairs. - - - - - - - - - - - - Property - - System.Diagnostics.Tracing - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Exception - - - Gets any exception that was thrown during the construction of the event source. - The exception that was thrown during the construction of the event source, or if no exception was thrown. - + ]]> + + + is . + + is not specified in key-value pairs. + + + + + + + + + + + + Property + + System.Diagnostics.Tracing + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Exception + + + Gets any exception that was thrown during the construction of the event source. + The exception that was thrown during the construction of the event source, or if no exception was thrown. + constructors do not throw exceptions. Instead, any exception that is thrown is assigned to the property and logged by the method. - ]]> - - - - - - - - - - - Property - - System.Diagnostics.Tracing - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [get: System.Security.SecurityCritical] - [<get: System.Security.SecurityCritical>] - - - [get: System.Security.SecuritySafeCritical] - [<get: System.Security.SecuritySafeCritical>] - - - - System.Guid - - - Gets the activity ID of the current thread. - The activity ID of the current thread. - To be added. - - - - - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - - - Releases all resources used by the current instance of the class. - - - - - - - - - - Method - - M:System.IDisposable.Dispose - - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Void - - - - Releases all resources used by the current instance of the class. - + ]]> + + + + + + + + + + + Property + + System.Diagnostics.Tracing + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [get: System.Security.SecurityCritical] + [<get: System.Security.SecurityCritical>] + + + [get: System.Security.SecuritySafeCritical] + [<get: System.Security.SecuritySafeCritical>] + + + + System.Guid + + + Gets the activity ID of the current thread. + The activity ID of the current thread. + To be added. + + + + + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + + + Releases all resources used by the current instance of the class. + + + + + + + + + + Method + + M:System.IDisposable.Dispose + + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Void + + + + Releases all resources used by the current instance of the class. + [!NOTE] > Always call `Dispose` before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. - ]]> - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Void - - - - - - - to release both managed and unmanaged resources; to release only unmanaged resources. - Releases the unmanaged resources used by the class and optionally releases the managed resources. - + ]]> + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Void + + + + + + + to release both managed and unmanaged resources; to release only unmanaged resources. + Releases the unmanaged resources used by the class and optionally releases the managed resources. + references. This method invokes the `Dispose()` method of each referenced object. - ]]> - - - + ]]> + + + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier the Dispose Method call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). - - - - - - - - - - - - Event - - System.Diagnostics.Tracing - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })>] - - - [System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Never)] - [<System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Never)>] - - - - System.EventHandler<System.Diagnostics.Tracing.EventCommandEventArgs> - - - Occurs when a command comes from an event listener. - To be added. - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Void - - - - Allows the object to attempt to free resources and perform other cleanup operations before the object is reclaimed by garbage collection. - To be added. - - - - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - - - Returns a string of the XML manifest that is associated with the current event source. - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.String - - - - - - [System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.All)] - [<System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.All)>] - - - [System.Runtime.CompilerServices.Nullable(1)] - [<System.Runtime.CompilerServices.Nullable(1)>] - - - - - - - The type of the event source. - The path to the assembly file (.dll) to include in the provider element of the manifest. - Returns a string of the XML manifest that is associated with the current event source. - The XML data string. - + For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + + + + + + + + + + + + Event + + System.Diagnostics.Tracing + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })>] + + + [System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Never)] + [<System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Never)>] + + + + System.EventHandler<System.Diagnostics.Tracing.EventCommandEventArgs> + + + Occurs when a command comes from an event listener. + To be added. + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Void + + + + Allows the object to attempt to free resources and perform other cleanup operations before the object is reclaimed by garbage collection. + To be added. + + + + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + + + Returns a string of the XML manifest that is associated with the current event source. + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.String + + + + + + [System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.All)] + [<System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.All)>] + + + [System.Runtime.CompilerServices.Nullable(1)] + [<System.Runtime.CompilerServices.Nullable(1)>] + + + + + + + The type of the event source. + The path to the assembly file (.dll) to include in the provider element of the manifest. + Returns a string of the XML manifest that is associated with the current event source. + The XML data string. + - - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.String - - - - - - [System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.All)] - [<System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.All)>] - - - [System.Runtime.CompilerServices.Nullable(1)] - [<System.Runtime.CompilerServices.Nullable(1)>] - - - - - - - - The type of the event source. - The path to the assembly file (.dll) file to include in the provider element of the manifest. - A bitwise combination of the enumeration values that specify how the manifest is generated. - Returns a string of the XML manifest that is associated with the current event source. - The XML data string or . - + ]]> + + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.String + + + + + + [System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.All)] + [<System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.All)>] + + + [System.Runtime.CompilerServices.Nullable(1)] + [<System.Runtime.CompilerServices.Nullable(1)>] + + + + + + + + The type of the event source. + The path to the assembly file (.dll) file to include in the provider element of the manifest. + A bitwise combination of the enumeration values that specify how the manifest is generated. + Returns a string of the XML manifest that is associated with the current event source. + The XML data string or . + returns `null`. - ]]> - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.Guid - - - - - - The type of the event source. - Gets the unique identifier for this implementation of the event source. - A unique identifier for this event source type. - + ]]> + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.Guid + + + + + + The type of the event source. + Gets the unique identifier for this implementation of the event source. + A unique identifier for this event source type. + that was passed to the constructor isn't specified as an , this method can return a different GUID to the one returned by the property. In such cases, the GUID that is used to register the is the one returned by property. - ]]>] - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.String - - - - - - The type of the event source. - Gets the friendly name of the event source. - The friendly name of the event source. The default is the simple name of the class. - To be added. - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.Collections.Generic.IEnumerable<System.Diagnostics.Tracing.EventSource> - - - - Gets a snapshot of all the event sources for the application domain. - An enumeration of all the event sources in the application domain. - To be added. - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.String - - - - - - The key of the trait to get. - Gets the trait value associated with the specified key. - The trait value associated with the specified key. If the key is not found, returns . - + ]]>] + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.String + + + + + + The type of the event source. + Gets the friendly name of the event source. + The friendly name of the event source. The default is the simple name of the class. + To be added. + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.Collections.Generic.IEnumerable<System.Diagnostics.Tracing.EventSource> + + + + Gets a snapshot of all the event sources for the application domain. + An enumeration of all the event sources in the application domain. + To be added. + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.String + + + + + + The key of the trait to get. + Gets the trait value associated with the specified key. + The trait value associated with the specified key. If the key is not found, returns . + - - - - - - - - - - - Property - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Guid - - - The unique identifier for the event source. - A unique identifier for the event source. - To be added. - - - - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - - - Determines whether the current event source is enabled. - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Boolean - - - - Determines whether the current event source is enabled. - - if the current event source is enabled; otherwise, . - To be added. - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Boolean - - - - - - - The level of the event source. - The keyword of the event source. - Determines whether the current event source that has the specified level and keyword is enabled. - - if the event source is enabled; otherwise, . - + ]]> + + + + + + + + + + + Property + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Guid + + + The unique identifier for the event source. + A unique identifier for the event source. + To be added. + + + + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + + + Determines whether the current event source is enabled. + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Boolean + + + + Determines whether the current event source is enabled. + + if the current event source is enabled; otherwise, . + To be added. + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Boolean + + + + + + + The level of the event source. + The keyword of the event source. + Determines whether the current event source that has the specified level and keyword is enabled. + + if the event source is enabled; otherwise, . + - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Boolean - - - - - - - - The event level to check. An event source will be considered enabled when its level is greater than or equal to . - The event keywords to check. - The event channel to check. - Determines whether the current event source is enabled for events with the specified level, keywords and channel. - + ]]> + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Boolean + + + + + + + + The event level to check. An event source will be considered enabled when its level is greater than or equal to . + The event keywords to check. + The event channel to check. + Determines whether the current event source is enabled for events with the specified level, keywords and channel. + if the event source is enabled for the specified event level, keywords and channel; otherwise, . - The result of this method is only an approximation of whether a particular event is active. Use it to avoid expensive computation for logging when logging is disabled. Event sources may have additional filtering that determines their activity. - + The result of this method is only an approximation of whether a particular event is active. Use it to avoid expensive computation for logging when logging is disabled. Event sources may have additional filtering that determines their activity. + - - - - - - - - - - - Property - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.CompilerServices.Nullable(1)] - [<System.Runtime.CompilerServices.Nullable(1)>] - - - [get: System.Runtime.CompilerServices.NullableContext(1)] - [<get: System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.String - - - The friendly name of the class that is derived from the event source. - The friendly name of the derived class. The default is the simple name of the class. - To be added. - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.Void - - - - - - The arguments for the event. - Called when the current event source is updated by the controller. - To be added. - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.Void - - - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1, 2 })>] - - - - - - The event source to send the command to. - The event command to send. - The arguments for the event command. - Sends a command to a specified event source. - + ]]> + + + + + + + + + + + Property + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.CompilerServices.Nullable(1)] + [<System.Runtime.CompilerServices.Nullable(1)>] + + + [get: System.Runtime.CompilerServices.NullableContext(1)] + [<get: System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.String + + + The friendly name of the class that is derived from the event source. + The friendly name of the derived class. The default is the simple name of the class. + To be added. + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.Void + + + + + + The arguments for the event. + Called when the current event source is updated by the controller. + To be added. + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.Void + + + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1, 2 })>] + + + + + + The event source to send the command to. + The event command to send. + The arguments for the event command. + Sends a command to a specified event source. + forwards the command to the callback. What the does with the command and its arguments is specific to the event source. The command and command arguments are passed to the callback of the specified event source. If possible, the current event source should not affect other event listeners' filtering events; however, that may not be possible if the command causes a garbage collection, a system flush, or some other global activity. - ]]> - - - - - - System.Diagnostics.Tracing - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - - - Sets the activity ID on the current thread. - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - The current thread's new activity ID, or to indicate that work on the current thread is not associated with any activity. - Sets the activity ID on the current thread. - + ]]> + + + + + + System.Diagnostics.Tracing + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + + + Sets the activity ID on the current thread. + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + The current thread's new activity ID, or to indicate that work on the current thread is not associated with any activity. + Sets the activity ID on the current thread. + - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - - The current thread's new activity ID, or to indicate that work on the current thread is not associated with any activity. - When this method returns, contains the previous activity ID on the current thread. - Sets the activity ID on the current thread, and returns the previous activity ID. - + ]]> + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + + The current thread's new activity ID, or to indicate that work on the current thread is not associated with any activity. + When this method returns, contains the previous activity ID on the current thread. + Sets the activity ID on the current thread, and returns the previous activity ID. + method to temporarily overwrite the current thread's activity ID with a new activity ID. You must then restore the previous activity ID by passing the `oldActivityThatWillContinue` argument to the method. - ]]> - - - - - - - - - - - Property - - System.Diagnostics.Tracing - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Diagnostics.Tracing.EventSourceSettings - - - Gets the settings applied to this event source. - The settings applied to this event source. - To be added. - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.String - - - - Obtains a string representation of the current event source instance. - The name and unique identifier that identify the current event source. - To be added. - - - - - System.Diagnostics.Tracing - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - - - Writes an event. - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - The name of the event to write. - Writes an event without fields, but with the specified name and default options. - To be added. - - is . - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - - The name of the event to write. - The options such as level, keywords and operation code for the event. - Writes an event without fields, but with the specified name and options. - To be added. - - is . - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")] - [<System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")>] - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - [System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.PublicProperties)] - [<System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.PublicProperties)>] - - - - - - - - - - [System.Runtime.CompilerServices.Nullable(1)] - [<System.Runtime.CompilerServices.Nullable(1)>] - - - - - - The type that defines the event and its associated data. This type must be an anonymous type or marked with the attribute. - The name of the event. - The event data. This type must be an anonymous type or marked with the attribute. - Writes an event with the specified name and data. - + ]]> + + + + + + + + + + + Property + + System.Diagnostics.Tracing + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Diagnostics.Tracing.EventSourceSettings + + + Gets the settings applied to this event source. + The settings applied to this event source. + To be added. + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.String + + + + Obtains a string representation of the current event source instance. + The name and unique identifier that identify the current event source. + To be added. + + + + + System.Diagnostics.Tracing + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + + + Writes an event. + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + The name of the event to write. + Writes an event without fields, but with the specified name and default options. + To be added. + + is . + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + + The name of the event to write. + The options such as level, keywords and operation code for the event. + Writes an event without fields, but with the specified name and options. + To be added. + + is . + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")] + [<System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")>] + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + [System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.PublicProperties)] + [<System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.PublicProperties)>] + + + + + + + + + + [System.Runtime.CompilerServices.Nullable(1)] + [<System.Runtime.CompilerServices.Nullable(1)>] + + + + + + The type that defines the event and its associated data. This type must be an anonymous type or marked with the attribute. + The name of the event. + The event data. This type must be an anonymous type or marked with the attribute. + Writes an event with the specified name and data. + ) or determined based on the name of type `T`. The public instance properties of `data` will be written recursively to create the event fields. - ]]> - - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")] - [<System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")>] - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - [System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.PublicProperties)] - [<System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.PublicProperties)>] - - - - - - - - - - - [System.Runtime.CompilerServices.Nullable(1)] - [<System.Runtime.CompilerServices.Nullable(1)>] - - - - - - The type that defines the event and its associated data. This type must be an anonymous type or marked with the attribute. - The name of the event. - The event options. - The event data. This type must be an anonymous type or marked with the attribute. - Writes an event with the specified name, event data and options. - + ]]> + + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")] + [<System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")>] + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + [System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.PublicProperties)] + [<System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.PublicProperties)>] + + + + + + + + + + + [System.Runtime.CompilerServices.Nullable(1)] + [<System.Runtime.CompilerServices.Nullable(1)>] + + + + + + The type that defines the event and its associated data. This type must be an anonymous type or marked with the attribute. + The name of the event. + The event options. + The event data. This type must be an anonymous type or marked with the attribute. + Writes an event with the specified name, event data and options. + ) or determined based on the name of type `T`. The public instance properties of `data` will be written recursively to create the event fields. - ]]> - - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")] - [<System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")>] - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - [System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.PublicProperties)] - [<System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.PublicProperties)>] - - - - - - - - - - - [System.Runtime.CompilerServices.Nullable(1)] - [<System.Runtime.CompilerServices.Nullable(1)>] - - - - - - The type that defines the event and its associated data. This type must be an anonymous type or marked with the attribute. - The name of the event. - The event options. - The event data. This type must be an anonymous type or marked with the attribute. - Writes an event with the specified name, options and event data. - + ]]> + + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")] + [<System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")>] + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + [System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.PublicProperties)] + [<System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.PublicProperties)>] + + + + + + + + + + + [System.Runtime.CompilerServices.Nullable(1)] + [<System.Runtime.CompilerServices.Nullable(1)>] + + + + + + The type that defines the event and its associated data. This type must be an anonymous type or marked with the attribute. + The name of the event. + The event options. + The event data. This type must be an anonymous type or marked with the attribute. + Writes an event with the specified name, options and event data. + ) or determined based on the name of type `T`. The public instance properties of `data` will be written recursively to create the event fields. - ]]> - - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")] - [<System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")>] - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - [System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.PublicProperties)] - [<System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.PublicProperties)>] - - - - - - - - - - - - - [System.Runtime.CompilerServices.Nullable(1)] - [<System.Runtime.CompilerServices.Nullable(1)>] - - - - - - The type that defines the event and its associated data. This type must be an anonymous type or marked with the attribute. - The name of the event. - The event options. - The ID of the activity associated with the event. - The ID of an associated activity, or if there is no associated activity. - The event data. This type must be an anonymous type or marked with the attribute. - Writes an event with the specified name, options, related activity and event data. - + ]]> + + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")] + [<System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")>] + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + [System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.PublicProperties)] + [<System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.PublicProperties)>] + + + + + + + + + + + + + [System.Runtime.CompilerServices.Nullable(1)] + [<System.Runtime.CompilerServices.Nullable(1)>] + + + + + + The type that defines the event and its associated data. This type must be an anonymous type or marked with the attribute. + The name of the event. + The event options. + The ID of the activity associated with the event. + The ID of an associated activity, or if there is no associated activity. + The event data. This type must be an anonymous type or marked with the attribute. + Writes an event with the specified name, options, related activity and event data. + ) or determined based on the name of type `T`. The public instance properties of `data` will be written recursively to create the event fields. - ]]> - - - - - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - - - Writes an event by using the provided event identifier and optional arguments. - + ]]> + + + + + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + + + Writes an event by using the provided event identifier and optional arguments. + [!IMPORTANT] > Event parameters with a type of `string` should not include `\0` characters. They are unsupported characters and can cause issues for parsers of the event payload. - ]]> - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - The event identifier. This value should be between 0 and 65535. - Writes an event by using the provided event identifier. - + ]]> + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + The event identifier. This value should be between 0 and 65535. + Writes an event by using the provided event identifier. + - - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - - The event identifier. This value should be between 0 and 65535. - A byte array argument. - Writes an event by using the provided event identifier and byte array argument. - + ]]> + + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + + The event identifier. This value should be between 0 and 65535. + A byte array argument. + Writes an event by using the provided event identifier and byte array argument. + - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 8.0.0.0 - - - mscorlib - - - netstandard - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.Void - - - - - - - [System.ParamArray] - [<System.ParamArray>] - - - - - - The event identifier. This value should be between 0 and 65535. - The event source primitives. - Writes an event by using the provided event identifier and a variable number of event source primitives. - This is a varargs helper for writing an event. It does create an array and box all the arguments so it is relatively inefficient and should only be used for relatively rare events (for example, less than 100 per second). If your rates are faster than that, use to create fast helpers for your particular method signature. Even if you use this for rare events, this call should be guarded by an check so that the varargs call is not made when the EventSource isn't active. - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - - The event identifier. This value should be between 0 and 65535. - An integer argument. - Writes an event by using the provided event identifier and 32-bit integer argument. - + ]]> + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 8.0.0.0 + + + mscorlib + + + netstandard + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.Void + + + + + + + [System.ParamArray] + [<System.ParamArray>] + + + + + + The event identifier. This value should be between 0 and 65535. + The event source primitives. + Writes an event by using the provided event identifier and a variable number of event source primitives. + This is a varargs helper for writing an event. It does create an array and box all the arguments so it is relatively inefficient and should only be used for relatively rare events (for example, less than 100 per second). If your rates are faster than that, use to create fast helpers for your particular method signature. Even if you use this for rare events, this call should be guarded by an check so that the varargs call is not made when the EventSource isn't active. + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + + The event identifier. This value should be between 0 and 65535. + An integer argument. + Writes an event by using the provided event identifier and 32-bit integer argument. + - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - - The event identifier. This value should be between 0 and 65535. - A 64 bit integer argument. - Writes an event by using the provided event identifier and 64-bit integer argument. - + ]]> + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + + The event identifier. This value should be between 0 and 65535. + A 64 bit integer argument. + Writes an event by using the provided event identifier and 64-bit integer argument. + - - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")] - [<System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")>] - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - - [System.ParamArray] - [<System.ParamArray>] - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] - - - - - - The event identifier. This value should be between 0 and 65535. - An array of objects. - Writes an event by using the provided event identifier and array of arguments. - + ]]> + + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")] + [<System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")>] + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + + [System.ParamArray] + [<System.ParamArray>] + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] + + + + + + The event identifier. This value should be between 0 and 65535. + An array of objects. + Writes an event by using the provided event identifier and array of arguments. + - - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - - The event identifier. This value should be between 0 and 65535. - A string argument. - Writes an event by using the provided event identifier and string argument. - + ]]> + + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + + The event identifier. This value should be between 0 and 65535. + A string argument. + Writes an event by using the provided event identifier and string argument. + - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - - - The event identifier. This value should be between 0 and 65535. - An integer argument. - An integer argument. - Writes an event by using the provided event identifier and 32-bit integer arguments. - + ]]> + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + + + The event identifier. This value should be between 0 and 65535. + An integer argument. + An integer argument. + Writes an event by using the provided event identifier and 32-bit integer arguments. + - - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - - - The event identifier. This value should be between 0 and 65535. - A 32-bit integer argument. - A string argument. - Writes an event by using the provided event identifier and 32-bit integer and string arguments. - To be added. - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - - - The event identifier. This value should be between 0 and 65535. - A 64-bit integer argument. - A byte array argument. - Writes the event data using the specified identifier and 64-bit integer and byte array arguments. - + ]]> + + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + + + The event identifier. This value should be between 0 and 65535. + A 32-bit integer argument. + A string argument. + Writes an event by using the provided event identifier and 32-bit integer and string arguments. + To be added. + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + + + The event identifier. This value should be between 0 and 65535. + A 64-bit integer argument. + A byte array argument. + Writes the event data using the specified identifier and 64-bit integer and byte array arguments. + - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - - - The event identifier. This value should be between 0 and 65535. - A 64 bit integer argument. - A 64 bit integer argument. - Writes an event by using the provided event identifier and 64-bit arguments. - + ]]> + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + + + The event identifier. This value should be between 0 and 65535. + A 64 bit integer argument. + A 64 bit integer argument. + Writes an event by using the provided event identifier and 64-bit arguments. + - - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - - - The event identifier. This value should be between 0 and 65535. - A 64-bit integer argument. - A string argument. - Writes an event by using the provided event identifier and 64-bit integer, and string arguments. - + ]]> + + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + + + The event identifier. This value should be between 0 and 65535. + A 64-bit integer argument. + A string argument. + Writes an event by using the provided event identifier and 64-bit integer, and string arguments. + - - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - - - The event identifier. This value should be between 0 and 65535. - A string argument. - A 32 bit integer argument. - Writes an event by using the provided event identifier and arguments. - + ]]> + + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + + + The event identifier. This value should be between 0 and 65535. + A string argument. + A 32 bit integer argument. + Writes an event by using the provided event identifier and arguments. + - - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - - - The event identifier. This value should be between 0 and 65535. - A string argument. - A 64 bit integer argument. - Writes an event by using the provided event identifier and arguments. - + ]]> + + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + + + The event identifier. This value should be between 0 and 65535. + A string argument. + A 64 bit integer argument. + Writes an event by using the provided event identifier and arguments. + - - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - - - The event identifier. This value should be between 0 and 65535. - A string argument. - A string argument. - Writes an event by using the provided event identifier and string arguments. - + ]]> + + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + + + The event identifier. This value should be between 0 and 65535. + A string argument. + A string argument. + Writes an event by using the provided event identifier and string arguments. + - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - - - - The event identifier. This value should be between 0 and 65535. - An integer argument. - An integer argument. - An integer argument. - Writes an event by using the provided event identifier and 32-bit integer arguments. - + ]]> + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + + + + The event identifier. This value should be between 0 and 65535. + An integer argument. + An integer argument. + An integer argument. + Writes an event by using the provided event identifier and 32-bit integer arguments. + - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - - - - The event identifier. This value should be between 0 and 65535. - A 64 bit integer argument. - A 64 bit integer argument. - A 64 bit integer argument. - Writes an event by using the provided event identifier and 64-bit arguments. - + ]]> + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + + + + The event identifier. This value should be between 0 and 65535. + A 64 bit integer argument. + A 64 bit integer argument. + A 64 bit integer argument. + Writes an event by using the provided event identifier and 64-bit arguments. + - - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - - - - The event identifier. This value should be between 0 and 65535. - A string argument. - A 32 bit integer argument. - A 32 bit integer argument. - Writes an event by using the provided event identifier and arguments. - + ]]> + + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + + + + The event identifier. This value should be between 0 and 65535. + A string argument. + A 32 bit integer argument. + A 32 bit integer argument. + Writes an event by using the provided event identifier and arguments. + - - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - - - - The event identifier. This value should be between 0 and 65535. - A string argument. - A string argument. - A string argument. - Writes an event by using the provided event identifier and string arguments. - + ]]> + + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + + + + The event identifier. This value should be between 0 and 65535. + A string argument. + A string argument. + A string argument. + Writes an event by using the provided event identifier and string arguments. + - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - [System.Security.SecurityCritical] - [<System.Security.SecurityCritical>] - - - [System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")] - [<System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")>] - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Void - - - - - - - - The event identifier. - The number of event data items. - The structure that contains the event data. - Creates a new overload by using the provided event identifier and event data. - + ]]> + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + [System.Security.SecurityCritical] + [<System.Security.SecurityCritical>] + + + [System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")] + [<System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")>] + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Void + + + + + + + + The event identifier. + The number of event data items. + The structure that contains the event data. + Creates a new overload by using the provided event identifier and event data. + - - - - - - - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")] - [<System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")>] - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - - - - [System.ParamArray] - [<System.ParamArray>] - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] - - - - - - An identifier that uniquely identifies this event within the . - The related activity identifier. - The related activity identifier. - An array of objects that contain data about the event. - Writes an event that indicates that the current activity is related to another activity. - + ]]> + + + + + + + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")] + [<System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")>] + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + + + + [System.ParamArray] + [<System.ParamArray>] + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] + + + + + + An identifier that uniquely identifies this event within the . + The related activity identifier. + The related activity identifier. + An array of objects that contain data about the event. + Writes an event that indicates that the current activity is related to another activity. + - - - - - - - - - - - - - - Method - - System.Diagnostics.Tracing - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - [System.Security.SecurityCritical] - [<System.Security.SecurityCritical>] - - - [System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")] - [<System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")>] - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Void - - - - - - - - - - An identifier that uniquely identifies this event within the . - A pointer to the GUID of the related activity ID. - A pointer to the GUID of the related activity ID. - The number of items in the field. - A pointer to the first item in the event data field. - Writes an event that indicates that the current activity is related to another activity. - + ]]> + + + + + + + + + + + + + + Method + + System.Diagnostics.Tracing + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + [System.Security.SecurityCritical] + [<System.Security.SecurityCritical>] + + + [System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")] + [<System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode("EventSource will serialize the whole object graph. Trimmer will not safely handle this case because properties may be trimmed. This can be suppressed if the object is a primitive type")>] + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Void + + + + + + + + + + An identifier that uniquely identifies this event within the . + A pointer to the GUID of the related activity ID. + A pointer to the GUID of the related activity ID. + The number of items in the field. + A pointer to the first item in the event data field. + Writes an event that indicates that the current activity is related to another activity. + - - - - - + ]]> + + + + + diff --git a/xml/System.Diagnostics.Tracing/EventWrittenEventArgs.xml b/xml/System.Diagnostics.Tracing/EventWrittenEventArgs.xml index dcf4fea18f5..da38951c688 100644 --- a/xml/System.Diagnostics.Tracing/EventWrittenEventArgs.xml +++ b/xml/System.Diagnostics.Tracing/EventWrittenEventArgs.xml @@ -54,29 +54,7 @@ Provides data for the callback. - - , the callback method is invoked. It is passed an `EventWrittenEventArgs` instance that contains information associated with the event. All property values of the `EventWrittenEventArgs` class are valid only during the callback. - -The following sections contain additional information about individual `EventWrittenEventArgs` properties. - -### ActivityId property - -When using and its derived classes, threads can be marked as having an activity associated with them. The `ActivityId` property returns the activity ID of the thread that logged the event. Note that threads do not have to have an activity, in which case this property returns . - -### OSThreadId and TimeStamp properties - -Starting with .NET Core 2.2, objects can subscribe to native runtime events (such as GC, JIT, and threadpool events) in addition to events emitted by objects. In previous versions of .NET Core and all versions of .NET Framework, the thread ID and timestamp can be gathered from the environment, because they are dispatched synchronously on the same thread that emitted them. Not all native runtime events can be dispatched synchronously, however. Some events, such as GC events, are emitted when managed thread execution is suspended. These events are buffered in native code and are dispatched by a dispatcher thread once managed code can execute again. Because these events are buffered, the environment cannot be used to reliably retrieve the thread ID and timestamp. Because of this, starting with .NET Core 2.2, thread ID and timestamp information are available as members of the `EventWrittenEventArgs` class. - -### RelatedActivityId property - - A related activity is an activity that is strongly related to the current one. Typically, it is either the activity that caused the current activity (events with the `Start` opcode typically do this) or an activity that was created by the current one (events with the `Send` opcode typically do this). When it is used, the `RelatedActivityID` is explicitly passed by the method doing the logging. Many events don't pass a `RelatedActivityId`, in which case this property returns . - - ]]> - + For more information about this API, see Supplemental API remarks for EventWrittenEventArgs. diff --git a/xml/System.Diagnostics/PerformanceCounterType.xml b/xml/System.Diagnostics/PerformanceCounterType.xml index 3698b4aea35..8deed4ad992 100644 --- a/xml/System.Diagnostics/PerformanceCounterType.xml +++ b/xml/System.Diagnostics/PerformanceCounterType.xml @@ -32,151 +32,7 @@ Specifies performance counter types that map directly to native types. - - [!NOTE] -> Unless otherwise indicated, the time base is seconds. - - When instrumenting applications (creating and writing custom performance counters), you might be working with performance counter types that rely on an accompanying base counter that is used in the calculations. The base counter must be immediately after its associated counter in the collection your application uses. The following table lists the base counter types with their corresponding performance counter types. - -|Base counter type|Performance counter types| -|-----------------------|-------------------------------| -|`AverageBase`|`AverageTimer32`

`AverageCount64`| -|`CounterMultiBase`|`CounterMultiTimer`

`CounterMultiTimerInverse`

`CounterMultiTimer100Ns`

`CounterMultiTimer100NsInverse`| -|`RawBase`|`RawFraction`| -|`SampleBase`|`SampleFraction`| - -The following are the formulas used by some of the counters that represent calculated values: - -- `AverageCount64`: (N1 - N0)/(B1 - B0), where N 1 and N 0 are performance counter readings, and B1 and B0 are their corresponding `AverageBase` values. Thus, the numerator represents the numbers of items processed during the sample interval, and the denominator represents the number of operations completed during the sample interval. - -- `AverageTimer32`: ((N1 - N0)/F)/(B1 - B0), where N1 and N0 are performance counter readings, B1 and B0 are their corresponding `AverageBase` values, and F is the number of ticks per second. The value of F is factored into the equation so that the result can be displayed in seconds. Thus, the numerator represents the numbers of ticks counted during the last sample interval, F represents the frequency of the ticks, and the denominator represents the number of operations completed during the last sample interval. - -- `CounterDelta32`: N1 - N0, where N1 and N0 are performance counter readings. - -- `CounterDelta64`: N1 - N0, where N1 and N0 are performance counter readings. - -- `CounterMultiTimer`: ((N1 - N0) / (D1 - D0)) x 100 / B, where N1 and N0 are performance counter readings, D1 and D0 are their corresponding time readings in ticks of the system performance timer, and the variable B denotes the base count for the monitored components (using a base counter of type `CounterMultiBase`). Thus, the numerator represents the portions of the sample interval during which the monitored components were active, and the denominator represents the total elapsed time of the sample interval. - -- `CounterMultiTimer100Ns`: ((N1 - N0) / (D1 - D0)) x 100 / B, where N1 and N0 are performance counter readings, D1 and D0 are their corresponding time readings in 100-nanosecond units, and the variable B denotes the base count for the monitored components (using a base counter of type `CounterMultiBase`). Thus, the numerator represents the portions of the sample interval during which the monitored components were active, and the denominator represents the total elapsed time of the sample interval. - -- `CounterMultiTimer100NsInverse`: (B - ((N1 - N0) / (D1 - D0))) x 100, where the denominator represents the total elapsed time of the sample interval, the numerator represents the time during the interval when monitored components were inactive, and B represents the number of components being monitored, using a base counter of type `CounterMultiBase`. - -- `CounterMultiTimerInverse`: (B- ((N1 - N0) / (D1 - D0))) x 100, where the denominator represents the total elapsed time of the sample interval, the numerator represents the time during the interval when monitored components were inactive, and B represents the number of components being monitored, using a base counter of type `CounterMultiBase`. - -- `CounterTimer`: (N1 - N0) / (D1 - D0), where N1 and N0 are performance counter readings, and D1 and D0 are their corresponding time readings. Thus, the numerator represents the portions of the sample interval during which the monitored components were active, and the denominator represents the total elapsed time of the sample interval. - -- `CounterTimerInverse`: (1- ((N1 - N0) / (D1 - D0))) x 100, where the numerator represents the time during the interval when the monitored components were inactive, and the denominator represents the total elapsed time of the sample interval. - -- `CountPerTimeInterval32`: (N1 - N0) / (D1 - D0), where the numerator represents the number of items in the queue, and the denominator represents the time elapsed during the last sample interval. - -- `CountPerTimeInterval64`: (N1 - N0) / (D1 - D0), where the numerator represents the number of items in a queue and the denominator represents the time elapsed during the sample interval. - -- `ElapsedTime`: (D0 - N0) / F, where D0 represents the current time, N0 represents the time the object was started, and F represents the number of time units that elapse in one second. The value of F is factored into the equation so that the result can be displayed in seconds. - -- `NumberOfItems32`: None. Does not display an average, but shows the raw data as it is collected. - -- `NumberOfItems64`: None. Does not display an average, but shows the raw data as it is collected. - -- `NumberOfItemsHEX32`: None. Does not display an average, but shows the raw data as it is collected. - -- `NumberOfItemsHEX64`: None. Does not display an average, but shows the raw data as it is collected - -- `RateOfCountsPerSecond32`: (N1 - N0) / ((D1 - D0) / F), where N1 and N0 are performance counter readings, D1 and D0 are their corresponding time readings, and F represents the number of ticks per second. Thus, the numerator represents the number of operations performed during the last sample interval, the denominator represents the number of ticks elapsed during the last sample interval, and F is the frequency of the ticks. The value of F is factored into the equation so that the result can be displayed in seconds. - -- `RateOfCountsPerSecond64`: (N1 - N0) / ((D1 - D0) / F), where N1 and N0 are performance counter readings, D1 and D0 are their corresponding time readings, and F represents the number of ticks per second. Thus, the numerator represents the number of operations performed during the last sample interval, the denominator represents the number of ticks elapsed during the last sample interval, and F is the frequency of the ticks. The value of F is factored into the equation so that the result can be displayed in seconds. - -- `RawFraction`: (N0 / D0) x 100, where D0 represents a measured attribute (using a base counter of type `RawBase`) and N0 represents one component of that attribute. - -- `SampleCounter`: (N1 - N0) / ((D1 - D0) / F), where the numerator (N) represents the number of operations completed, the denominator (D) represents elapsed time in units of ticks of the system performance timer, and F represents the number of ticks that elapse in one second. F is factored into the equation so that the result can be displayed in seconds. - -- `SampleFraction`: ((N1 - N0) / (D1 - D0)) x 100, where the numerator represents the number of successful operations during the last sample interval, and the denominator represents the change in the number of all operations (of the type measured) completed during the sample interval, using counters of type `SampleBase`. - -- `Timer100Ns`: (N1 - N0) / (D1 - D0) x 100, where the numerator represents the portions of the sample interval during which the monitored components were active, and the denominator represents the total elapsed time of the sample interval. - -- `Timer100NsInverse`: (1- ((N1 - N0) / (D1 - D0))) x 100, where the numerator represents the time during the interval when the monitored components were inactive, and the denominator represents the total elapsed time of the sample interval. - -## Examples - The following examples demonstrate several of the counter types in the enumeration. - -### AverageCount64 - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/PerformanceCounterType.AverageCounter64/CPP/averagecount32.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationData/Overview/averagecount32.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/PerformanceCounterType.AverageCounter64/VB/averagecount32.vb" id="Snippet1"::: - -### AverageTimer32 - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/PerformanceCounterType.AverageTimer32/CPP/averagetimer32.cpp" id="Snippet2"::: - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterType/Overview/averagetimer32.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/PerformanceCounterType.AverageTimer32/VB/averagetimer32.vb" id="Snippet2"::: - -### ElapsedTime - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/PerformanceCounterType.ElapsedTime/CPP/elapsedtime.cpp" id="Snippet2"::: - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounter/NextValue/elapsedtime.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/PerformanceCounterType.ElapsedTime/VB/elapsedtime.vb" id="Snippet2"::: - -### NumberOfItems32 - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/PerformanceCounterType.NumberOfItems32/CPP/numberofitems32.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterType/Overview/numberofitems32.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/PerformanceCounterType.NumberOfItems32/VB/numberofitems32.vb" id="Snippet1"::: - -### NumberOfItems64 - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/PerformanceCounterType.NumberOfItems64/CPP/numberofitems64.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterType/Overview/numberofitems64.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/PerformanceCounterType.NumberOfItems64/VB/numberofitems64.vb" id="Snippet1"::: - -### SampleFraction - - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterType/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/PerformanceCounterType.SampleFraction/VB/program.vb" id="Snippet1"::: - -### RateOfCountsPerSecond32 - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/PerformanceCounterType.RateOfCountsPerSecond/CPP/rateofcountspersecond32.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterType/Overview/rateofcountspersecond32.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/PerformanceCounterType.RateOfCountsPerSecond/VB/rateofcountspersecond32.vb" id="Snippet1"::: - -### RateOfCountsPerSecond64 - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/PerformanceCounterType.RateOfCountsPerSecond64/CPP/rateofcountspersecond64.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterType/Overview/rateofcountspersecond64.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/PerformanceCounterType.RateOfCountsPerSecond64/VB/rateofcountspersecond64.vb" id="Snippet1"::: - -### RawFraction - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/PerformanceCounterType.RawFraction/CPP/rawfraction.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterType/Overview/rawfraction.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/PerformanceCounterType.RawFraction/VB/rawfraction.vb" id="Snippet1"::: - - ]]> - + For more information about this API, see Supplemental API remarks for PerformanceCounterType. diff --git a/xml/System.Drawing.Drawing2D/Matrix.xml b/xml/System.Drawing.Drawing2D/Matrix.xml index 95de521b2a8..031e8f39275 100644 --- a/xml/System.Drawing.Drawing2D/Matrix.xml +++ b/xml/System.Drawing.Drawing2D/Matrix.xml @@ -42,51 +42,7 @@ Encapsulates a 3-by-3 affine matrix that represents a geometric transform. This class cannot be inherited. - - object. Because the third column of a matrix that represents an affine transformation is always (0, 0, 1), you specify only the six numbers in the first two columns when you construct a object. The statement `Matrix myMatrix = new Matrix(0, 1, -1, 0, 3, 4)` constructs the matrix shown in the following figure. - - ![Transformations](~/add/media/aboutgdip05-art10.gif "Transformations") - -[!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] - -## Composite Transformations - -A composite transformation is a sequence of transformations, one followed by the other. Consider the matrices and transformations in the following list: - -||| -|-|-| -|Matrix A|Rotate 90 degrees| -|Matrix B|Scale by a factor of 2 in the x direction| -|Matrix C|Translate 3 units in the y direction| - - If we start with the point (2, 1) - represented by the matrix [2 1 1] - and multiply by A, then B, then C, the point (2, 1) will undergo the three transformations in the order listed. - - [2 1 1]ABC = [-2 5 1] - - Rather than store the three parts of the composite transformation in three separate matrices, you can multiply A, B, and C together to get a single 3×3 matrix that stores the entire composite transformation. Suppose ABC = D. Then a point multiplied by D gives the same result as a point multiplied by A, then B, then C. - - [2 1 1]D = [-2 5 1] - - The following illustration shows the matrices A, B, C, and D. - - ![Transformations](~/add/media/aboutgdip05-art12.gif "Transformations") - - The fact that the matrix of a composite transformation can be formed by multiplying the individual transformation matrices means that any sequence of affine transformations can be stored in a single object. - -> [!CAUTION] -> The order of a composite transformation is important. In general, rotate, then scale, then translate is not the same as scale, then rotate, then translate. Similarly, the order of matrix multiplication is important. In general, ABC is not the same as BAC. - - The class provides several methods for building a composite transformation: , , , , , and . The following example creates the matrix of a composite transformation that first rotates 30 degrees, then scales by a factor of 2 in the y direction, and then translates 5 units in the x direction: - - :::code language="csharp" source="~/snippets/csharp/System.Drawing.Drawing2D/Matrix/Overview/Class1.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/System.Drawing.CoordinateSystems/VB/Class1.vb" id="Snippet11"::: - - ]]> - + For more information about this API, see Supplemental API remarks for Matrix. Coordinate Systems and Transformations diff --git a/xml/System.Dynamic/ExpandoObject.xml b/xml/System.Dynamic/ExpandoObject.xml index 7f27fcbfddd..130ee72793f 100644 --- a/xml/System.Dynamic/ExpandoObject.xml +++ b/xml/System.Dynamic/ExpandoObject.xml @@ -79,129 +79,7 @@ Represents an object whose members can be dynamically added and removed at run time. - - , which enables you to share instances of the `ExpandoObject` class between languages that support the DLR interoperability model. For example, you can create an instance of the `ExpandoObject` class in C# and then pass it to an IronPython function. For more information, see [Dynamic Language Runtime Overview](/dotnet/framework/reflection-and-codedom/dynamic-language-runtime-overview) and [Introducing the ExpandoObject](https://go.microsoft.com/fwlink/?LinkID=169157) on the C# Frequently Asked Questions Web site. - - The `ExpandoObject` class is an implementation of the dynamic object concept that enables getting, setting, and invoking members. If you want to define types that have their own dynamic dispatch semantics, use the class. If you want to define how dynamic objects participate in the interoperability protocol and manage DLR fast dynamic dispatch caching, create your own implementation of the interface. - -## Creating an Instance - In C#, to enable late binding for an instance of the `ExpandoObject` class, you must use the `dynamic` keyword. For more information, see [Using Type dynamic](/dotnet/csharp/programming-guide/types/using-type-dynamic). - - In Visual Basic, dynamic operations are supported by late binding. For more information, see [Early and Late Binding (Visual Basic)](/dotnet/visual-basic/programming-guide/language-features/early-late-binding/). - - The following code example demonstrates how to create an instance of the `ExpandoObject` class. - - :::code language="csharp" source="~/snippets/csharp/System.Dynamic/ExpandoObject/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.dynamic.expandoobject/vb/module1.vb" id="Snippet1"::: - -## Adding New Members - You can add properties, methods, and events to instances of the `ExpandoObject` class. - - The following code example demonstrates how to add a new property to an instance of the `ExpandoObject` class. - - :::code language="csharp" source="~/snippets/csharp/System.Dynamic/ExpandoObject/Overview/program.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.dynamic.expandoobject/vb/module1.vb" id="Snippet2"::: - - The methods represent lambda expressions that are stored as delegates, which can be invoked when they are needed. The following code example demonstrates how to add a method that increments a value of the dynamic property. - - :::code language="csharp" source="~/snippets/csharp/System.Dynamic/ExpandoObject/Overview/program.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.dynamic.expandoobject/vb/module1.vb" id="Snippet3"::: - - The following code example demonstrates how to add an event to an instance of the `ExpandoObject` class. - -```csharp -class Program -{ - static void Main(string[] args) - { - dynamic sampleObject = new ExpandoObject(); - - // Create a new event and initialize it with null. - sampleObject.sampleEvent = null; - - // Add an event handler. - sampleObject.sampleEvent += new EventHandler(SampleHandler); - - // Raise an event for testing purposes. - sampleObject.sampleEvent(sampleObject, new EventArgs()); - } - - // Event handler. - static void SampleHandler(object sender, EventArgs e) - { - Console.WriteLine("SampleHandler for {0} event", sender); - } -} -// This code example produces the following output: -// SampleHandler for System.Dynamic.ExpandoObject event. -``` - -```vb -Module Module1 - -Sub Main() - Dim sampleObject As Object = New ExpandoObject() - - ' Create a new event and initialize it with null. - sampleObject.sampleEvent = Nothing - - ' Add an event handler. - Dim handler As EventHandler = AddressOf SampleHandler - sampleObject.sampleEvent = - [Delegate].Combine(sampleObject.sampleEvent, handler) - - ' Raise an event for testing purposes. - sampleObject.sampleEvent.Invoke(sampleObject, New EventArgs()) - -End Sub - -' Event handler. -Sub SampleHandler(ByVal sender As Object, ByVal e As EventArgs) - Console.WriteLine("SampleHandler for {0} event", sender) -End Sub - -' This code example produces the following output: -' SampleHandler for System.Dynamic.ExpandoObject event. - -End Module -``` - -## Passing As a Parameter - You can pass instances of the `ExpandoObject` class as parameters. Note that these instances are treated as dynamic objects in C# and late-bound objects in Visual Basic. This means that you do not have IntelliSense for object members and you do not receive compiler errors when you call non-existent members. If you call a member that does not exist, an exception occurs. - - The following code example demonstrates how you can create and use a method to print the names and values of properties. - - :::code language="csharp" source="~/snippets/csharp/System.Dynamic/ExpandoObject/Overview/program.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.dynamic.expandoobject/vb/module1.vb" id="Snippet4"::: - -## Enumerating and Deleting Members - The `ExpandoObject` class implements the `IDictionary` interface. This enables enumeration of members added to the instance of the `ExpandoObject` class at run time. This can be useful if you do not know at compile time what members an instance might have. - - The following code example shows how you can cast an instance of the `ExpandoObject` class to the interface and enumerate the instance's members. - - :::code language="csharp" source="~/snippets/csharp/System.Dynamic/ExpandoObject/Overview/program.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.dynamic.expandoobject/vb/module1.vb" id="Snippet5"::: - - In languages that do not have syntax for deleting members (such as C# and Visual Basic), you can delete a member by implicitly casting an instance of the `ExpandoObject` to the `IDictionary` interface and then deleting the member as a key/value pair. This is shown in the following example. - - :::code language="csharp" source="~/snippets/csharp/System.Dynamic/ExpandoObject/Overview/program.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.dynamic.expandoobject/vb/module1.vb" id="Snippet6"::: - -## Receiving Notifications of Property Changes - The `ExpandoObject` class implements the interface and can raise a event when a member is added, deleted, or modified. This enables `ExpandoObject` class integration with Windows Presentation Foundation (WPF) data binding and other environments that require notification about changes in the object content. - - The following code example demonstrates how to create an event handler for the `PropertyChanged` event. - - :::code language="csharp" source="~/snippets/csharp/System.Dynamic/ExpandoObject/Overview/program.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.dynamic.expandoobject/vb/module1.vb" id="Snippet7"::: - - ]]> - + For more information about this API, see Supplemental API remarks for ExpandoObject. diff --git a/xml/System.Globalization/CompareInfo.xml b/xml/System.Globalization/CompareInfo.xml index 6c3319dd4f4..526c2afbfd3 100644 --- a/xml/System.Globalization/CompareInfo.xml +++ b/xml/System.Globalization/CompareInfo.xml @@ -92,7 +92,7 @@ :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CompareInfo/VB/CompareInfo.vb" id="Snippet1"::: ]]> - For more information about this API, see System.Globalization.CompareInfo class. + For more information about this API, see Supplemental API remarks for CompareInfo. Sorting Weight Tables for Windows operating systems Default Unicode Collation Element Table, for Linux and macOS diff --git a/xml/System.Globalization/CompareOptions.xml b/xml/System.Globalization/CompareOptions.xml index 2e542820c86..2fee02b069d 100644 --- a/xml/System.Globalization/CompareOptions.xml +++ b/xml/System.Globalization/CompareOptions.xml @@ -74,7 +74,7 @@ :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CompareOptions.StringSort/VB/compareoptions_stringsort.vb" id="Snippet1"::: ]]> - For more information about this API, see System.Globalization.CompareOptions enum. + For more information about this API, see Supplemental API remarks for CompareOptions. Basic String Operations in .NET diff --git a/xml/System.Globalization/CultureAndRegionInfoBuilder.xml b/xml/System.Globalization/CultureAndRegionInfoBuilder.xml index 071f78312e4..e19036d02c6 100644 --- a/xml/System.Globalization/CultureAndRegionInfoBuilder.xml +++ b/xml/System.Globalization/CultureAndRegionInfoBuilder.xml @@ -29,7 +29,7 @@ :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureandregioninfobuilder.class/vb/car.vb" id="Snippet1"::: ]]> - For more information about this API, see System.Globalization.CultureAndRegionInfoBuilder class. + For more information about this API, see Supplemental API remarks for CultureAndRegionInfoBuilder. diff --git a/xml/System.Globalization/CultureInfo.xml b/xml/System.Globalization/CultureInfo.xml index 7dea07e0754..25a63e0fe35 100644 --- a/xml/System.Globalization/CultureInfo.xml +++ b/xml/System.Globalization/CultureInfo.xml @@ -93,7 +93,7 @@ :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CultureInfo_esES/VB/spanishspain.vb" id="Snippet1"::: ]]> - For more information about this API, see System.Globalization.CultureInfo class. + For more information about this API, see Supplemental API remarks for CultureInfo. diff --git a/xml/System.Globalization/DateTimeFormatInfo.xml b/xml/System.Globalization/DateTimeFormatInfo.xml index 754ac39b840..6d0bf1a8d8c 100644 --- a/xml/System.Globalization/DateTimeFormatInfo.xml +++ b/xml/System.Globalization/DateTimeFormatInfo.xml @@ -98,7 +98,7 @@ :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.datetimeformatinfo.class/vb/format1.vb" id="Snippet5"::: ]]> - For more information about this API, see System.Globalization.DateTimeFormatInfo class. + For more information about this API, see Supplemental API remarks for DateTimeFormatInfo. diff --git a/xml/System.Globalization/NumberFormatInfo.xml b/xml/System.Globalization/NumberFormatInfo.xml index f1d5b3afb74..d363ba03925 100644 --- a/xml/System.Globalization/NumberFormatInfo.xml +++ b/xml/System.Globalization/NumberFormatInfo.xml @@ -91,7 +91,7 @@ :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/NumberFormatInfo/vb/numberformatinfo.vb" id="Snippet1"::: ]]> - For more information about this API, see System.Globalization.NumberFormatInfo class. + For more information about this API, see Supplemental API remarks for NumberFormatInfo. Custom Numeric Format Strings diff --git a/xml/System.Globalization/PersianCalendar.xml b/xml/System.Globalization/PersianCalendar.xml index 15f78f94f29..d661e6127bc 100644 --- a/xml/System.Globalization/PersianCalendar.xml +++ b/xml/System.Globalization/PersianCalendar.xml @@ -78,7 +78,7 @@ :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/sys.glob.persianCal/vb/pcal.vb" id="Snippet1"::: ]]> - For more information about this API, see System.Globalization.PersianCalendar class. + For more information about this API, see Supplemental API remarks for PersianCalendar. diff --git a/xml/System.Globalization/RegionInfo.xml b/xml/System.Globalization/RegionInfo.xml index 3418cc38d1c..24bee26e5c7 100644 --- a/xml/System.Globalization/RegionInfo.xml +++ b/xml/System.Globalization/RegionInfo.xml @@ -80,7 +80,7 @@ :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.RegionInfo/VB/regioninfo.vb" id="Snippet1"::: ]]> - For more information about this API, see System.Globalization.RegionInfo class. + For more information about this API, see Supplemental API remarks for RegionInfo. diff --git a/xml/System.Globalization/SortKey.xml b/xml/System.Globalization/SortKey.xml index 6ceb5ddcdfe..b9ea6017721 100644 --- a/xml/System.Globalization/SortKey.xml +++ b/xml/System.Globalization/SortKey.xml @@ -77,7 +77,7 @@ :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.sortkey.class/vb/sortkey1.vb" id="Snippet1"::: ]]> - For more information about this API, see System.Globalization.SortKey class. + For more information about this API, see Supplemental API remarks for SortKey. diff --git a/xml/System.Globalization/SortVersion.xml b/xml/System.Globalization/SortVersion.xml index 058b9da4ae5..ffbcc4518ee 100644 --- a/xml/System.Globalization/SortVersion.xml +++ b/xml/System.Globalization/SortVersion.xml @@ -63,7 +63,7 @@ :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.sortversion/vb/example1.vb" id="Snippet1"::: ]]> - For more information about this API, see System.Globalization.SortVersion class. + For more information about this API, see Supplemental API remarks for SortVersion. diff --git a/xml/System.IO/FileStream.xml b/xml/System.IO/FileStream.xml index 35dbcfed5ca..e4758c2db01 100644 --- a/xml/System.IO/FileStream.xml +++ b/xml/System.IO/FileStream.xml @@ -66,54 +66,22 @@ Provides a for a file, supporting both synchronous and asynchronous read and write operations. - - class to read from, write to, open, and close files on a file system, and to manipulate other file-related operating system handles, including pipes, standard input, and standard output. You can use the , , , and methods to perform synchronous operations, or the , , , and methods to perform asynchronous operations. Use the asynchronous methods to perform resource-intensive file operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. buffers input and output for better performance. - -> [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - - The property detects whether the file handle was opened asynchronously. You specify this value when you create an instance of the class using a constructor that has an `isAsync`, `useAsync`, or `options` parameter. When the property is `true`, the stream utilizes overlapped I/O to perform file operations asynchronously. However, the property does not have to be `true` to call the , , or method. When the property is `false` and you call the asynchronous read and write operations, the UI thread is still not blocked, but the actual I/O operation is performed synchronously. - - The method supports random access to files. allows the read/write position to be moved to any position within the file. This is done with byte offset reference point parameters. The byte offset is relative to the seek reference point, which can be the beginning, the current position, or the end of the underlying file, as represented by the three members of the enumeration. - -> [!NOTE] -> Disk files always support random access. At the time of construction, the property value is set to `true` or `false` depending on the underlying file type. If the underlying file type is FILE_TYPE_DISK, as defined in winbase.h, the property value is `true`. Otherwise, the property value is `false`. - - If a process terminates with part of a file locked or closes a file that has outstanding locks, the behavior is undefined. - - For directory operations and other file operations, see the , , and classes. The class is a utility class that has static methods primarily for the creation of objects based on file paths. The class creates a stream from a byte array and is similar to the class. - - For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - -## Detection of Stream Position Changes - When a object does not have an exclusive hold on its handle, another thread could access the file handle concurrently and change the position of the operating system's file pointer that is associated with the file handle. In this case, the cached position in the object and the cached data in the buffer could be compromised. The object routinely performs checks on methods that access the cached buffer to ensure that the operating system's handle position is the same as the cached position used by the object. - - If an unexpected change in the handle position is detected in a call to the method, the .NET Framework discards the contents of the buffer and reads the stream from the file again. This can affect performance, depending on the size of the file and any other processes that could affect the position of the file stream. - - If an unexpected change in the handle position is detected in a call to the method, the contents of the buffer are discarded and an exception is thrown. - - A object will not have an exclusive hold on its handle when either the property is accessed to expose the handle or the object is given the property in its constructor. - - - -## Examples - The following example demonstrates some of the constructors. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/FStream Class/CPP/fstream class.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/Overview/fstream class.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/Overview/fstream class.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FStream Class/VB/fstream class.vb" id="Snippet1"::: - - The following example shows how to write to a file asynchronously. This code runs in a WPF app that has a TextBlock named UserInput and a button hooked up to a Click event handler that is named Button_Click. The file path needs to be changed to a file that exists on the computer. - - :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/Overview/example3.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Asynchronous_File_IO_async/vb/example3.vb" id="Snippet3"::: - - ]]> - + + constructors. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/FStream Class/CPP/fstream class.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/Overview/fstream class.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/Overview/fstream class.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FStream Class/VB/fstream class.vb" id="Snippet1"::: + + The following example shows how to write to a file asynchronously. This code runs in a WPF app that has a TextBlock named UserInput and a button hooked up to a Click event handler that is named Button_Click. The file path needs to be changed to a file that exists on the computer. + + :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/Overview/example3.cs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Asynchronous_File_IO_async/vb/example3.vb" id="Snippet3"::: + ]]> + + For more information about this API, see Supplemental API remarks for FileStream. @@ -182,29 +150,29 @@ A bitwise combination of the enumeration values that sets the and properties of the object. Initializes a new instance of the class for the specified file handle, with the specified read/write permission. - is called, the handle is also closed and the file's handle count is decremented. - - `FileStream` assumes that it has exclusive control over the handle. Reading, writing, or seeking while a `FileStream` is also holding a handle could result in data corruption. For data safety, call before using the handle, and avoid calling any methods other than `Close` after you are done using the handle. - + is called, the handle is also closed and the file's handle count is decremented. + + `FileStream` assumes that it has exclusive control over the handle. Reading, writing, or seeking while a `FileStream` is also holding a handle could result in data corruption. For data safety, call before using the handle, and avoid calling any methods other than `Close` after you are done using the handle. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - `FileShare.Read` is the default for those constructors without a `FileShare` parameter. - - For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + `FileShare.Read` is the default for those constructors without a `FileShare` parameter. + + For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> is not a field of . The caller does not have the required permission. - An I/O error, such as a disk error, occurred. - - -or- - + An I/O error, such as a disk error, occurred. + + -or- + The stream has been closed. The requested is not permitted by the operating system for the specified file handle, such as when is or and the file handle is set for read-only access. File and Stream I/O @@ -280,29 +248,29 @@ A bitwise combination of the enumeration values that sets the and properties of the object. Initializes a new instance of the class for the specified file handle, with the specified read/write permission. - is called, the handle is also closed and the file's handle count is decremented. - - `FileStream` assumes that it has exclusive control over the handle. Reading, writing, or seeking while a `FileStream` is also holding a handle could result in data corruption. For data safety, call before using the handle, and avoid calling any methods other than `Close` after you are done using the handle. - + is called, the handle is also closed and the file's handle count is decremented. + + `FileStream` assumes that it has exclusive control over the handle. Reading, writing, or seeking while a `FileStream` is also holding a handle could result in data corruption. For data safety, call before using the handle, and avoid calling any methods other than `Close` after you are done using the handle. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - `FileShare.Read` is the default for those constructors without a `FileShare` parameter. - - For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + `FileShare.Read` is the default for those constructors without a `FileShare` parameter. + + For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> is not a field of . The caller does not have the required permission. - An I/O error, such as a disk error, occurred. - - -or- - + An I/O error, such as a disk error, occurred. + + -or- + The stream has been closed. The requested is not permitted by the operating system for the specified file handle, such as when is or and the file handle is set for read-only access. File and Stream I/O @@ -360,49 +328,49 @@ One of the enumeration values that determines how to open or create the file. Initializes a new instance of the class with the specified path and creation mode. - [!NOTE] -> `path` is not required to be a file stored on disk; it can be any part of a system that supports access through streams. For example, depending on the system, this class can access a physical device. - - is `true` for all objects that encapsulate files. If `path` indicates a device that does not support seeking, the property on the resulting is `false`. For additional information, see . - - `FileShare.Read` is the default for those constructors without a `FileShare` parameter. - - For constructors without a parameter, if the `mode` parameter is set to , is the default access. Otherwise, the access is set to . - +> `path` is not required to be a file stored on disk; it can be any part of a system that supports access through streams. For example, depending on the system, this class can access a physical device. + + is `true` for all objects that encapsulate files. If `path` indicates a device that does not support seeking, the property on the resulting is `false`. For additional information, see . + + `FileShare.Read` is the default for those constructors without a `FileShare` parameter. + + For constructors without a parameter, if the `mode` parameter is set to , is the default access. Otherwise, the access is set to . + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example shows how to write data to a file, byte by byte, and then verify that the data was written correctly. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example shows how to write data to a file, byte by byte, and then verify that the data was written correctly. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.FileStream1/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/.ctor/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/.ctor/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileStream1/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileStream1/VB/source.vb" id="Snippet1"::: + ]]> - .NET Framework and .NET Core versions older than 2.1: is an empty string (""), contains only white space, or contains one or more invalid characters. - - -or- - + .NET Framework and .NET Core versions older than 2.1: is an empty string (""), contains only white space, or contains one or more invalid characters. + + -or- + refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in an NTFS environment. refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in a non-NTFS environment. @@ -412,10 +380,10 @@ The file cannot be found, such as when is or , and the file specified by does not exist. The file must already exist in these modes. specifies a file that is read-only. - An I/O error, such as specifying when the file specified by already exists, occurred. - - -or- - + An I/O error, such as specifying when the file specified by already exists, occurred. + + -or- + The stream has been closed. The specified path is invalid, such as being on an unmapped drive. The specified path, file name, or both exceed the system-defined maximum length. @@ -552,30 +520,30 @@ The file was too large (when A positive value greater than 0 indicating the buffer size. The default buffer size is 4096. Initializes a new instance of the class for the specified file handle, with the specified read/write permission, and buffer size. - before using the handle, and avoid calling any methods other than `Close` after you are done using the handle. Alternately, read and write to the handle before calling this `FileStream` constructor. - - `FileShare.Read` is the default for those constructors without a `FileShare` parameter. - + before using the handle, and avoid calling any methods other than `Close` after you are done using the handle. Alternately, read and write to the handle before calling this `FileStream` constructor. + + `FileShare.Read` is the default for those constructors without a `FileShare` parameter. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> - The parameter is an invalid handle. - - -or- - + The parameter is an invalid handle. + + -or- + The parameter is a synchronous handle and it was used asynchronously. The parameter is negative. - An I/O error, such as a disk error, occurred. - - -or- - + An I/O error, such as a disk error, occurred. + + -or- + The stream has been closed. The caller does not have the required permission. The requested is not permitted by the operating system for the specified file handle, such as when is or and the file handle is set for read-only access. @@ -655,29 +623,29 @@ The file was too large (when if the file handle will be owned by this instance; otherwise, . Initializes a new instance of the class for the specified file handle, with the specified read/write permission and instance ownership. - method will also close the handle and the file's handle count is decremented. The `FileStream` object is given the default buffer size of 4096 bytes. - - `FileStream` assumes that it has exclusive control over the handle. Reading, writing, or seeking while a `FileStream` is also holding a handle could result in data corruption. For data safety, call before using the handle, and avoid calling methods other than `Close` after you are done using the handle. - - `FileShare.Read` is the default for those constructors without a `FileShare` parameter. - + method will also close the handle and the file's handle count is decremented. The `FileStream` object is given the default buffer size of 4096 bytes. + + `FileStream` assumes that it has exclusive control over the handle. Reading, writing, or seeking while a `FileStream` is also holding a handle could result in data corruption. For data safety, call before using the handle, and avoid calling methods other than `Close` after you are done using the handle. + + `FileShare.Read` is the default for those constructors without a `FileShare` parameter. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> is not a field of . The caller does not have the required permission. - An I/O error, such as a disk error, occurred. - - -or- - + An I/O error, such as a disk error, occurred. + + -or- + The stream has been closed. The requested is not permitted by the operating system for the specified file handle, such as when is or and the file handle is set for read-only access. File and Stream I/O @@ -737,43 +705,43 @@ The file was too large (when A bitwise combination of the enumeration values that determines how the file can be accessed by the object. This also determines the values returned by the and properties of the object. is if specifies a disk file. Initializes a new instance of the class with the specified path, creation mode, and read/write permission. - [!NOTE] -> `path` is not required to be a file stored on disk; it can be any part of a system that supports access through streams. For example, depending on the system, this class can access a physical device. - - is `true` for all objects that encapsulate files. If `path` indicates a device that does not support seeking, the property on the resulting is `false`. For additional information, see . - - `FileShare.Read` is the default for those constructors without a `FileShare` parameter. - +> `path` is not required to be a file stored on disk; it can be any part of a system that supports access through streams. For example, depending on the system, this class can access a physical device. + + is `true` for all objects that encapsulate files. If `path` indicates a device that does not support seeking, the property on the resulting is `false`. For additional information, see . + + `FileShare.Read` is the default for those constructors without a `FileShare` parameter. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> is . - .NET Framework and .NET Core versions older than 2.1: is an empty string (""), contains only white space, or contains one or more invalid characters. - - -or- - + .NET Framework and .NET Core versions older than 2.1: is an empty string (""), contains only white space, or contains one or more invalid characters. + + -or- + refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in an NTFS environment. refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in a non-NTFS environment. The file cannot be found, such as when is or , and the file specified by does not exist. The file must already exist in these modes. - An I/O error, such as specifying when the file specified by already exists, occurred. - - -or- - + An I/O error, such as specifying when the file specified by already exists, occurred. + + -or- + The stream has been closed. The caller does not have the required permission. The specified path is invalid, such as being on an unmapped drive. @@ -840,32 +808,32 @@ The file was too large (when if the handle was opened asynchronously (that is, in overlapped I/O mode); otherwise, . Initializes a new instance of the class for the specified file handle, with the specified read/write permission, buffer size, and synchronous or asynchronous state. - , , or method. When the `isAsync` parameter is `false` and you call the asynchronous read and write operations, the UI thread is still not blocked, but the actual I/O operation is performed synchronously. - - `FileStream` assumes that it has exclusive control over the handle. Reading, writing, or seeking while a `FileStream` is also holding a handle could result in data corruption. For data safety, call before using the handle, and avoid calling any methods other than `Close` after you are done using the handle. Alternately, read and write to the handle before calling this `FileStream` constructor. - - `FileShare.Read` is the default for those constructors without a `FileShare` parameter. - + , , or method. When the `isAsync` parameter is `false` and you call the asynchronous read and write operations, the UI thread is still not blocked, but the actual I/O operation is performed synchronously. + + `FileStream` assumes that it has exclusive control over the handle. Reading, writing, or seeking while a `FileStream` is also holding a handle could result in data corruption. For data safety, call before using the handle, and avoid calling any methods other than `Close` after you are done using the handle. Alternately, read and write to the handle before calling this `FileStream` constructor. + + `FileShare.Read` is the default for those constructors without a `FileShare` parameter. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> - The parameter is an invalid handle. - - -or- - + The parameter is an invalid handle. + + -or- + The parameter is a synchronous handle and it was used asynchronously. The parameter is negative. - An I/O error, such as a disk error, occurred. - - -or- - + An I/O error, such as a disk error, occurred. + + -or- + The stream has been closed. The caller does not have the required permission. The requested is not permitted by the operating system for the specified file handle, such as when is or and the file handle is set for read-only access. @@ -947,28 +915,28 @@ The file was too large (when A positive value greater than 0 indicating the buffer size. The default buffer size is 4096. Initializes a new instance of the class for the specified file handle, with the specified read/write permission, instance ownership, and buffer size. - method will also close the handle. In particular, the file's handle count is decremented. The `FileStream` object is given the specified buffer size. - - `FileStream` assumes that it has exclusive control over the handle. Reading, writing, or seeking while a `FileStream` is also holding a handle could result in data corruption. For data safety, call before using the handle, and avoid calling any methods other than `Close` after you are done using the handle. Alternately, read and write to the handle before calling this `FileStream` constructor. - - `FileShare.Read` is the default for those constructors without a `FileShare` parameter. - + method will also close the handle. In particular, the file's handle count is decremented. The `FileStream` object is given the specified buffer size. + + `FileStream` assumes that it has exclusive control over the handle. Reading, writing, or seeking while a `FileStream` is also holding a handle could result in data corruption. For data safety, call before using the handle, and avoid calling any methods other than `Close` after you are done using the handle. Alternately, read and write to the handle before calling this `FileStream` constructor. + + `FileShare.Read` is the default for those constructors without a `FileShare` parameter. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> is negative. - An I/O error, such as a disk error, occurred. - - -or- - + An I/O error, such as a disk error, occurred. + + -or- + The stream has been closed. The caller does not have the required permission. The requested is not permitted by the operating system for the specified file handle, such as when is or and the file handle is set for read-only access. @@ -1031,51 +999,51 @@ The file was too large (when A bitwise combination of the enumeration values that determines how the file will be shared by processes. Initializes a new instance of the class with the specified path, creation mode, read/write permission, and sharing permission. - [!NOTE] -> `path` is not required to be a file stored on disk; it can be any part of a system that supports access through streams. For example, depending on the system, this class can access a physical device. - - is `true` for all objects that encapsulate files. If `path` indicates a device that does not support seeking, the property on the resulting is `false`. For additional information, see . - +> `path` is not required to be a file stored on disk; it can be any part of a system that supports access through streams. For example, depending on the system, this class can access a physical device. + + is `true` for all objects that encapsulate files. If `path` indicates a device that does not support seeking, the property on the resulting is `false`. For additional information, see . + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - This code example is part of a larger example provided for the method. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + This code example is part of a larger example provided for the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.FileStream3/CPP/fstreamlock.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/.ctor/fstreamlock.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/.ctor/fstreamlock.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileStream3/VB/fstreamlock.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileStream3/VB/fstreamlock.vb" id="Snippet2"::: + ]]> is . - .NET Framework and .NET Core versions older than 2.1: is an empty string (""), contains only white space, or contains one or more invalid characters. - - -or- - + .NET Framework and .NET Core versions older than 2.1: is an empty string (""), contains only white space, or contains one or more invalid characters. + + -or- + refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in an NTFS environment. refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in a non-NTFS environment. The file cannot be found, such as when is or , and the file specified by does not exist. The file must already exist in these modes. An I/O error, such as specifying when the file specified by already exists, occurred. - - -or- - + + -or- + The stream has been closed. The caller does not have the required permission. The specified path is invalid, such as being on an unmapped drive. @@ -1164,29 +1132,29 @@ The file was too large (when if the handle was opened asynchronously (that is, in overlapped I/O mode); otherwise, . Initializes a new instance of the class for the specified file handle, with the specified read/write permission, instance ownership, buffer size, and synchronous or asynchronous state. - method will also close the handle. In particular, the file's handle count is decremented. The `FileStream` object is given the specified buffer size. - - `FileStream` assumes that it has exclusive control over the handle. Reading, writing, or seeking while a `FileStream` is also holding a handle could result in data corruption. For data safety, call before using the handle, and avoid calling any methods other than `Close` after you are done using the handle. Alternately, read and write to the handle before calling this `FileStream` constructor. - - `FileShare.Read` is the default for those constructors without a `FileShare` parameter. - + method will also close the handle. In particular, the file's handle count is decremented. The `FileStream` object is given the specified buffer size. + + `FileStream` assumes that it has exclusive control over the handle. Reading, writing, or seeking while a `FileStream` is also holding a handle could result in data corruption. For data safety, call before using the handle, and avoid calling any methods other than `Close` after you are done using the handle. Alternately, read and write to the handle before calling this `FileStream` constructor. + + `FileShare.Read` is the default for those constructors without a `FileShare` parameter. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> is less than or greater than or is less than or equal to 0. The handle is invalid. - An I/O error, such as a disk error, occurred. - - -or- - + An I/O error, such as a disk error, occurred. + + -or- + The stream has been closed. The caller does not have the required permission. The requested is not permitted by the operating system for the specified file handle, such as when is or and the file handle is set for read-only access. @@ -1251,45 +1219,45 @@ The file was too large (when A positive value greater than 0 indicating the buffer size. The default buffer size is 4096. Initializes a new instance of the class with the specified path, creation mode, read/write and sharing permission, and buffer size. - [!NOTE] -> `path` is not required to be a file stored on disk; it can be any part of a system that supports access through streams. For example, depending on the system, this class can access a physical device. - - is `true` for all objects that encapsulate files. If `path` indicates a device that does not support seeking, the property on the resulting is `false`. For additional information, see . - +> `path` is not required to be a file stored on disk; it can be any part of a system that supports access through streams. For example, depending on the system, this class can access a physical device. + + is `true` for all objects that encapsulate files. If `path` indicates a device that does not support seeking, the property on the resulting is `false`. For additional information, see . + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> is . - .NET Framework and .NET Core versions older than 2.1: is an empty string (""), contains only white space, or contains one or more invalid characters. - - -or- - + .NET Framework and .NET Core versions older than 2.1: is an empty string (""), contains only white space, or contains one or more invalid characters. + + -or- + refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in an NTFS environment. refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in a non-NTFS environment. - is negative or zero. - - -or- - + is negative or zero. + + -or- + , , or contain an invalid value. The file cannot be found, such as when is or , and the file specified by does not exist. The file must already exist in these modes. An I/O error, such as specifying when the file specified by already exists, occurred. - - -or- - + + -or- + The stream has been closed. The caller does not have the required permission. The specified path is invalid, such as being on an unmapped drive. @@ -1358,55 +1326,55 @@ The file was too large (when Specifies whether to use asynchronous I/O or synchronous I/O. However, note that the underlying operating system might not support asynchronous I/O, so when specifying , the handle might be opened synchronously depending on the platform. When opened asynchronously, the and methods perform better on large reads or writes, but they might be much slower for small reads or writes. If the application is designed to take advantage of asynchronous I/O, set the parameter to . Using asynchronous I/O correctly can speed up applications by as much as a factor of 10, but using it without redesigning the application for asynchronous I/O can decrease performance by as much as a factor of 10. Initializes a new instance of the class with the specified path, creation mode, read/write and sharing permission, buffer size, and synchronous or asynchronous state. - [!NOTE] -> `path` is not required to be a file stored on disk; it can be any part of a system that supports access through streams. For example, depending on the system, this class can access a physical device. - - is `true` for all objects that encapsulate files. If `path` indicates a device that does not support seeking, the property on the resulting is `false`. For additional information, see . - +> `path` is not required to be a file stored on disk; it can be any part of a system that supports access through streams. For example, depending on the system, this class can access a physical device. + + is `true` for all objects that encapsulate files. If `path` indicates a device that does not support seeking, the property on the resulting is `false`. For additional information, see . + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example shows how to asynchronously write data to a file and then verify that the data was written correctly. A `State` object is created to pass information from the main thread to the `EndReadCallback` and `EndWriteCallback` methods. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example shows how to asynchronously write data to a file and then verify that the data was written correctly. A `State` object is created to pass information from the main thread to the `EndReadCallback` and `EndWriteCallback` methods. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.FileStream2/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/.ctor/source1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/.ctor/source1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileStream2/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileStream2/VB/source.vb" id="Snippet1"::: + ]]> is . - .NET Framework and .NET Core versions older than 2.1: is an empty string (""), contains only white space, or contains one or more invalid characters. - - -or- - + .NET Framework and .NET Core versions older than 2.1: is an empty string (""), contains only white space, or contains one or more invalid characters. + + -or- + refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in an NTFS environment. refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in a non-NTFS environment. - is negative or zero. - - -or- - + is negative or zero. + + -or- + , , or contain an invalid value. The file cannot be found, such as when is or , and the file specified by does not exist. The file must already exist in these modes. An I/O error, such as specifying when the file specified by already exists, occurred. - - -or- - + + -or- + The stream has been closed. The caller does not have the required permission. The specified path is invalid, such as being on an unmapped drive. @@ -1475,64 +1443,64 @@ The file was too large (when A bitwise combination of the enumeration values that specifies additional file options. Initializes a new instance of the class with the specified path, creation mode, read/write and sharing permission, the access other FileStreams can have to the same file, the buffer size, and additional file options. - object. - - The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. - + object. + + The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. + > [!NOTE] -> `path` is not required to be a file stored on disk; it can be any part of a system that supports access through streams. For example, depending on the system, this class can access a physical device. - - is `true` for all objects that encapsulate files. If `path` indicates a device that does not support seeking, the property on the resulting is `false`. For additional information, see . - +> `path` is not required to be a file stored on disk; it can be any part of a system that supports access through streams. For example, depending on the system, this class can access a physical device. + + is `true` for all objects that encapsulate files. If `path` indicates a device that does not support seeking, the property on the resulting is `false`. For additional information, see . + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example writes data to a file and then reads the data using the object. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example writes data to a file and then reads the data using the object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/IO.FileStream.ctor1/cpp/example.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/.ctor/example.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/.ctor/example.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.FileStream.ctor1/VB/example.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.FileStream.ctor1/VB/example.vb" id="Snippet1"::: + ]]> is . - .NET Framework and .NET Core versions older than 2.1: is an empty string (""), contains only white space, or contains one or more invalid characters. - - -or- - + .NET Framework and .NET Core versions older than 2.1: is an empty string (""), contains only white space, or contains one or more invalid characters. + + -or- + refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in an NTFS environment. refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in a non-NTFS environment. - is negative or zero. - - -or- - + is negative or zero. + + -or- + , , or contain an invalid value. The file cannot be found, such as when is or , and the file specified by does not exist. The file must already exist in these modes. - An I/O error, such as specifying when the file specified by already exists, occurred. - - -or- - + An I/O error, such as specifying when the file specified by already exists, occurred. + + -or- + The stream has been closed. The caller does not have the required permission. The specified path is invalid, such as being on an unmapped drive. - The requested is not permitted by the operating system for the specified , such as when is or and the file or directory is set for read-only access. - - -or- - + The requested is not permitted by the operating system for the specified , such as when is or and the file or directory is set for read-only access. + + -or- + is specified for , but file encryption is not supported on the current platform. The specified path, file name, or both exceed the system-defined maximum length. File and Stream I/O @@ -1586,57 +1554,57 @@ The file was too large (when A bitwise combination of the enumeration values that specifies additional file options. Initializes a new instance of the class with the specified path, creation mode, access rights and sharing permission, the buffer size, and additional file options. - constructor to apply access rights at the point of creation of a file. To access or modify rights on an existing file, consider using the and methods. - - The `fileOptions` parameter is used to provide access to more advanced operations that can be leveraged when creating a object. - - The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. - + constructor to apply access rights at the point of creation of a file. To access or modify rights on an existing file, consider using the and methods. + + The `fileOptions` parameter is used to provide access to more advanced operations that can be leveraged when creating a object. + + The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. + > [!NOTE] -> `path` is not required to be a file stored on disk; it can be any part of a system that supports access through streams. For example, depending on the system, this class can access a physical device. - - is `true` for all objects that encapsulate files. If `path` indicates a device that does not support seeking, the property on the resulting is `false`. For additional information, see . - +> `path` is not required to be a file stored on disk; it can be any part of a system that supports access through streams. For example, depending on the system, this class can access a physical device. + + is `true` for all objects that encapsulate files. If `path` indicates a device that does not support seeking, the property on the resulting is `false`. For additional information, see . + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> is . - .NET Framework and .NET Core versions older than 2.1: is an empty string (""), contains only white space, or contains one or more invalid characters. - - -or- - + .NET Framework and .NET Core versions older than 2.1: is an empty string (""), contains only white space, or contains one or more invalid characters. + + -or- + refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in an NTFS environment. refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in a non-NTFS environment. - is negative or zero. - - -or- - + is negative or zero. + + -or- + , , or contain an invalid value. The file cannot be found, such as when is or , and the file specified by does not exist. The file must already exist in these modes. The current operating system is not Windows NT or later. - An I/O error, such as specifying when the file specified by already exists, occurred. - - -or- - + An I/O error, such as specifying when the file specified by already exists, occurred. + + -or- + The stream has been closed. The caller does not have the required permission. The specified path is invalid, such as being on an unmapped drive. - The requested is not permitted by the operating system for the specified , such as when is or and the file or directory is set for read-only access. - - -or- - + The requested is not permitted by the operating system for the specified , such as when is or and the file or directory is set for read-only access. + + -or- + is specified for , but file encryption is not supported on the current platform. The specified , file name, or both exceed the system-defined maximum length. File and Stream I/O @@ -1692,67 +1660,67 @@ The file was too large (when An object that determines the access control and audit security for the file. Initializes a new instance of the class with the specified path, creation mode, access rights and sharing permission, the buffer size, additional file options, access control and audit security. - constructor to apply access rights at the point of creation of a file. To access or modify rights on an existing file, consider using the and methods. - - The `fileOptions` parameter is used to provide access to more advanced operations that can be leveraged when creating a object. - - The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. - + constructor to apply access rights at the point of creation of a file. To access or modify rights on an existing file, consider using the and methods. + + The `fileOptions` parameter is used to provide access to more advanced operations that can be leveraged when creating a object. + + The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. + > [!NOTE] -> `path` is not required to be a file stored on disk; it can be any part of a system that supports access through streams. For example, depending on the system, this class can access a physical device. - - is `true` for all objects that encapsulate files. If `path` indicates a device that does not support seeking, the property on the resulting is `false`. For additional information, see . - +> `path` is not required to be a file stored on disk; it can be any part of a system that supports access through streams. For example, depending on the system, this class can access a physical device. + + is `true` for all objects that encapsulate files. If `path` indicates a device that does not support seeking, the property on the resulting is `false`. For additional information, see . + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + > [!IMPORTANT] > This constructor does not exist in .NET Core. Instead, starting in .NET Core 3.1, you can use the following extension method of the `FileSystemAclExtensions` class inside the `System.Security.AccessControl` assembly: . - -## Examples - The following example writes data to a file and then reads the data using the object. - + +## Examples + The following example writes data to a file and then reads the data using the object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/IO.FileStream.ctor2/cpp/example.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileOptions/Overview/example.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileOptions/Overview/example.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.FileStream.ctor2/VB/example.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.FileStream.ctor2/VB/example.vb" id="Snippet1"::: + ]]> is . - .NET Framework and .NET Core versions older than 2.1: is an empty string (""), contains only white space, or contains one or more invalid characters. - - -or- - + .NET Framework and .NET Core versions older than 2.1: is an empty string (""), contains only white space, or contains one or more invalid characters. + + -or- + refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in an NTFS environment. refers to a non-file device, such as "con:", "com1:", "lpt1:", etc. in a non-NTFS environment. - is negative or zero. - - -or- - + is negative or zero. + + -or- + , , or contain an invalid value. The file cannot be found, such as when is or , and the file specified by does not exist. The file must already exist in these modes. - An I/O error, such as specifying when the file specified by already exists, occurred. - - -or- - + An I/O error, such as specifying when the file specified by already exists, occurred. + + -or- + The stream has been closed. The caller does not have the required permission. The specified path is invalid, such as being on an unmapped drive. - The requested is not permitted by the operating system for the specified , such as when is or and the file or directory is set for read-only access. - - -or- - + The requested is not permitted by the operating system for the specified , such as when is or and the file or directory is set for read-only access. + + -or- + is specified for , but file encryption is not supported on the current platform. The specified , file name, or both exceed the system-defined maximum length. The current operating system is not Windows NT or later. @@ -2009,23 +1977,23 @@ The file was too large (when if the stream supports reading; if the stream is closed or was opened with write-only access. - does not support reading, calls to the , , and methods throw a . - - If the stream is closed, this property returns `false`. - - - -## Examples - The following example demonstrates a use of the `CanRead` property. The output of this code is "MyFile.txt is not writable." To get the output message "MyFile.txt can be both written to and read from.", change the `FileAccess` parameter to `ReadWrite` in the `FileStream` constructor. - + does not support reading, calls to the , , and methods throw a . + + If the stream is closed, this property returns `false`. + + + +## Examples + The following example demonstrates a use of the `CanRead` property. The output of this code is "MyFile.txt is not writable." To get the output message "MyFile.txt can be both written to and read from.", change the `FileAccess` parameter to `ReadWrite` in the `FileStream` constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic FileStream.CanRead Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/CanRead/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/CanRead/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic FileStream.CanRead Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic FileStream.CanRead Example/VB/source.vb" id="Snippet1"::: + ]]> File and Stream I/O @@ -2076,23 +2044,23 @@ The file was too large (when if the stream supports seeking; if the stream is closed or if the was constructed from an operating-system handle such as a pipe or output to the console. - does not support seeking, calls to , , , and throw a . - - If the stream is closed, this property returns `false`. - - - -## Examples - The following example uses the `CanSeek` property to check whether a stream supports seeking. - + does not support seeking, calls to , , , and throw a . + + If the stream is closed, this property returns `false`. + + + +## Examples + The following example uses the `CanSeek` property to check whether a stream supports seeking. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/FStream CanSeek/CPP/fstream canseek.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/CanSeek/fstream canseek.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/CanSeek/fstream canseek.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FStream CanSeek/VB/fstream canseek.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FStream CanSeek/VB/fstream canseek.vb" id="Snippet1"::: + ]]> File and Stream I/O @@ -2143,30 +2111,30 @@ The file was too large (when if the stream supports writing; if the stream is closed or was opened with read-only access. - does not support writing, a call to , , , or throws a . - - If the stream is closed, this property returns `false`. - - - -## Examples - The following example uses the `CanWrite` property to check whether a stream supports writing. - + does not support writing, a call to , , , or throws a . + + If the stream is closed, this property returns `false`. + + + +## Examples + The following example uses the `CanWrite` property to check whether a stream supports writing. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/FStream CanWrite/CPP/fstream canwrite.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/CanWrite/fstream canwrite.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/CanWrite/fstream canwrite.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FStream CanWrite/VB/fstream canwrite.vb" id="Snippet1"::: - - The following is an example using the `CanWrite` property. The output of this code is "MyFile.txt is writable." To get the output message "MyFile.txt can be both written to and read from.", change the `FileAccess` parameter to `ReadWrite` in the `FileStream` constructor. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FStream CanWrite/VB/fstream canwrite.vb" id="Snippet1"::: + + The following is an example using the `CanWrite` property. The output of this code is "MyFile.txt is writable." To get the output message "MyFile.txt can be both written to and read from.", change the `FileAccess` parameter to `ReadWrite` in the `FileStream` constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic FileStream.CanWrite Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/CanWrite/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/CanWrite/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic FileStream.CanWrite Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic FileStream.CanWrite Example/VB/source.vb" id="Snippet1"::: + ]]> File and Stream I/O @@ -2328,19 +2296,19 @@ For an example of copying between two streams, see the to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. - - When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the `Dispose()` method of each referenced object. - + method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. + + When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the `Dispose()` method of each referenced object. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). File and Stream I/O @@ -2383,7 +2351,7 @@ For an example of copying between two streams, see the Asynchronously releases the unmanaged resources used by the . A task that represents the asynchronous dispose operation. - Waits for the pending asynchronous read operation to complete. (Consider using instead.) The number of bytes read from the stream, between 0 and the number of bytes you requested. Streams only return 0 at the end of the stream, otherwise, they should block until at least 1 byte is available. - and to implement asynchronous file operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous file operations more easily. - - must be called exactly for every call to . Failing to end a read process before beginning another read can cause undesirable behavior such as deadlock. - - This method overrides . - - can be called on every from . Calling tells you how many bytes were read from the stream. will block until the I/O operation has completed. - - - -## Examples - This code example is part of a larger example provided for the constructor. - + and to implement asynchronous file operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous file operations more easily. + + must be called exactly for every call to . Failing to end a read process before beginning another read can cause undesirable behavior such as deadlock. + + This method overrides . + + can be called on every from . Calling tells you how many bytes were read from the stream. will block until the I/O operation has completed. + + + +## Examples + This code example is part of a larger example provided for the constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.FileStream2/CPP/source.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/.ctor/source1.cs" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/.ctor/source1.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileStream2/VB/source.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileStream2/VB/source.vb" id="Snippet4"::: + ]]> @@ -2531,25 +2499,25 @@ Calling `DisposeAsync` allows the resources used by the The pending asynchronous I/O request. Ends an asynchronous write operation and blocks until the I/O operation is complete. (Consider using instead.) - and to implement asynchronous file operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous file operations more easily. - - This method overrides . - - must be called exactly once on every from . will block until the I/O operation has completed. - - - -## Examples - This code example is part of a larger example provided for the constructor. - + and to implement asynchronous file operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous file operations more easily. + + This method overrides . + + must be called exactly once on every from . will block until the I/O operation has completed. + + + +## Examples + This code example is part of a larger example provided for the constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.FileStream2/CPP/source.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/.ctor/source1.cs" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/.ctor/source1.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileStream2/VB/source.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileStream2/VB/source.vb" id="Snippet3"::: + ]]> @@ -2612,11 +2580,11 @@ Calling `DisposeAsync` allows the resources used by the Ensures that resources are freed and other cleanup operations are performed when the garbage collector reclaims the . - File and Stream I/O @@ -2681,33 +2649,33 @@ Calling `DisposeAsync` allows the resources used by the Clears buffers for this stream and causes any buffered data to be written to the file. - . - - When you call the method, the operating system I/O buffer is also flushed. - - A stream's encoder is not flushed unless you explicitly call or dispose of the object. 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. - - Because a buffer can be used for either reading or writing, performs the following two functions: - -- Any data previously written to the buffer is copied to the file and the buffer is cleared except for its encoder state. - -- If is `true` and data was previously copied from the file to the buffer for reading, the current position within the file is decremented by the number of unread bytes in the buffer. The buffer is then cleared. - - Use the method overload when you want to ensure that all buffered data in intermediate file buffers is written to disk. - - - -## Examples - This code example is part of a larger example provided for the method. - + . + + When you call the method, the operating system I/O buffer is also flushed. + + A stream's encoder is not flushed unless you explicitly call or dispose of the object. 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. + + Because a buffer can be used for either reading or writing, performs the following two functions: + +- Any data previously written to the buffer is copied to the file and the buffer is cleared except for its encoder state. + +- If is `true` and data was previously copied from the file to the buffer for reading, the current position within the file is decremented by the number of unread bytes in the buffer. The buffer is then cleared. + + Use the method overload when you want to ensure that all buffered data in intermediate file buffers is written to disk. + + + +## Examples + This code example is part of a larger example provided for the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.FileStream3/CPP/fstreamlock.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/.ctor/fstreamlock.cs" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/.ctor/fstreamlock.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileStream3/VB/fstreamlock.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileStream3/VB/fstreamlock.vb" id="Snippet4"::: + ]]> An I/O error occurred. @@ -2766,13 +2734,13 @@ Calling `DisposeAsync` allows the resources used by the to flush all intermediate file buffers; otherwise, . Clears buffers for this stream and causes any buffered data to be written to the file, and also clears all intermediate file buffers. - method, the operating system I/O buffer is also flushed. - + method, the operating system I/O buffer is also flushed. + ]]> @@ -2832,11 +2800,11 @@ Calling `DisposeAsync` allows the resources used by the Asynchronously clears all buffers for this stream, causes any buffered data to be written to the underlying device, and monitors cancellation requests. A task that represents the asynchronous flush operation. - value for the property. If the handle to the file is disposed, the returned task contains the exception in the property. - + value for the property. If the handle to the file is disposed, the returned task contains the exception in the property. + This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> @@ -2883,24 +2851,24 @@ Calling `DisposeAsync` allows the resources used by the Gets a object that encapsulates the access control list (ACL) entries for the file described by the current object. An object that encapsulates the access control settings for the file described by the current object. - class and can be used to retrieve the access control list (ACL) entries of an existing file, consider using method, as it is easier to use. - - Use the method to retrieve the ACL entries for a file. - - An ACL describes individuals and/or groups who have, or do not have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). - + class and can be used to retrieve the access control list (ACL) entries of an existing file, consider using method, as it is easier to use. + + Use the method to retrieve the ACL entries for a file. + + An ACL describes individuals and/or groups who have, or do not have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). + ]]> The file is closed. An I/O error occurred while opening the file. The file could not be found. - This operation is not supported on the current platform. - - -or- - + This operation is not supported on the current platform. + + -or- + The caller does not have the required permission. @@ -2966,16 +2934,16 @@ Calling `DisposeAsync` allows the resources used by the Gets the operating system file handle for the file that the current object encapsulates. The operating system file handle for the file encapsulated by this object, or -1 if the has been closed. - property to discover whether this handle was opened asynchronously. In Win32, this means the handle was opened for overlapped IO, and it requires different parameters to `ReadFile` and `WriteFile`. - + property to discover whether this handle was opened asynchronously. In Win32, this means the handle was opened for overlapped IO, and it requires different parameters to `ReadFile` and `WriteFile`. + > [!CAUTION] -> Data corruption might occur if a `FileStream` is created, its handle is passed, some operation moves the handle's file pointer, and then the `FileStream` is used again. Multiple threads cannot safely write to the same file simultaneously, and `FileStream` buffering code assumes that it exclusively controls the handle. `FileStream` might throw an if `FileStream` detects that some other process has moved the file pointer. To avoid this, do not write any data into a portion of the file that `FileStream` might have buffered, and restore the file pointer to the location it had when methods were last called on `FileStream`. - +> Data corruption might occur if a `FileStream` is created, its handle is passed, some operation moves the handle's file pointer, and then the `FileStream` is used again. Multiple threads cannot safely write to the same file simultaneously, and `FileStream` buffering code assumes that it exclusively controls the handle. `FileStream` might throw an if `FileStream` detects that some other process has moved the file pointer. To avoid this, do not write any data into a portion of the file that `FileStream` might have buffered, and restore the file pointer to the location it had when methods were last called on `FileStream`. + ]]> The caller does not have the required permission. @@ -3027,23 +2995,23 @@ Calling `DisposeAsync` allows the resources used by the if the was opened asynchronously; otherwise, . - property correctly. In Win32, `IsAsync` being true means the handle was opened for overlapped I/O, and thus requires different parameters to `ReadFile` and `WriteFile`. - - You specify this value when you create an instance of the class using a constructor that has an `isAsync`, `useAsync`, or `options` parameter. When the property is `true`, the stream utilizes overlapped I/O to perform file operations asynchronously. However, the property does not have to be `true` to call the , , or method. When the property is `false` and you call the asynchronous read and write operations, the UI thread is still not blocked, but the actual I/O operation is performed synchronously. - - - -## Examples - This code example is part of a larger example provided for the constructor. - + property correctly. In Win32, `IsAsync` being true means the handle was opened for overlapped I/O, and thus requires different parameters to `ReadFile` and `WriteFile`. + + You specify this value when you create an instance of the class using a constructor that has an `isAsync`, `useAsync`, or `options` parameter. When the property is `true`, the stream utilizes overlapped I/O to perform file operations asynchronously. However, the property does not have to be `true` to call the , , or method. When the property is `false` and you call the asynchronous read and write operations, the UI thread is still not blocked, but the actual I/O operation is performed synchronously. + + + +## Examples + This code example is part of a larger example provided for the constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.FileStream2/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/.ctor/source1.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/.ctor/source1.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileStream2/VB/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileStream2/VB/source.vb" id="Snippet2"::: + ]]> File and Stream I/O @@ -3099,21 +3067,21 @@ Calling `DisposeAsync` allows the resources used by the Gets the length in bytes of the stream. A long value representing the length of the stream in bytes. - @@ -3191,23 +3159,23 @@ Calling `DisposeAsync` allows the resources used by the The range to be locked. Prevents other processes from reading from or writing to the . - @@ -3270,24 +3238,24 @@ Calling `DisposeAsync` allows the resources used by the Gets the absolute path of the file opened in the . A string that is the absolute path of the file. - constructor. - + For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + This code example is part of a larger example provided for the constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.FileStream2/CPP/source.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/.ctor/source1.cs" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/.ctor/source1.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileStream2/VB/source.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileStream2/VB/source.vb" id="Snippet4"::: + ]]> File and Stream I/O @@ -3347,21 +3315,21 @@ If the absolute path is not known, this property returns a string similar to "[U Gets or sets the current position of this stream. The current position of this stream. - The stream does not support seeking. @@ -3495,30 +3463,30 @@ Use for reading primitive data types. Reads a block of bytes from the stream and writes the data in a given buffer. The total number of bytes read into the buffer. This might be less than the number of bytes requested if that number of bytes are not currently available, or zero if the end of the stream is reached. - . - - The `offset` parameter gives the offset of the byte in `array` (the buffer index) at which to begin reading, and the `count` parameter gives the maximum number of bytes to be read from this stream. The returned value is the actual number of bytes read, or zero if the end of the stream is reached. If the read operation is successful, the current position of the stream is advanced by the number of bytes read. If an exception occurs, the current position of the stream is unchanged. - - The method returns zero only after reaching the end of the stream. Otherwise, always reads at least one byte from the stream before returning. If no data is available from the stream upon a call to , the method will block until at least one byte of data can be returned. An implementation is free to return fewer bytes than requested even if the end of the stream has not been reached. - - Use for reading primitive data types. - - Do not interrupt a thread that is performing a read operation. Although the application may appear to run successfully after the thread is unblocked, the interruption can decrease your application's performance and reliability. - - For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example reads the contents from a and writes it into another . - + . + + The `offset` parameter gives the offset of the byte in `array` (the buffer index) at which to begin reading, and the `count` parameter gives the maximum number of bytes to be read from this stream. The returned value is the actual number of bytes read, or zero if the end of the stream is reached. If the read operation is successful, the current position of the stream is advanced by the number of bytes read. If an exception occurs, the current position of the stream is unchanged. + + The method returns zero only after reaching the end of the stream. Otherwise, always reads at least one byte from the stream before returning. If no data is available from the stream upon a call to , the method will block until at least one byte of data can be returned. An implementation is free to return fewer bytes than requested even if the end of the stream has not been reached. + + Use for reading primitive data types. + + Do not interrupt a thread that is performing a read operation. Although the application may appear to run successfully after the thread is unblocked, the interruption can decrease your application's performance and reliability. + + For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example reads the contents from a and writes it into another . + :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/Read/fsread.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/Read/fsread.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FSRead/VB/fsread.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FSRead/VB/fsread.vb" id="Snippet1"::: + ]]> @@ -3592,11 +3560,11 @@ If the operation is canceled before it completes, the returned task contains the ## Examples -The following example shows how to read from a file asynchronously. +The following example shows how to read from a file asynchronously. :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/Overview/example4.cs" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/Overview/example4.fs" id="Snippet4"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Asynchronous_File_IO_async/vb/example4.vb" id="Snippet4"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Asynchronous_File_IO_async/vb/example4.vb" id="Snippet4"::: ]]> @@ -3746,31 +3714,31 @@ The following example shows how to read from a file asynchronously. Reads a byte from the file and advances the read position one byte. The byte, cast to an , or -1 if the end of the stream has been reached. - . - + . + > [!NOTE] -> Use the property to determine whether the current instance supports reading. For additional information, see . - - - -## Examples - The following code example shows how to write data to a file, byte by byte, and then verify that the data was written correctly. - +> Use the property to determine whether the current instance supports reading. For additional information, see . + + + +## Examples + The following code example shows how to write data to a file, byte by byte, and then verify that the data was written correctly. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.FileStream1/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/.ctor/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/.ctor/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileStream1/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileStream1/VB/source.vb" id="Snippet1"::: + ]]> The current stream does not support reading. The current stream is closed. - The default implementation on creates a new single-byte array and then calls . While this is formally correct, it is inefficient. Any stream with an internal buffer should override this method and provide a much more efficient version that reads the buffer directly, avoiding the extra array allocation on every call. - + The default implementation on creates a new single-byte array and then calls . While this is formally correct, it is inefficient. Any stream with an internal buffer should override this method and provide a much more efficient version that reads the buffer directly, avoiding the extra array allocation on every call. + For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). File and Stream I/O @@ -3825,11 +3793,11 @@ The following example shows how to read from a file asynchronously. Gets a object that represents the operating system file handle for the file that the current object encapsulates. An object that represents the operating system file handle for the file that the current object encapsulates. - property automatically flushes the stream and sets the current stream position to 0. This allows the file to be moved or the stream position to be reset by another stream using the returned by this property. - + property automatically flushes the stream and sets the current stream position to 0. This allows the file to be moved or the stream position to be reset by another stream using the returned by this property. + ]]> File and Stream I/O @@ -3891,32 +3859,32 @@ The following example shows how to read from a file asynchronously. Sets the current position of this stream to the given value. The new position in the stream. - . - + . + > [!NOTE] -> Use the property to determine whether the current instance supports seeking. For additional information, see . - +> Use the property to determine whether the current instance supports seeking. For additional information, see . + You can seek to any location beyond the length of the stream. When you seek beyond the length of the file, the file size grows. Data added to the end of the file is set to zero. - + For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - -## Examples - The following example shows how to write data to a file, byte by byte, and then verify that the data was written correctly. - + +## Examples + The following example shows how to write data to a file, byte by byte, and then verify that the data was written correctly. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.FileStream1/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/.ctor/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/.ctor/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileStream1/VB/source.vb" id="Snippet1"::: - - The following example reads text in the reverse direction, from the end of file to the beginning of the file, by using the various values with the method. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileStream1/VB/source.vb" id="Snippet1"::: + + The following example reads text in the reverse direction, from the end of file to the beginning of the file, by using the various values with the method. + :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/Seek/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/Seek/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.filestream.seek/vb/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.filestream.seek/vb/source.vb" id="Snippet1"::: + ]]> An I/O error occurred. @@ -3967,18 +3935,18 @@ The following example shows how to read from a file asynchronously. An object that describes an ACL entry to apply to the current file. Applies access control list (ACL) entries described by a object to the file described by the current object. - class and can be used on an existing file, consider using the method as it is easier to use. - - The method applies access control list (ACL) entries to a file that represents the noninherited ACL list. - + class and can be used on an existing file, consider using the method as it is easier to use. + + The method applies access control list (ACL) entries to a file that represents the noninherited ACL list. + > [!CAUTION] -> The ACL specified for the `fileSecurity` parameter replaces the existing ACL for the file. To add permissions for a new user, use the method to obtain the existing ACL, modify it, and then use to apply it back to the file. - - An ACL describes individuals and/or groups who have, or do not have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). - +> The ACL specified for the `fileSecurity` parameter replaces the existing ACL for the file. To add permissions for a new user, use the method to obtain the existing ACL, modify it, and then use to apply it back to the file. + + An ACL describes individuals and/or groups who have, or do not have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). + ]]> The file is closed. @@ -4038,20 +4006,20 @@ The following example shows how to read from a file asynchronously. The new length of the stream. Sets the length of this stream to the given value. - . - - If the given value is less than the current length of the stream, the stream is truncated. In this scenario, if the current position is greater than the new length, the current position is moved to the last byte of the stream. If the given value is larger than the current length of the stream, the stream is expanded, and the current position remains the same. If the stream is expanded, the contents of the stream between the old and the new length are undefined on Windows, while on Linux, that space is filled with zeros. - - A stream must support both writing and seeking for `SetLength` to work. - + . + + If the given value is less than the current length of the stream, the stream is truncated. In this scenario, if the current position is greater than the new length, the current position is moved to the last byte of the stream. If the given value is larger than the current length of the stream, the stream is expanded, and the current position remains the same. If the stream is expanded, the contents of the stream between the old and the new length are undefined on Windows, while on Linux, that space is filled with zeros. + + A stream must support both writing and seeking for `SetLength` to work. + > [!NOTE] -> Use the property to determine whether the current instance supports writing, and the property to determine whether seeking is supported. For additional information, see and . - - For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - +> Use the property to determine whether the current instance supports writing, and the property to determine whether seeking is supported. For additional information, see and . + + For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> An I/O error has occurred. @@ -4129,21 +4097,21 @@ The following example shows how to read from a file asynchronously. The range to be unlocked. Allows access by other processes to all or part of a file that was previously locked. - @@ -4271,29 +4239,29 @@ If the write operation is successful, the position within the file stream advanc The maximum number of bytes to write. Writes a block of bytes to the file stream. - . - -The `offset` parameter gives the offset of the byte in `array` (the buffer index) at which to begin copying, and the `count` parameter gives the number of bytes that will be written to the stream. If the write operation is successful, the current position of the stream is advanced by the number of bytes written. If an exception occurs, the current position of the stream is unchanged. - +This method overrides . + +The `offset` parameter gives the offset of the byte in `array` (the buffer index) at which to begin copying, and the `count` parameter gives the number of bytes that will be written to the stream. If the write operation is successful, the current position of the stream is advanced by the number of bytes written. If an exception occurs, the current position of the stream is unchanged. + > [!NOTE] -> Use the property to determine whether the current instance supports writing. For additional information, see . - -Do not interrupt a thread that's performing a write operation. Although the application may appear to run successfully after the thread is unblocked, the interruption can decrease your application's performance and reliability. - +> Use the property to determine whether the current instance supports writing. For additional information, see . + +Do not interrupt a thread that's performing a write operation. Although the application may appear to run successfully after the thread is unblocked, the interruption can decrease your application's performance and reliability. + For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - -## Examples - This code example is part of a larger example provided for the method. - + +## Examples + This code example is part of a larger example provided for the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.FileStream3/CPP/fstreamlock.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/.ctor/fstreamlock.cs" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/.ctor/fstreamlock.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileStream3/VB/fstreamlock.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileStream3/VB/fstreamlock.vb" id="Snippet3"::: + ]]> @@ -4302,10 +4270,10 @@ For a list of common file and directory operations, see [Common I/O Tasks](/dotn and describe an invalid range in . or is negative. - An I/O error occurred. - + An I/O error occurred. + -or- - + Another thread may have caused an unexpected change in the position of the operating system's file handle. -or- @@ -4438,20 +4406,20 @@ If the operation is canceled before it completes, the returned task contains the Asynchronously writes a sequence of bytes to the current stream, advances the current position within this stream by the number of bytes written, and monitors cancellation requests. A task that represents the asynchronous write operation. - method enables you to perform resource-intensive file operations without blocking the main thread. This performance consideration is particularly important in apps where a time-consuming stream operation can block the UI thread and make your app appear as if it isn't working. - - Use the property to determine whether the current instance supports writing. - + + Use the property to determine whether the current instance supports writing. + If the operation is canceled before it completes, the returned task contains the value for the property. If the handle to the file is disposed, the returned task contains the exception in the property. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - -## Examples - The following example shows how to write asynchronously to a file. - + +## Examples + The following example shows how to write asynchronously to a file. + :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/Overview/example3.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Asynchronous_File_IO_async/vb/example3.vb" id="Snippet3"::: @@ -4520,32 +4488,32 @@ This method stores in the task it returns all non-usage exceptions that the meth A byte to write to the stream. Writes a byte to the current position in the file stream. - . - - Use `WriteByte` to write a byte to a `FileStream` efficiently. If the stream is closed or not writable, an exception will be thrown. - + . + + Use `WriteByte` to write a byte to a `FileStream` efficiently. If the stream is closed or not writable, an exception will be thrown. + > [!NOTE] > Use the property to determine whether the current instance supports writing. For additional information, see . - -## Examples - The following code example shows how to write data to a file, byte by byte, and then verify that the data was written correctly. - + +## Examples + The following code example shows how to write data to a file, byte by byte, and then verify that the data was written correctly. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.FileStream1/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/.ctor/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/.ctor/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileStream1/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileStream1/VB/source.vb" id="Snippet1"::: + ]]> The stream is closed. The stream does not support writing. .NET 8 and later versions: The underlying pipe is closed or disconnected. - The default implementation on creates a new single-byte array and then calls . While this is formally correct, it is inefficient. Any stream with an internal buffer should override this method and provide a much more efficient version that reads the buffer directly, avoiding the extra array allocation on every call. - + The default implementation on creates a new single-byte array and then calls . While this is formally correct, it is inefficient. Any stream with an internal buffer should override this method and provide a much more efficient version that reads the buffer directly, avoiding the extra array allocation on every call. + For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). File and Stream I/O diff --git a/xml/System.IO/FileSystemWatcher.xml b/xml/System.IO/FileSystemWatcher.xml index 475487a0b02..c93fd28a409 100644 --- a/xml/System.IO/FileSystemWatcher.xml +++ b/xml/System.IO/FileSystemWatcher.xml @@ -81,68 +81,16 @@ Listens to the file system change notifications and raises events when a directory, or file in a directory, changes. - - to watch for changes in a specified directory. You can watch for changes in files and subdirectories of the specified directory. You can create a component to watch files on a local computer, a network drive, or a remote computer. - - To watch for changes in all files, set the property to an empty string ("") or use wildcards ("*.\*"). To watch a specific file, set the property to the file name. For example, to watch for changes in the file MyDoc.txt, set the property to "MyDoc.txt". You can also watch for changes in a certain type of file. For example, to watch for changes in text files, set the property to "\*.txt". - - There are several types of changes you can watch for in a directory or file. For example, you can watch for changes in `Attributes`, the `LastWrite` date and time, or the `Size` of files or directories. This is done by setting the property to one of the values. For more information on the type of changes you can watch, see . - - You can watch for renaming, deletion, or creation of files or directories. For example, to watch for renaming of text files, set the property to "*.txt" and call the method with a specified for its parameter. - - The Windows operating system notifies your component of file changes in a buffer created by the . If there are many changes in a short time, the buffer can overflow. This causes the component to lose track of changes in the directory, and it will only provide blanket notification. Increasing the size of the buffer with the property is expensive, as it comes from non-paged memory that cannot be swapped out to disk, so keep the buffer as small yet large enough to not miss any file change events. To avoid a buffer overflow, use the and properties so you can filter out unwanted change notifications. - - For a list of initial property values for an instance of , see the constructor. - - Please note the following when using the class. - -- Hidden files are not ignored. - -- In some systems, reports changes to files using the short 8.3 file name format. For example, a change to "LongFileName.LongExtension" could be reported as "LongFil~.Lon". - -- This class contains a link demand and an inheritance demand at the class level that applies to all members. A is thrown when either the immediate caller or the derived class does not have full-trust permission. For details about security demands, see [Link Demands](/dotnet/framework/misc/link-demands). - -- The maximum size you can set for the property for monitoring a directory over the network is 64 KB. - -## Copying and moving folders - The operating system and object interpret a cut-and-paste action or a move action as a rename action for a folder and its contents. If you cut and paste a folder with files into a folder being watched, the object reports only the folder as new, but not its contents because they are essentially only renamed. - - To be notified that the contents of folders have been moved or copied into a watched folder, provide and event handler methods as suggested in the following table. - -|Event Handler|Events Handled|Performs| -|-------------------|--------------------|--------------| -||, , |Report changes in file attributes, created files, and deleted files.| -|||List the old and new paths of renamed files and folders, expanding recursively if needed.| - -## Events and Buffer Sizes - Note that several factors can affect which file system change events are raised, as described by the following: - -- Common file system operations might raise more than one event. For example, when a file is moved from one directory to another, several and some and events might be raised. Moving a file is a complex operation that consists of multiple simple operations, therefore raising multiple events. Likewise, some applications (for example, antivirus software) might cause additional file system events that are detected by . - -- The can watch disks as long as they are not switched or removed. The does not raise events for CDs and DVDs, because time stamps and properties cannot change. Remote computers must have one of the required platforms installed for the component to function properly. - - Note that a may miss an event when the buffer size is exceeded. To avoid missing events, follow these guidelines: - -- Increase the buffer size by setting the property. - -- Avoid watching files with long file names, because a long file name contributes to filling up the buffer. Consider renaming these files using shorter names. - -- Keep your event handling code as short as possible. - - - -## Examples - The following example creates a to watch the directory specified at run time. The component is set to watch for changes in `LastWrite` and `LastAccess` time, the creation, deletion, or renaming of text files in the directory. If a file is changed, created, or deleted, the path to the file prints to the console. When a file is renamed, the old and new paths print to the console. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic NotifyFilters Example/CPP/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.IO/FileSystemWatcher/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic NotifyFilters Example/VB/source.vb" id="Snippet1"::: - - ]]> - + + to watch the directory specified at run time. The component is set to watch for changes in `LastWrite` and `LastAccess` time, the creation, deletion, or renaming of text files in the directory. If a file is changed, created, or deleted, the path to the file prints to the console. When a file is renamed, the old and new paths print to the console. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic NotifyFilters Example/CPP/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.IO/FileSystemWatcher/Overview/source.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic NotifyFilters Example/VB/source.vb" id="Snippet1"::: + ]]> + + For more information about this API, see Supplemental API remarks for FileSystemWatcher. @@ -201,36 +149,36 @@ Initializes a new instance of the class. - . - -|Property|Initial Value| -|--------------|-------------------| -||bitwise OR combination of `LastWrite`, `FileName`, and `DirectoryName`| -||`false`| -||"*.\*" (Watch all files.)| -||`false`| -||8192| -||empty string ("")| - + . + +|Property|Initial Value| +|--------------|-------------------| +||bitwise OR combination of `LastWrite`, `FileName`, and `DirectoryName`| +||`false`| +||"*.\*" (Watch all files.)| +||`false`| +||8192| +||empty string ("")| + > [!NOTE] -> The component will not watch the specified directory until the is set, and is `true`. - - - -## Examples - The following example creates a object to watch the directory specified at run time. The object watches for changes in `LastWrite` and `LastAccess` times, and for the creation, deletion, or renaming of text files in the directory. If a file is changed, created, or deleted, the path to the file displays to the console. When a file is renamed, the old and new paths display to the console. - - This example uses the and namespaces. - +> The component will not watch the specified directory until the is set, and is `true`. + + + +## Examples + The following example creates a object to watch the directory specified at run time. The object watches for changes in `LastWrite` and `LastAccess` times, and for the creation, deletion, or renaming of text files in the directory. If a file is changed, created, or deleted, the path to the file displays to the console. When a file is renamed, the old and new paths display to the console. + + This example uses the and namespaces. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic NotifyFilters Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileSystemWatcher/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic NotifyFilters Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic NotifyFilters Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -292,24 +240,24 @@ The directory to monitor, in standard or Universal Naming Convention (UNC) notation. Initializes a new instance of the class, given the specified directory to monitor. - [!NOTE] -> The component will not watch the specified directory until the is set, and is `true`. - - The component can watch files on your personal computer, a network drive, or a remote computer. - - You cannot watch a remote computer that does not have Windows NT or Windows 2000. You cannot watch a remote Windows NT 4.0 computer from a Windows NT 4.0 computer. The property is set by default to watch all files. - +> The component will not watch the specified directory until the is set, and is `true`. + + The component can watch files on your personal computer, a network drive, or a remote computer. + + You cannot watch a remote computer that does not have Windows NT or Windows 2000. You cannot watch a remote Windows NT 4.0 computer from a Windows NT 4.0 computer. The property is set by default to watch all files. + ]]> The parameter is . - The parameter is an empty string (""). - - -or- - + The parameter is an empty string (""). + + -or- + The path specified through the parameter does not exist. is too long. @@ -371,28 +319,28 @@ The type of files to watch. For example, "*.txt" watches for changes to all text files. Initializes a new instance of the class, given the specified directory and type of files to monitor. - [!NOTE] -> The component will not watch the specified directory until the is set, and is `true`. - - The component can watch files on your personal computer, a network drive, or a remote computer. - - You cannot watch a remote computer that does not have Windows NT or Windows 2000. You cannot watch a remote Windows NT 4.0 computer from a Windows NT 4.0 computer. - +> The component will not watch the specified directory until the is set, and is `true`. + + The component can watch files on your personal computer, a network drive, or a remote computer. + + You cannot watch a remote computer that does not have Windows NT or Windows 2000. You cannot watch a remote Windows NT 4.0 computer from a Windows NT 4.0 computer. + ]]> - The parameter is . - - -or- - + The parameter is . + + -or- + The parameter is . - The parameter is an empty string (""). - - -or- - + The parameter is an empty string (""). + + -or- + The path specified through the parameter does not exist. is too long. @@ -448,11 +396,11 @@ Begins the initialization of a used on a form or used by another component. The initialization occurs at run time. - method ends the initialization. Using the and methods prevents the control from being used before it is fully initialized. - + method ends the initialization. Using the and methods prevents the control from being used before it is fully initialized. + ]]> @@ -506,31 +454,31 @@ Occurs when a file or directory in the specified is changed. - event is raised when changes are made to the size, system attributes, last write time, last access time, or security permissions of a file or directory in the directory being monitored. - + event is raised when changes are made to the size, system attributes, last write time, last access time, or security permissions of a file or directory in the directory being monitored. + > [!NOTE] -> Common file system operations might raise more than one event. For example, when a file is moved from one directory to another, several and some and events might be raised. Moving a file is a complex operation that consists of multiple simple operations, therefore raising multiple events. Likewise, some applications (for example, antivirus software) might cause additional file system events that are detected by . - - Use to restrict the number of notifications raised when this event is handled. - +> Common file system operations might raise more than one event. For example, when a file is moved from one directory to another, several and some and events might be raised. Moving a file is a complex operation that consists of multiple simple operations, therefore raising multiple events. Likewise, some applications (for example, antivirus software) might cause additional file system events that are detected by . + + Use to restrict the number of notifications raised when this event is handled. + > [!NOTE] -> The event is raised unexpectedly when a file is renamed, but is not raised when a directory is renamed. To watch for renaming, use the event. - +> The event is raised unexpectedly when a file is renamed, but is not raised when a directory is renamed. To watch for renaming, use the event. + > [!NOTE] -> The order in which the event is raised in relation to the other events may change when the property is not `null`. - - - -## Examples - The following example uses the event to display the file path to the console whenever the watched file is changed. - +> The order in which the event is raised in relation to the other events may change when the property is not `null`. + + + +## Examples + The following example uses the event to display the file path to the console whenever the watched file is changed. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic NotifyFilters Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileSystemWatcher/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic NotifyFilters Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic NotifyFilters Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -588,28 +536,28 @@ Occurs when a file or directory in the specified is created. - event in the directory to which the file was copied, if that directory is being watched. If the directory from which you copied was being watched by another instance of , no event would be raised. For example, you create two instances of . FileSystemWatcher1 is set to watch "C:\My Documents", and FileSystemWatcher2 is set to watch "C:\Your Documents". If you copy a file from "My Documents" into "Your Documents", a event will be raised by FileSystemWatcher2, but no event is raised for FileSystemWatcher1. Unlike copying, moving a file or directory would raise two events. From the previous example, if you moved a file from "My Documents" to "Your Documents", a event would be raised by FileSystemWatcher2 and a event would be raised by FileSystemWatcher1. - + event in the directory to which the file was copied, if that directory is being watched. If the directory from which you copied was being watched by another instance of , no event would be raised. For example, you create two instances of . FileSystemWatcher1 is set to watch "C:\My Documents", and FileSystemWatcher2 is set to watch "C:\Your Documents". If you copy a file from "My Documents" into "Your Documents", a event will be raised by FileSystemWatcher2, but no event is raised for FileSystemWatcher1. Unlike copying, moving a file or directory would raise two events. From the previous example, if you moved a file from "My Documents" to "Your Documents", a event would be raised by FileSystemWatcher2 and a event would be raised by FileSystemWatcher1. + > [!NOTE] -> Common file system operations might raise more than one event. For example, when a file is moved from one directory to another, several and some and events might be raised. Moving a file is a complex operation that consists of multiple simple operations, therefore raising multiple events. Likewise, some applications (for example, antivirus software) might cause additional file system events that are detected by . - +> Common file system operations might raise more than one event. For example, when a file is moved from one directory to another, several and some and events might be raised. Moving a file is a complex operation that consists of multiple simple operations, therefore raising multiple events. Likewise, some applications (for example, antivirus software) might cause additional file system events that are detected by . + > [!NOTE] -> The order in which the event is raised in relation to the other events may change when the property is not `null`. - - The event is raised as soon as a file is created. If a file is being copied or transferred into a watched directory, the event will be raised immediately, followed by one or more events. - - - -## Examples - The following example uses the event to display the file path to the console whenever the watched file is created. - +> The order in which the event is raised in relation to the other events may change when the property is not `null`. + + The event is raised as soon as a file is created. If a file is being copied or transferred into a watched directory, the event will be raised immediately, followed by one or more events. + + + +## Examples + The following example uses the event to display the file path to the console whenever the watched file is created. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic NotifyFilters Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileSystemWatcher/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic NotifyFilters Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic NotifyFilters Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -668,26 +616,26 @@ Occurs when a file or directory in the specified is deleted. - event in the directory to which the file was copied, if that directory is being watched. If the directory from which you copied was being watched by another instance of , no event would be raised. For example, you create two instances of . FileSystemWatcher1 is set to watch "C:\My Documents", and FileSystemWatcher2 is set to watch "C:\Your Documents". If you copy a file from "My Documents" into "Your Documents", a event will be raised by FileSystemWatcher2, but no event is raised for FileSystemWatcher1. Unlike copying, moving a file or directory would raise two events. From the previous example, if you moved a file from "My Documents" to "Your Documents", a event would be raised by FileSystemWatcher2 and a event would be raised by FileSystemWatcher1. - + event in the directory to which the file was copied, if that directory is being watched. If the directory from which you copied was being watched by another instance of , no event would be raised. For example, you create two instances of . FileSystemWatcher1 is set to watch "C:\My Documents", and FileSystemWatcher2 is set to watch "C:\Your Documents". If you copy a file from "My Documents" into "Your Documents", a event will be raised by FileSystemWatcher2, but no event is raised for FileSystemWatcher1. Unlike copying, moving a file or directory would raise two events. From the previous example, if you moved a file from "My Documents" to "Your Documents", a event would be raised by FileSystemWatcher2 and a event would be raised by FileSystemWatcher1. + > [!NOTE] -> Common file system operations might raise more than one event. For example, when a file is moved from one directory to another, several and some and events might be raised. Moving a file is a complex operation that consists of multiple simple operations, therefore raising multiple events. Likewise, some applications (for example, antivirus software) might cause additional file system events that are detected by . - +> Common file system operations might raise more than one event. For example, when a file is moved from one directory to another, several and some and events might be raised. Moving a file is a complex operation that consists of multiple simple operations, therefore raising multiple events. Likewise, some applications (for example, antivirus software) might cause additional file system events that are detected by . + > [!NOTE] -> The order in which the event is raised in relation to the other events may change when the property is not `null`. - - - -## Examples - The following example uses the event to display the file path to the console whenever the watched file is deleted. - +> The order in which the event is raised in relation to the other events may change when the property is not `null`. + + + +## Examples + The following example uses the event to display the file path to the console whenever the watched file is deleted. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic NotifyFilters Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileSystemWatcher/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic NotifyFilters Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic NotifyFilters Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -779,19 +727,19 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. - - When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the method of each referenced object. - + method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. + + When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the method of each referenced object. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). @@ -853,25 +801,25 @@ if the component is enabled; otherwise, . The default is . If you are using the component on a designer in Visual Studio 2005, the default is . - to `true`. - + to `true`. + > [!NOTE] -> The component will not watch the specified directory until the property has been set and is `true`. - - The method allows event handlers to be invoked to respond to file changes even if this property is set to `false`. - - - -## Examples - The following example creates a to watch the directory specified at run time. The component is set to watch for changes in `LastWrite` and `LastAccess` time, the creation, deletion, or renaming of text files in the directory. If a file is changed, created, or deleted, the path to the file prints to the console. When a file is renamed, the old and new paths print to the console. - +> The component will not watch the specified directory until the property has been set and is `true`. + + The method allows event handlers to be invoked to respond to file changes even if this property is set to `false`. + + + +## Examples + The following example creates a to watch the directory specified at run time. The component is set to watch for changes in `LastWrite` and `LastAccess` time, the creation, deletion, or renaming of text files in the directory. If a file is changed, created, or deleted, the path to the file prints to the console. When a file is renamed, the old and new paths print to the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic NotifyFilters Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileSystemWatcher/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic NotifyFilters Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic NotifyFilters Example/VB/source.vb" id="Snippet1"::: + ]]> The object has been disposed. @@ -921,11 +869,11 @@ Ends the initialization of a used on a form or used by another component. The initialization occurs at run time. - method starts the initialization. Using the and methods prevents the control from being used before it is fully initialized. - + method starts the initialization. Using the and methods prevents the control from being used before it is fully initialized. + ]]> @@ -975,16 +923,16 @@ Occurs when the instance of is unable to continue monitoring changes or when the internal buffer overflows. - object from monitoring changes. For example, if the object is monitoring changes in a remote directory and the connection to that directory is lost, the event is raised. - - The system notifies you of file changes, and it stores those changes in a buffer that the component creates and passes to the APIs. If there are many changes in a short time, the buffer can overflow. This causes the component to lose track of changes in the directory, and it will only provide blanket notification. Increasing the size of the buffer is expensive, because it comes from non paged memory that cannot be swapped out to disk, so keep the buffer as small as possible. To avoid a buffer overflow, use the , , and properties to filter out unwanted change notifications. - + object from monitoring changes. For example, if the object is monitoring changes in a remote directory and the connection to that directory is lost, the event is raised. + + The system notifies you of file changes, and it stores those changes in a buffer that the component creates and passes to the APIs. If there are many changes in a short time, the buffer can overflow. This causes the component to lose track of changes in the directory, and it will only provide blanket notification. Increasing the size of the buffer is expensive, because it comes from non paged memory that cannot be swapped out to disk, so keep the buffer as small as possible. To avoid a buffer overflow, use the , , and properties to filter out unwanted change notifications. + > [!NOTE] -> Common file system operations might raise more than one event. For example, when a file is moved from one directory to another, several and some and events might be raised. Moving a file is a complex operation that consists of multiple simple operations, therefore raising multiple events. Likewise, some applications (for example, antivirus software) might cause additional file system events that are detected by . - +> Common file system operations might raise more than one event. For example, when a file is moved from one directory to another, several and some and events might be raised. Moving a file is a complex operation that consists of multiple simple operations, therefore raising multiple events. Likewise, some applications (for example, antivirus software) might cause additional file system events that are detected by . + ]]> @@ -1083,35 +1031,35 @@ Gets or sets the filter string used to determine what files are monitored in a directory. The filter string. The default is "*.\*" (Watches all files.) - property to an empty string (""). To watch a specific file, set the property to the file name. For example, to watch for changes in the file MyDoc.txt, set the property to "MyDoc.txt". You can also watch for changes in a certain type of file. For example, to watch for changes in any text files, set the property to "*.txt". Use of multiple filters such as "\*.txt|\*.doc" is not supported. - - The property can be changed after the object has started receiving events. - - For more information about filtering out unwanted notifications, see the , , and properties. - - accepts wildcards for matching files, as shown in the following examples. - -|Filter string|Watches the following files| -|-------------------|---------------------------------| -|*.\*|All files (default). An empty string ("") also watches all files.| -|*.txt|All files with a "txt" extension.| -|*recipe.doc|All files ending in "recipe" with a "doc" extension.| -|win*.xml|All files beginning with "win" with an "xml" extension.| -|Sales*200?.xls|Matches the following:

- Sales July 2001.xls
- Sales Aug 2002.xls
- Sales March 2004.xls

but does not match:

- Sales Nov 1999.xls| -|MyReport.Doc|Watches only MyReport.doc| - - - -## Examples - The following example creates a to watch the directory specified at run time. The component is set to watch for changes in `LastWrite` and `LastAccess` time, the creation, deletion, or renaming of text files in the directory. If a file is changed, created, or deleted, the path to the file prints to the console. When a file is renamed, the old and new paths print to the console. - + property to an empty string (""). To watch a specific file, set the property to the file name. For example, to watch for changes in the file MyDoc.txt, set the property to "MyDoc.txt". You can also watch for changes in a certain type of file. For example, to watch for changes in any text files, set the property to "*.txt". Use of multiple filters such as "\*.txt|\*.doc" is not supported. + + The property can be changed after the object has started receiving events. + + For more information about filtering out unwanted notifications, see the , , and properties. + + accepts wildcards for matching files, as shown in the following examples. + +|Filter string|Watches the following files| +|-------------------|---------------------------------| +|*.\*|All files (default). An empty string ("") also watches all files.| +|*.txt|All files with a "txt" extension.| +|*recipe.doc|All files ending in "recipe" with a "doc" extension.| +|win*.xml|All files beginning with "win" with an "xml" extension.| +|Sales*200?.xls|Matches the following:

- Sales July 2001.xls
- Sales Aug 2002.xls
- Sales March 2004.xls

but does not match:

- Sales Nov 1999.xls| +|MyReport.Doc|Watches only MyReport.doc| + + + +## Examples + The following example creates a to watch the directory specified at run time. The component is set to watch for changes in `LastWrite` and `LastAccess` time, the creation, deletion, or renaming of text files in the directory. If a file is changed, created, or deleted, the path to the file prints to the console. When a file is renamed, the old and new paths print to the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic NotifyFilters Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileSystemWatcher/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic NotifyFilters Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic NotifyFilters Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1251,15 +1199,15 @@ if you want to monitor subdirectories; otherwise, . The default is . - to `true` when you want to watch for change notifications for files and directories contained within the directory specified through the property, and its subdirectories. Setting the property to `false` helps reduce the number of notifications sent to the internal buffer. For more information on filtering out unwanted notifications, see the and properties. - - When `true`, is recursive through the entire subtree, not just the immediate child directories. The relative path to a file or directory within the subtree returns in the property of and the property of , depending on changes you are watching for. You can get the fully qualified path from the property of and the property of , depending on the changes you are watching for. - - If a directory is created in the subtree of the directory you are watching, and is `true`, that directory will automatically be watched. - + to `true` when you want to watch for change notifications for files and directories contained within the directory specified through the property, and its subdirectories. Setting the property to `false` helps reduce the number of notifications sent to the internal buffer. For more information on filtering out unwanted notifications, see the and properties. + + When `true`, is recursive through the entire subtree, not just the immediate child directories. The relative path to a file or directory within the subtree returns in the property of and the property of , depending on changes you are watching for. You can get the fully qualified path from the property of and the property of , depending on the changes you are watching for. + + If a directory is created in the subtree of the directory you are watching, and is `true`, that directory will automatically be watched. + ]]> @@ -1326,13 +1274,13 @@ Gets or sets the size (in bytes) of the internal buffer. The internal buffer size in bytes. The default is 8192 (8 KB). - property to less than 4096 bytes, your value is discarded and the property is set to 4096 bytes. For best performance, use a multiple of 4 KB on Intel-based computers. - - The system notifies the component of file changes, and it stores those changes in a buffer the component creates and passes to the APIs. Each event can use up to 16 bytes of memory, not including the file name. If there are many changes in a short time, the buffer can overflow. This causes the component to lose track of changes in the directory, and it will only provide blanket notification. Increasing the size of the buffer can prevent missing file system change events. However, increasing buffer size is expensive, because it comes from non-paged memory that cannot be swapped out to disk, so keep the buffer as small as possible. To avoid a buffer overflow, use the and properties to filter out unwanted change notifications. - + property to less than 4096 bytes, your value is discarded and the property is set to 4096 bytes. For best performance, use a multiple of 4 KB on Intel-based computers. + + The system notifies the component of file changes, and it stores those changes in a buffer the component creates and passes to the APIs. Each event can use up to 16 bytes of memory, not including the file name. If there are many changes in a short time, the buffer can overflow. This causes the component to lose track of changes in the directory, and it will only provide blanket notification. Increasing the size of the buffer can prevent missing file system change events. However, increasing buffer size is expensive, because it comes from non-paged memory that cannot be swapped out to disk, so keep the buffer as small as possible. To avoid a buffer overflow, use the and properties to filter out unwanted change notifications. + ]]> @@ -1398,22 +1346,22 @@ Gets or sets the type of changes to watch for. One of the values. The default is the bitwise OR combination of , , and . - enumeration to watch for more than one type of change at a time. For example, you can watch for changes in size of a file, and for changes in the `LastWrite` time. This raises an event anytime there is a change in file or folder size, or a change in the `LastWrite` time of the file or folder. - - This is one way to filter out unwanted notifications. For more information on filtering out unwanted notifications, see the , , and properties. - - - -## Examples - The following example creates a to watch the directory specified at run time. The component is set to watch for changes in `LastWrite` and `LastAccess` time, the creation, deletion, or renaming of text files in the directory. If a file is changed, created, or deleted, the path to the file prints to the console. When a file is renamed, the old and new paths print to the console. - + enumeration to watch for more than one type of change at a time. For example, you can watch for changes in size of a file, and for changes in the `LastWrite` time. This raises an event anytime there is a change in file or folder size, or a change in the `LastWrite` time of the file or folder. + + This is one way to filter out unwanted notifications. For more information on filtering out unwanted notifications, see the , , and properties. + + + +## Examples + The following example creates a to watch the directory specified at run time. The component is set to watch for changes in `LastWrite` and `LastAccess` time, the creation, deletion, or renaming of text files in the directory. If a file is changed, created, or deleted, the path to the file prints to the console. When a file is renamed, the old and new paths print to the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic NotifyFilters Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileSystemWatcher/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic NotifyFilters Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic NotifyFilters Example/VB/source.vb" id="Snippet1"::: + ]]> The value is not a valid bitwise OR combination of the values. @@ -1471,17 +1419,17 @@ A that contains the event data. Raises the event. - is called when changes are made to the size, system attributes, last write time, last access time, or security permissions of a file or directory in the directory being monitored. - - Use the property to restrict the number of events raised when the event is handled. - - The event is raised as soon as a file is created. If a file is being copied or transferred into a watched directory, the event will be raised immediately, followed by one or more events. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - + is called when changes are made to the size, system attributes, last write time, last access time, or security permissions of a file or directory in the directory being monitored. + + Use the property to restrict the number of events raised when the event is handled. + + The event is raised as soon as a file is created. If a file is being copied or transferred into a watched directory, the event will be raised immediately, followed by one or more events. + + Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). + ]]> @@ -1540,17 +1488,17 @@ A that contains the event data. Raises the event. - is called when a file or directory is created in the directory being monitored. - - Some common occurrences, such as copying or moving a file or directory, do not correspond directly to an event, but these occurrences do cause events to be raised. When you copy a file or directory, the system raises a event in the directory to which the file was copied, if that directory is being watched. If the directory from which you copied was being watched by another instance of , no event would be raised. For example, you create two instances of . FileSystemWatcher1 is set to watch "C:\My Documents", and FileSystemWatcher2 is set to watch "C:\Your Documents". If you copy a file from "My Documents" and paste it into "Your Documents", a event will be raised in FileSystemWatcher2, but no event is raised for FileSystemWatcher1. Unlike copying, moving a file or directory raises two events. From the previous example, if you moved a file from "My Documents" to "Your Documents", a event would be raised in FileSystemWatcher2 and a event would be raised in FileSystemWatcher1. - - The event is raised as soon as a file is created. If a file is being copied or transferred into a watched directory, the event will be raised immediately, followed by one or more events. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - + is called when a file or directory is created in the directory being monitored. + + Some common occurrences, such as copying or moving a file or directory, do not correspond directly to an event, but these occurrences do cause events to be raised. When you copy a file or directory, the system raises a event in the directory to which the file was copied, if that directory is being watched. If the directory from which you copied was being watched by another instance of , no event would be raised. For example, you create two instances of . FileSystemWatcher1 is set to watch "C:\My Documents", and FileSystemWatcher2 is set to watch "C:\Your Documents". If you copy a file from "My Documents" and paste it into "Your Documents", a event will be raised in FileSystemWatcher2, but no event is raised for FileSystemWatcher1. Unlike copying, moving a file or directory raises two events. From the previous example, if you moved a file from "My Documents" to "Your Documents", a event would be raised in FileSystemWatcher2 and a event would be raised in FileSystemWatcher1. + + The event is raised as soon as a file is created. If a file is being copied or transferred into a watched directory, the event will be raised immediately, followed by one or more events. + + Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). + ]]> @@ -1609,15 +1557,15 @@ A that contains the event data. Raises the event. - is called when a file or directory, within the directory being monitored, is deleted. - - Some common occurrences, such as copying or moving a file or directory, do not correspond directly to an event, but these occurrences do cause events to be raised. When you copy a file or directory, the system raises a event in the directory to which the file was copied, if that directory is being watched. If the directory from which you copied was being watched by another instance of , no event would be raised. For example, you create two instances of . FileSystemWatcher1 is set to watch "C:\My Documents", and FileSystemWatcher2 is set to watch "C:\Your Documents". If you copy a file from "My Documents" into "Your Documents", a event will be raised by FileSystemWatcher2, but no event is raised for FileSystemWatcher1. Unlike copying, moving a file or directory raises two events. From the previous example, if you moved a file from "My Documents" to "Your Documents", a event would be raised by FileSystemWatcher2 and a event would be raised by FileSystemWatcher1. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - + is called when a file or directory, within the directory being monitored, is deleted. + + Some common occurrences, such as copying or moving a file or directory, do not correspond directly to an event, but these occurrences do cause events to be raised. When you copy a file or directory, the system raises a event in the directory to which the file was copied, if that directory is being watched. If the directory from which you copied was being watched by another instance of , no event would be raised. For example, you create two instances of . FileSystemWatcher1 is set to watch "C:\My Documents", and FileSystemWatcher2 is set to watch "C:\Your Documents". If you copy a file from "My Documents" into "Your Documents", a event will be raised by FileSystemWatcher2, but no event is raised for FileSystemWatcher1. Unlike copying, moving a file or directory raises two events. From the previous example, if you moved a file from "My Documents" to "Your Documents", a event would be raised by FileSystemWatcher2 and a event would be raised by FileSystemWatcher1. + + Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). + ]]> @@ -1676,13 +1624,13 @@ An that contains the event data. Raises the event. - is called when an error occurs. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - + is called when an error occurs. + + Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). + ]]> @@ -1741,13 +1689,13 @@ A that contains the event data. Raises the event. - is called when a file or directory within the directory being monitored is renamed. Its argument contains information about the renaming operation, such as the type of change, the old and new path, and the old and new name. Note that its property may be null for renamed events if the does not get matching old and new name events from the operating system. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - + is called when a file or directory within the directory being monitored is renamed. Its argument contains information about the renaming operation, such as the type of change, the old and new path, and the old and new name. Note that its property may be null for renamed events if the does not get matching old and new name events from the operating system. + + Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). + ]]> @@ -1858,37 +1806,37 @@ Gets or sets the path of the directory to watch. The path to monitor. The default is an empty string (""). - property is `true`, this directory is the root at which the system watches for changes; otherwise it is the only directory watched. To watch a specific file, set the property to the fully qualified, correct directory, and the property to the file name. - - The property supports Universal Naming Convention (UNC) paths. - + property is `true`, this directory is the root at which the system watches for changes; otherwise it is the only directory watched. To watch a specific file, set the property to the fully qualified, correct directory, and the property to the file name. + + The property supports Universal Naming Convention (UNC) paths. + > [!NOTE] -> This property must be set before the component can watch for changes. - - When a directory is renamed, the automatically reattaches itself to the newly renamed item. For example, if you set the property to "C:\My Documents" and then manually rename the directory to "C:\Your Documents", the component continues listening for change notifications on the newly renamed directory. However, when you ask for the property, it contains the old path. This happens because the component determines what directory watches based on the handle, rather than the name of the directory. Renaming does not affect the handle. So, if you destroy the component, and then recreate it without updating the property, your application will fail because the directory no longer exists. - - - -## Examples - The following example creates a to watch the directory specified at run time. The component is set to watch for changes in `LastWrite` and `LastAccess` time, the creation, deletion, or renaming of text files in the directory. If a file is changed, created, or deleted, the path to the file prints to the console. When a file is renamed, the old and new paths print to the console. - +> This property must be set before the component can watch for changes. + + When a directory is renamed, the automatically reattaches itself to the newly renamed item. For example, if you set the property to "C:\My Documents" and then manually rename the directory to "C:\Your Documents", the component continues listening for change notifications on the newly renamed directory. However, when you ask for the property, it contains the old path. This happens because the component determines what directory watches based on the handle, rather than the name of the directory. Renaming does not affect the handle. So, if you destroy the component, and then recreate it without updating the property, your application will fail because the directory no longer exists. + + + +## Examples + The following example creates a to watch the directory specified at run time. The component is set to watch for changes in `LastWrite` and `LastAccess` time, the creation, deletion, or renaming of text files in the directory. If a file is changed, created, or deleted, the path to the file prints to the console. When a file is renamed, the old and new paths print to the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic NotifyFilters Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileSystemWatcher/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic NotifyFilters Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic NotifyFilters Example/VB/source.vb" id="Snippet1"::: + ]]> - The specified path does not exist or could not be found. - - -or- - - The specified path contains wildcard characters. - - -or- - + The specified path does not exist or could not be found. + + -or- + + The specified path contains wildcard characters. + + -or- + The specified path contains invalid path characters. @@ -1942,9 +1890,9 @@ Occurs when a file or directory in the specified is renamed. - delegate that has the following signature: ```csharp @@ -1955,17 +1903,17 @@ Public Delegate Sub RenamedEventHandler(sender As Object, e As RenamedEventArgs) ``` The object provides information about the renaming operation, such as the type of the rename (the property), the old and new name, and the old and new path. Note that the property may be null for renamed events if the does not get matching old and new name events from the operating system. - Renaming the directory you are watching will not raise a notification. Notifications are only raised for entries inside the directory you are watching. - - - -## Examples - The following example uses the event to display the file path to the console whenever the watched file is renamed. - + Renaming the directory you are watching will not raise a notification. Notifications are only raised for entries inside the directory you are watching. + + + +## Examples + The following example uses the event to display the file path to the console whenever the watched file is renamed. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic NotifyFilters Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileSystemWatcher/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic NotifyFilters Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic NotifyFilters Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2019,11 +1967,11 @@ Public Delegate Sub RenamedEventHandler(sender As Object, e As RenamedEventArgs) Gets or sets an for the . An for the . - to a and enable communication between them, as well as provide a way for the container to manage its components. - + to a and enable communication between them, as well as provide a way for the container to manage its components. + ]]> @@ -2088,15 +2036,15 @@ Public Delegate Sub RenamedEventHandler(sender As Object, e As RenamedEventArgs) Gets or sets the object used to marshal the event handler calls issued as a result of a directory change. The that represents the object used to marshal the event handler calls issued as a result of a directory change. The default is . - is `null`, methods handling the , , , and events are called on a thread from the system thread pool. For more information on system thread pools, see . - - When the , , , and events are handled by a visual Windows Forms component, such as a , accessing the component through the system thread pool might not work, or may result in an exception. Avoid this by setting to a Windows Forms component, which causes the methods that handle the , , , and events to be called on the same thread on which the component was created. - - If the is used inside Visual Studio 2005 in a Windows Forms designer, automatically sets to the control that contains the . For example, if you place a on a designer for Form1 (which inherits from ) the property of is set to the instance of Form1. - + is `null`, methods handling the , , , and events are called on a thread from the system thread pool. For more information on system thread pools, see . + + When the , , , and events are handled by a visual Windows Forms component, such as a , accessing the component through the system thread pool might not work, or may result in an exception. Avoid this by setting to a Windows Forms component, which causes the methods that handle the , , , and events to be called on the same thread on which the component was created. + + If the is used inside Visual Studio 2005 in a Windows Forms designer, automatically sets to the control that contains the . For example, if you place a on a designer for Form1 (which inherits from ) the property of is set to the instance of Form1. + ]]> @@ -2160,16 +2108,16 @@ Public Delegate Sub RenamedEventHandler(sender As Object, e As RenamedEventArgs) A synchronous method that returns a structure that contains specific information on the change that occurred, given the type of change you want to monitor. A that contains specific information on the change that occurred. - with the `timeout` parameter set to -1. - + with the `timeout` parameter set to -1. + > [!NOTE] -> This method allows an event handler to be invoked to respond to file changes even if the property is set to `false`. - - In some systems, reports changes to files using the short 8.3 file name format. For example, a change to "LongFileName.LongExtension" could be reported as "LongFi~.Lon". - +> This method allows an event handler to be invoked to respond to file changes even if the property is set to `false`. + + In some systems, reports changes to files using the short 8.3 file name format. For example, a change to "LongFileName.LongExtension" could be reported as "LongFi~.Lon". + ]]> @@ -2219,16 +2167,16 @@ Public Delegate Sub RenamedEventHandler(sender As Object, e As RenamedEventArgs) A synchronous method that returns a structure that contains specific information on the change that occurred, given the type of change you want to monitor and the time (in milliseconds) to wait before timing out. A that contains specific information on the change that occurred. - [!NOTE] -> This method allows an event handler to be invoked to respond to file changes even if the property is set to `false`. - - In some systems, reports changes to files using the short 8.3 file name format. For example, a change to "LongFileName.LongExtension" could be reported as "LongFi~.Lon". - +> This method allows an event handler to be invoked to respond to file changes even if the property is set to `false`. + + In some systems, reports changes to files using the short 8.3 file name format. For example, a change to "LongFileName.LongExtension" could be reported as "LongFi~.Lon". + ]]> diff --git a/xml/System.Linq.Expressions/BinaryExpression.xml b/xml/System.Linq.Expressions/BinaryExpression.xml index 6bbabcd2270..d67c6473572 100644 --- a/xml/System.Linq.Expressions/BinaryExpression.xml +++ b/xml/System.Linq.Expressions/BinaryExpression.xml @@ -60,83 +60,15 @@ Represents an expression that has a binary operator. - - that has a specific node type, represented by the property. Each table contains information for a specific class of operations such as arithmetic or bitwise. - -## Binary Arithmetic Operations - -|Node Type|Factory Method| -|---------------|--------------------| -||| -||| -||| -||| -||| -||| -||| -||| -||| - -## Bitwise Operations - -|Node Type|Factory Method| -|---------------|--------------------| -||| -||| -||| - -## Shift Operations - -|Node Type|Factory Method| -|---------------|--------------------| -||| -||| - -## Conditional Boolean Operations - -|Node Type|Factory Method| -|---------------|--------------------| -||| -||| - -## Comparison Operations - -|Node Type|Factory Method| -|---------------|--------------------| -||| -||| -||| -||| -||| -||| - -## Coalescing Operations - -|Node Type|Factory Method| -|---------------|--------------------| -||| - -## Array Indexing Operations - -|Node Type|Factory Method| -|---------------|--------------------| -||| - - In addition, the methods can also be used to create a . These factory methods can be used to create a of any node type that represents a binary operation. The parameter of these methods that is of type specifies the desired node type. - - - -## Examples - The following example creates a object that represents the subtraction of one number from another. - - :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BinaryExpression/Overview/Expression.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet8"::: - - ]]> - + + object that represents the subtraction of one number from another. + + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BinaryExpression/Overview/Expression.cs" id="Snippet8"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet8"::: + ]]> + + For more information about this API, see Supplemental API remarks for BinaryExpression. @@ -181,11 +113,11 @@ Dispatches to the specific visit method for this node type. For example, calls the . The result of visiting this node. - nodes calls . Override this method to call into a more specific method on a derived visitor class of the class. However, it should still support unknown visitors by calling . - + nodes calls . Override this method to call into a more specific method on a derived visitor class of the class. However, it should still support unknown visitors by calling . + ]]> @@ -285,11 +217,11 @@ Gets the type conversion function that is used by a coalescing or compound assignment operation. A that represents a type conversion function. - property is `null` for any whose property is not . - + property is `null` for any whose property is not . + ]]> @@ -334,11 +266,11 @@ if the node represents a lifted call; otherwise, . - @@ -383,11 +315,11 @@ if the operator's return type is lifted to a nullable type; otherwise, . - is `true`, the operator returns a nullable type, and if a nullable operand evaluates to `null`, the operator returns `null`. - + is `true`, the operator returns a nullable type, and if a nullable operand evaluates to `null`, the operator returns `null`. + ]]> @@ -493,11 +425,11 @@ Gets the implementing method for the binary operation. The that represents the implementing method. - represents an operation that uses a predefined operator, the property is `null`. - + represents an operation that uses a predefined operator, the property is `null`. + ]]> @@ -541,13 +473,13 @@ Reduces the binary expression node to a simpler expression. The reduced expression. - diff --git a/xml/System.Net.Http/HttpClient.xml b/xml/System.Net.Http/HttpClient.xml index 060ffee389b..550c255e5a9 100644 --- a/xml/System.Net.Http/HttpClient.xml +++ b/xml/System.Net.Http/HttpClient.xml @@ -45,160 +45,14 @@ Provides a class for sending HTTP requests and receiving HTTP responses from a resource identified by a URI. - - class instance acts as a session to send HTTP requests. An instance is a collection of settings applied to all requests executed by that instance. In addition, every instance uses its own connection pool, isolating its requests from requests executed by other instances. - -### Instancing - - is intended to be instantiated once and reused throughout the life of an application. In .NET Core and .NET 5+, HttpClient pools connections inside the handler instance and reuses a connection across multiple requests. If you instantiate an HttpClient class for every request, the number of sockets available under heavy loads will be exhausted. This exhaustion will result in errors. - -You can configure additional options by passing in a "handler", such as (or in .NET Core 2.1 or later), as part of the constructor. The connection properties on the handler cannot be changed once a request has been submitted, so one reason to create a new HttpClient instance would be if you need to change the connection properties. If different requests require different settings, this may also lead to an application having multiple instances, where each instance is configured appropriately, and then requests are issued on the relevant client. - -HttpClient only resolves DNS entries when a connection is created. It does not track any time to live (TTL) durations specified by the DNS server. If DNS entries change regularly, which can happen in some container scenarios, the client won't respect those updates. To solve this issue, you can limit the lifetime of the connection by setting the property, so that DNS lookup is required when the connection is replaced. - -```csharp -public class GoodController : ApiController -{ - private static readonly HttpClient httpClient; - - static GoodController() - { - var socketsHandler = new SocketsHttpHandler - { - PooledConnectionLifetime = TimeSpan.FromMinutes(2) - }; - - httpClient = new HttpClient(socketsHandler); - } -} -``` - -As an alternative to creating only one HttpClient instance, you can also use to manage the HttpClient instances for you. For more information, see [Guidelines for using HttpClient](/dotnet/fundamentals/networking/httpclient-guidelines). - -### Derivation - - The also acts as a base class for more specific HTTP clients. An example would be a FacebookHttpClient that provides additional methods specific to a Facebook web service (for example, a `GetFriends` method). Derived classes should not override the virtual methods on the class. Instead, use a constructor overload that accepts to configure any pre-request or post-request processing. - -### Transports - -The is a high-level API that wraps the lower-level functionality available on each platform where it runs. - -On each platform, tries to use the best available transport: - -| **Host/Runtime** | **Backend** | -| --------------------------- | ----------------------------------------------------------------------------------------- | -| Windows/.NET Framework | | -| Windows/Mono | | -| Windows/UWP | Windows native (HTTP 2.0 capable) | -| Windows/.NET Core 1.0-2.0 | Windows native (HTTP 2.0 capable) | -| Android/Xamarin | Selected at build-time. Can either use or be configured to use Android's native [`HttpURLConnection`](https://developer.xamarin.com/api/type/Java.Net.HttpURLConnection/) | -| iOS, tvOS, watchOS/Xamarin | Selected at build-time. Can either use or be configured to use Apple's [`NSUrlSession`](https://developer.xamarin.com/api/type/MonoTouch.Foundation.NSUrlSession/) (HTTP 2.0 capable) | -| macOS/Xamarin | Selected at build-time. Can either use or be configured to use Apple's [`NSUrlSession`](https://developer.xamarin.com/api/type/MonoTouch.Foundation.NSUrlSession/) (HTTP 2.0 capable) | -| macOS/Mono | | -| macOS/.NET Core 1.0-2.0 | `libcurl`-based HTTP transport (HTTP 2.0 capable) | -| Linux/Mono | | -| Linux/.NET Core 1.0-2.0 | `libcurl`-based HTTP transport (HTTP 2.0 capable) | -| .NET Core 2.1 and later | | - -Users can also configure a specific transport for by invoking the constructor that takes an . - -#### .NET Framework & Mono - - By default on .NET Framework and Mono, is used to send requests to the server. This behavior can be modified by specifying a different handler in one of the constructor overloads with an parameter. If you require features like authentication or caching, you can use to configure settings and the instance can be passed to the constructor. The returned handler can be passed to a constructor overload that has an parameter. - -#### .NET Core - -Starting with .NET Core 2.1, the class instead of provides the implementation used by higher-level HTTP networking classes such as . The use of offers a number of advantages: - -- A significant performance improvement when compared with the previous implementation. -- The elimination of platform dependencies, which simplifies deployment and servicing. For example, `libcurl` is no longer a dependency on .NET Core for macOS and .NET Core for Linux. -- Consistent behavior across all .NET platforms. - -If this change is undesirable, on Windows you can continue to use by referencing its [NuGet package](https://www.nuget.org/packages/System.Net.Http.WinHttpHandler/) and passing it to [HttpClient's constructor](xref:System.Net.Http.HttpClient.%23ctor(System.Net.Http.HttpMessageHandler)) manually. - -### Configure behavior using runtime configuration options - -Certain aspects of 's behavior are customizable through [Runtime configuration options](/dotnet/core/run-time-config/networking). However, the behavior of these switches differs through .NET versions. For example, in .NET Core 2.1 - 3.1, you can configure whether is used by default, but that option is no longer available starting in .NET 5.0. - -### Connection pooling - -HttpClient pools HTTP connections where possible and uses them for more than one request. This can have a significant performance benefit, especially for HTTPS requests, as the connection handshake is only done once. - -Connection pool properties can be configured on a or passed in during construction, including , , and . - -Disposing of the HttpClient instance closes the open connections and cancels any pending requests. - -> [!NOTE] -> If you concurrently send HTTP/1.1 requests to the same server, new connections can be created. Even if you reuse the `HttpClient` instance, if the rate of requests is high, or if there are any firewall limitations, that can exhaust the available sockets because of default TCP cleanup timers. To limit the number of concurrent connections, you can set the `MaxConnectionsPerServer` property. By default, the number of concurrent HTTP/1.1 connections is unlimited. - -### Buffering and request lifetime - -By default, HttpClient methods (except ) buffer the responses from the server, reading all the response body into memory before returning the async result. Those requests will continue until one of the following occurs: - -* The succeeds and returns a result. -* The is reached, in which case the will be cancelled. -* The passable to some method overloads is fired. -* is called. -* The HttpClient is disposed. - -You can change the buffering behavior on a per-request basis using the parameter available on some method overloads. This argument can be used to specify if the should be considered complete after reading just the response headers, or after reading and buffering the response content. - -If your app that uses and related classes in the namespace intends to download large amounts of data (50 megabytes or more), then the app should stream those downloads and not use the default buffering. If you use the default buffering, the client memory usage will get very large, potentially resulting in substantially reduced performance. - -### Thread safety - - The following methods are thread safe: - -- -- -- -- -- -- -- -- -- - -### Proxies - -By default, HttpClient reads proxy configuration from environment variables or user/system settings, depending on the platform. You can change this behavior by passing a or to, in order of precedence: - -* The property on a HttpClientHandler passed in during HttpClient construction -* The static property (affects all instances) - -You can disable the proxy using . The default configuration for Windows users is to try and detect a proxy using network discovery, which can be slow. For high throughput applications where it's known that a proxy isn't required, you should disable the proxy. - -Proxy settings (like ) should be changed only before the first request is made using the HttpClient. Changes made after using the HttpClient for the first time may not be reflected in subsequent requests. - -### Timeouts - -You can use to set a default timeout for all HTTP requests from the HttpClient instance. The timeout only applies to the xxxAsync methods that cause a request/response to be initiated. If the timeout is reached, the for that request is cancelled. - -You can set some additional timeouts if you pass in a instance when constructing the HttpClient object: - -| **Property** | **Description**| -| ------------ | -------------- | -| | Specifies a timeout that's used when a request requires a new TCP connection to be created. If the timeout occurs, the request is cancelled. | -| | Specifies a timeout to be used for each connection in the connection pool. If the connection is idle, the connection is immediately closed; otherwise, the connection is closed at the end of the current request. | -| | If a connection in the connection pool is idle for this long, the connection is closed. | -| | If request has an "Expect: 100-continue" header, it delays sending content until the timeout or until a "100-continue" response is received. | - -HttpClient only resolves DNS entries when the connections are created. It does not track any time to live (TTL) durations specified by the DNS server. If DNS entries are changing regularly, which can happen in some container scenarios, you can use the to limit the lifetime of the connection so that DNS lookup is required when replacing the connection. - -## Examples - - :::code language="csharp" source="~/snippets/csharp/System.Net.Http/HttpClient/source.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Net.Http/HttpClient/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.net.http.httpclient/vb/source.vb" id="Snippet1"::: - - The preceding code example uses an `async Task Main()` entry point. That feature requires C# 7.1 or later. - - ]]> - + + + + For more information about this API, see Supplemental API remarks for HttpClient. Guidelines for using HttpClient HttpClient Sample @@ -213,30 +67,30 @@ HttpClient only resolves DNS entries when the connections are created. It does n Initializes a new instance of the class. - is intended to be instantiated once and re-used throughout the life of an application. Instantiating an HttpClient class for every request will exhaust the number of sockets available under heavy loads. This will result in SocketException errors. Below is an example using HttpClient correctly. - -```csharp -public class GoodController : ApiController -{ - private static readonly HttpClient HttpClient; - - static GoodController() - { - HttpClient = new HttpClient(); - } -} + is intended to be instantiated once and re-used throughout the life of an application. Instantiating an HttpClient class for every request will exhaust the number of sockets available under heavy loads. This will result in SocketException errors. Below is an example using HttpClient correctly. + +```csharp +public class GoodController : ApiController +{ + private static readonly HttpClient HttpClient; + + static GoodController() + { + HttpClient = new HttpClient(); + } +} ``` ```vb Public Class GoodController - Inherits ApiController - + Inherits ApiController + Private Shared ReadOnly HttpClient As HttpClient - - Shared Sub New() + + Shared Sub New() HttpClient = New HttpClient() End Sub End Class @@ -275,8 +129,8 @@ End Class Initializes a new instance of the class using a that is disposed when this instance is disposed. - @@ -315,11 +169,11 @@ Using this constructor is equivalent to calling the [`HttpClient(new HttpClientH The HTTP handler stack to use for sending requests. Initializes a new instance of the class with the specified handler. The handler is disposed when this instance is disposed. - The is . @@ -412,13 +266,13 @@ The specified `handler` will be disposed of by calling [HttpClient.Dispose](xref Gets or sets the base address of Uniform Resource Identifier (URI) of the Internet resource used when sending requests. The base address of Uniform Resource Identifier (URI) of the Internet resource used when sending requests. - with a relative Uri, the message Uri will be added to the property to create an absolute Uri. - + with a relative Uri, the message Uri will be added to the property to create an absolute Uri. + Note that all characters after the right-most "/" in the base URI are excluded when combined with the message URI. See [RFC 3986](https://tools.ietf.org/html/rfc3986) Uniform Resource Identifier (URI) Generic Syntax specification. - + ]]> @@ -456,11 +310,11 @@ The specified `handler` will be disposed of by calling [HttpClient.Dispose](xref Cancel all pending requests on this instance. - instance can still be used to execute additional requests. - + instance can still be used to execute additional requests. + ]]> @@ -492,8 +346,8 @@ The specified `handler` will be disposed of by calling [HttpClient.Dispose](xref Gets or sets the global HTTP proxy. A proxy used by every HTTP request. -  instances use if no proxy is set explicitly in the  passed through its constructor. @@ -551,11 +405,11 @@ The proxy server may be a hostname or IP address, optionally followed by a colon Gets the headers which should be sent with each request. The headers which should be sent with each request. - @@ -587,9 +441,9 @@ The proxy server may be a hostname or IP address, optionally followed by a colon Gets or sets the default HTTP version used on subsequent requests made by this instance. The default version to use for any requests made with this instance. - by default. The `DefaultRequestVersion` property specifies the default HTTP version to use for requests sent using this instance when it constructs the to send, specifically with calls to methods such as , , , , , , , and . @@ -629,9 +483,9 @@ The `DefaultRequestVersion` property can be changed as long as the Gets or sets the default version policy for implicitly created requests in convenience methods, for example, and . The HttpVersionPolicy used when the HTTP connection is established. - or overloads that accept an . ]]> @@ -698,10 +552,10 @@ This property has no effect on any of the Send a DELETE request to the specified Uri as an asynchronous operation. The task object representing the asynchronous operation. - object will complete after the whole response (including content) is read. + object will complete after the whole response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -768,10 +622,10 @@ The is not an absolute URI. Send a DELETE request to the specified Uri as an asynchronous operation. The task object representing the asynchronous operation. - object will complete after the whole response (including content) is read. + object will complete after the whole response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -844,10 +698,10 @@ The is not an absolute URI. Send a DELETE request to the specified Uri with a cancellation token as an asynchronous operation. The task object representing the asynchronous operation. - object will complete after the whole response (including content) is read. + object will complete after the whole response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -917,10 +771,10 @@ The is not an absolute URI. Send a DELETE request to the specified Uri with a cancellation token as an asynchronous operation. The task object representing the asynchronous operation. - object will complete after the whole response (including content) is read. + object will complete after the whole response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -980,15 +834,15 @@ The is not an absolute URI. to release both managed and unmanaged resources; to releases only unmanaged resources. Releases the unmanaged resources used by the and optionally disposes of the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `false`. - - When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the `Dispose()` method of each referenced object. - - When this method is called, the method is called to abort all pending requests. - + + When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the `Dispose()` method of each referenced object. + + When this method is called, the method is called to abort all pending requests. + ]]> @@ -1003,11 +857,11 @@ The is not an absolute URI. Send a GET request to the specified Uri as an asynchronous operation. - @@ -1061,9 +915,9 @@ The is not an absolute URI. Send a GET request to the specified Uri as an asynchronous operation. The task object representing the asynchronous operation. - object will complete after the whole response (including content) is read. The behavior is the same as if has been explicitly specified. > [!NOTE] @@ -1124,9 +978,9 @@ The is not an absolute URI. Send a GET request to the specified Uri as an asynchronous operation. The task object representing the asynchronous operation. - object will complete after the whole response (including content) is read. The behavior is the same as if has been explicitly specified. > [!NOTE] @@ -1192,10 +1046,10 @@ The is not an absolute URI. Send a GET request to the specified Uri with an HTTP completion option as an asynchronous operation. The task object representing the asynchronous operation. - object will complete based on the `completionOption` parameter after the part or all of the response (including content) is read. + object will complete based on the `completionOption` parameter after the part or all of the response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -1261,9 +1115,9 @@ The is not an absolute URI. Send a GET request to the specified Uri with a cancellation token as an asynchronous operation. The task object representing the asynchronous operation. - object will complete after the whole response (including content) is read. The behavior is the same as if has been explicitly specified. > [!NOTE] @@ -1327,10 +1181,10 @@ The is not an absolute URI. Send a GET request to the specified Uri with an HTTP completion option as an asynchronous operation. The task object representing the asynchronous operation. - object will complete based on the `completionOption` parameter after the part or all of the response (including content) is read. + object will complete based on the `completionOption` parameter after the part or all of the response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -1391,9 +1245,9 @@ The is not an absolute URI. Send a GET request to the specified Uri with a cancellation token as an asynchronous operation. The task object representing the asynchronous operation. - object will complete after the whole response (including content) is read. The behavior is the same as if has been explicitly specified. > [!NOTE] @@ -1462,10 +1316,10 @@ The is not an absolute URI. Send a GET request to the specified Uri with an HTTP completion option and a cancellation token as an asynchronous operation. The task object representing the asynchronous operation. - object will complete based on the `completionOption` parameter after the part or all of the response (including content) is read. + object will complete based on the `completionOption` parameter after the part or all of the response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -1530,10 +1384,10 @@ The is not an absolute URI. Send a GET request to the specified Uri with an HTTP completion option and a cancellation token as an asynchronous operation. The task object representing the asynchronous operation. - object will complete based on the `completionOption` parameter after the part or all of the response (including content) is read. + object will complete based on the `completionOption` parameter after the part or all of the response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -1558,11 +1412,11 @@ The is not an absolute URI. Send a GET request to the specified Uri and return the response body as a byte array in an asynchronous operation. - @@ -1622,10 +1476,10 @@ The is not an absolute URI. Sends a GET request to the specified Uri and return the response body as a byte array in an asynchronous operation. The task object representing the asynchronous operation. - object will complete after the whole response body is read. + object will complete after the whole response body is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -1691,10 +1545,10 @@ The is not an absolute URI. Send a GET request to the specified Uri and return the response body as a byte array in an asynchronous operation. The task object representing the asynchronous operation. - object will complete after the whole response body is read. + object will complete after the whole response body is read. > [!NOTE] > In case of a timeout: @@ -1751,10 +1605,10 @@ The is not an absolute URI. Sends a GET request to the specified Uri and return the response body as a byte array in an asynchronous operation. The task object representing the asynchronous operation. - object will complete after the whole response body is read. + object will complete after the whole response body is read. > [!NOTE] > In case of a timeout: @@ -1808,10 +1662,10 @@ The is not an absolute URI. Send a GET request to the specified Uri and return the response body as a byte array in an asynchronous operation. The task object representing the asynchronous operation. - object will complete after the whole response body is read. + object will complete after the whole response body is read. > [!NOTE] > In case of a timeout: @@ -1836,11 +1690,11 @@ The is not an absolute URI. Send a GET request to the specified Uri and return the response body as a stream in an asynchronous operation. - @@ -1900,10 +1754,10 @@ The is not an absolute URI. Send a GET request to the specified Uri and return the response body as a stream in an asynchronous operation. The task object representing the asynchronous operation. - ](xref:System.Threading.Tasks.Task%601) object will complete after the response headers are read. This method does not read nor buffer the response body. + ](xref:System.Threading.Tasks.Task%601) object will complete after the response headers are read. This method does not read nor buffer the response body. > [!NOTE] > In case of a timeout: @@ -1969,10 +1823,10 @@ The is not an absolute URI. Send a GET request to the specified Uri and return the response body as a stream in an asynchronous operation. The task object representing the asynchronous operation. - ](xref:System.Threading.Tasks.Task%601) object will complete after the response headers are read. This method does not read nor buffer the response body. + ](xref:System.Threading.Tasks.Task%601) object will complete after the response headers are read. This method does not read nor buffer the response body. > [!NOTE] > In case of a timeout: @@ -2029,9 +1883,9 @@ The is not an absolute URI. The task object representing the asynchronous operation. ](xref:System.Threading.Tasks.Task%601) object will complete after the response headers are read. This method does not read nor buffer the response body. + +## Remarks + This operation will not block. The returned [Task\](xref:System.Threading.Tasks.Task%601) object will complete after the response headers are read. This method does not read nor buffer the response body. > [!NOTE] > In case of a timeout: @@ -2085,10 +1939,10 @@ The is not an absolute URI. Send a GET request to the specified Uri and return the response body as a stream in an asynchronous operation. The task object representing the asynchronous operation. - ](xref:System.Threading.Tasks.Task%601) object will complete after the response headers are read. This method does not read nor buffer the response body. + ](xref:System.Threading.Tasks.Task%601) object will complete after the response headers are read. This method does not read nor buffer the response body. > [!NOTE] > In case of a timeout: @@ -2113,11 +1967,11 @@ The is not an absolute URI. Send a GET request to the specified Uri and return the response body as a string in an asynchronous operation. - @@ -2177,10 +2031,10 @@ The is not an absolute URI. Send a GET request to the specified Uri and return the response body as a string in an asynchronous operation. The task object representing the asynchronous operation. - object will complete after the whole response body is read. + object will complete after the whole response body is read. > [!NOTE] > In case of a timeout: @@ -2246,10 +2100,10 @@ The is not an absolute URI. Send a GET request to the specified Uri and return the response body as a string in an asynchronous operation. The task object representing the asynchronous operation. - object will complete after the whole response body is read. + object will complete after the whole response body is read. > [!NOTE] > In case of a timeout: @@ -2305,10 +2159,10 @@ The is not an absolute URI. Send a GET request to the specified Uri and return the response body as a string in an asynchronous operation. The task object representing the asynchronous operation. - object will complete after the whole response body is read. + object will complete after the whole response body is read. > [!NOTE] > In case of a timeout: @@ -2362,10 +2216,10 @@ The is not an absolute URI. Send a GET request to the specified Uri and return the response body as a string in an asynchronous operation. The task object representing the asynchronous operation. - object will complete after the whole response body is read. + object will complete after the whole response body is read. > [!NOTE] > In case of a timeout: @@ -2413,11 +2267,11 @@ The is not an absolute URI. Gets or sets the maximum number of bytes to buffer when reading the response content. The maximum number of bytes to buffer when reading the response content. The default value for this property is 2 gigabytes. - property to a lower value to limit the size of the response to buffer when reading the response. If the size of the response content is greater than the property, an exception is thrown. - + property to a lower value to limit the size of the response to buffer when reading the response. If the size of the response content is greater than the property, an exception is thrown. + ]]> The size specified is less than or equal to zero. @@ -2474,11 +2328,11 @@ The is not an absolute URI. Sends a PATCH request to a Uri designated as a string as an asynchronous operation. The task object representing the asynchronous operation. - object will complete after the whole response (including content) is read. - + object will complete after the whole response (including content) is read. + ]]> The provided request URI is not valid relative or absolute URI. @@ -2526,11 +2380,11 @@ The is not an absolute URI. Sends a PATCH request as an asynchronous operation. The task object representing the asynchronous operation. - object will complete after the whole response (including content) is read. - + object will complete after the whole response (including content) is read. + ]]> @@ -2586,11 +2440,11 @@ The is not an absolute URI. Sends a PATCH request with a cancellation token to a Uri represented as a string as an asynchronous operation. The task object representing the asynchronous operation. - object will complete after the whole response (including content) is read. - + object will complete after the whole response (including content) is read. + ]]> The provided request URI is not valid relative or absolute URI. @@ -2641,11 +2495,11 @@ The is not an absolute URI. Sends a PATCH request with a cancellation token as an asynchronous operation. The task object representing the asynchronous operation. - object will complete after the whole response (including content) is read. - + object will complete after the whole response (including content) is read. + ]]> The cancellation token was canceled. This exception is stored into the returned task. @@ -2661,11 +2515,11 @@ The is not an absolute URI. Send a POST request to the specified Uri as an asynchronous operation. - @@ -2724,10 +2578,10 @@ The is not an absolute URI. Send a POST request to the specified Uri as an asynchronous operation. The task object representing the asynchronous operation. - object will complete after the whole response (including content) is read. + object will complete after the whole response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -2789,10 +2643,10 @@ The is not an absolute URI. Send a POST request to the specified Uri as an asynchronous operation. The task object representing the asynchronous operation. - object will complete after the whole response (including content) is read. + object will complete after the whole response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -2862,10 +2716,10 @@ The is not an absolute URI. Send a POST request with a cancellation token as an asynchronous operation. The task object representing the asynchronous operation. - object will complete after the whole response (including content) is read. + object will complete after the whole response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -2930,10 +2784,10 @@ The is not an absolute URI. Send a POST request with a cancellation token as an asynchronous operation. The task object representing the asynchronous operation. - object will complete after the whole response (including content) is read. + object will complete after the whole response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -2958,11 +2812,11 @@ The is not an absolute URI. Send a PUT request to the specified Uri as an asynchronous operation. - @@ -3021,10 +2875,10 @@ The is not an absolute URI. Send a PUT request to the specified Uri as an asynchronous operation. The task object representing the asynchronous operation. - object will complete after the whole response (including content) is read. + object will complete after the whole response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -3086,10 +2940,10 @@ The is not an absolute URI. Send a PUT request to the specified Uri as an asynchronous operation. The task object representing the asynchronous operation. - object will complete after the whole response (including content) is read. + object will complete after the whole response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -3159,10 +3013,10 @@ The is not an absolute URI. Send a PUT request with a cancellation token as an asynchronous operation. The task object representing the asynchronous operation. - object will complete after the whole response (including content) is read. + object will complete after the whole response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -3227,10 +3081,10 @@ The is not an absolute URI. Send a PUT request with a cancellation token as an asynchronous operation. The task object representing the asynchronous operation. - object will complete after the whole response (including content) is read. + object will complete after the whole response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -3477,11 +3331,11 @@ The custom does not override Send an HTTP request as an asynchronous operation. - @@ -3523,9 +3377,9 @@ The custom does not override Send an HTTP request as an asynchronous operation. The task object representing the asynchronous operation. - object will complete once the entire response including content is read. The behavior is the same as if has been explicitly specified. > [!NOTE] @@ -3583,10 +3437,10 @@ This method stores in the task it returns all non-usage exceptions that the meth Send an HTTP request as an asynchronous operation. The task object representing the asynchronous operation. - object will complete as soon as a response is available or the entire response including content is read. + object will complete as soon as a response is available or the entire response including content is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -3643,9 +3497,9 @@ This method stores in the task it returns all non-usage exceptions that the meth Send an HTTP request as an asynchronous operation. The task object representing the asynchronous operation. - object will complete once the entire response including content is read. The behavior is the same as if has been explicitly specified. > [!NOTE] @@ -3706,10 +3560,10 @@ This method stores in the task it returns all non-usage exceptions that the meth Send an HTTP request as an asynchronous operation. The task object representing the asynchronous operation. - object will complete as soon as a response is available or the entire response including content is read. + object will complete as soon as a response is available or the entire response including content is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -3761,21 +3615,21 @@ This method stores in the task it returns all non-usage exceptions that the meth Gets or sets the timespan to wait before the request times out. The timespan to wait before the request times out. - . - - A Domain Name System (DNS) query may take up to 15 seconds to return or time out. If your request contains a host name that requires resolution and you set to a value less than 15 seconds, it may take 15 seconds or more before a is thrown to indicate a timeout on your request. - - The same timeout will apply for all requests using this instance. You may also set different timeouts for individual requests using a on a task. Note that only the shorter of the two timeouts will apply. - + . + + A Domain Name System (DNS) query may take up to 15 seconds to return or time out. If your request contains a host name that requires resolution and you set to a value less than 15 seconds, it may take 15 seconds or more before a is thrown to indicate a timeout on your request. + + The same timeout will apply for all requests using this instance. You may also set different timeouts for individual requests using a on a task. Note that only the shorter of the two timeouts will apply. + ## Examples - + The following example sets the `Timeout` property. - + ```csharp HttpClient httpClient = new HttpClient(); httpClient.Timeout = TimeSpan.FromMinutes(10); diff --git a/xml/System.Net.Http/HttpClientHandler.xml b/xml/System.Net.Http/HttpClientHandler.xml index 6616b1e3f7e..21630f12d0c 100644 --- a/xml/System.Net.Http/HttpClientHandler.xml +++ b/xml/System.Net.Http/HttpClientHandler.xml @@ -45,50 +45,12 @@ The default message handler used by in .NET Framework and .NET Core 2.0 and earlier. - + class. Prior to .NET Core 2.1, the `HttpClientHandler` class used older HTTP protocol stacks ( on Windows and `CurlHandler`, an internal class implemented on top of Linux's native `libcurl` component, on Linux). - -On .NET Core 2.1 - 3.1 only, you can configure your app to use the older HTTP protocol stacks in one of the following three ways: - -- Call the method: - - ```csharp - AppContext.SetSwitch("System.Net.Http.UseSocketsHttpHandler", false); - ``` - - ```vb - AppContext.SetSwitch("System.Net.Http.UseSocketsHttpHandler", False) - ``` - -- Define the `System.Net.Http.UseSocketsHttpHandler` switch in the *.netcore.runtimeconfig.json* configuration file: - - ```json - "runtimeOptions": { - "configProperties": { - "System.Net.Http.UseSocketsHttpHandler": false - } - } - ``` - -- Define an environment variable named `DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER` and set it to either `false` or **0**. - -These configuration options are not available starting with .NET 5. - -## Examples - :::code language="csharp" source="~/snippets/csharp/System.Net.Http/HttpClientHandler/Overview/source.cs" id="Snippet1"::: - - The preceding code example uses an `async Task Main()` entry point. That feature requires C# 7.1 or later. - - ]]> - + :::code language="csharp" source="~/snippets/csharp/System.Net.Http/HttpClientHandler/Overview/source.cs" id="Snippet1"::: + ]]> + + For more information about this API, see Supplemental API remarks for HttpClientHandler. Connecting to a web service Quickstart: Connecting using HttpClient How to use HttpClient handlers @@ -371,9 +333,9 @@ After NuGet package v4.3.2, the default value of Gets the collection of security certificates that are associated with requests to the server. The X509CertificateCollection that is presented to the server when performing certificate based client authentication. - Gets or sets the maximum number of concurrent connections (per server endpoint) allowed when making requests using an object. Note that the limit is per server endpoint, so for example a value of 256 would permit 256 concurrent connections to http://www.adatum.com/ and another 256 to http://www.adventure-works.com/. The maximum number of concurrent connections (per server endpoint) allowed by an object. - @@ -1202,7 +1164,7 @@ handler.ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousA Gets or sets a callback method to validate the server certificate. A callback method to validate the server certificate. - can be used to obtain and validate the server certificate. @@ -1456,7 +1418,7 @@ handler.ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousA ## Remarks Set this property to `true` when requests made by the object should, if requested by the server, be authenticated using the credentials of the currently logged on user. For client applications, this is the desired behavior in most scenarios. For middle-tier applications, such as ASP.NET applications, instead of using this property, you would typically set the property to the credentials of the client on whose behalf the request is made. - + This property doesn't affect proxy credentials. When the default (system) proxy is being used, set credentials explicitly by using the property. When the proxy is set by the property, set credentials for the proxy via its property. If this property has been set to `true` then, it has a side effect on property, and will be set to . diff --git a/xml/System.Net.Sockets/Socket.xml b/xml/System.Net.Sockets/Socket.xml index 877339ea3a4..e5c70078ec8 100644 --- a/xml/System.Net.Sockets/Socket.xml +++ b/xml/System.Net.Sockets/Socket.xml @@ -60,51 +60,22 @@ Implements the Berkeley sockets interface. - + For more information about this API, see Supplemental API remarks for Socket. + class can be used to send data to an HTTP server, printing the ASCII response to the standard output. This example blocks the calling thread until the entire page is received. -## Remarks - The class provides a rich set of methods and properties for network communications. The class allows you to perform both synchronous and asynchronous data transfer using any of the communication protocols listed in the enumeration. - - The class follows the .NET Framework naming pattern for asynchronous methods. For example, the synchronous method corresponds to the asynchronous variants. - - Use the following methods for synchronous operation mode. - -- If you are using a connection-oriented protocol such as TCP, your server can listen for connections using the method. The method processes any incoming connection requests and returns a that you can use to communicate data with the remote host. Use this returned to call the or method. Call the method prior to calling the method if you want to specify the local IP address and port number. Use a port number of zero if you want the underlying service provider to assign a free port for you. If you want to connect to a listening host, call the method. To communicate data, call the or method. - -- If you are using a connectionless protocol such as UDP, you do not need to listen for connections at all. Call the method to accept any incoming datagrams. Use the method to send datagrams to a remote host. - - To process communications asynchronously, use the following methods. - -- If you are using a connection-oriented protocol such as TCP, use to connect with a listening host. Use or to communicate data asynchronously. Incoming connection requests can be processed using . - -- If you are using a connectionless protocol such as UDP, you can use to send datagrams, and to receive datagrams. - - If you perform multiple asynchronous operations on a socket, they do not necessarily complete in the order in which they are started. + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/Socket/Overview/socket.cs" id="Snippet1"::: - When you are finished sending and receiving data, use the method to disable the . After calling , call the method to release all resources associated with the . + The next example demonstrates the same HTTP GET scenario, using Task-based asynchronous APIs, while also forwarding a to the asynchronous methods, making the entire operation cancellable. - The class allows you to configure your using the method. Retrieve these settings using the method. + > [!TIP] + > 's async methods that do not take a typically return a , which is allocated on the heap. + > Cancellable overloads are always -returning; using them helps reducing allocations in high-performance code. -## Examples - -### Synchronous mode - The following example shows how the class can be used to send data to an HTTP server, printing the ASCII response to the standard output. - This example blocks the calling thread until the entire page is received. - - :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/Socket/Overview/socket.cs" id="Snippet1"::: - -### Asynchronous mode - The second example demonstrates the same HTTP GET scenario, using Task-based asynchronous API-s, while also forwarding a to the asynchronous methods, making the entire operation cancellable. - - > [!TIP] - > 's async methods that do not take a typically return a , which is allocated on the heap. - > Cancellable overloads are always -returning; using them helps reducing allocations in high-performance code. - - :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/Socket/Overview/socket.cs" id="Snippet2"::: - - ]]> - + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/Socket/Overview/socket.cs" id="Snippet2"::: + ]]> + It is safe to perform a send and a receive operation simultaneously on a instance, but it's not recommended to issue multiple send or multiple receive calls concurrently. Depending on the underlying platform diff --git a/xml/System.Net/HttpListener.xml b/xml/System.Net/HttpListener.xml index 825c5204e13..a00e0fdef63 100644 --- a/xml/System.Net/HttpListener.xml +++ b/xml/System.Net/HttpListener.xml @@ -52,57 +52,13 @@ Provides a simple, programmatically controlled HTTP protocol listener. This class cannot be inherited. - - class, you can create a simple HTTP protocol listener that responds to HTTP requests. The listener is active for the lifetime of the object and runs within your application with its permissions. - - To use , create a new instance of the class using the constructor and use the property to gain access to the collection that holds the strings that specify which Uniform Resource Identifier (URI) prefixes the should process. - - A URI prefix string is composed of a scheme (http or https), a host, an optional port, and an optional path. An example of a complete prefix string is *http://www.contoso.com:8080/customerData/*. Prefixes must end in a forward slash ("/"). The object with the prefix that most closely matches a requested URI responds to the request. Multiple objects cannot add the same prefix; a exception is thrown if a adds a prefix that is already in use. - - When a port is specified, the host element can be replaced with "\*" to indicate that the accepts requests sent to the port if the requested URI does not match any other prefix. For example, to receive all requests sent to port 8080 when the requested URI is not handled by any , the prefix is *http://\*:8080/*. Similarly, to specify that the accepts all requests sent to a port, replace the host element with the "+" character. For example, *https://+:8080*. The "\*" and "+" characters can be present in prefixes that include paths. - - Starting with .NET Core 2.0 or .NET Framework 4.6 on Windows 10, wildcard subdomains are supported in URI prefixes that are managed by an object. To specify a wildcard subdomain, use the "\*" character as part of the hostname in a URI prefix. For example, *http://\*.foo.com/*. Pass this as the argument to the method. This works as of .NET Core 2.0 or .NET Framework 4.6 on Windows 10; in earlier versions, this generates an . - - > [!WARNING] - > Top-level wildcard bindings (*http://\*:8080/* and *http://+:8080*) should **not** be used. Top-level wildcard bindings can open up your app to security vulnerabilities. This applies to both strong and weak wildcards. Use explicit host names rather than wildcards. Subdomain wildcard binding (for example, `*.mysub.com`) doesn't have this security risk if you control the entire parent domain (as opposed to `*.com`, which is vulnerable). See [rfc7230 section-5.4](https://tools.ietf.org/html/rfc7230#section-5.4) for more information. - - To begin listening for requests from clients, add the URI prefixes to the collection and call the method. offers both synchronous and asynchronous models for processing client requests. Requests and their associated responses are accessed using the object returned by the method or its asynchronous counterparts, the and methods. - - The synchronous model is appropriate if your application should block while waiting for a client request and if you want to process only one request at a time. Using the synchronous model, call the method, which waits for a client to send a request. The method returns an object to you for processing when one occurs. - - In the more complex asynchronous model, your application does not block while waiting for requests and each request is processed in its own execution thread. Use the method to specify an application-defined method to be called for each incoming request. Within that method, call the method to obtain the request, process it, and respond. - - In either model, incoming requests are accessed using the property and are represented by objects. Similarly, responses are accessed using the property and are represented by objects. These objects share some functionality with the and objects, but the latter objects cannot be used in conjunction with because they implement client, not server, behaviors. - - An can require client authentication. You can either specify a particular scheme to use for authentication, or you can specify a delegate that determines the scheme to use. You must require some form of authentication to obtain information about the client's identity. For additional information, see the , , and properties. - -> [!NOTE] -> If you create an using https, you must select a Server Certificate for that listener. Otherwise, requests to this will fail with an unexpected close of the connection. - -> [!NOTE] -> You can configure Server Certificates and other listener options by using Network Shell (netsh.exe). See [Network Shell (Netsh)](/windows-server/networking/technologies/netsh/netsh) for more details. The executable began shipping with Windows Server 2008 and Windows Vista. - -> [!NOTE] -> If you specify multiple authentication schemes for the , the listener will challenge clients in the following order: `Negotiate`, `NTLM`, `Digest`, and then `Basic`. - -### HTTP.sys - -The class is built on top of `HTTP.sys`, which is the kernel mode listener that handles all HTTP traffic for Windows. -`HTTP.sys` provides connection management, bandwidth throttling, and web server logging. -Use the [HttpCfg.exe](/windows/win32/http/httpcfg-exe) tool to add SSL certificates. - -## Examples - The following code example demonstrates using a . - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet2"::: - - ]]> - + For more information about this API, see Supplemental API remarks for HttpListener. + + + Changes to NTLM authentication for HTTPWebRequest in Version 3.5 SP1 HttpCfg.exe @@ -139,19 +95,19 @@ Use the [HttpCfg.exe](/windows/win32/http/httpcfg-exe) tool to add SSL certifica Initializes a new instance of the class. - method. - - - -## Examples - The following code example demonstrates using the constructor to create a new object. For the complete example, see the class topic. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet9"::: - + method. + + + +## Examples + The following code example demonstrates using the constructor to create a new object. For the complete example, see the class topic. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet9"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet9"::: + ]]> This class cannot be used on the current operating system. Windows Server 2003 or Windows XP SP2 is required to use instances of this class. @@ -196,21 +152,21 @@ Use the [HttpCfg.exe](/windows/win32/http/httpcfg-exe) tool to add SSL certifica Shuts down the object immediately, discarding all currently queued requests. - if you attempt to use this . - - - -## Examples - The following code example demonstrates calling this method. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet11"::: - + if you attempt to use this . + + + +## Examples + The following code example demonstrates calling this method. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet11"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet11"::: + ]]> @@ -260,26 +216,26 @@ Use the [HttpCfg.exe](/windows/win32/http/httpcfg-exe) tool to add SSL certifica Gets or sets the scheme used to authenticate clients. A bitwise combination of enumeration values that indicates how clients are to be authenticated. The default value is . - uses the specified scheme to authenticate all incoming requests. The and methods return an incoming client request only if the successfully authenticates the request. - - You can interrogate the identity of a successfully authenticated client by using the property. - - If you want an object to use different authentication mechanisms based on characteristics of the requests it receives (for example, the request's or property), you must implement a method that chooses the authentication scheme. For instructions about how to do this, see the property documentation. - + uses the specified scheme to authenticate all incoming requests. The and methods return an incoming client request only if the successfully authenticates the request. + + You can interrogate the identity of a successfully authenticated client by using the property. + + If you want an object to use different authentication mechanisms based on characteristics of the requests it receives (for example, the request's or property), you must implement a method that chooses the authentication scheme. For instructions about how to do this, see the property documentation. + > [!NOTE] -> To set this property to enable Digest, NTLM, or Negotiate requires the , . - - - -## Examples - The following code example demonstrates using the property to specify an authentication scheme. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet14"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet14"::: - +> To set this property to enable Digest, NTLM, or Negotiate requires the , . + + + +## Examples + The following code example demonstrates using the property to specify an authentication scheme. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet14"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet14"::: + ]]> This object has been closed. @@ -336,33 +292,33 @@ Use the [HttpCfg.exe](/windows/win32/http/httpcfg-exe) tool to add SSL certifica Gets or sets the delegate called to determine the protocol used to authenticate clients. An delegate that invokes the method used to select an authentication protocol. The default value is . - [!NOTE] -> If you want the same authentication protocol to be used for all requests handled by a particular instance of , you do not need to set this property. To specify a protocol to be used for all client requests, use the property. - - If the client has not specified authentication information in its headers, the calls the specified delegate for each unauthenticated incoming request to determine which, if any, protocol to use to authenticate the client. The and methods return an incoming request only if the successfully authenticated the request. If a request cannot be authenticated, the automatically sends back a 401 response. You can get the identity of a successfully authenticated client using the property. - - The ability to delegate the choice of authentication protocol to an application-specific method is useful if you want an instance of to use different authentication protocols depending on the characteristics of the requests it receives (for example, the request's or property). - +> If you want the same authentication protocol to be used for all requests handled by a particular instance of , you do not need to set this property. To specify a protocol to be used for all client requests, use the property. + + If the client has not specified authentication information in its headers, the calls the specified delegate for each unauthenticated incoming request to determine which, if any, protocol to use to authenticate the client. The and methods return an incoming request only if the successfully authenticated the request. If a request cannot be authenticated, the automatically sends back a 401 response. You can get the identity of a successfully authenticated client using the property. + + The ability to delegate the choice of authentication protocol to an application-specific method is useful if you want an instance of to use different authentication protocols depending on the characteristics of the requests it receives (for example, the request's or property). + > [!NOTE] -> To set this property to enable Digest, NTLM, or Negotiate requires the , . - - - -## Examples - The following code example sets the value of this property. - +> To set this property to enable Digest, NTLM, or Negotiate requires the , . + + + +## Examples + The following code example sets the value of this property. + :::code language="csharp" source="~/snippets/csharp/System.Net/AuthenticationSchemes/Overview/sample.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLListener/vb/sample.vb" id="Snippet2"::: - - The following code example provides an implementation of a method invoked by an delegate. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLListener/vb/sample.vb" id="Snippet2"::: + + The following code example provides an implementation of a method invoked by an delegate. + :::code language="csharp" source="~/snippets/csharp/System.Net/AuthenticationSchemes/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLListener/vb/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLListener/vb/sample.vb" id="Snippet1"::: + ]]> This object has been closed. @@ -417,30 +373,30 @@ Use the [HttpCfg.exe](/windows/win32/http/httpcfg-exe) tool to add SSL certifica Begins asynchronously retrieving an incoming request. An object that indicates the status of the asynchronous operation. - method begins an asynchronous (non-blocking) call to receive incoming client requests. Before calling this method, you must call the method and add at least one Uniform Resource Identifier (URI) prefix to listen for by adding the URI strings to the returned by the property. - - The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the `callback` delegate. - - This method does not block while the operation completes. To get an incoming request and block until the operation completes, call the method. - - For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) - - - -## Examples - The following code example demonstrates using the method to specify a callback method that will handle incoming client requests. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet12"::: - - The following code example implements a callback method. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet13"::: - + method begins an asynchronous (non-blocking) call to receive incoming client requests. Before calling this method, you must call the method and add at least one Uniform Resource Identifier (URI) prefix to listen for by adding the URI strings to the returned by the property. + + The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the `callback` delegate. + + This method does not block while the operation completes. To get an incoming request and block until the operation completes, call the method. + + For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) + + + +## Examples + The following code example demonstrates using the method to specify a callback method that will handle incoming client requests. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet12"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet12"::: + + The following code example implements a callback method. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet13"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet13"::: + ]]> A Win32 function call failed. Check the exception's property to determine the cause of the exception. @@ -487,20 +443,20 @@ Use the [HttpCfg.exe](/windows/win32/http/httpcfg-exe) tool to add SSL certifica Shuts down the . - object. To temporarily pause an object, use the method. - - This method shut downs the object without processing queued requests. Any pending requests are unable to complete. - -## Examples + object. To temporarily pause an object, use the method. + + This method shut downs the object without processing queued requests. Any pending requests are unable to complete. + +## Examples The following code example demonstrates calling the `Close` method: - -:::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet12"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet12"::: - + +:::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet12"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet12"::: + ]]> @@ -544,37 +500,37 @@ The following code example demonstrates calling the `Close` method: Gets a default list of Service Provider Names (SPNs) as determined by registered prefixes. A that contains a list of SPNs. - property is used with integrated Windows authentication to provide extended protection. The list of SPNs is initialized from the property when accessed and cleared when new prefixes are added to the property. - - The property is used if an application doesn't set the property on its extended protection policy. - - The that is retrieved with the property is built from the property according to the following rules: - -1. If the hostname is "+", "*", or an IPv4 or IPv6 literal (equivalent to "\*" but restricted to a specific local interface), the following SPN is added: - - `"HTTP/"` plus the fully qualified domain name of the computer. - -1. If the hostname contains no dots (no domains or subdomains), an attempt is made to resolve the fully-qualified domain name using DNS (the same behavior used by ). If the fully-qualified domain name can be resolved, the following SPNs are added: - - `"HTTP/"` plus the hostname (the short name). - - `"HTTP/"` plus the fully qualified domain name for the hostname. - -1. If the hostname contains not dots (no domains or subdomains) and a fully-qualified domain name can't be resolved, the following SPN is added: - - `"HTTP/"` plus the hostname. - -1. If the hostname contains dots (domains or subdomains), the following SPN is added: - - `"HTTP/"` plus the hostname. - - The property can be used by an application to review the list of default SPNs which will be used for authentication if no custom list is supplied. If other SPNs are needed, an application can add them using one of the methods. - - It is not safe when using extended protection to make policy decisions based on the requested URL, since this can be spoofed. Rather, applications should rely on the or properties to make such policy decisions. - + property is used with integrated Windows authentication to provide extended protection. The list of SPNs is initialized from the property when accessed and cleared when new prefixes are added to the property. + + The property is used if an application doesn't set the property on its extended protection policy. + + The that is retrieved with the property is built from the property according to the following rules: + +1. If the hostname is "+", "*", or an IPv4 or IPv6 literal (equivalent to "\*" but restricted to a specific local interface), the following SPN is added: + + `"HTTP/"` plus the fully qualified domain name of the computer. + +1. If the hostname contains no dots (no domains or subdomains), an attempt is made to resolve the fully-qualified domain name using DNS (the same behavior used by ). If the fully-qualified domain name can be resolved, the following SPNs are added: + + `"HTTP/"` plus the hostname (the short name). + + `"HTTP/"` plus the fully qualified domain name for the hostname. + +1. If the hostname contains not dots (no domains or subdomains) and a fully-qualified domain name can't be resolved, the following SPN is added: + + `"HTTP/"` plus the hostname. + +1. If the hostname contains dots (domains or subdomains), the following SPN is added: + + `"HTTP/"` plus the hostname. + + The property can be used by an application to review the list of default SPNs which will be used for authentication if no custom list is supplied. If other SPNs are needed, an application can add them using one of the methods. + + It is not safe when using extended protection to make policy decisions based on the requested URL, since this can be spoofed. Rather, applications should rely on the or properties to make such policy decisions. + ]]> @@ -625,23 +581,23 @@ The following code example demonstrates calling the `Close` method: Completes an asynchronous operation to retrieve an incoming client request. An object that represents the client request. - method is called, usually within an application-defined callback method invoked by a delegate, to obtain the object that contains an incoming client request and its associated response. This method completes an operation previously started by calling the method. If the operation has not completed, this method blocks until it does. - - Because calling the method requires the object, this object is typically passed into a callback method by using the state object passed into the method. You can obtain this state object by using the property of the `asyncResult` object. - - For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) - - - -## Examples - The following code example shows the implementation of a callback method that calls the method. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet13"::: - + method is called, usually within an application-defined callback method invoked by a delegate, to obtain the object that contains an incoming client request and its associated response. This method completes an operation previously started by calling the method. If the operation has not completed, this method blocks until it does. + + Because calling the method requires the object, this object is typically passed into a callback method by using the state object passed into the method. You can obtain this state object by using the property of the `asyncResult` object. + + For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) + + + +## Examples + The following code example shows the implementation of a callback method that calls the method. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet13"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet13"::: + ]]> @@ -702,13 +658,13 @@ The following code example demonstrates calling the `Close` method: Gets or sets the to use for extended protection for a session. A that specifies the policy to use for extended protection. - property is used with integrated Windows authentication to provide extended protection. The property allows the configuration of the extended protection policy for the whole session. The property allows the configuration of the extended protection policy for each individual request. - - The property must be `null`. The instance gets the Channel Binding Token (CBT) directly from its own TLS session if there is one. - + property is used with integrated Windows authentication to provide extended protection. The property allows the configuration of the extended protection policy for the whole session. The property allows the configuration of the extended protection policy for each individual request. + + The property must be `null`. The instance gets the Channel Binding Token (CBT) directly from its own TLS session if there is one. + ]]> An attempt was made to set the property, but the property was not . @@ -779,17 +735,17 @@ The following code example demonstrates calling the `Close` method: Gets or sets the delegate called to determine the to use for each request. A that specifies the policy to use for extended protection. - property is used with integrated Windows authentication to provide extended protection. The property allows the configuration of the extended protection policy for the whole session. The property allows the configuration of the extended protection policy per individual request. - - The property must be `null`. The instance gets the Channel Binding Token (CBT) directly from its own TLS session if there is one. - - For each request, the delegate can choose the settings that the instance will use to provide extended protection. - - If a delegate returns `null` for this property, this represents a which the property set to . - + property is used with integrated Windows authentication to provide extended protection. The property allows the configuration of the extended protection policy for the whole session. The property allows the configuration of the extended protection policy per individual request. + + The property must be `null`. The instance gets the Channel Binding Token (CBT) directly from its own TLS session if there is one. + + For each request, the delegate can choose the settings that the instance will use to provide extended protection. + + If a delegate returns `null` for this property, this represents a which the property set to . + ]]> An attempt was made to set the property, but the property must be . @@ -842,28 +798,28 @@ The following code example demonstrates calling the `Close` method: Waits for an incoming request and returns when one is received. An object that represents a client request. - method and add at least one URI prefix to listen for by adding the URI strings to the returned by the property. For a detailed description of prefixes, see the class overview. - - This method blocks while waiting for an incoming request. If you want incoming requests to be processed asynchronously (on separate threads) so that your application does not block, use the method. - - - -## Examples - The following code example demonstrates calling this method. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet2"::: - + method and add at least one URI prefix to listen for by adding the URI strings to the returned by the property. For a detailed description of prefixes, see the class overview. + + This method blocks while waiting for an incoming request. If you want incoming requests to be processed asynchronously (on separate threads) so that your application does not block, use the method. + + + +## Examples + The following code example demonstrates calling this method. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet2"::: + ]]> A Win32 function call failed. Check the exception's property to determine the cause of the exception. - This object has not been started or is currently stopped. - - -or- - + This object has not been started or is currently stopped. + + -or- + The does not have any Uniform Resource Identifier (URI) prefixes to respond to. This object is closed. @@ -907,13 +863,13 @@ The following code example demonstrates calling the `Close` method: Waits for an incoming request as an asynchronous operation. The task object representing the asynchronous operation. The property on the task object returns an object that represents a client request. - object will complete when the incoming request has been received. - - Before calling this method, you must call the method and add at least one URI prefix to listen for by adding the URI strings to the returned by the property. For a detailed description of prefixes, see the class overview. - + object will complete when the incoming request has been received. + + Before calling this method, you must call the method and add at least one URI prefix to listen for by adding the URI strings to the returned by the property. For a detailed description of prefixes, see the class overview. + This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> @@ -964,19 +920,19 @@ The following code example demonstrates calling the `Close` method: if this should not return exceptions that occur when sending the response to the client; otherwise, . The default value is . - This object has been closed. @@ -1019,19 +975,19 @@ The following code example demonstrates calling the `Close` method: if the was started; otherwise, . - , call the method. - - - -## Examples - The following code example demonstrates using this property to determine the listening state of an instance. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet1"::: - + , call the method. + + + +## Examples + The following code example demonstrates using this property to determine the listening state of an instance. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet1"::: + ]]> @@ -1073,14 +1029,14 @@ The following code example demonstrates calling the `Close` method: on all platforms. - property to detect whether an object can be used with the current operating system. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet2"::: - + property to detect whether an object can be used with the current operating system. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet2"::: + ]]> @@ -1121,19 +1077,19 @@ The following code example demonstrates calling the `Close` method: Gets the Uniform Resource Identifier (URI) prefixes handled by this object. An that contains the URI prefixes that this object is configured to handle. - class overview. - - - -## Examples - The following code example demonstrates using the property to obtain and print the URI prefixes that are handled. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet1"::: - + class overview. + + + +## Examples + The following code example demonstrates using the property to obtain and print the URI prefixes that are handled. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet1"::: + ]]> This object has been closed. @@ -1194,21 +1150,21 @@ The following code example demonstrates calling the `Close` method: Gets or sets the realm, or resource partition, associated with this object. A value that contains the name of the realm associated with the object. - has only one associated realm. - - - -## Examples - The following code example demonstrates setting the property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet10"::: - + has only one associated realm. + + + +## Examples + The following code example demonstrates setting the property. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet10"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet10"::: + ]]> This object has been closed. @@ -1250,24 +1206,24 @@ The following code example demonstrates calling the `Close` method: Allows this instance to receive incoming requests. - or method. - - After you have started an object, you can use the method to stop it. - + or method. + + After you have started an object, you can use the method to stop it. + > [!NOTE] > If this listener instance uses https, you must install and select a Server Certificate. Otherwise, an query of this will fail with an unexpected close of the connection. You can configure Server Certificates and other listener options by using [HttpCfg.exe](/windows/win32/http/httpcfg-exe). - - - -## Examples - The following code example demonstrates using the method to begin processing incoming requests. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet12"::: - + + + +## Examples + The following code example demonstrates using the method to begin processing incoming requests. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet12"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet12"::: + ]]> A Win32 function call failed. Check the exception's property to determine the cause of the exception. @@ -1313,22 +1269,22 @@ The following code example demonstrates calling the `Close` method: Causes this instance to stop receiving new incoming requests and terminates processing of all ongoing requests. - object, you can use the method to restart it. + object, you can use the method to restart it. This method does not block to finish sending responses for currently accepted connections. - -## Examples - -The following code example demonstrates using the method to stop processing incoming requests. - -:::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet2"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet2"::: - + +## Examples + +The following code example demonstrates using the method to stop processing incoming requests. + +:::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet2"::: + ]]> This object has been closed. @@ -1382,11 +1338,11 @@ The following code example demonstrates using the Releases the resources held by this object. - method instead of calling this method. - + method instead of calling this method. + ]]> @@ -1426,11 +1382,11 @@ The following code example demonstrates using the The timeout manager for this instance. The timeout manager for this instance. - instance. - + instance. + ]]> @@ -1478,24 +1434,24 @@ The following code example demonstrates using the if the of the first request will be used for subsequent requests on the same connection; otherwise, . The default value is . - ) of the initial request. - - This property has no effect when NTLM is not the authentication protocol. When Negotiate is specified as the authentication protocol, this property has an effect only if NTLM is the actual protocol used for authentication. - + ) of the initial request. + + This property has no effect when NTLM is not the authentication protocol. When Negotiate is specified as the authentication protocol, this property has an effect only if NTLM is the actual protocol used for authentication. + > [!NOTE] -> While setting this property to `true` increases performance because the does not send additional NTLM authentication challenges, there is a security risk in not requiring all requests to provide authentication information. You must determine whether the increase in performance is worth this risk. - - - -## Examples - The following code example demonstrates setting this property. - - :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet14"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet14"::: - +> While setting this property to `true` increases performance because the does not send additional NTLM authentication challenges, there is a security risk in not requiring all requests to provide authentication information. You must determine whether the increase in performance is worth this risk. + + + +## Examples + The following code example demonstrates setting this property. + + :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet14"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Net_Listener_Basic/VB/test.vb" id="Snippet14"::: + ]]> This object has been closed. diff --git a/xml/System.Numerics/BigInteger.xml b/xml/System.Numerics/BigInteger.xml index e1671967e7c..3beb8f4f0a9 100644 --- a/xml/System.Numerics/BigInteger.xml +++ b/xml/System.Numerics/BigInteger.xml @@ -226,124 +226,7 @@ Represents an arbitrarily large signed integer. - - type is an immutable type that represents an arbitrarily large integer whose value in theory has no upper or lower bounds. The members of the type closely parallel those of other integral types (the , , , , , , , and types). This type differs from the other integral types in the .NET Framework, which have a range indicated by their `MinValue` and `MaxValue` properties. - -> [!NOTE] -> Because the type is immutable (see [Mutability and the BigInteger Structure](#mutability)) and because it has no upper or lower bounds, an can be thrown for any operation that causes a value to grow too large. - -## Instantiating a BigInteger Object - You can instantiate a object in several ways: - -- You can use the `new` keyword and provide any integral or floating-point value as a parameter to the constructor. (Floating-point values are truncated before they are assigned to the .) The following example illustrates how to use the `new` keyword to instantiate values. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Overview/BigInteger_Examples.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet1"::: - -- You can declare a variable and assign it a value just as you would any numeric type, as long as that value is an integral type. The following example uses assignment to create a value from an . - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Overview/BigInteger_Examples.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet2"::: - -- You can assign a decimal or floating-point value to a object if you cast the value or convert it first. The following example explicitly casts (in C#) or converts (in Visual Basic) a and a value to a . - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Overview/BigInteger_Examples.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet3"::: - - These methods enable you to instantiate a object whose value is in the range of one of the existing numeric types only. You can instantiate a object whose value can exceed the range of the existing numeric types in one of three ways: - -- You can use the `new` keyword and provide a byte array of any size to the constructor. For example: - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Overview/BigInteger_Examples.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet4"::: - -- You can call the or methods to convert the string representation of a number to a . For example: - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Overview/BigInteger_Examples.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet5"::: - -- You can call a `static` (`Shared` in Visual Basic) method that performs some operation on a numeric expression and returns a calculated result. The following example does this by cubing and assigning the result to a . - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Overview/BigInteger_Examples.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet6"::: - - The uninitialized value of a is . - -## Performing Operations on BigInteger Values - You can use a instance as you would use any other integral type. overloads the standard numeric operators to enable you to perform basic mathematical operations such as addition, subtraction, division, multiplication, and unary negation. You can also use the standard numeric operators to compare two values with each other. Like the other integral types, also supports the bitwise `And`, `Or`, `XOr`, left shift, and right shift operators. For languages that do not support custom operators, the structure also provides equivalent methods for performing mathematical operations. These include , , , , , and several others. - - Many members of the structure correspond directly to members of the other integral types. In addition, adds members such as the following: - -- , which returns a value that indicates the sign of a value. - -- , which returns the absolute value of a value. - -- , which returns both the quotient and remainder of a division operation. - -- , which returns the greatest common divisor of two values. - - Many of these additional members correspond to the members of the class, which provides the functionality to work with the primitive numeric types. - - -## Mutability and the BigInteger Structure - The following example instantiates a object and then increments its value by one. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Overview/Mutability_Examples.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class.Mutability/vb/Mutability_Examples.vb" id="Snippet1"::: - - Although this example appears to modify the value of the existing object, this is not the case. objects are immutable, which means that internally, the common language runtime actually creates a new object and assigns it a value one greater than its previous value. This new object is then returned to the caller. - -> [!NOTE] -> The other numeric types in .NET are also immutable. However, because the type has no upper or lower bounds, its values can grow extremely large and have a measurable impact on performance. - - Although this process is transparent to the caller, it does incur a performance penalty. In some cases, especially when repeated operations are performed in a loop on very large values, that performance penalty can be significant. For example, in the following example, an operation is performed repetitively up to a million times, and a value is incremented by one every time the operation succeeds. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Overview/Mutability_Examples.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class.Mutability/vb/Mutability_Examples.vb" id="Snippet12"::: - - In such a case, you can improve performance by performing all intermediate assignments to an variable. The final value of the variable can then be assigned to the object when the loop exits. The following example provides an illustration. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Overview/Mutability_Examples.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class.Mutability/vb/Mutability_Examples.vb" id="Snippet3"::: - -## Working with Byte Arrays and Hexadecimal Strings - If you convert values to byte arrays, or if you convert byte arrays to values, you must consider the order of bytes. The structure expects the individual bytes in a byte array to appear in little-endian order (that is, the lower-order bytes of the value precede the higher-order bytes). You can round-trip a value by calling the method and then passing the resulting byte array to the constructor, as the following example shows. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Overview/ByteAndHex_Examples.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class.ByteAndHex/vb/ByteAndHex_Examples.vb" id="Snippet1"::: - - To instantiate a value from a byte array that represents a value of some other integral type, you can pass the integral value to the method, and then pass the resulting byte array to the constructor. The following example instantiates a value from a byte array that represents an value. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Overview/ByteAndHex_Examples.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class.ByteAndHex/vb/ByteAndHex_Examples.vb" id="Snippet2"::: - - The structure assumes that negative values are stored by using two's complement representation. Because the structure represents a numeric value with no fixed length, the constructor always interprets the most significant bit of the last byte in the array as a sign bit. To prevent the constructor from confusing the two's complement representation of a negative value with the sign and magnitude representation of a positive value, positive values in which the most significant bit of the last byte in the byte array would ordinarily be set should include an additional byte whose value is 0. For example, 0xC0 0xBD 0xF0 0xFF is the little-endian hexadecimal representation of either -1,000,000 or 4,293,967,296. Because the most significant bit of the last byte in this array is on, the value of the byte array would be interpreted by the constructor as -1,000,000. To instantiate a whose value is positive, a byte array whose elements are 0xC0 0xBD 0xF0 0xFF 0x00 must be passed to the constructor. The following example illustrates this. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Overview/ByteAndHex_Examples.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class.ByteAndHex/vb/ByteAndHex_Examples.vb" id="Snippet3"::: - - Byte arrays created by the method from positive values include this extra zero-value byte. Therefore, the structure can successfully round-trip values by assigning them to, and then restoring them from, byte arrays, as the following example shows. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Overview/ByteAndHex_Examples.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class.ByteAndHex/vb/ByteAndHex_Examples.vb" id="Snippet4"::: - - However, you may need to add this additional zero-value byte to byte arrays that are created dynamically by the developer or that are returned by methods that convert unsigned integers to byte arrays (such as , , and ). - - When parsing a hexadecimal string, the and methods assume that if the most significant bit of the first byte in the string is set, or if the first hexadecimal digit of the string represents the lower four bits of a byte value, the value is represented by using two's complement representation. For example, both "FF01" and "F01" represent the decimal value -255. To differentiate positive from negative values, positive values should include a leading zero. The relevant overloads of the method, when they are passed the "X" format string, add a leading zero to the returned hexadecimal string for positive values. This makes it possible to round-trip values by using the and methods, as the following example shows. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Overview/ByteAndHex_Examples.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class.ByteAndHex/vb/ByteAndHex_Examples.vb" id="Snippet5"::: - - However, the hexadecimal strings created by calling the `ToString` methods of the other integral types or the overloads of the method that include a `toBase` parameter do not indicate the sign of the value or the source data type from which the hexadecimal string was derived. Successfully instantiating a value from such a string requires some additional logic. The following example provides one possible implementation. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Overview/ByteAndHex_Examples2.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class.ByteAndHex/vb/ByteAndHex_Examples2.vb" id="Snippet6"::: - - ]]> - + For more information about this API, see Supplemental API remarks for BigInteger. @@ -402,48 +285,48 @@ An array of byte values in little-endian order. Initializes a new instance of the structure using the values in a byte array. - and , return byte arrays in little-endian order. - - The constructor expects positive values in the byte array to use sign-and-magnitude representation, and negative values to use two's complement representation. In other words, if the highest-order bit of the highest-order byte in `value` is set, the resulting value is negative. Depending on the source of the byte array, this may cause a positive value to be misinterpreted as a negative value. Byte arrays are typically generated in the following ways: - -- By calling the method. Because this method returns a byte array with the highest-order bit of the highest-order byte in the array set to zero for positive values, there is no chance of misinterpreting a positive value as negative. Unmodified byte arrays created by the method always successfully round-trip when they are passed to the constructor. - -- By calling the method and passing it a signed integer as a parameter. Because signed integers handle both sign-and-magnitude representation and two's complement representation, there is no chance of misinterpreting a positive value as negative. - -- By calling the method and passing it an unsigned integer as a parameter. Because unsigned integers are represented by their magnitude only, positive values can be misinterpreted as negative values. To prevent this misinterpretation, you can add a zero-byte value to the end of the array. The example in the next section provides an illustration. - -- By creating a byte array either dynamically or statically without necessarily calling any of the previous methods, or by modifying an existing byte array. To prevent positive values from being misinterpreted as negative values, you can add a zero-byte value to the end of the array. - - If `value` is an empty array, the new object is initialized to a value of . If `value` is `null`, the constructor throws an . - - - -## Examples - The following example instantiates a object from a 5-element byte array whose value is {5, 4, 3, 2, 1}. It then displays the value, represented as both decimal and hexadecimal numbers, to the console. A comparison of the input array with the text output makes it clear why this overload of the class constructor creates a object whose value is 4328719365 (or 0x102030405). The first element of the byte array, whose value is 5, defines the value of the lowest-order byte of the object, which is 0x05. The second element of the byte array, whose value is 4, defines the value of the second byte of the object, which is 0x04, and so on. - + and , return byte arrays in little-endian order. + + The constructor expects positive values in the byte array to use sign-and-magnitude representation, and negative values to use two's complement representation. In other words, if the highest-order bit of the highest-order byte in `value` is set, the resulting value is negative. Depending on the source of the byte array, this may cause a positive value to be misinterpreted as a negative value. Byte arrays are typically generated in the following ways: + +- By calling the method. Because this method returns a byte array with the highest-order bit of the highest-order byte in the array set to zero for positive values, there is no chance of misinterpreting a positive value as negative. Unmodified byte arrays created by the method always successfully round-trip when they are passed to the constructor. + +- By calling the method and passing it a signed integer as a parameter. Because signed integers handle both sign-and-magnitude representation and two's complement representation, there is no chance of misinterpreting a positive value as negative. + +- By calling the method and passing it an unsigned integer as a parameter. Because unsigned integers are represented by their magnitude only, positive values can be misinterpreted as negative values. To prevent this misinterpretation, you can add a zero-byte value to the end of the array. The example in the next section provides an illustration. + +- By creating a byte array either dynamically or statically without necessarily calling any of the previous methods, or by modifying an existing byte array. To prevent positive values from being misinterpreted as negative values, you can add a zero-byte value to the end of the array. + + If `value` is an empty array, the new object is initialized to a value of . If `value` is `null`, the constructor throws an . + + + +## Examples + The following example instantiates a object from a 5-element byte array whose value is {5, 4, 3, 2, 1}. It then displays the value, represented as both decimal and hexadecimal numbers, to the console. A comparison of the input array with the text output makes it clear why this overload of the class constructor creates a object whose value is 4328719365 (or 0x102030405). The first element of the byte array, whose value is 5, defines the value of the lowest-order byte of the object, which is 0x05. The second element of the byte array, whose value is 4, defines the value of the second byte of the object, which is 0x04, and so on. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/.ctor/Example1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ctors/vb/Example1.vb" id="Snippet1"::: - - The following example instantiates a positive and a negative value, passes them to the method, and then restores the original values from the resulting byte array. Note that the two values are represented by identical byte arrays. The only difference between them is in the most significant bit of the last element in the byte array. This bit is set (the value of the byte is 0xFF) if the array is created from a negative value. The bit is not set (the value of the byte is zero), if the array is created from a positive value. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ctors/vb/Example1.vb" id="Snippet1"::: + + The following example instantiates a positive and a negative value, passes them to the method, and then restores the original values from the resulting byte array. Note that the two values are represented by identical byte arrays. The only difference between them is in the most significant bit of the last element in the byte array. This bit is set (the value of the byte is 0xFF) if the array is created from a negative value. The bit is not set (the value of the byte is zero), if the array is created from a positive value. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/.ctor/Example1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ctors/vb/Example1.vb" id="Snippet2"::: - - The following example illustrates how to make sure that a positive value is not incorrectly instantiated as a negative value by adding a byte whose value is zero to the end of the array. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ctors/vb/Example1.vb" id="Snippet2"::: + + The following example illustrates how to make sure that a positive value is not incorrectly instantiated as a negative value by adding a byte whose value is zero to the end of the array. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/.ctor/Example1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ctors/vb/Example1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ctors/vb/Example1.vb" id="Snippet3"::: + ]]> @@ -487,21 +370,21 @@ A decimal number. Initializes a new instance of the structure using a value. - value to a variable. - - Calling this constructor can cause data loss; any fractional part of `value` is truncated when instantiating a object. - - - -## Examples - The following example illustrates the use of the constructor to instantiate a object. It defines an array of values, and then passes each value to the constructor. Note that the value is truncated instead of rounded when it is assigned to the object. - + value to a variable. + + Calling this constructor can cause data loss; any fractional part of `value` is truncated when instantiating a object. + + + +## Examples + The following example illustrates the use of the constructor to instantiate a object. It defines an array of values, and then passes each value to the constructor. Note that the value is truncated instead of rounded when it is assigned to the object. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/.ctor/Example2.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ctors/vb/Example2.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ctors/vb/Example2.vb" id="Snippet4"::: + ]]> @@ -542,23 +425,23 @@ A double-precision floating-point value. Initializes a new instance of the structure using a double-precision floating-point value. - object. - - Because of the lack of precision of the data type, calling this constructor can cause data loss. - - The value that results from calling this constructor is identical to the value that results from explicitly assigning a value to a . - - - -## Examples - The following example illustrates the use of the constructor to instantiate a object. It also illustrates the loss of precision that may occur when you use the data type. A is assigned a large value, which is then assigned to a object. As the output shows, this assignment involves a loss of precision. Both values are then incremented by one. The output shows that the object reflects the changed value, whereas the object does not. - + object. + + Because of the lack of precision of the data type, calling this constructor can cause data loss. + + The value that results from calling this constructor is identical to the value that results from explicitly assigning a value to a . + + + +## Examples + The following example illustrates the use of the constructor to instantiate a object. It also illustrates the loss of precision that may occur when you use the data type. A is assigned a large value, which is then assigned to a object. As the output shows, this assignment involves a loss of precision. Both values are then incremented by one. The output shows that the object reflects the changed value, whereas the object does not. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/.ctor/Example2.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ctors/vb/Example2.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ctors/vb/Example2.vb" id="Snippet5"::: + ]]> @@ -601,23 +484,23 @@ A 32-bit signed integer. Initializes a new instance of the structure using a 32-bit signed integer value. - object by using this constructor. - - The value that results from calling this constructor is identical to the value that results from assigning an value to a . - - The structure does not include constructors with a parameter of type , , , or . However, the type supports the implicit conversion of 8-bit and 16-bit signed and unsigned integers to signed 32-bit integers. As a result, this constructor is called if `value` is any one of these four integral types. - - - -## Examples - The following example calls the constructor to instantiate values from an array of 32-bit integers. It also uses implicit conversion to assign each 32-bit integer value to a variable. It then compares the two values to establish that the resulting values are the same. - + object by using this constructor. + + The value that results from calling this constructor is identical to the value that results from assigning an value to a . + + The structure does not include constructors with a parameter of type , , , or . However, the type supports the implicit conversion of 8-bit and 16-bit signed and unsigned integers to signed 32-bit integers. As a result, this constructor is called if `value` is any one of these four integral types. + + + +## Examples + The following example calls the constructor to instantiate values from an array of 32-bit integers. It also uses implicit conversion to assign each 32-bit integer value to a variable. It then compares the two values to establish that the resulting values are the same. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/.ctor/Example2.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ctors/vb/Example2.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ctors/vb/Example2.vb" id="Snippet6"::: + ]]> @@ -658,21 +541,21 @@ A 64-bit signed integer. Initializes a new instance of the structure using a 64-bit signed integer value. - object by using this constructor. - - The value that results from calling this constructor is identical to the value that results from assigning an value to a . - - - -## Examples - The following example calls the constructor to instantiate values from an array of 64-bit integers. It also uses implicit conversion to assign each 64-bit integer value to a variable. It then compares the two values to establish that the resulting values are the same. - + object by using this constructor. + + The value that results from calling this constructor is identical to the value that results from assigning an value to a . + + + +## Examples + The following example calls the constructor to instantiate values from an array of 64-bit integers. It also uses implicit conversion to assign each 64-bit integer value to a variable. It then compares the two values to establish that the resulting values are the same. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/.ctor/Example2.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ctors/vb/Example2.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ctors/vb/Example2.vb" id="Snippet7"::: + ]]> @@ -713,23 +596,23 @@ A single-precision floating-point value. Initializes a new instance of the structure using a single-precision floating-point value. - object. - - Because of the lack of precision of the data type, calling this constructor can result in data loss. - - The value that results from calling this constructor is identical to the value that results from explicitly assigning a value to a . - - - -## Examples - The following example illustrates the use of the constructor to instantiate a object. It also illustrates the loss of precision that may occur when you use the data type. A is assigned a large negative value, which is then assigned to a object. As the output shows, this assignment involves a loss of precision. Both values are then incremented by one. The output shows that the object reflects the changed value, whereas the object does not. - + object. + + Because of the lack of precision of the data type, calling this constructor can result in data loss. + + The value that results from calling this constructor is identical to the value that results from explicitly assigning a value to a . + + + +## Examples + The following example illustrates the use of the constructor to instantiate a object. It also illustrates the loss of precision that may occur when you use the data type. A is assigned a large negative value, which is then assigned to a object. As the output shows, this assignment involves a loss of precision. Both values are then incremented by one. The output shows that the object reflects the changed value, whereas the object does not. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/.ctor/Example2.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ctors/vb/Example2.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ctors/vb/Example2.vb" id="Snippet8"::: + ]]> @@ -778,21 +661,21 @@ An unsigned 32-bit integer value. Initializes a new instance of the structure using an unsigned 32-bit integer value. - using this constructor. - - The value that results from calling this constructor is identical to the value that results from assigning a value to a . - - - -## Examples - The following example uses the constructor and an assignment statement to initialize values from an array of unsigned 32-bit integers. It then compares the two values to demonstrate that the two methods of initializing a value produce identical results. - + using this constructor. + + The value that results from calling this constructor is identical to the value that results from assigning a value to a . + + + +## Examples + The following example uses the constructor and an assignment statement to initialize values from an array of unsigned 32-bit integers. It then compares the two values to demonstrate that the two methods of initializing a value produce identical results. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/.ctor/Example2.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ctors/vb/Example2.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ctors/vb/Example2.vb" id="Snippet9"::: + ]]> @@ -840,21 +723,21 @@ An unsigned 64-bit integer. Initializes a new instance of the structure with an unsigned 64-bit integer value. - using this constructor. - - The value that results from calling this constructor is identical to the value that results from assigning a value to a . - - - -## Examples - The following example uses the constructor to instantiate a object whose value is equal to . - + using this constructor. + + The value that results from calling this constructor is identical to the value that results from assigning a value to a . + + + +## Examples + The following example uses the constructor to instantiate a object whose value is equal to . + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/.ctor/Example2.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ctors/vb/Example2.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ctors/vb/Example2.vb" id="Snippet10"::: + ]]> @@ -942,18 +825,18 @@ Gets the absolute value of a object. The absolute value of . - = 0|`value`| -|`value` < 0|`value` * -1| - + = 0|`value`| +|`value` < 0|`value` * -1| + The method is equivalent to the method for the primitive numeric types. - + ]]> @@ -1007,16 +890,16 @@ Adds two values and returns the result. The sum of and . - method to perform addition using values. - - The method is a useful substitute for the addition operator when instantiating a variable by assigning it a sum that results from addition, as shown in the following example. - + method to perform addition using values. + + The method is a useful substitute for the addition operator when instantiating a variable by assigning it a sum that results from addition, as shown in the following example. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Add/Multiply1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.OperationMethods/vb/Multiply1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.OperationMethods/vb/Multiply1.vb" id="Snippet2"::: + ]]> @@ -1102,34 +985,34 @@ The first value to compare. The second value to compare. Compares two values and returns an integer that indicates whether the first value is less than, equal to, or greater than the second value. - A signed integer that indicates the relative values of and , as shown in the following table. - - Value - - Condition - - Less than zero - - is less than . - - Zero - - equals . - - Greater than zero - - is greater than . - + A signed integer that indicates the relative values of and , as shown in the following table. + + Value + + Condition + + Less than zero + + is less than . + + Zero + + equals . + + Greater than zero + + is greater than . + - type has no fixed range, comparisons of values are not characterized by the lack of precision that characterizes the comparison of floating-point numbers. The following example compares two values that differ by one and that each have 1,896 digits. The method correctly reports that the two values are not equal. - + type has no fixed range, comparisons of values are not characterized by the lack of precision that characterizes the comparison of floating-point numbers. The following example compares two values that differ by one and that each have 1,896 digits. The method correctly reports that the two values are not equal. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Compare/Compare1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Compare/vb/Compare1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Compare/vb/Compare1.vb" id="Snippet1"::: + ]]> @@ -1183,39 +1066,39 @@ The signed 64-bit integer to compare. Compares this instance to a signed 64-bit integer and returns an integer that indicates whether the value of this instance is less than, equal to, or greater than the value of the signed 64-bit integer. - A signed integer value that indicates the relationship of this instance to , as shown in the following table. - - Return value - - Description - - Less than zero - - The current instance is less than . - - Zero - - The current instance equals . - - Greater than zero - - The current instance is greater than . - + A signed integer value that indicates the relationship of this instance to , as shown in the following table. + + Return value + + Description + + Less than zero + + The current instance is less than . + + Zero + + The current instance equals . + + Greater than zero + + The current instance is greater than . + - , , , , , or value, it is implicitly converted to an value when the method is called. - - - -## Examples - The following example illustrates the result of calling the method with integral values. - + , , , , , or value, it is implicitly converted to an value when the method is called. + + + +## Examples + The following example illustrates the result of calling the method with integral values. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/CompareTo/Example2.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.CompareTo/vb/Example2.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.CompareTo/vb/Example2.vb" id="Snippet3"::: + ]]> @@ -1261,44 +1144,44 @@ The object to compare. Compares this instance to a second and returns an integer that indicates whether the value of this instance is less than, equal to, or greater than the value of the specified object. - A signed integer value that indicates the relationship of this instance to , as shown in the following table. - - Return value - - Description - - Less than zero - - The current instance is less than . - - Zero - - The current instance equals . - - Greater than zero - - The current instance is greater than . - + A signed integer value that indicates the relationship of this instance to , as shown in the following table. + + Return value + + Description + + Less than zero + + The current instance is less than . + + Zero + + The current instance equals . + + Greater than zero + + The current instance is greater than . + - method implements the method. It is used by generic collection objects to order the items in the collection. - - - -## Examples - The following example illustrates the use of the method to order a list of `StarInfo` objects. Each `StarInfo` object provides information about a star's name and its distance from the Earth in miles. `StarInfo` implements the interface, which enables `StarInfo` objects to be sorted by generic collection classes. Its implementation just wraps a call to . - + method implements the method. It is used by generic collection objects to order the items in the collection. + + + +## Examples + The following example illustrates the use of the method to order a list of `StarInfo` objects. Each `StarInfo` object provides information about a star's name and its distance from the Earth in miles. `StarInfo` implements the interface, which enables `StarInfo` objects to be sorted by generic collection classes. Its implementation just wraps a call to . + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/CompareTo/Example1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.CompareTo/vb/Example1.vb" id="Snippet1"::: - - The following code then instantiates four `StarInfo` objects and stores them in a generic object. After the method is called, `StarInfo` objects are displayed in order of their distance from the Earth. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.CompareTo/vb/Example1.vb" id="Snippet1"::: + + The following code then instantiates four `StarInfo` objects and stores them in a generic object. After the method is called, `StarInfo` objects are displayed in order of their distance from the Earth. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/CompareTo/Example1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.CompareTo/vb/Example1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.CompareTo/vb/Example1.vb" id="Snippet2"::: + ]]> @@ -1353,45 +1236,45 @@ The object to compare. Compares this instance to a specified object and returns an integer that indicates whether the value of this instance is less than, equal to, or greater than the value of the specified object. - A signed integer that indicates the relationship of the current instance to the parameter, as shown in the following table. - - Return value - - Description - - Less than zero - - The current instance is less than . - - Zero - - The current instance equals . - - Greater than zero - - The current instance is greater than , or the parameter is . - + A signed integer that indicates the relationship of the current instance to the parameter, as shown in the following table. + + Return value + + Description + + Less than zero + + The current instance is less than . + + Zero + + The current instance equals . + + Greater than zero + + The current instance is greater than , or the parameter is . + - method implements the method. It is used by non-generic collection objects to order the items in the collection. - - The `obj` parameter must be one of the following: - -- An object whose run-time type is . - -- An variable whose value is `null`. If the value of the `obj` parameter is `null`, the method returns 1, which indicates that the current instance is greater than `obj`. - - - -## Examples - The following example calls the method to compare a value with each element in an object array: - + method implements the method. It is used by non-generic collection objects to order the items in the collection. + + The `obj` parameter must be one of the following: + +- An object whose run-time type is . + +- An variable whose value is `null`. If the value of the `obj` parameter is `null`, the method returns 1, which indicates that the current instance is greater than `obj`. + + + +## Examples + The following example calls the method to compare a value with each element in an object array: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/CompareTo/Example2.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.CompareTo/vb/Example2.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.CompareTo/vb/Example2.vb" id="Snippet4"::: + ]]> @@ -1702,21 +1585,21 @@ Divides one value by another and returns the result. The quotient of the division. - method performs integer division; any remainder that results from the division is discarded. To perform integer division while preserving the remainder, call the method. To retrieve only the remainder, call the method. - - The method can be used by languages that do not support operator overloading. Its behavior is identical to division using the division operator. - - - -## Examples - The following example creates an array of values. It then uses each element as the quotient in a division operation that uses the method, the division operator (/), and the method. - + method performs integer division; any remainder that results from the division is discarded. To perform integer division while preserving the remainder, call the method. To retrieve only the remainder, call the method. + + The method can be used by languages that do not support operator overloading. Its behavior is identical to division using the division operator. + + + +## Examples + The following example creates an array of values. It then uses each element as the quotient in a division operation that uses the method, the division operator (/), and the method. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Divide/Divide1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Divide/vb/Divide1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Divide/vb/Divide1.vb" id="Snippet1"::: + ]]> @@ -1814,23 +1697,23 @@ Divides one value by another, returns the result, and returns the remainder in an output parameter. The quotient of the division. - method or the division operator; if you are only interested in the remainder, use the method. - - The sign of the returned `remainder` value is the same as the sign of the `dividend` parameter. - - The behavior of the method is identical to that of the method. - - - -## Examples - The following example creates an array of values. It then uses each element as the quotient in a division operation that uses the method, the division operator (/), and the method. - + method or the division operator; if you are only interested in the remainder, use the method. + + The sign of the returned `remainder` value is the same as the sign of the `dividend` parameter. + + The behavior of the method is identical to that of the method. + + + +## Examples + The following example creates an array of values. It then uses each element as the quotient in a division operation that uses the method, the division operator (/), and the method. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Divide/Divide1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Divide/vb/Divide1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Divide/vb/Divide1.vb" id="Snippet1"::: + ]]> @@ -1888,22 +1771,22 @@ if the signed 64-bit integer and the current instance have the same value; otherwise, . - , , , , , or value, it is implicitly converted to an value when the method is called. - - To determine the relationship between the two objects instead of just testing for equality, call the method. - - - -## Examples - The following example instantiates a object from each integral type except . It then calls the method to compare the value with the original integer value that was passed to the constructor. As the output shows, the values are equal in each case. - + , , , , , or value, it is implicitly converted to an value when the method is called. + + To determine the relationship between the two objects instead of just testing for equality, call the method. + + + +## Examples + The following example instantiates a object from each integral type except . It then calls the method to compare the value with the original integer value that was passed to the constructor. As the output shows, the values are equal in each case. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Equals/cpp/equals.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Equals/EqualsExample1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Equals/vb/EqualsExample1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Equals/vb/EqualsExample1.vb" id="Snippet1"::: + ]]> @@ -1952,22 +1835,22 @@ if this object and have the same value; otherwise, . - interface and performs slightly better than because it does not have to convert the `other` parameter to a object. - - To determine the relationship between the two objects instead of just testing for equality, call the method. - - - -## Examples - The following example compares the approximate distance of several stars from Earth with the distance of Epsilon Indi from Earth to determine whether they are equal. The example uses each overload of the method to test for equality. - + interface and performs slightly better than because it does not have to convert the `other` parameter to a object. + + To determine the relationship between the two objects instead of just testing for equality, call the method. + + + +## Examples + The following example compares the approximate distance of several stars from Earth with the distance of Epsilon Indi from Earth to determine whether they are equal. The example uses each overload of the method to test for equality. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Equals/cpp/equals2.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Equals/EqualsExample1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Equals/vb/EqualsExample1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Equals/vb/EqualsExample1.vb" id="Snippet2"::: + ]]> @@ -2027,21 +1910,21 @@ if the argument is a object, and its value is equal to the value of the current instance; otherwise, . - value, the method returns `false`. The method returns `true` only if `obj` is a instance whose value is equal to the current instance. - - To determine the relationship between the two objects instead of just testing for equality, call the method. - - - -## Examples - The following example defines parallel and arrays. Each element of one array has the same value as the corresponding element of the second array. As the output from the example shows, the instance in the array is considered to be equal to the instance in the array only if the latter is a and their values are equal. - + value, the method returns `false`. The method returns `true` only if `obj` is a instance whose value is equal to the current instance. + + To determine the relationship between the two objects instead of just testing for equality, call the method. + + + +## Examples + The following example defines parallel and arrays. Each element of one array has the same value as the corresponding element of the second array. As the output from the example shows, the instance in the array is considered to be equal to the instance in the array only if the latter is a and their values are equal. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Equals/Equals_Obj1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Equals/vb/Equals_Obj1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Equals/vb/Equals_Obj1.vb" id="Snippet3"::: + ]]> @@ -2093,20 +1976,20 @@ if the current instance and the unsigned 64-bit integer have the same value; otherwise, . - method. - - - -## Examples - The following example compares the approximate distance of several stars from Earth with the distance of Epsilon Indi from Earth to determine whether they are equal. The example uses each overload of the method to test for equality. - + method. + + + +## Examples + The following example compares the approximate distance of several stars from Earth with the distance of Epsilon Indi from Earth to determine whether they are equal. The example uses each overload of the method to test for equality. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Equals/cpp/equals2.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Equals/EqualsExample1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Equals/vb/EqualsExample1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Equals/vb/EqualsExample1.vb" id="Snippet2"::: + ]]> @@ -2268,26 +2151,26 @@ This method returns 0 if the value of current object is equal to Finds the greatest common divisor of two values. The greatest common divisor of and . - values can be divided without returning a remainder. - - If the `left` and `right` parameters are non-zero numbers, the method always returns at least a value of 1 because all numbers can be divided by 1. If either parameter is zero, the method returns the absolute value of the non-zero parameter. If both values are zero, the method returns zero. - + values can be divided without returning a remainder. + + If the `left` and `right` parameters are non-zero numbers, the method always returns at least a value of 1 because all numbers can be divided by 1. If either parameter is zero, the method returns the absolute value of the non-zero parameter. If both values are zero, the method returns zero. + > [!NOTE] -> Computing the greatest common divisor of very large values of `left` and `right` can be a very time-consuming operation. - - The value returned by the method is always positive regardless of the sign of the `left` and `right` parameters. - - - -## Examples - The following example illustrates a call to the method and the exception handling necessary to provide useful information about an . The result indicates that the greatest common divisor of these two numbers is 1. - +> Computing the greatest common divisor of very large values of `left` and `right` can be a very time-consuming operation. + + The value returned by the method is always positive regardless of the sign of the `left` and `right` parameters. + + + +## Examples + The following example illustrates a call to the method and the exception handling necessary to provide useful information about an . The result indicates that the greatest common divisor of these two numbers is 1. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/GreatestCommonDivisor/BigInteger_Examples.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet10"::: + ]]> @@ -2329,21 +2212,21 @@ This method returns 0 if the value of current object is equal to if the value of the object is an even number; otherwise, . - value is evenly divisible by two. It is equivalent to the following expression: - -```csharp -value % 2 == 0; -``` - -```vb -value Mod 2 = 0 -``` - - If the value of the current object is , the property returns `true`. - + value is evenly divisible by two. It is equivalent to the following expression: + +```csharp +value % 2 == 0; +``` + +```vb +value Mod 2 = 0 +``` + + If the value of the current object is , the property returns `true`. + ]]> @@ -2524,11 +2407,11 @@ A return value of `false` does not imply that if the value of the object is ; otherwise, . - @@ -2653,11 +2536,11 @@ A return value of `false` does not imply that if the value of the object is a power of two; otherwise, . - value has a single non-zero bit set. This means that it returns `true` if the value of the current object is 1 (that is, 20) or any greater power of two. It returns `false` if the value of the current object is 0. - + value has a single non-zero bit set. This means that it returns `true` if the value of the current object is 1 (that is, 20) or any greater power of two. It returns `false` if the value of the current object is 0. + ]]> @@ -2699,11 +2582,11 @@ A return value of `false` does not imply that if the value of the object is ; otherwise, . - @@ -2801,28 +2684,28 @@ A return value of `false` does not imply that Returns the natural (base ) logarithm of a specified number. The natural (base ) logarithm of , as shown in the table in the Remarks section. - .| -|Negative|.| - - To calculate the base 10 logarithm of a value, call the method. To calculate the logarithm of a number in another base, call the method. - - You can find the square root of a number by calling the method along with the method. Note that the result is if the result is greater than . The following example calculates the square root of each element in an array of values. - + .| +|Negative|.| + + To calculate the base 10 logarithm of a value, call the method. To calculate the logarithm of a number in another base, call the method. + + You can find the square root of a number by calling the method along with the method. Note that the result is if the result is greater than . The following example calculates the square root of each element in an array of values. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/LogMethod/log1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.biginteger.log/vb/log1.vb" id="Snippet1"::: - - This method corresponds to the method for the primitive numeric types. - + + This method corresponds to the method for the primitive numeric types. + ]]> The natural log of is out of range of the data type. @@ -2871,31 +2754,31 @@ A return value of `false` does not imply that Returns the logarithm of a specified number in a specified base. The base logarithm of , as shown in the table in the Remarks section. - 0|(0 < `baseValue` < 1) -or-(`baseValue` > 1)|logbaseValue(`value`)| -|`value` < 0|(any value)|| -|(any value)|`baseValue` < 0|| -|`value` != 1|`baseValue` = 0|| -|`value` != 1|`baseValue` = || -|(any value)|`baseValue` = || -|(any value)|`baseValue` = 1|| -|`value` = 0|0 < `baseValue` < 1|| -|`value` = 0|`baseValue` > 1|| -|`value` = 1|`baseValue` = 0|0| -|`value` = 1|`baseValue` = |0| - - To calculate the base 10 logarithm of a value, call the method. To calculate the natural logarithm of a number, call the method. - - This method corresponds to the method for the primitive numeric types. - + 0|(0 < `baseValue` < 1) -or-(`baseValue` > 1)|logbaseValue(`value`)| +|`value` < 0|(any value)|| +|(any value)|`baseValue` < 0|| +|`value` != 1|`baseValue` = 0|| +|`value` != 1|`baseValue` = || +|(any value)|`baseValue` = || +|(any value)|`baseValue` = 1|| +|`value` = 0|0 < `baseValue` < 1|| +|`value` = 0|`baseValue` > 1|| +|`value` = 1|`baseValue` = 0|0| +|`value` = 1|`baseValue` = |0| + + To calculate the base 10 logarithm of a value, call the method. To calculate the natural logarithm of a number, call the method. + + This method corresponds to the method for the primitive numeric types. + ]]> The log of is out of range of the data type. @@ -2948,23 +2831,23 @@ A return value of `false` does not imply that Returns the base 10 logarithm of a specified number. The base 10 logarithm of , as shown in the table in the Remarks section. - .| -|Negative|.| - - To calculate the natural logarithm of a value, call the method. To calculate the logarithm of a number in another base, call the method. - - This method corresponds to the method for the primitive numeric types. - + .| +|Negative|.| + + To calculate the natural logarithm of a value, call the method. To calculate the logarithm of a number in another base, call the method. + + This method corresponds to the method for the primitive numeric types. + ]]> The base 10 log of is out of range of the data type. @@ -3052,19 +2935,19 @@ A return value of `false` does not imply that Returns the larger of two values. The or parameter, whichever is larger. - method for primitive numeric types. - - - -## Examples - The following example uses the method to select the largest number in an array of values. - + method for primitive numeric types. + + + +## Examples + The following example uses the method to select the largest number in an array of values. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Max/Max1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Max/vb/Max1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Max/vb/Max1.vb" id="Snippet1"::: + ]]> @@ -3163,19 +3046,19 @@ For this method matches the IEE Returns the smaller of two values. The or parameter, whichever is smaller. - method for primitive numeric types. - - - -## Examples - The following example uses the method to select the smallest number in an array of values. - + method for primitive numeric types. + + + +## Examples + The following example uses the method to select the smallest number in an array of values. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Min/Min1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Min/vb/Min1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Min/vb/Min1.vb" id="Snippet1"::: + ]]> @@ -3270,11 +3153,11 @@ For this method matches the IEE Gets a value that represents the number negative one (-1). An integer whose value is negative one (-1). - property is used to compare a value to -1 or to assign -1 to a object. - + property is used to compare a value to -1 or to assign -1 to a object. + ]]> @@ -3325,20 +3208,20 @@ For this method matches the IEE Performs modulus division on a number raised to the power of another number. The remainder after dividing exponent by . - method evaluates the following expression: - - (baseValue ^ exponent) Mod modulus - - To perform exponentiation on values without modulus division, use the method. - - - -## Examples - The following example provides a simple illustration of calling the method. - + method evaluates the following expression: + + (baseValue ^ exponent) Mod modulus + + To perform exponentiation on values without modulus division, use the method. + + + +## Examples + The following example provides a simple illustration of calling the method. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/ModPow/ModPow1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ModPow/vb/ModPow1.vb" id="Snippet1"::: @@ -3399,24 +3282,24 @@ For this method matches the IEE Returns the product of two values. The product of the and parameters. - method is implemented for languages that do not support operator overloading. Its behavior is identical to multiplication using the multiplication operator. In addition, the method is a useful substitute for the multiplication operator when instantiating a variable by assigning it a product that results from multiplication, as shown in the following example. - + method is implemented for languages that do not support operator overloading. Its behavior is identical to multiplication using the multiplication operator. In addition, the method is a useful substitute for the multiplication operator when instantiating a variable by assigning it a product that results from multiplication, as shown in the following example. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Add/Multiply1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.OperationMethods/vb/Multiply1.vb" id="Snippet1"::: - - If necessary, this method automatically performs implicit conversion of other integral types to objects. This is illustrated in the example in the next section, where the method is passed two values. - - - -## Examples - The following example tries to perform multiplication with two long integers. Because the result exceeds the range of a long integer, an is thrown, and the method is called to handle the multiplication. Note that C# requires that you use either the `checked` keyword (as in this example) or the `/checked+` compiler option to make sure an exception is thrown on a numeric overflow. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.OperationMethods/vb/Multiply1.vb" id="Snippet1"::: + + If necessary, this method automatically performs implicit conversion of other integral types to objects. This is illustrated in the example in the next section, where the method is passed two values. + + + +## Examples + The following example tries to perform multiplication with two long integers. Because the result exceeds the range of a long integer, an is thrown, and the method is called to handle the multiplication. Note that C# requires that you use either the `checked` keyword (as in this example) or the `/checked+` compiler option to make sure an exception is thrown on a numeric overflow. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/GreatestCommonDivisor/BigInteger_Examples.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet7"::: + ]]> @@ -3468,24 +3351,24 @@ For this method matches the IEE Negates a specified value. The result of the parameter multiplied by negative one (-1). - method is implemented for languages that do not support custom operators. Its behavior is identical to negation using the unary negation operator. In addition, the method is a useful substitute for the negation operator when instantiating a variable, as shown in the following example. - + method is implemented for languages that do not support custom operators. Its behavior is identical to negation using the unary negation operator. In addition, the method is a useful substitute for the negation operator when instantiating a variable, as shown in the following example. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Add/Multiply1.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.OperationMethods/vb/Multiply1.vb" id="Snippet4"::: - - - -## Examples - The following example illustrates three ways to negate the value of a object. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.OperationMethods/vb/Multiply1.vb" id="Snippet4"::: + + + +## Examples + The following example illustrates three ways to negate the value of a object. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/GreatestCommonDivisor/BigInteger_Examples.cs" id="Snippet16"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet16"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet16"::: + ]]> @@ -3537,11 +3420,11 @@ For this method matches the IEE Gets a value that represents the number one (1). An object whose value is one (1). - property is usually used to compare a value to 1 or to assign 1 to a object. - + property is usually used to compare a value to 1 or to assign 1 to a object. + ]]> @@ -3594,16 +3477,16 @@ For this method matches the IEE Adds the values of two specified objects. The sum of and . - method defines the addition operation for values. It enables code such as the following: - + method defines the addition operation for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/GreatestCommonDivisor/BigInteger_Examples.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet12"::: - - Languages that do not support custom operators can call the method instead. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet12"::: + + Languages that do not support custom operators can call the method instead. + ]]> @@ -3655,25 +3538,25 @@ For this method matches the IEE Performs a bitwise operation on two values. The result of the bitwise operation. - method defines the bitwise `And` operation for values. The bitwise `And` operation sets a result bit only if the corresponding bits in `left` and `right` are also set, as shown in the following table. - -|Bit in `left`|Bit in `right`|Bit in result| -|-------------------|--------------------|-------------------| -|0|0|0| -|1|0|0| -|1|1|1| -|0|1|0| - - The method enables code such as the following: - + method defines the bitwise `And` operation for values. The bitwise `And` operation sets a result bit only if the corresponding bits in `left` and `right` are also set, as shown in the following table. + +|Bit in `left`|Bit in `right`|Bit in result| +|-------------------|--------------------|-------------------| +|0|0|0| +|1|0|0| +|1|1|1| +|0|1|0| + + The method enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet1"::: - - The method performs the bitwise `And` operation on two values as if they were both in two's complement representation with virtual sign extension. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet1"::: + + The method performs the bitwise `And` operation on two values as if they were both in two's complement representation with virtual sign extension. + ]]> @@ -3724,25 +3607,25 @@ For this method matches the IEE Performs a bitwise operation on two values. The result of the bitwise operation. - method defines the bitwise `Or` operation for values. The bitwise `Or` operation sets a result bit only if either or both of the corresponding bits in `left` and `right` are set, as shown in the following table. - -|Bit in `left`|Bit in `right`|Bit in result| -|-------------------|--------------------|-------------------| -|0|0|0| -|1|0|1| -|1|1|1| -|0|1|1| - - The method enables code such as the following: - + method defines the bitwise `Or` operation for values. The bitwise `Or` operation sets a result bit only if either or both of the corresponding bits in `left` and `right` are set, as shown in the following table. + +|Bit in `left`|Bit in `right`|Bit in result| +|-------------------|--------------------|-------------------| +|0|0|0| +|1|0|1| +|1|1|1| +|0|1|1| + + The method enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet2"::: - - The method performs the bitwise `Or` operation on two values as if they were both in two's complement representation with virtual sign extension. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet2"::: + + The method performs the bitwise `Or` operation on two values as if they were both in two's complement representation with virtual sign extension. + ]]> @@ -3791,20 +3674,20 @@ For this method matches the IEE Decrements a value by 1. The value of the parameter decremented by 1. - method defines the decrement operation for values. It enables code such as the following: - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/GreatestCommonDivisor/BigInteger_Examples.cs" id="Snippet17"::: - - Languages that do not support custom operators can call the method instead. For example: - + method defines the decrement operation for values. It enables code such as the following: + + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/GreatestCommonDivisor/BigInteger_Examples.cs" id="Snippet17"::: + + Languages that do not support custom operators can call the method instead. For example: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet3"::: - - Because objects are immutable, the operator creates a new object whose value is one less than the object represented by `value`. This means that repeated calls to may be expensive. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet3"::: + + Because objects are immutable, the operator creates a new object whose value is one less than the object represented by `value`. This means that repeated calls to may be expensive. + The equivalent method for this operator is .]]> @@ -3856,24 +3739,24 @@ For this method matches the IEE Divides a specified value by another specified value by using integer division. The integral result of the division. - method defines the division operation for values. It enables code such as the following: - + method defines the division operation for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/GreatestCommonDivisor/BigInteger_Examples.cs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet13"::: - - Languages that do not support custom operators and operator overloading can call the method instead. - - The equivalent method for this operator is - -## Examples - The following example creates an array of values. It then uses each element as the quotient in a division operation that uses the method, the division operator (/), and the method. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet13"::: + + Languages that do not support custom operators and operator overloading can call the method instead. + + The equivalent method for this operator is + +## Examples + The following example creates an array of values. It then uses each element as the quotient in a division operation that uses the method, the division operator (/), and the method. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Divide/Divide1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Divide/vb/Divide1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Divide/vb/Divide1.vb" id="Snippet1"::: + ]]> @@ -3934,18 +3817,18 @@ For this method matches the IEE if the and parameters have the same value; otherwise, . - method defines the equality comparison operation for values. It enables code such as the following: - + method defines the equality comparison operation for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet4"::: - - Languages that do not support custom operators can call the instance method instead. - - If `left` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet4"::: + + Languages that do not support custom operators can call the instance method instead. + + If `left` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. + The equivalent method for this operator is .]]> @@ -3994,18 +3877,18 @@ For this method matches the IEE if the and parameters have the same value; otherwise, . - method defines the equality comparison operation for values. It enables code such as the following: - + method defines the equality comparison operation for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet5"::: - - Languages that do not support custom operators can call the instance method instead. - - If `right` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet5"::: + + Languages that do not support custom operators can call the instance method instead. + + If `right` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. + The equivalent method for this operator is .]]> @@ -4058,16 +3941,16 @@ For this method matches the IEE if the and parameters have the same value; otherwise, . - method defines the operation of the equality operator for values. It enables code such as the following: - + method defines the operation of the equality operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/GreatestCommonDivisor/BigInteger_Examples.cs" id="Snippet19"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet19"::: - - Languages that do not support custom operators can call the instance method instead. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet19"::: + + Languages that do not support custom operators can call the instance method instead. + The equivalent method for this operator is .]]> @@ -4123,16 +4006,16 @@ For this method matches the IEE if the and parameters have the same value; otherwise, . - method defines the equality comparison operation for values. It enables code such as the following: - + method defines the equality comparison operation for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet6"::: - - Languages that do not support custom operators can call the instance method instead. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet6"::: + + Languages that do not support custom operators can call the instance method instead. + ]]> @@ -4187,16 +4070,16 @@ For this method matches the IEE if the and parameters have the same value; otherwise, . - method defines the equality comparison operation for values. It enables code such as the following: - + method defines the equality comparison operation for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet7"::: - - Languages that do not support custom operators can call the instance method instead. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet7"::: + + Languages that do not support custom operators can call the instance method instead. + ]]> @@ -4248,25 +4131,25 @@ For this method matches the IEE Performs a bitwise exclusive () operation on two values. The result of the bitwise operation. - method enables code such as the following: - + method enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet8"::: - - The method performs the bitwise exclusive `Or` operation on two values as if they were both in two's complement representation with virtual sign extension. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet8"::: + + The method performs the bitwise exclusive `Or` operation on two values as if they were both in two's complement representation with virtual sign extension. + ]]> @@ -4321,21 +4204,21 @@ For this method matches the IEE Defines an explicit conversion of a object to a value. An object that contains the value of the parameter. - method define the types to which or from which a object can be converted. Because the conversion from to can involve truncating any fractional part of `value`, language compilers do not perform this conversion automatically. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` in Visual Basic) is used. Otherwise, they display a compiler error. + The overloads of the method define the types to which or from which a object can be converted. Because the conversion from to can involve truncating any fractional part of `value`, language compilers do not perform this conversion automatically. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` in Visual Basic) is used. Otherwise, they display a compiler error. For languages that do not support custom operators, the alternative method is . ## Examples - The following example converts the individual elements in an array of values to objects, and then displays the result of each conversion. Note that any fractional part of a value is truncated during the conversion. + The following example converts the individual elements in an array of values to objects, and then displays the result of each conversion. Note that any fractional part of a value is truncated during the conversion. - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/Explicit1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Explicit/vb/Explicit1.vb" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/Explicit1.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Explicit/vb/Explicit1.vb" id="Snippet1"::: ]]> @@ -4381,9 +4264,9 @@ For this method matches the IEE Defines an explicit conversion of a value to a value. An object that contains the value of the parameter. - method define the types to which or from which a object can be converted. Because the conversion from to can involve truncating any fractional part of `value`, language compilers do not perform this conversion automatically. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` in Visual Basic) is used. Otherwise, they display a compiler error. @@ -4392,10 +4275,10 @@ For this method matches the IEE ## Examples - The following example converts the individual elements in an array of values to objects, and then displays the result of each conversion. Note that any fractional part of a value is truncated during the conversion. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/Explicit1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Explicit/vb/Explicit1.vb" id="Snippet2"::: + The following example converts the individual elements in an array of values to objects, and then displays the result of each conversion. Note that any fractional part of a value is truncated during the conversion. + + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/Explicit1.cs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Explicit/vb/Explicit1.vb" id="Snippet2"::: ]]> @@ -4476,18 +4359,18 @@ For this method matches the IEE Defines an explicit conversion of a object to an unsigned byte value. An object that contains the value of the parameter. - method define the types to which or from which a object can be converted. Language compilers do not perform this conversion automatically because it can involve data loss. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` or `CByte` in Visual Basic) is used. Otherwise, they display a compiler error. + method define the types to which or from which a object can be converted. Language compilers do not perform this conversion automatically because it can involve data loss. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` or `CByte` in Visual Basic) is used. Otherwise, they display a compiler error. Because this operation defines a narrowing conversion, it can throw an at run time if the value is outside the range of the data type. There is no loss of precision in the resulting value if the conversion is successful. ## Examples - The following example illustrates the conversion of to values. It also handles an that is thrown because the value is outside the range of the data type. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/System.Numeric.BigInteger.Explicit.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Explicit/vb/System.Numeric.BigInteger.Explicit.vb" id="Snippet1"::: + The following example illustrates the conversion of to values. It also handles an that is thrown because the value is outside the range of the data type. + + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/System.Numeric.BigInteger.Explicit.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Explicit/vb/System.Numeric.BigInteger.Explicit.vb" id="Snippet1"::: ]]> @@ -4568,18 +4451,18 @@ For this method matches the IEE Defines an explicit conversion of a object to a value. An object that contains the value of the parameter. - method define the types to which or from which a object can be converted. Language compilers do not perform this conversion automatically because it can involve data loss. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` or `CDec` in Visual Basic) is used. + method define the types to which or from which a object can be converted. Language compilers do not perform this conversion automatically because it can involve data loss. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` or `CDec` in Visual Basic) is used. - Because this operation defines a narrowing conversion, it can throw an at run time if the value is outside the range of the data type. + Because this operation defines a narrowing conversion, it can throw an at run time if the value is outside the range of the data type. ## Examples - The following example illustrates the conversion of to values. It also handles an that is thrown because the value is outside the range of the data type. - + The following example illustrates the conversion of to values. It also handles an that is thrown because the value is outside the range of the data type. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/System.Numeric.BigInteger.Explicit.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Explicit/vb/System.Numeric.BigInteger.Explicit.vb" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Explicit/vb/System.Numeric.BigInteger.Explicit.vb" id="Snippet2"::: ]]> @@ -4627,25 +4510,25 @@ For this method matches the IEE Defines an explicit conversion of a object to a value. An object that contains the value of the parameter. - method define the types to which or from which a object can be converted. Language compilers do not perform this conversion automatically because it can involve data loss. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` or `CDbl` in Visual Basic) is used. + method define the types to which or from which a object can be converted. Language compilers do not perform this conversion automatically because it can involve data loss. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` or `CDbl` in Visual Basic) is used. Because the value can be outside the range of the data type, this operation is a narrowing conversion. If the conversion is unsuccessful, it does not throw an . Instead, if the value is less than , the resulting value is . If the value is greater than , the resulting value is . - - The conversion of a to a may involve a loss of precision. In some cases, the loss of precision may cause the casting or conversion operation to succeed even if the value is outside the range of the data type. The following example provides an illustration. It assigns the maximum value of a to two variables, increments one variable by 9.999e291, and tests the two variables for equality. As expected, the call to the method shows that they are unequal. However, the conversion of the larger value back to a succeeds, although the value now exceeds . - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/Explicit1.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Explicit/vb/Explicit1.vb" id="Snippet4"::: + + The conversion of a to a may involve a loss of precision. In some cases, the loss of precision may cause the casting or conversion operation to succeed even if the value is outside the range of the data type. The following example provides an illustration. It assigns the maximum value of a to two variables, increments one variable by 9.999e291, and tests the two variables for equality. As expected, the call to the method shows that they are unequal. However, the conversion of the larger value back to a succeeds, although the value now exceeds . + + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/Explicit1.cs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Explicit/vb/Explicit1.vb" id="Snippet4"::: ## Examples - The following example illustrates the conversion of to values. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/System.Numeric.BigInteger.Explicit.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Explicit/vb/System.Numeric.BigInteger.Explicit.vb" id="Snippet3"::: + The following example illustrates the conversion of to values. + + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/System.Numeric.BigInteger.Explicit.cs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Explicit/vb/System.Numeric.BigInteger.Explicit.vb" id="Snippet3"::: ]]> @@ -4757,18 +4640,18 @@ For this method matches the IEE Defines an explicit conversion of a object to a 16-bit signed integer value. An object that contains the value of the parameter. - method define the types to which or from which a object can be converted. Language compilers do not perform this conversion automatically because it can involve data loss. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` or `CShort` in Visual Basic) is used. Otherwise, they display a compiler error. + method define the types to which or from which a object can be converted. Language compilers do not perform this conversion automatically because it can involve data loss. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` or `CShort` in Visual Basic) is used. Otherwise, they display a compiler error. Because this operation defines a narrowing conversion, it can throw an at run time if the value is outside the range of the data type. There is no loss of precision in the resulting value if the conversion is successful. ## Examples - The following example illustrates the conversion of to values. It also handles an that is thrown because the value is outside the range of the data type. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/System.Numeric.BigInteger.Explicit.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Explicit/vb/System.Numeric.BigInteger.Explicit.vb" id="Snippet4"::: + The following example illustrates the conversion of to values. It also handles an that is thrown because the value is outside the range of the data type. + + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/System.Numeric.BigInteger.Explicit.cs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Explicit/vb/System.Numeric.BigInteger.Explicit.vb" id="Snippet4"::: ]]> @@ -4816,18 +4699,18 @@ For this method matches the IEE Defines an explicit conversion of a object to a 32-bit signed integer value. An object that contains the value of the parameter. - method define the types to which or from which a object can be converted. Language compilers do not perform this conversion automatically because it can involve data loss. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` or `CInt` in Visual Basic) is used. Otherwise, they display a compiler error. + method define the types to which or from which a object can be converted. Language compilers do not perform this conversion automatically because it can involve data loss. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` or `CInt` in Visual Basic) is used. Otherwise, they display a compiler error. Because this operation defines a narrowing conversion, it can throw an at run time if the value is outside the range of the data type. There is no loss of precision in the resulting value if the conversion is successful. ## Examples - The following example illustrates the conversion of to values. It also handles an that is thrown because the value is outside the range of the data type. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/System.Numeric.BigInteger.Explicit.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Explicit/vb/System.Numeric.BigInteger.Explicit.vb" id="Snippet5"::: + The following example illustrates the conversion of to values. It also handles an that is thrown because the value is outside the range of the data type. + + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/System.Numeric.BigInteger.Explicit.cs" id="Snippet5"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Explicit/vb/System.Numeric.BigInteger.Explicit.vb" id="Snippet5"::: ]]> @@ -4875,18 +4758,18 @@ For this method matches the IEE Defines an explicit conversion of a object to a 64-bit signed integer value. An object that contains the value of the parameter. - method define the types to which or from which a object can be converted. Language compilers do not perform this conversion automatically because it can involve data loss. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` or `CLng` in Visual Basic) is used. Otherwise, they display a compiler error. + at run time if the value is outside the range of the data type. +## Remarks + The overloads of the method define the types to which or from which a object can be converted. Language compilers do not perform this conversion automatically because it can involve data loss. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` or `CLng` in Visual Basic) is used. Otherwise, they display a compiler error. + + Because this operation defines a narrowing conversion, it can throw an at run time if the value is outside the range of the data type. ## Examples - The following example illustrates the conversion of to values. It also handles an that is thrown because the value is outside the range of the data type. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/System.Numeric.BigInteger.Explicit.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Explicit/vb/System.Numeric.BigInteger.Explicit.vb" id="Snippet6"::: + The following example illustrates the conversion of to values. It also handles an that is thrown because the value is outside the range of the data type. + + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/System.Numeric.BigInteger.Explicit.cs" id="Snippet6"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Explicit/vb/System.Numeric.BigInteger.Explicit.vb" id="Snippet6"::: ]]> @@ -4970,23 +4853,23 @@ For this method matches the IEE The value to convert to a signed 8-bit value. - Defines an explicit conversion of a object to a signed 8-bit value. - + Defines an explicit conversion of a object to a signed 8-bit value. + This API is not CLS-compliant. The compliant alternative is . An object that contains the value of the parameter. - method define the types to which or from which a object can be converted. Language compilers do not perform this conversion automatically because it can involve data loss. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` or `CSByte` in Visual Basic) is used. Otherwise, they display a compiler error. + method define the types to which or from which a object can be converted. Language compilers do not perform this conversion automatically because it can involve data loss. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` or `CSByte` in Visual Basic) is used. Otherwise, they display a compiler error. Because this operation defines a narrowing conversion, it can throw an at run time if the value is outside the range of the data type. There is no loss of precision in the resulting value if the conversion is successful. ## Examples - The following example illustrates the conversion of to values. It also handles an that is thrown because the value is outside the range of the data type. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/System.Numeric.BigInteger.Explicit.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Explicit/vb/System.Numeric.BigInteger.Explicit.vb" id="Snippet7"::: + The following example illustrates the conversion of to values. It also handles an that is thrown because the value is outside the range of the data type. + + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/System.Numeric.BigInteger.Explicit.cs" id="Snippet7"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Explicit/vb/System.Numeric.BigInteger.Explicit.vb" id="Snippet7"::: ]]> @@ -5035,25 +4918,25 @@ For this method matches the IEE Defines an explicit conversion of a object to a single-precision floating-point value. An object that contains the closest possible representation of the parameter. - method define the types to which or from which a object can be converted. Language compilers do not perform this conversion automatically because it can involve data loss or a loss of precision. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` or `CSng` in Visual Basic) is used. Otherwise, they display a compiler error. + method define the types to which or from which a object can be converted. Language compilers do not perform this conversion automatically because it can involve data loss or a loss of precision. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` or `CSng` in Visual Basic) is used. Otherwise, they display a compiler error. Because the value can be outside the range of the data type, this operation is a narrowing conversion. If the conversion is unsuccessful, it does not throw an . Instead, if the value is less than , the resulting value is . If the value is greater than , the resulting value is . - The conversion of a to a may involve a loss of precision. In some cases, the loss of precision may cause the casting or conversion operation to succeed even if the value is outside the range of the data type. The following example provides an illustration. It assigns the maximum value of a to two variables, increments one variable by 9.999e291, and tests the two variables for equality. As expected, the call to the method shows that they are unequal. However, the conversion of the larger value back to a succeeds, although the value now exceeds . - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/Explicit1.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Explicit/vb/Explicit1.vb" id="Snippet5"::: + The conversion of a to a may involve a loss of precision. In some cases, the loss of precision may cause the casting or conversion operation to succeed even if the value is outside the range of the data type. The following example provides an illustration. It assigns the maximum value of a to two variables, increments one variable by 9.999e291, and tests the two variables for equality. As expected, the call to the method shows that they are unequal. However, the conversion of the larger value back to a succeeds, although the value now exceeds . + + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/Explicit1.cs" id="Snippet5"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Explicit/vb/Explicit1.vb" id="Snippet5"::: ## Examples - The following example illustrates the conversion of to values. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/System.Numeric.BigInteger.Explicit.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Explicit/vb/System.Numeric.BigInteger.Explicit.vb" id="Snippet8"::: + The following example illustrates the conversion of to values. + + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/System.Numeric.BigInteger.Explicit.cs" id="Snippet8"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Explicit/vb/System.Numeric.BigInteger.Explicit.vb" id="Snippet8"::: ]]> @@ -5141,23 +5024,23 @@ For this method matches the IEE The value to convert to an unsigned 16-bit integer. - Defines an explicit conversion of a object to an unsigned 16-bit integer value. - + Defines an explicit conversion of a object to an unsigned 16-bit integer value. + This API is not CLS-compliant. The compliant alternative is . An object that contains the value of the parameter. - method define the types to which or from which a object can be converted. Language compilers do not perform this conversion automatically because it can involve data loss. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` or `CUShort` in Visual Basic) is used. Otherwise, they display a compiler error. + method define the types to which or from which a object can be converted. Language compilers do not perform this conversion automatically because it can involve data loss. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` or `CUShort` in Visual Basic) is used. Otherwise, they display a compiler error. Because this operation defines a narrowing conversion, it can throw an at run time if the value is outside the range of the data type. There is no loss of precision in the resulting value if the conversion is successful. ## Examples - The following example illustrates the conversion of to values. It also handles an that is thrown because the value is outside the range of the data type. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/System.Numeric.BigInteger.Explicit.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Explicit/vb/System.Numeric.BigInteger.Explicit.vb" id="Snippet9"::: + The following example illustrates the conversion of to values. It also handles an that is thrown because the value is outside the range of the data type. + + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/System.Numeric.BigInteger.Explicit.cs" id="Snippet9"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Explicit/vb/System.Numeric.BigInteger.Explicit.vb" id="Snippet9"::: ]]> @@ -5209,23 +5092,23 @@ For this method matches the IEE The value to convert to an unsigned 32-bit integer. - Defines an explicit conversion of a object to an unsigned 32-bit integer value. - + Defines an explicit conversion of a object to an unsigned 32-bit integer value. + This API is not CLS-compliant. The compliant alternative is . An object that contains the value of the parameter. - method define the types to which or from which a object can be converted. Language compilers do not perform this conversion automatically because it can involve data loss. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` or `CUInt` in Visual Basic) is used. Otherwise, they display a compiler error. + method define the types to which or from which a object can be converted. Language compilers do not perform this conversion automatically because it can involve data loss. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` or `CUInt` in Visual Basic) is used. Otherwise, they display a compiler error. Because this operation defines a narrowing conversion, it can throw an at run time if the value is outside the range of the data type. There is no loss of precision in the resulting value if the conversion is successful. ## Examples - The following example illustrates the conversion of to values. It also handles an that is thrown because the value is outside the range of the data type. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/System.Numeric.BigInteger.Explicit.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Explicit/vb/System.Numeric.BigInteger.Explicit.vb" id="Snippet10"::: + The following example illustrates the conversion of to values. It also handles an that is thrown because the value is outside the range of the data type. + + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/System.Numeric.BigInteger.Explicit.cs" id="Snippet10"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Explicit/vb/System.Numeric.BigInteger.Explicit.vb" id="Snippet10"::: ]]> @@ -5277,23 +5160,23 @@ For this method matches the IEE The value to convert to an unsigned 64-bit integer. - Defines an explicit conversion of a object to an unsigned 64-bit integer value. - + Defines an explicit conversion of a object to an unsigned 64-bit integer value. + This API is not CLS-compliant. The compliant alternative is . An object that contains the value of the parameter. - method define the types to which or from which a object can be converted. Language compilers do not perform this conversion automatically because it can involve data loss. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` or `CULng` in Visual Basic) is used. Otherwise, they display a compiler error. + method define the types to which or from which a object can be converted. Language compilers do not perform this conversion automatically because it can involve data loss. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` or `CULng` in Visual Basic) is used. Otherwise, they display a compiler error. Because this operation defines a narrowing conversion, it can throw an at run time if the value is outside the range of the data type. There is no loss of precision in the resulting value if the conversion is successful. ## Examples - The following example illustrates the conversion of to values. It also handles an that is thrown because the value is outside the range of the data type. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/System.Numeric.BigInteger.Explicit.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Explicit/vb/System.Numeric.BigInteger.Explicit.vb" id="Snippet11"::: + The following example illustrates the conversion of to values. It also handles an that is thrown because the value is outside the range of the data type. + + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/System.Numeric.BigInteger.Explicit.cs" id="Snippet11"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Explicit/vb/System.Numeric.BigInteger.Explicit.vb" id="Snippet11"::: ]]> @@ -5414,11 +5297,11 @@ For this method matches the IEE Defines an explicit conversion of a value to a value. An object that contains the value of the parameter. - method define the types to which or from which a object can be converted. Because the conversion from to can involve truncating any fractional part of `value`, language compilers do not perform this conversion automatically. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` in Visual Basic) is used. Otherwise, they display a compiler error. For languages that do not support custom operators, the alternative method is . @@ -5426,9 +5309,9 @@ For this method matches the IEE ## Examples The following example converts the individual elements in an array of values to objects, and then displays the result of each conversion. Note that any fractional part of a value is truncated during the conversion. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/Explicit1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Explicit/vb/Explicit1.vb" id="Snippet3"::: + + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Explicit/Explicit1.cs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Explicit/vb/Explicit1.vb" id="Snippet3"::: ]]> @@ -5489,20 +5372,20 @@ For this method matches the IEE if is greater than ; otherwise, . - method defines the operation of the greater than operator for values. It enables code such as the following: - + method defines the operation of the greater than operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet9"::: - - Languages that do not support custom operators can call the instance method instead. Some languages can also call the method directly, as the following example shows. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet10"::: - - If `left` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet9"::: + + Languages that do not support custom operators can call the instance method instead. Some languages can also call the method directly, as the following example shows. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet10"::: + + If `left` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. + The equivalent method for this operator is .]]> @@ -5551,20 +5434,20 @@ For this method matches the IEE if is greater than ; otherwise, . - method defines the operation of the greater than operator for values. It enables code such as the following: - + method defines the operation of the greater than operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet11"::: - - Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet12"::: - - If `right` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet11"::: + + Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet12"::: + + If `right` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. + The equivalent method for this operator is .]]> @@ -5617,18 +5500,18 @@ For this method matches the IEE if is greater than ; otherwise, . - method defines the operation of the greater than operator for values. It enables code such as the following: - + method defines the operation of the greater than operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/GreatestCommonDivisor/BigInteger_Examples.cs" id="Snippet20"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet20"::: - - Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet21"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet20"::: + + Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet21"::: + The equivalent method for this operator is .]]> @@ -5683,18 +5566,18 @@ For this method matches the IEE if is greater than ; otherwise, . - method defines the operation of the greater than operator for values. It enables code such as the following: - + method defines the operation of the greater than operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet13"::: - - Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet14"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet13"::: + + Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet14"::: + ]]> @@ -5748,18 +5631,18 @@ For this method matches the IEE if is greater than ; otherwise, . - method defines the operation of the greater than operator for values. It enables code such as the following: - + method defines the operation of the greater than operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet15"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet15"::: - - Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet16"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet15"::: + + Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet16"::: + ]]> @@ -5818,20 +5701,20 @@ For this method matches the IEE if is greater than ; otherwise, . - method defines the operation of the greater than or equal to operator for values. It enables code such as the following: - + method defines the operation of the greater than or equal to operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet17"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet17"::: - - Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet18"::: - - If `left` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet17"::: + + Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet18"::: + + If `left` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. + The equivalent method for this operator is .]]> @@ -5880,20 +5763,20 @@ For this method matches the IEE if is greater than ; otherwise, . - method defines the operation of the greater than or equal to operator for values. It enables code such as the following: - + method defines the operation of the greater than or equal to operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet19"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet19"::: - - Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet20"::: - - If `right` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet19"::: + + Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet20"::: + + If `right` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. + The equivalent method for this operator is .]]> @@ -5946,18 +5829,18 @@ For this method matches the IEE if is greater than ; otherwise, . - method defines the operation of the greater than or equal to operator for values. It enables code such as the following: - + method defines the operation of the greater than or equal to operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/GreatestCommonDivisor/BigInteger_Examples.cs" id="Snippet22"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet22"::: - - Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet23"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet22"::: + + Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet23"::: + The equivalent method for this operator is .]]> @@ -6012,18 +5895,18 @@ For this method matches the IEE if is greater than ; otherwise, . - method defines the operation of the greater than or equal to operator for values. It enables code such as the following: - + method defines the operation of the greater than or equal to operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet21"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet21"::: - - Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet22"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet21"::: + + Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet22"::: + The equivalent method for this operator is .]]> @@ -6078,18 +5961,18 @@ For this method matches the IEE if is greater than ; otherwise, . - method defines the operation of the greater than or equal to operator for values. It enables code such as the following: - + method defines the operation of the greater than or equal to operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet23"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet23"::: - - Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet24"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet23"::: + + Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet24"::: + The equivalent method for this operator is .]]> @@ -6145,17 +6028,17 @@ For this method matches the IEE Defines an implicit conversion of an unsigned byte to a value. An object that contains the value of the parameter. - . + For languages that do not support implicit operators, the alternative method is . - The overloads of the method define the types to which or from which a 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 . This overload lets the compiler handle conversions from a value to a value, as the following example shows. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Implicit/Implicit1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Implicit/vb/Implicit1.vb" id="Snippet1"::: + The overloads of the method define the types to which or from which a 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 . This overload lets the compiler handle conversions from a value to a value, as the following example shows. + + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Implicit/Implicit1.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Implicit/vb/Implicit1.vb" id="Snippet1"::: ]]> @@ -6267,15 +6150,15 @@ For this method matches the IEE Defines an implicit conversion of a signed 16-bit integer to a value. An object that contains the value of the parameter. - . + method define the types to which or from which a 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 . This overload lets the compiler handle conversions from a value to a value, as the following example shows. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Implicit/Implicit1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Implicit/vb/Implicit1.vb" id="Snippet2"::: +## Remarks + For languages that do not support implicit operators, the alternative method is . + + The overloads of the method define the types to which or from which a 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 . This overload lets the compiler handle conversions from a value to a value, as the following example shows. + + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Implicit/Implicit1.cs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Implicit/vb/Implicit1.vb" id="Snippet2"::: ]]> @@ -6321,15 +6204,15 @@ For this method matches the IEE Defines an implicit conversion of a signed 32-bit integer to a value. An object that contains the value of the parameter. - . + method define the types to which or from which a 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 . This overload lets the compiler handle conversions from a value to a value, as the following example shows. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Implicit/Implicit1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Implicit/vb/Implicit1.vb" id="Snippet3"::: +## Remarks + For languages that do not support implicit operators, the alternative method is . + + The overloads of the method define the types to which or from which a 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 . This overload lets the compiler handle conversions from a value to a value, as the following example shows. + + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Implicit/Implicit1.cs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Implicit/vb/Implicit1.vb" id="Snippet3"::: ]]> @@ -6375,15 +6258,15 @@ For this method matches the IEE Defines an implicit conversion of a signed 64-bit integer to a value. An object that contains the value of the parameter. - . - - The overloads of the method define the types to which or from which a 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 . This overload lets the compiler handle conversions from a value to a value, as the following example shows. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Implicit/Implicit1.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Implicit/vb/Implicit1.vb" id="Snippet4"::: + . + + The overloads of the method define the types to which or from which a 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 . This overload lets the compiler handle conversions from a value to a value, as the following example shows. + + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Implicit/Implicit1.cs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Implicit/vb/Implicit1.vb" id="Snippet4"::: ]]> @@ -6465,20 +6348,20 @@ For this method matches the IEE The value to convert to a . - Defines an implicit conversion of an 8-bit signed integer to a value. - + Defines an implicit conversion of an 8-bit signed integer to a value. + This API is not CLS-compliant. The compliant alternative is . An object that contains the value of the parameter. - . + . - The overloads of the method define the types to which or from which a 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 . This overload lets the compiler handle conversions from a value to a value, as the following example shows. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Implicit/Implicit1.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Implicit/vb/Implicit1.vb" id="Snippet5"::: + The overloads of the method define the types to which or from which a 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 . This overload lets the compiler handle conversions from a value to a value, as the following example shows. + + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Implicit/Implicit1.cs" id="Snippet5"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Implicit/vb/Implicit1.vb" id="Snippet5"::: ]]> @@ -6567,20 +6450,20 @@ For this method matches the IEE The value to convert to a . - Defines an implicit conversion of a 16-bit unsigned integer to a value. - + Defines an implicit conversion of a 16-bit unsigned integer to a value. + This API is not CLS-compliant. The compliant alternative is . An object that contains the value of the parameter. - . + . + + The overloads of the method define the types to which or from which a 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 . This overload lets the compiler handle conversions from a value to a value, as the following example shows. - The overloads of the method define the types to which or from which a 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 . This overload lets the compiler handle conversions from a value to a value, as the following example shows. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Implicit/Implicit1.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Implicit/vb/Implicit1.vb" id="Snippet6"::: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Implicit/Implicit1.cs" id="Snippet6"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Implicit/vb/Implicit1.vb" id="Snippet6"::: ]]> @@ -6630,20 +6513,20 @@ For this method matches the IEE The value to convert to a . - Defines an implicit conversion of a 32-bit unsigned integer to a value. - + Defines an implicit conversion of a 32-bit unsigned integer to a value. + This API is not CLS-compliant. The compliant alternative is . An object that contains the value of the parameter. - . + method define the types to which or from which a 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 . This overload lets the compiler handle conversions from a value to a value, as the following example shows. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Implicit/Implicit1.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Implicit/vb/Implicit1.vb" id="Snippet7"::: +## Remarks + For languages that do not support implicit operators, the alternative method is . + + The overloads of the method define the types to which or from which a 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 . This overload lets the compiler handle conversions from a value to a value, as the following example shows. + + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Implicit/Implicit1.cs" id="Snippet7"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Implicit/vb/Implicit1.vb" id="Snippet7"::: ]]> @@ -6693,20 +6576,20 @@ For this method matches the IEE The value to convert to a . - Defines an implicit conversion of a 64-bit unsigned integer to a value. - + Defines an implicit conversion of a 64-bit unsigned integer to a value. + This API is not CLS-compliant. The compliant alternative is . An object that contains the value of the parameter. - . + . + + The overloads of the method define the types to which or from which a 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 . This overload lets the compiler handle conversions from a value to a value, as the following example shows. - The overloads of the method define the types to which or from which a 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 . This overload lets the compiler handle conversions from a value to a value, as the following example shows. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Implicit/Implicit1.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Implicit/vb/Implicit1.vb" id="Snippet8"::: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_Implicit/Implicit1.cs" id="Snippet8"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Implicit/vb/Implicit1.vb" id="Snippet8"::: ]]> @@ -6796,19 +6679,19 @@ For this method matches the IEE Increments a value by 1. The value of the parameter incremented by 1. - method defines the increment operation for values. It enables code such as the following: - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/GreatestCommonDivisor/BigInteger_Examples.cs" id="Snippet24"::: - - Some languages (such as Visual Basic) that lack an increment operator or do not support operator overloading can call the method directly, as the following example shows. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet25"::: - - Because objects are immutable, the operator creates a new object whose value is one more than the object represented by `value`. Therefore, repeated calls to may be expensive. - + method defines the increment operation for values. It enables code such as the following: + + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/GreatestCommonDivisor/BigInteger_Examples.cs" id="Snippet24"::: + + Some languages (such as Visual Basic) that lack an increment operator or do not support operator overloading can call the method directly, as the following example shows. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet25"::: + + Because objects are immutable, the operator creates a new object whose value is one more than the object represented by `value`. Therefore, repeated calls to may be expensive. + The equivalent method for this operator is .]]> @@ -6867,22 +6750,22 @@ For this method matches the IEE if and are not equal; otherwise, . - method defines the operation of the inequality operator for values. It enables code such as the following: - + method defines the operation of the inequality operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet25"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet25"::: - - Languages that do not support custom operators can test for inequality by using one of the following techniques: - -- Calling the instance method, which indicates the relationship between a and a signed long integer value. - -- Calling the instance method and reversing its value. - - If `left` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet25"::: + + Languages that do not support custom operators can test for inequality by using one of the following techniques: + +- Calling the instance method, which indicates the relationship between a and a signed long integer value. + +- Calling the instance method and reversing its value. + + If `left` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. + ]]> @@ -6931,22 +6814,22 @@ For this method matches the IEE if and are not equal; otherwise, . - method defines the operation of the inequality operator for values. It enables code such as the following: - + method defines the operation of the inequality operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet26"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet26"::: - - Languages that do not support custom operators can test for inequality by using one of the following techniques: - -- Calling the method, which indicates the relationship between a and a signed long integer value. - -- Calling the method and reversing its value. - - If `right` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet26"::: + + Languages that do not support custom operators can test for inequality by using one of the following techniques: + +- Calling the method, which indicates the relationship between a and a signed long integer value. + +- Calling the method and reversing its value. + + If `right` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. + The equivalent method for this operator is .]]> @@ -6999,20 +6882,20 @@ For this method matches the IEE if and are not equal; otherwise, . - method defines the operation of the inequality operator for values. It enables code such as the following: - + method defines the operation of the inequality operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/GreatestCommonDivisor/BigInteger_Examples.cs" id="Snippet26"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet26"::: - - Languages that do not support custom operators can test for inequality by using one of the following techniques: - -- Calling the method, which indicates the relationship between two objects. - -- Calling the method and reversing its value. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet26"::: + + Languages that do not support custom operators can test for inequality by using one of the following techniques: + +- Calling the method, which indicates the relationship between two objects. + +- Calling the method and reversing its value. + The equivalent method for this operator is .]]> @@ -7067,20 +6950,20 @@ For this method matches the IEE if and are not equal; otherwise, . - method defines the operation of the inequality operator for values. It enables code such as the following: - + method defines the operation of the inequality operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet27"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet27"::: - - Languages that do not support custom operators can test for inequality by using one of the following techniques: - -- Calling the method, which indicates the relationship between a and an unsigned long integer value. - -- Calling the method and reversing its value. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet27"::: + + Languages that do not support custom operators can test for inequality by using one of the following techniques: + +- Calling the method, which indicates the relationship between a and an unsigned long integer value. + +- Calling the method and reversing its value. + ]]> @@ -7135,20 +7018,20 @@ For this method matches the IEE if and are not equal; otherwise, . - method defines the operation of the inequality operator for values. It enables code such as the following: - + method defines the operation of the inequality operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet28"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet28"::: - - Languages that do not support custom operators can test for inequality by using one of the following techniques: - -- Calling the method, which indicates the relationship between a and an unsigned long integer value. - -- Calling the method and reversing its value. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet28"::: + + Languages that do not support custom operators can test for inequality by using one of the following techniques: + +- Calling the method, which indicates the relationship between a and an unsigned long integer value. + +- Calling the method and reversing its value. + ]]> @@ -7200,22 +7083,22 @@ For this method matches the IEE Shifts a value a specified number of bits to the left. A value that has been shifted to the left by the specified number of bits. - method defines the operation of the bitwise left-shift operator for values. It enables code such as the following: - + method defines the operation of the bitwise left-shift operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet29"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet29"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet29"::: + > [!NOTE] -> Unlike the bitwise left-shift operation with integer primitives, the method preserves the sign of the original value. - - Languages that do not support custom operators can perform a bitwise left-shift operation by multiplying `value` by `BigInteger.Pow(2, shift)`. The following example shows that the results are identical to the results of using this operator. - +> Unlike the bitwise left-shift operation with integer primitives, the method preserves the sign of the original value. + + Languages that do not support custom operators can perform a bitwise left-shift operation by multiplying `value` by `BigInteger.Pow(2, shift)`. The following example shows that the results are identical to the results of using this operator. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet30"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet30"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet30"::: + ]]> @@ -7274,20 +7157,20 @@ For this method matches the IEE if is less than ; otherwise, . - method defines the operation of the less than operator for values. It enables code such as the following: - + method defines the operation of the less than operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet31"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet31"::: - - Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet32"::: - - If `left` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet31"::: + + Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet32"::: + + If `left` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. + The equivalent method for this operator is .]]> @@ -7336,20 +7219,20 @@ For this method matches the IEE if is less than ; otherwise, . - method defines the operation of the less than operator for values. It enables code such as the following: - + method defines the operation of the less than operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet33"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet33"::: - - Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet34"::: - - If `right` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet33"::: + + Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet34"::: + + If `right` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. + The equivalent method for this operator is .]]> @@ -7402,18 +7285,18 @@ For this method matches the IEE if is less than ; otherwise, . - method defines the operation of the less than operator for values. It enables code such as the following: - + method defines the operation of the less than operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/GreatestCommonDivisor/BigInteger_Examples.cs" id="Snippet27"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet27"::: - - Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet28"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet27"::: + + Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet28"::: + The equivalent method for this operator is .]]> @@ -7468,18 +7351,18 @@ For this method matches the IEE if is less than ; otherwise, . - method defines the operation of the less than operator for values. It enables code such as the following: - + method defines the operation of the less than operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet35"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet35"::: - - Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet36"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet35"::: + + Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet36"::: + The equivalent method for this operator is .]]> @@ -7534,18 +7417,18 @@ For this method matches the IEE if is less than ; otherwise, . - method defines the operation of the less than operator for values. It enables code such as the following: - + method defines the operation of the less than operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet37"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet37"::: - - Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet38"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet37"::: + + Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet38"::: + The equivalent method for this operator is .]]> @@ -7604,20 +7487,20 @@ For this method matches the IEE if is less than or equal to ; otherwise, . - method defines the operation of the less than or equal to operator for values. It enables code such as the following: - + method defines the operation of the less than or equal to operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet39"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet39"::: - - Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet40"::: - - If `left` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet39"::: + + Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet40"::: + + If `left` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. + The equivalent method for this operator is .]]> @@ -7666,20 +7549,20 @@ For this method matches the IEE if is less than or equal to ; otherwise, . - method defines the operation of the less than or equal to operator for values. It enables code such as the following: - + method defines the operation of the less than or equal to operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet41"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet41"::: - - Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet42"::: - - If `right` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet41"::: + + Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet42"::: + + If `right` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. + The equivalent method for this operator is .]]> @@ -7732,18 +7615,18 @@ For this method matches the IEE if is less than or equal to ; otherwise, . - method defines the operation of the less than or equal to operator for values. It enables code such as the following: - + method defines the operation of the less than or equal to operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/GreatestCommonDivisor/BigInteger_Examples.cs" id="Snippet29"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet29"::: - - Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet30"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet29"::: + + Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet30"::: + The equivalent method for this operator is .]]> @@ -7798,18 +7681,18 @@ For this method matches the IEE if is less than or equal to ; otherwise, . - method defines the operation of the less than or equal to operator for values. It enables code such as the following: - + method defines the operation of the less than or equal to operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet43"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet43"::: - - Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet44"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet43"::: + + Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet44"::: + The equivalent method for this operator is .]]> @@ -7864,18 +7747,18 @@ For this method matches the IEE if is less than or equal to ; otherwise, . - method defines the operation of the less than or equal to operator for values. It enables code such as the following: - + method defines the operation of the less than or equal to operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/Operator1.cs" id="Snippet45"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet45"::: - - Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet46"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet45"::: + + Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet46"::: + The equivalent method for this operator is .]]> @@ -7927,18 +7810,18 @@ For this method matches the IEE Returns the remainder that results from division with two specified values. The remainder that results from the division. - method defines the operation of the modulus operator for values. It enables code such as the following: - + method defines the operation of the modulus operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/GreatestCommonDivisor/BigInteger_Examples.cs" id="Snippet31"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet31"::: - - Languages that do not support custom operators can call the method instead. - - The sign of the value returned by the modulus operation depends on the sign of `dividend`: If `dividend` is positive, the modulus operation returns a positive result; if it is negative, the modulus operation returns a negative result. The behavior of the modulus operation with values is identical to the modulus operation with other integral types. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet31"::: + + Languages that do not support custom operators can call the method instead. + + The sign of the value returned by the modulus operation depends on the sign of `dividend`: If `dividend` is positive, the modulus operation returns a positive result; if it is negative, the modulus operation returns a negative result. The behavior of the modulus operation with values is identical to the modulus operation with other integral types. + The equivalent method for this operator is .]]> @@ -7993,14 +7876,14 @@ For this method matches the IEE Multiplies two specified values. The product of and . - method defines the operation of the multiplication operator for values. It enables code such as the following: - + method defines the operation of the multiplication operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/GreatestCommonDivisor/BigInteger_Examples.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet11"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet11"::: + The equivalent method for this operator is .]]> @@ -8050,18 +7933,18 @@ For this method matches the IEE Returns the bitwise one's complement of a value. The bitwise one's complement of . - method defines the operation of the bitwise one's complement operator for values. The bitwise one's complement operator reverses each bit in a numeric value. That is, bits in `value` that are 0 are set to 1 in the result, and bits that are 1 are set to 0 in the result. The method enables code such as the following: - + method defines the operation of the bitwise one's complement operator for values. The bitwise one's complement operator reverses each bit in a numeric value. That is, bits in `value` that are 0 are set to 1 in the result, and bits that are 1 are set to 0 in the result. The method enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_OnesComplement/OnesComplement1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.OnesComplement/vb/OnesComplement1.vb" id="Snippet1"::: - - Languages that do not support custom operators may be able to call the method directly to perform a bitwise one's complement operation. For example: - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.OnesComplement/vb/onescomplement2.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.OnesComplement/vb/OnesComplement1.vb" id="Snippet1"::: + + Languages that do not support custom operators may be able to call the method directly to perform a bitwise one's complement operation. For example: + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.OnesComplement/vb/onescomplement2.vb" id="Snippet2"::: + ]]> @@ -8112,21 +7995,21 @@ For this method matches the IEE Shifts a value a specified number of bits to the right. A value that has been shifted to the right by the specified number of bits. - method defines the operation of the bitwise right-shift operator for values. It enables code such as the following: - + method defines the operation of the bitwise right-shift operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/RightShift1.cs" id="Snippet47"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet47"::: - - Languages that do not support custom operators can perform a bitwise right-shift operation by dividing `value` by `BigInteger.Pow(2, shift)` and subtracting 1 times `shift` for negative values. The following example shows that the results are identical to the results of using this operator. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet47"::: + + Languages that do not support custom operators can perform a bitwise right-shift operation by dividing `value` by `BigInteger.Pow(2, shift)` and subtracting 1 times `shift` for negative values. The following example shows that the results are identical to the results of using this operator. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/op_BitwiseAnd/RightShift1.cs" id="Snippet48"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet48"::: - - If `shift` is greater than or equal to the number of bits in a positive value, the result of the right-shift operation is . If `shift` is greater than the number of bits in a negative value, the result of the right-shift operation is . - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb" id="Snippet48"::: + + If `shift` is greater than or equal to the number of bits in a positive value, the result of the right-shift operation is . If `shift` is greater than the number of bits in a negative value, the result of the right-shift operation is . + ]]> @@ -8178,16 +8061,16 @@ For this method matches the IEE Subtracts a value from another value. The result of subtracting from . - method defines the operation of the subtraction operator for values. It enables code such as the following: - + method defines the operation of the subtraction operator for values. It enables code such as the following: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/GreatestCommonDivisor/BigInteger_Examples.cs" id="Snippet14"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet14"::: - - Languages that do not support custom operators can call the method instead. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet14"::: + + Languages that do not support custom operators can call the method instead. + The equivalent method for this operator is .]]> @@ -8237,19 +8120,19 @@ For this method matches the IEE Negates a specified BigInteger value. The result of the parameter multiplied by negative one (-1). - method defines the operation of the unary negation operator (or the additive inverse operator) for values. The operation produces a value that results in 0 (zero) when it is added to the original number. Languages that do not support custom operators can call the method instead. - - The equivalent method for this operator is - -## Examples - The following example illustrates three different ways to negate the value of a object. - + method defines the operation of the unary negation operator (or the additive inverse operator) for values. The operation produces a value that results in 0 (zero) when it is added to the original number. Languages that do not support custom operators can call the method instead. + + The equivalent method for this operator is + +## Examples + The following example illustrates three different ways to negate the value of a object. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/GreatestCommonDivisor/BigInteger_Examples.cs" id="Snippet16"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet16"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet16"::: + ]]> @@ -8298,11 +8181,11 @@ For this method matches the IEE Returns the value of the operand. (The sign of the operand is unchanged.) The value of the operand. - method defines the operation of the unary positive operator for values. - + method defines the operation of the unary positive operator for values. + ]]> @@ -8409,37 +8292,37 @@ This operation performs an unsigned (otherwise known as a logical) right shift o Converts the string representation of a number to its equivalent. A value that is equivalent to the number specified in the parameter. - and properties of the current culture.| -|*digits*|A sequence of digits ranging from 0 to 9. Any leading zeros are ignored.| - + and properties of the current culture.| +|*digits*|A sequence of digits ranging from 0 to 9. Any leading zeros are ignored.| + > [!NOTE] -> The string specified by the `value` parameter is interpreted by using the style. It cannot contain any group separators or decimal separator, and it cannot have a decimal portion. - - The `value` parameter is parsed by using the formatting information in a object that is initialized for the current system culture. For more information, see . To parse a string by using the formatting information of a specific culture, use the method. - +> The string specified by the `value` parameter is interpreted by using the style. It cannot contain any group separators or decimal separator, and it cannot have a decimal portion. + + The `value` parameter is parsed by using the formatting information in a object that is initialized for the current system culture. For more information, see . To parse a string by using the formatting information of a specific culture, use the method. + > [!IMPORTANT] -> If you use the method to round-trip the string representation of a value that was output by the method, you should use the method with the "R" format specifier to generate the string representation of the value. Otherwise, the string representation of the preserves only the 50 most significant digits of the original value, and data may be lost when you use the method to restore the value. - - - -## Examples - The following example uses the method to instantiate two objects. It multiplies each object by another number and then calls the method to determine the relationship between the two values. - +> If you use the method to round-trip the string representation of a value that was output by the method, you should use the method with the "R" format specifier to generate the string representation of the value. Otherwise, the string representation of the preserves only the 50 most significant digits of the original value, and data may be lost when you use the method to restore the value. + + + +## Examples + The following example uses the method to instantiate two objects. It multiplies each object by another number and then calls the method to determine the relationship between the two values. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Parse/Parse1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Parse/vb/Parse1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Parse/vb/Parse1.vb" id="Snippet1"::: + ]]> @@ -8542,84 +8425,84 @@ This operation performs an unsigned (otherwise known as a logical) right shift o Converts the string representation of a number in a specified style to its equivalent. A value that is equivalent to the number specified in the parameter. - enumeration. The `style` parameter makes this method overload useful when `value` contains the string representation of a hexadecimal value, when the number system (decimal or hexadecimal) represented by `value` is known only at run time, or when you want to disallow white space or a sign symbol in `value`. - - Depending on the value of `style`, the `value` parameter may include the following elements: - - [*ws*][*$*][*sign*][*digits*,]*digits*[.*fractional_digits*][E[*sign*]*exponential_digits*][*ws*] - - If `style` includes , the `value` parameter may contain the following elements: - - [*ws*]*hexdigits*[*ws*] - - Elements in square brackets ([ and ]) are optional. The following table describes each element. - -|Element|Description| -|-------------|-----------------| -|*ws*|Optional white space. White space can appear at the start of `value` if `style` includes the flag, and it can appear at the end of `value` if `style` includes the flag.| -|*$*|A culture-specific currency symbol. Its position in the string is defined by the and properties of the current culture. The current culture's currency symbol can appear in `value` if `style` includes the flag.| -|*sign*|An optional sign. The sign can appear at the start of `value` if `style` includes the flag, and it can appear at the end of `value` if `style` includes the flag. Parentheses can be used in `value` to indicate a negative value if `style` includes the flag.| -|*digits*

*fractional_digits*

*exponential_digits*|A sequence of digits from 0 through 9. For *fractional_digits*, only the digit 0 is valid.| -|*,*|A culture-specific group separator symbol. The current culture's group separator can appear in `value` if `style` includes the flag.| -|*.*|A culture-specific decimal point symbol. The current culture's decimal point symbol can appear in `value` if `style` includes the flag. Only the digit 0 can appear as a fractional digit for the parse operation to succeed; if *fractional_digits* includes any other digit, a is thrown.| -|E|The "e" or "E" character, which indicates that the value is represented in exponential (scientific) notation. The `value` parameter can represent a number in exponential notation if `style` includes the flag.| -|*hexdigits*|A sequence of hexadecimal digits from 0 through f, or 0 through F.| - + enumeration. The `style` parameter makes this method overload useful when `value` contains the string representation of a hexadecimal value, when the number system (decimal or hexadecimal) represented by `value` is known only at run time, or when you want to disallow white space or a sign symbol in `value`. + + Depending on the value of `style`, the `value` parameter may include the following elements: + + [*ws*][*$*][*sign*][*digits*,]*digits*[.*fractional_digits*][E[*sign*]*exponential_digits*][*ws*] + + If `style` includes , the `value` parameter may contain the following elements: + + [*ws*]*hexdigits*[*ws*] + + Elements in square brackets ([ and ]) are optional. The following table describes each element. + +|Element|Description| +|-------------|-----------------| +|*ws*|Optional white space. White space can appear at the start of `value` if `style` includes the flag, and it can appear at the end of `value` if `style` includes the flag.| +|*$*|A culture-specific currency symbol. Its position in the string is defined by the and properties of the current culture. The current culture's currency symbol can appear in `value` if `style` includes the flag.| +|*sign*|An optional sign. The sign can appear at the start of `value` if `style` includes the flag, and it can appear at the end of `value` if `style` includes the flag. Parentheses can be used in `value` to indicate a negative value if `style` includes the flag.| +|*digits*

*fractional_digits*

*exponential_digits*|A sequence of digits from 0 through 9. For *fractional_digits*, only the digit 0 is valid.| +|*,*|A culture-specific group separator symbol. The current culture's group separator can appear in `value` if `style` includes the flag.| +|*.*|A culture-specific decimal point symbol. The current culture's decimal point symbol can appear in `value` if `style` includes the flag. Only the digit 0 can appear as a fractional digit for the parse operation to succeed; if *fractional_digits* includes any other digit, a is thrown.| +|E|The "e" or "E" character, which indicates that the value is represented in exponential (scientific) notation. The `value` parameter can represent a number in exponential notation if `style` includes the flag.| +|*hexdigits*|A sequence of hexadecimal digits from 0 through f, or 0 through F.| + > [!NOTE] > Any terminating NUL (U+0000) characters in `s` are ignored by the parsing operation, regardless of the value of the `style` argument. - A string with digits only (which corresponds to the style) always parses successfully. Most of the remaining members control elements that may be present, but are not required to be present, in the input string. The following table indicates how individual members affect the elements that may be present in `value`. - -|`NumberStyles` value|Elements permitted in `value` in addition to digits| -|--------------------------|---------------------------------------------------------| -||The *digits* element only.| -||The decimal point (.) and *fractional-digits* elements.| -||The "e" or "E" character, which indicates exponential notation, along with *exponential_digits*.| -||The *ws* element at the start of `value`.| -||The *ws* element at the end of `value`.| -||The *sign* element at the start of `value`.| -||The *sign* element at the end of `value`.| -||The *sign* element in the form of parentheses enclosing the numeric value.| -||The group separator (,) element.| -||The currency ($) element.| -||All elements. However, `value` cannot represent a hexadecimal number or a number in exponential notation.| -||The *ws* element at the start or end of `value`, *sign* at the start of `value`, and the decimal point (*.*) symbol. The `value` parameter can also use exponential notation.| -||The `ws`, `sign`, group separator (*,*), and decimal point (*.*) elements.| -||All elements. However, `value` cannot represent a hexadecimal number.| - + A string with digits only (which corresponds to the style) always parses successfully. Most of the remaining members control elements that may be present, but are not required to be present, in the input string. The following table indicates how individual members affect the elements that may be present in `value`. + +|`NumberStyles` value|Elements permitted in `value` in addition to digits| +|--------------------------|---------------------------------------------------------| +||The *digits* element only.| +||The decimal point (.) and *fractional-digits* elements.| +||The "e" or "E" character, which indicates exponential notation, along with *exponential_digits*.| +||The *ws* element at the start of `value`.| +||The *ws* element at the end of `value`.| +||The *sign* element at the start of `value`.| +||The *sign* element at the end of `value`.| +||The *sign* element in the form of parentheses enclosing the numeric value.| +||The group separator (,) element.| +||The currency ($) element.| +||All elements. However, `value` cannot represent a hexadecimal number or a number in exponential notation.| +||The *ws* element at the start or end of `value`, *sign* at the start of `value`, and the decimal point (*.*) symbol. The `value` parameter can also use exponential notation.| +||The `ws`, `sign`, group separator (*,*), and decimal point (*.*) elements.| +||All elements. However, `value` cannot represent a hexadecimal number.| + > [!IMPORTANT] -> If you use the method to round-trip the string representation of a value that was output by the method, you should use the method with the "R" format specifier to generate the string representation of the value. Otherwise, the string representation of the preserves only the 50 most significant digits of the original value, and data may be lost when you use the method to restore the value. - - Unlike the other values, which allow for, but do not require, the presence of particular style elements in `value`, the style value means that the individual numeric characters in `value` are always interpreted as hexadecimal characters. Valid hexadecimal characters are 0-9, A-F, and a-f. The only other flags that can be combined with the `style` parameter are and . (The enumeration includes a composite number style, , that includes both white-space flags.) - +> If you use the method to round-trip the string representation of a value that was output by the method, you should use the method with the "R" format specifier to generate the string representation of the value. Otherwise, the string representation of the preserves only the 50 most significant digits of the original value, and data may be lost when you use the method to restore the value. + + Unlike the other values, which allow for, but do not require, the presence of particular style elements in `value`, the style value means that the individual numeric characters in `value` are always interpreted as hexadecimal characters. Valid hexadecimal characters are 0-9, A-F, and a-f. The only other flags that can be combined with the `style` parameter are and . (The enumeration includes a composite number style, , that includes both white-space flags.) + > [!NOTE] -> If `value` is the string representation of a hexadecimal number, it cannot be preceded by any decoration (such as `0x` or `&h`) that differentiates it as a hexadecimal number. This causes the conversion to fail. - - If `value` is a hexadecimal string, the method interprets `value` as a negative number stored by using two's complement representation if its first two hexadecimal digits are greater than or equal to `0x80`. In other words, the method interprets the highest-order bit of the first byte in `value` as the sign bit. To make sure that a hexadecimal string is correctly interpreted as a positive number, the first digit in `value` must have a value of zero. For example, the method interprets `0x80` as a negative value, but it interprets either `0x080` or `0x0080` as a positive value. The following example illustrates the difference between hexadecimal strings that represent negative and positive values. - +> If `value` is the string representation of a hexadecimal number, it cannot be preceded by any decoration (such as `0x` or `&h`) that differentiates it as a hexadecimal number. This causes the conversion to fail. + + If `value` is a hexadecimal string, the method interprets `value` as a negative number stored by using two's complement representation if its first two hexadecimal digits are greater than or equal to `0x80`. In other words, the method interprets the highest-order bit of the first byte in `value` as the sign bit. To make sure that a hexadecimal string is correctly interpreted as a positive number, the first digit in `value` must have a value of zero. For example, the method interprets `0x80` as a negative value, but it interprets either `0x080` or `0x0080` as a positive value. The following example illustrates the difference between hexadecimal strings that represent negative and positive values. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Parse/ParseHex1.cs" interactive="try-dotnet" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Parse/vb/ParseHex1.vb" id="Snippet3"::: - - The `value` parameter is parsed by using the formatting information in a object that is initialized for the current system culture. To specify the culture whose formatting information is used for the parse operation, call the overload. - - - -## Examples - The following example illustrates calls to the method with several possible values for the `style` parameter. It illustrates how to interpret a string as a hexadecimal value, and how to disallow spaces and sign symbols. - + + The `value` parameter is parsed by using the formatting information in a object that is initialized for the current system culture. To specify the culture whose formatting information is used for the parse operation, call the overload. + + + +## Examples + The following example illustrates calls to the method with several possible values for the `style` parameter. It illustrates how to interpret a string as a hexadecimal value, and how to disallow spaces and sign symbols. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Parse/System.Numeric.BigInteger.Parse.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Parse/vb/System.Numeric.BigInteger.Parse.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Parse/vb/System.Numeric.BigInteger.Parse.vb" id="Snippet5"::: + ]]> - is not a value. - - -or- - + is not a value. + + -or- + includes the or flag along with another value. is . @@ -8688,57 +8571,57 @@ This operation performs an unsigned (otherwise known as a logical) right shift o Converts the string representation of a number in a specified culture-specific format to its equivalent. A value that is equivalent to the number specified in the parameter. - and properties of the object that is returned by the `provider` object's method.| -|*digits*|A sequence of digits ranging from 0 to 9. Any leading zeros are ignored.| - + and properties of the object that is returned by the `provider` object's method.| +|*digits*|A sequence of digits ranging from 0 to 9. Any leading zeros are ignored.| + > [!NOTE] -> The string specified by the `value` parameter is interpreted using the style. It cannot contain any group separators or decimal separator, and it cannot have a decimal portion. - +> The string specified by the `value` parameter is interpreted using the style. It cannot contain any group separators or decimal separator, and it cannot have a decimal portion. + > [!IMPORTANT] -> If you use the method to round-trip the string representation of a value that was output by the method, you should use the method with the "R" format specifier to generate the string representation of the value. Otherwise, the string representation of the preserves only the 50 most significant digits of the original value, and data may be lost when you use the method to restore the value. - - The `provider` parameter is an implementation whose method returns a object that provides culture-specific formatting information. When the method is invoked, it calls the `provider` parameter's method and passes it a object that represents the type. The method then returns the object that provides information about the format of the `value` parameter. There are three ways to use the `provider` parameter to supply custom formatting information to the parse operation: - -- You can pass a object that represents the culture that supplies formatting information. Its method returns the object that provides numeric formatting information for that culture. - -- You can pass the actual object that provides numeric formatting information. (Its implementation of just returns itself.) - -- You can pass a custom object that implements . Its method instantiates and returns the object that provides formatting information. - - If `provider` is `null`, the formatting of `value` is interpreted based on the object of the current culture. - - - -## Examples - The following examples show two ways to define the tilde (~) as a negative sign for formatting values. Note that to display the values in the same format as the original strings, your code must call the method and pass it the object that provides formatting information. - - The first example defines a class that implements and uses the method to return the object that provides formatting information. - +> If you use the method to round-trip the string representation of a value that was output by the method, you should use the method with the "R" format specifier to generate the string representation of the value. Otherwise, the string representation of the preserves only the 50 most significant digits of the original value, and data may be lost when you use the method to restore the value. + + The `provider` parameter is an implementation whose method returns a object that provides culture-specific formatting information. When the method is invoked, it calls the `provider` parameter's method and passes it a object that represents the type. The method then returns the object that provides information about the format of the `value` parameter. There are three ways to use the `provider` parameter to supply custom formatting information to the parse operation: + +- You can pass a object that represents the culture that supplies formatting information. Its method returns the object that provides numeric formatting information for that culture. + +- You can pass the actual object that provides numeric formatting information. (Its implementation of just returns itself.) + +- You can pass a custom object that implements . Its method instantiates and returns the object that provides formatting information. + + If `provider` is `null`, the formatting of `value` is interpreted based on the object of the current culture. + + + +## Examples + The following examples show two ways to define the tilde (~) as a negative sign for formatting values. Note that to display the values in the same format as the original strings, your code must call the method and pass it the object that provides formatting information. + + The first example defines a class that implements and uses the method to return the object that provides formatting information. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Parse/System.Numeric.BigInteger.Parse.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Parse/vb/System.Numeric.BigInteger.Parse.vb" id="Snippet2"::: - - A object can then be instantiated with the following code: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Parse/vb/System.Numeric.BigInteger.Parse.vb" id="Snippet2"::: + + A object can then be instantiated with the following code: + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Parse/System.Numeric.BigInteger.Parse.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Parse/vb/System.Numeric.BigInteger.Parse.vb" id="Snippet3"::: - - The second example is more straightforward. It passes the object that provides formatting information to the `provider` parameter. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Parse/vb/System.Numeric.BigInteger.Parse.vb" id="Snippet3"::: + + The second example is more straightforward. It passes the object that provides formatting information to the `provider` parameter. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Parse/System.Numeric.BigInteger.Parse.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Parse/vb/System.Numeric.BigInteger.Parse.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Parse/vb/System.Numeric.BigInteger.Parse.vb" id="Snippet4"::: + ]]> @@ -8862,10 +8745,10 @@ If `provider` is `null`, the object ]]> - is not a value. - - -or- - + is not a value. + + -or- + includes the or flag along with another value. is . @@ -8936,97 +8819,97 @@ If `provider` is `null`, the object Converts the string representation of a number in a specified style and culture-specific format to its equivalent. A value that is equivalent to the number specified in the parameter. - enumeration. The `style` parameter makes this method overload useful when `value` contains the string representation of a hexadecimal value, when the number system (decimal or hexadecimal) represented by `value` is known only at run time, or when you want to disallow white space or a sign symbol in `value`. - - Depending on the value of `style`, the `value` parameter may include the following elements: - - [*ws*][*$*][*sign*][*digits*,]*digits*[*.fractional_digits*][E[*sign*]*exponential_digits*][*ws*] - - If `style` includes , the `value` parameter may include the following elements: - - [*ws*]*hexdigits*[*ws*] - - Elements in square brackets ([ and ]) are optional. The following table describes each element. - -|Element|Description| -|-------------|-----------------| -|*ws*|Optional white space. White space can appear at the start of `value` if `style` includes the flag, and it can appear at the end of `value` if `style` includes the flag.| -|*$*|A culture-specific currency symbol. Its position in the string is defined by the and properties of the culture indicated by the `provider` parameter. The current culture's currency symbol can appear in `value` if `style` includes the flag.| -|*sign*|An optional sign. The sign can appear at the start of `value` if `style` includes the flag, and it can appear at the end of `value` if `style` includes the flag. Parentheses can be used in `value` to indicate a negative value if `style` includes the flag.| -|*digits*

*fractional_digits*

*exponential_digits*|A sequence of digits from 0 through 9. For *fractional_digits*, only the digit 0 is valid.| -|*,*|A culture-specific group separator symbol. The group separator symbol of the culture specified by `provider` can appear in `value` if `style` includes the flag.| -|*.*|A culture-specific decimal point symbol. The decimal point symbol of the culture designated by `provider` can appear in `value` if `style` includes the flag. Only the digit 0 can appear as a fractional digit for the parse operation to succeed; if *fractional_digits* includes any other digit, a is thrown.| -|E|The "e" or "E" character, which indicates that the value is represented in exponential (scientific) notation. The `value` parameter can represent a number in exponential notation if `style` includes the flag.| -|*hexdigits*|A sequence of hexadecimal digits from 0 through f, or 0 through F.| - + enumeration. The `style` parameter makes this method overload useful when `value` contains the string representation of a hexadecimal value, when the number system (decimal or hexadecimal) represented by `value` is known only at run time, or when you want to disallow white space or a sign symbol in `value`. + + Depending on the value of `style`, the `value` parameter may include the following elements: + + [*ws*][*$*][*sign*][*digits*,]*digits*[*.fractional_digits*][E[*sign*]*exponential_digits*][*ws*] + + If `style` includes , the `value` parameter may include the following elements: + + [*ws*]*hexdigits*[*ws*] + + Elements in square brackets ([ and ]) are optional. The following table describes each element. + +|Element|Description| +|-------------|-----------------| +|*ws*|Optional white space. White space can appear at the start of `value` if `style` includes the flag, and it can appear at the end of `value` if `style` includes the flag.| +|*$*|A culture-specific currency symbol. Its position in the string is defined by the and properties of the culture indicated by the `provider` parameter. The current culture's currency symbol can appear in `value` if `style` includes the flag.| +|*sign*|An optional sign. The sign can appear at the start of `value` if `style` includes the flag, and it can appear at the end of `value` if `style` includes the flag. Parentheses can be used in `value` to indicate a negative value if `style` includes the flag.| +|*digits*

*fractional_digits*

*exponential_digits*|A sequence of digits from 0 through 9. For *fractional_digits*, only the digit 0 is valid.| +|*,*|A culture-specific group separator symbol. The group separator symbol of the culture specified by `provider` can appear in `value` if `style` includes the flag.| +|*.*|A culture-specific decimal point symbol. The decimal point symbol of the culture designated by `provider` can appear in `value` if `style` includes the flag. Only the digit 0 can appear as a fractional digit for the parse operation to succeed; if *fractional_digits* includes any other digit, a is thrown.| +|E|The "e" or "E" character, which indicates that the value is represented in exponential (scientific) notation. The `value` parameter can represent a number in exponential notation if `style` includes the flag.| +|*hexdigits*|A sequence of hexadecimal digits from 0 through f, or 0 through F.| + > [!NOTE] > Any terminating NUL (U+0000) characters in `s` are ignored by the parsing operation, regardless of the value of the `style` argument. - A string with digits only (which corresponds to the style) always parses successfully. Most of the remaining members control elements that may be present, but are not required to be present, in the input string. The following table indicates how individual members affect the elements that may be present in `value`. - -|NumberStyles value|Elements permitted in value in addition to digits| -|------------------------|-------------------------------------------------------| -||The *digits* element only.| -||The decimal point (.) and *fractional-digits* elements.| -||The "e" or "E" character, which indicates exponential notation. along with *exponential_digits*.| -||The *ws* element at the start of `value`.| -||The *ws* element at the end of `value`.| -||The *sign* element at the start of `value`.| -||The *sign* element at the end of `value`.| -||The *sign* element in the form of parentheses enclosing the numeric value.| -||The group separator (,) element.| -||The currency ($) element.| -||All elements. However, `value` cannot represent a hexadecimal number or a number in exponential notation.| -||The *ws* element at the start or end of `value`, *sign* at the start of `value`, and the decimal point (.) symbol. The `value` parameter can also use exponential notation.| -||The `ws`, `sign`, group separator (,), and decimal point (.) elements.| -||All elements. However, `value` cannot represent a hexadecimal number.| - + A string with digits only (which corresponds to the style) always parses successfully. Most of the remaining members control elements that may be present, but are not required to be present, in the input string. The following table indicates how individual members affect the elements that may be present in `value`. + +|NumberStyles value|Elements permitted in value in addition to digits| +|------------------------|-------------------------------------------------------| +||The *digits* element only.| +||The decimal point (.) and *fractional-digits* elements.| +||The "e" or "E" character, which indicates exponential notation. along with *exponential_digits*.| +||The *ws* element at the start of `value`.| +||The *ws* element at the end of `value`.| +||The *sign* element at the start of `value`.| +||The *sign* element at the end of `value`.| +||The *sign* element in the form of parentheses enclosing the numeric value.| +||The group separator (,) element.| +||The currency ($) element.| +||All elements. However, `value` cannot represent a hexadecimal number or a number in exponential notation.| +||The *ws* element at the start or end of `value`, *sign* at the start of `value`, and the decimal point (.) symbol. The `value` parameter can also use exponential notation.| +||The `ws`, `sign`, group separator (,), and decimal point (.) elements.| +||All elements. However, `value` cannot represent a hexadecimal number.| + > [!IMPORTANT] -> If you use the method to round-trip the string representation of a value that was output by the method, you should use the method with the "R" format specifier to generate the string representation of the value. Otherwise, the string representation of the preserves only the 50 most significant digits of the original value, and data may be lost when you use the method to restore the value. - - Unlike the other values, which allow for but do not require the presence of particular style elements in `value`, the style value means that the individual numeric characters in `value` are always interpreted as hexadecimal characters. Valid hexadecimal characters are 0-9, A-F, and a-f. The only other flags that can be combined with the `style` parameter are and . (The enumeration includes a composite number style, , that includes both white-space flags.) - +> If you use the method to round-trip the string representation of a value that was output by the method, you should use the method with the "R" format specifier to generate the string representation of the value. Otherwise, the string representation of the preserves only the 50 most significant digits of the original value, and data may be lost when you use the method to restore the value. + + Unlike the other values, which allow for but do not require the presence of particular style elements in `value`, the style value means that the individual numeric characters in `value` are always interpreted as hexadecimal characters. Valid hexadecimal characters are 0-9, A-F, and a-f. The only other flags that can be combined with the `style` parameter are and . (The enumeration includes a composite number style, , that includes both white-space flags.) + > [!NOTE] -> If `value` is the string representation of a hexadecimal number, it cannot be preceded by any decoration (such as `0x` or `&h`) that differentiates it as a hexadecimal number. This causes the conversion to fail. - - If `value` is a hexadecimal string, the method interprets `value` as a negative number stored by using two's complement representation if its first two hexadecimal digits are greater than or equal to `0x80`. In other words, the method interprets the highest-order bit of the first byte in `value` as the sign bit. To make sure that a hexadecimal string is correctly interpreted as a positive number, the first digit in `value` must have a value of zero. For example, the method interprets `0x80` as a negative value, but it interprets either `0x080` or `0x0080` as a positive value. The following example illustrates the difference between hexadecimal strings that represent negative and positive values. - +> If `value` is the string representation of a hexadecimal number, it cannot be preceded by any decoration (such as `0x` or `&h`) that differentiates it as a hexadecimal number. This causes the conversion to fail. + + If `value` is a hexadecimal string, the method interprets `value` as a negative number stored by using two's complement representation if its first two hexadecimal digits are greater than or equal to `0x80`. In other words, the method interprets the highest-order bit of the first byte in `value` as the sign bit. To make sure that a hexadecimal string is correctly interpreted as a positive number, the first digit in `value` must have a value of zero. For example, the method interprets `0x80` as a negative value, but it interprets either `0x080` or `0x0080` as a positive value. The following example illustrates the difference between hexadecimal strings that represent negative and positive values. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Parse/ParseHex1.cs" interactive="try-dotnet" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Parse/vb/ParseHex1.vb" id="Snippet3"::: - The `provider` parameter is an implementation. Its method returns a object that provides culture-specific information about the format of `value`. Typically, `provider` can be any one of the following: - -- A object that represents the culture that provides numeric formatting information. Its method returns the object that provides numeric formatting information. - -- A object that provides formatting information. (Its implementation of just returns itself.) - -- A custom object that implements and uses the method to instantiate and return the object that provides formatting information. - - If `provider` is `null`, the object for the current culture is used. - - - -## Examples - The following example makes several calls to the method using various combinations of values for the `style` and `provider` parameters. - + The `provider` parameter is an implementation. Its method returns a object that provides culture-specific information about the format of `value`. Typically, `provider` can be any one of the following: + +- A object that represents the culture that provides numeric formatting information. Its method returns the object that provides numeric formatting information. + +- A object that provides formatting information. (Its implementation of just returns itself.) + +- A custom object that implements and uses the method to instantiate and return the object that provides formatting information. + + If `provider` is `null`, the object for the current culture is used. + + + +## Examples + The following example makes several calls to the method using various combinations of values for the `style` and `provider` parameters. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Parse/Parse1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Parse/vb/Parse1.vb" id="Snippet2"::: - - A number of the individual calls to the method pass an instance of the following `BigIntegerFormatProvider` class, which defines a tilde (~) as the negative sign. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Parse/vb/Parse1.vb" id="Snippet2"::: + + A number of the individual calls to the method pass an instance of the following `BigIntegerFormatProvider` class, which defines a tilde (~) as the negative sign. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Parse/Parse1.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Parse/vb/Parse1.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Parse/vb/Parse1.vb" id="Snippet4"::: + ]]> - is not a value. - - -or- - + is not a value. + + -or- + includes the or flag along with another value. is . @@ -9113,21 +8996,21 @@ If `provider` is `null`, the object Raises a value to the power of a specified value. The result of raising to the power. - method returns 1 if the value of the exponent parameter is 0, or if the values of both the `value` and `exponent` parameters are 0. If `exponent` is 1, the method returns `value`. If `value` is negative, the method returns a negative result. - - This method corresponds to the method for primitive numeric types. - - - -## Examples - The following example illustrates exponentiation using a value and an exponent whose value ranges from 0 to 10. - + method returns 1 if the value of the exponent parameter is 0, or if the values of both the `value` and `exponent` parameters are 0. If `exponent` is 1, the method returns `value`. If `value` is negative, the method returns a negative result. + + This method corresponds to the method for primitive numeric types. + + + +## Examples + The following example illustrates exponentiation using a value and an exponent whose value ranges from 0 to 10. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/GreatestCommonDivisor/BigInteger_Examples.cs" id="Snippet32"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet32"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb" id="Snippet32"::: + ]]> @@ -9182,23 +9065,23 @@ If `provider` is `null`, the object Performs integer division on two values and returns the remainder. The remainder after dividing by . - method is implemented for languages that do not support custom operators. Its behavior is identical to division using the modulus operator. - - If necessary, the method automatically performs implicit conversion of other integral types to objects before it performs the modulus operation. - - - -## Examples - The following example compares the remainder from the method with the remainder returned by the method to establish that the two methods calculate identical remainders. - + method is implemented for languages that do not support custom operators. Its behavior is identical to division using the modulus operator. + + If necessary, the method automatically performs implicit conversion of other integral types to objects before it performs the modulus operation. + + + +## Examples + The following example compares the remainder from the method with the remainder returned by the method to establish that the two methods calculate identical remainders. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Remainder/Remainder1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Remainder/vb/Remainder1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Remainder/vb/Remainder1.vb" id="Snippet1"::: + ]]> @@ -9317,31 +9200,31 @@ If `provider` is `null`, the object Gets a number that indicates the sign (negative, positive, or zero) of the current object. - A number that indicates the sign of the object, as shown in the following table. - - Number - - Description - - -1 - - The value of this object is negative. - - 0 - - The value of this object is 0 (zero). - - 1 - - The value of this object is positive. - + A number that indicates the sign of the object, as shown in the following table. + + Number + + Description + + -1 + + The value of this object is negative. + + 0 + + The value of this object is 0 (zero). + + 1 + + The value of this object is positive. + - property is equivalent to the method for the primitive numeric types. - + property is equivalent to the method for the primitive numeric types. + ]]> @@ -9394,16 +9277,16 @@ If `provider` is `null`, the object Subtracts one value from another and returns the result. The result of subtracting from . - method to perform subtraction using values. - - The method is a useful substitute for the subtraction operator when instantiating a variable by assigning it the difference that results from subtraction, as shown in the following example. - + method to perform subtraction using values. + + The method is a useful substitute for the subtraction operator when instantiating a variable by assigning it the difference that results from subtraction, as shown in the following example. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/Add/Multiply1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.OperationMethods/vb/Multiply1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.OperationMethods/vb/Multiply1.vb" id="Snippet3"::: + ]]> @@ -10820,33 +10703,33 @@ The following example calls the Converts a value to a byte array. The value of the current object converted to an array of bytes. - value, the second byte reflects the next eight bits, and so on. For example, the value 1024, or 0x0400, is stored as the following array of two bytes: - -|Element|Byte value| -|-------------|----------------| -|0|0x00| -|1|0x04| - - Negative values are written to the array using two's complement representation in the most compact form possible. For example, -1 is represented as a single byte whose value is `0xFF` instead of as an array with multiple elements, such as `0xFF`, `0xFF` or `0xFF`, `0xFF`, `0xFF`, `0xFF`. - - Because two's complement representation always interprets the highest-order bit of the last byte in the array (the byte at position `- 1`) as the sign bit, the method returns a byte array with an extra element whose value is zero to disambiguate positive values that could otherwise be interpreted as having their sign bits set. For example, the value 120 or `0x78` is represented as a single-byte array: `0x78`. However, 128, or `0x80`, is represented as a two-byte array: `0x80`, `0x00`. - - You can round-trip a value by storing it to a byte array and then restoring it using the constructor. - + value, the second byte reflects the next eight bits, and so on. For example, the value 1024, or 0x0400, is stored as the following array of two bytes: + +|Element|Byte value| +|-------------|----------------| +|0|0x00| +|1|0x04| + + Negative values are written to the array using two's complement representation in the most compact form possible. For example, -1 is represented as a single byte whose value is `0xFF` instead of as an array with multiple elements, such as `0xFF`, `0xFF` or `0xFF`, `0xFF`, `0xFF`, `0xFF`. + + Because two's complement representation always interprets the highest-order bit of the last byte in the array (the byte at position `- 1`) as the sign bit, the method returns a byte array with an extra element whose value is zero to disambiguate positive values that could otherwise be interpreted as having their sign bits set. For example, the value 120 or `0x78` is represented as a single-byte array: `0x78`. However, 128, or `0x80`, is represented as a two-byte array: `0x80`, `0x00`. + + You can round-trip a value by storing it to a byte array and then restoring it using the constructor. + > [!CAUTION] -> If your code modifies the value of individual bytes in the array returned by this method before it restores the value, you must make sure that you do not unintentionally change the sign bit. For example, if your modifications increase a positive value so that the highest-order bit in the last element of the byte array becomes set, you can add a new byte whose value is zero to the end of the array. - - - -## Examples - The following example illustrates how some values are represented in byte arrays. - +> If your code modifies the value of individual bytes in the array returned by this method before it restores the value, you must make sure that you do not unintentionally change the sign bit. For example, if your modifications increase a positive value so that the highest-order bit in the last element of the byte array becomes set, you can add a new byte whose value is zero to the end of the array. + + + +## Examples + The following example illustrates how some values are represented in byte arrays. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/ToByteArray/ToByteArray1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ToByteArray/vb/ToByteArray1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ToByteArray/vb/ToByteArray1.vb" id="Snippet1"::: + ]]> @@ -10966,27 +10849,27 @@ The integer value `33022` can be exported in four different arrays: Converts the numeric value of the current object to its equivalent string representation. The string representation of the current value. - method formats a value in the "R", or round-trip, format of the current culture. If you want to specify a different format or culture, use the other overloads of the method, as follows: - -|To use format|For culture|Use the overload| -|-------------------|-----------------|----------------------| -|Round-trip ("R") format|A specific culture|| -|A specific format|Default (current) culture|| -|A specific format|A specific culture|| - - The string representation of the value includes a negative sign if its value is negative, and a sequence of digits ranging from 0 to 9 without leading zeros. The negative sign is defined by the object for the current culture. - - - -## Examples - The following example displays a value by using the default method. It also displays the string representations of the value that results from using some standard format specifiers. The examples are displayed using the formatting conventions of the en-US culture. - + method formats a value in the "R", or round-trip, format of the current culture. If you want to specify a different format or culture, use the other overloads of the method, as follows: + +|To use format|For culture|Use the overload| +|-------------------|-----------------|----------------------| +|Round-trip ("R") format|A specific culture|| +|A specific format|Default (current) culture|| +|A specific format|A specific culture|| + + The string representation of the value includes a negative sign if its value is negative, and a sequence of digits ranging from 0 to 9 without leading zeros. The negative sign is defined by the object for the current culture. + + + +## Examples + The following example displays a value by using the default method. It also displays the string representations of the value that results from using some standard format specifiers. The examples are displayed using the formatting conventions of the en-US culture. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/ToString/ToString1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ToString/vb/ToString1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ToString/vb/ToString1.vb" id="Snippet1"::: + ]]> Standard Numeric Format Strings @@ -11047,35 +10930,35 @@ The integer value `33022` can be exported in four different arrays: Converts the numeric value of the current object to its equivalent string representation by using the specified culture-specific formatting information. The string representation of the current value in the format specified by the parameter. - method formats a value in the "R", or round-trip, format by using the object of a specified culture. If you want to specify a different format or the current culture, use the other overloads of the method, as follows: - -|To use format|For culture|Use the overload| -|-------------------|-----------------|----------------------| -|Round-trip ("R") format|Default (current) culture|| -|A specific format|Default (current) culture|| -|A specific format|A specific culture|| - - The `provider` parameter is an implementation. Its method returns a object that provides culture-specific information about the format of the string returned by this method. If `provider` is `null`, the value is formatted using the object of the current culture. The only property of the object that controls the string representation of the value using the general format specifier is , which defines the character that represents the negative sign. - - The `provider` parameter can be one of the following: - -- A object that represents the culture that supplies formatting information. - -- The object that supplies formatting information. - -- A custom object that implements . Its method returns the object that supplies formatting information. - - - -## Examples - The following example instantiates a custom object that defines the tilde (~) as a negative sign. The method then uses the custom object to display a negative value. - + method formats a value in the "R", or round-trip, format by using the object of a specified culture. If you want to specify a different format or the current culture, use the other overloads of the method, as follows: + +|To use format|For culture|Use the overload| +|-------------------|-----------------|----------------------| +|Round-trip ("R") format|Default (current) culture|| +|A specific format|Default (current) culture|| +|A specific format|A specific culture|| + + The `provider` parameter is an implementation. Its method returns a object that provides culture-specific information about the format of the string returned by this method. If `provider` is `null`, the value is formatted using the object of the current culture. The only property of the object that controls the string representation of the value using the general format specifier is , which defines the character that represents the negative sign. + + The `provider` parameter can be one of the following: + +- A object that represents the culture that supplies formatting information. + +- The object that supplies formatting information. + +- A custom object that implements . Its method returns the object that supplies formatting information. + + + +## Examples + The following example instantiates a custom object that defines the tilde (~) as a negative sign. The method then uses the custom object to display a negative value. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/ToString/System.Numeric.BigInteger.ToString.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.ToString/vb/System.Numeric.BigInteger.ToString.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.ToString/vb/System.Numeric.BigInteger.ToString.vb" id="Snippet1"::: + ]]> @@ -11138,35 +11021,35 @@ The integer value `33022` can be exported in four different arrays: Converts the numeric value of the current object to its equivalent string representation by using the specified format. The string representation of the current value in the format specified by the parameter. - method formats a value in a specified format by using a object that represents the conventions of the current culture. If you want to use the "R", or round-trip, format or specify a different culture, use the other overloads of the method, as follows: - -|To use format|For culture|Use the overload| -|-------------------|-----------------|----------------------| -|Round-trip ("R") format|Default (current) culture|| -|Round-trip ("R") format|A specific culture|| -|A specific format|A specific culture|| - - The `format` parameter can be any valid [standard numeric string](/dotnet/standard/base-types/standard-numeric-format-strings), or any combination of [custom numeric format strings](/dotnet/standard/base-types/custom-numeric-format-strings). If `format` is equal to or is `null`, the return value of the current object is formatted with the round-trip format specifier ("R"). If `format` is any other value, the method throws a . - -.NET provides extensive formatting support, which is described in greater detail in the following formatting topics: - -- For more information about numeric format specifiers, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). - -- For more information about support for formatting in .NET, see [Formatting Types](/dotnet/standard/base-types/formatting-types). - - The format of the returned string is determined by the object for the current culture. Depending on the `format` parameter, this object controls symbols such as the negative sign, the group separator, and the decimal point symbol in the output string. To provide formatting information for cultures other than the current culture, call the overload. - - - -## Examples - The following example initializes a value and displays it by using each standard format string and some custom format strings. - + method formats a value in a specified format by using a object that represents the conventions of the current culture. If you want to use the "R", or round-trip, format or specify a different culture, use the other overloads of the method, as follows: + +|To use format|For culture|Use the overload| +|-------------------|-----------------|----------------------| +|Round-trip ("R") format|Default (current) culture|| +|Round-trip ("R") format|A specific culture|| +|A specific format|A specific culture|| + + The `format` parameter can be any valid [standard numeric string](/dotnet/standard/base-types/standard-numeric-format-strings), or any combination of [custom numeric format strings](/dotnet/standard/base-types/custom-numeric-format-strings). If `format` is equal to or is `null`, the return value of the current object is formatted with the round-trip format specifier ("R"). If `format` is any other value, the method throws a . + +.NET provides extensive formatting support, which is described in greater detail in the following formatting topics: + +- For more information about numeric format specifiers, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). + +- For more information about support for formatting in .NET, see [Formatting Types](/dotnet/standard/base-types/formatting-types). + + The format of the returned string is determined by the object for the current culture. Depending on the `format` parameter, this object controls symbols such as the negative sign, the group separator, and the decimal point symbol in the output string. To provide formatting information for cultures other than the current culture, call the overload. + + + +## Examples + The following example initializes a value and displays it by using each standard format string and some custom format strings. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/ToString/ToString1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ToString/vb/ToString1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ToString/vb/ToString1.vb" id="Snippet3"::: + ]]> @@ -11234,43 +11117,43 @@ The integer value `33022` can be exported in four different arrays: Converts the numeric value of the current object to its equivalent string representation by using the specified format and culture-specific format information. The string representation of the current value as specified by the and parameters. - method formats a value in a specified format by using the object of a specified culture. If you want to use the round-trip format or default culture settings, use the other overloads of the method, as follows: - -|To use format|For culture|Use the overload| -|-------------------|-----------------|----------------------| -|Round-trip ("R") format|Default (current) culture|| -|Round-trip ("R") format|A specific culture|| -|A specific format|Default (current) culture|| - - The `format` parameter can be any valid [standard numeric string](/dotnet/standard/base-types/standard-numeric-format-strings), or any combination of [custom numeric format strings](/dotnet/standard/base-types/custom-numeric-format-strings). If `format` is equal to or is `null`, the return value of the current object is formatted with the round-trip format specifier ("R"). If `format` is any other value, the method throws a . - -.NET provides extensive formatting support, which is described in greater detail in the following formatting topics: - -- For more information about numeric format specifiers, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). - -- For more information about support for formatting in .NET, see [Formatting Types](/dotnet/standard/base-types/formatting-types). - - The `provider` parameter is an implementation. Its method returns a object that provides culture-specific information about the format of the string returned by this method. When the method is invoked, it calls the `provider` parameter's method and passes it a object that represents the type. The method then returns the object that provides information for formatting the `value` parameter, such as the negative sign symbol, the group separator symbol, or the decimal point symbol. There are three ways to use the `provider` parameter to supply formatting information to the method: - -- You can pass a object that represents the culture that supplies formatting information. Its method returns the object that provides numeric formatting information for that culture. - -- You can pass the actual object that provides numeric formatting information. (Its implementation of just returns itself.) - -- You can pass a custom object that implements . Its method instantiates and returns the object that provides formatting information. - - If `provider` is `null`, the formatting of the returned string is based on the object of the current culture. - - - -## Examples - The following example initializes a value, and displays it to the console using a standard format string and a object that defines the tilde (~) as a negative sign. - + method formats a value in a specified format by using the object of a specified culture. If you want to use the round-trip format or default culture settings, use the other overloads of the method, as follows: + +|To use format|For culture|Use the overload| +|-------------------|-----------------|----------------------| +|Round-trip ("R") format|Default (current) culture|| +|Round-trip ("R") format|A specific culture|| +|A specific format|Default (current) culture|| + + The `format` parameter can be any valid [standard numeric string](/dotnet/standard/base-types/standard-numeric-format-strings), or any combination of [custom numeric format strings](/dotnet/standard/base-types/custom-numeric-format-strings). If `format` is equal to or is `null`, the return value of the current object is formatted with the round-trip format specifier ("R"). If `format` is any other value, the method throws a . + +.NET provides extensive formatting support, which is described in greater detail in the following formatting topics: + +- For more information about numeric format specifiers, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). + +- For more information about support for formatting in .NET, see [Formatting Types](/dotnet/standard/base-types/formatting-types). + + The `provider` parameter is an implementation. Its method returns a object that provides culture-specific information about the format of the string returned by this method. When the method is invoked, it calls the `provider` parameter's method and passes it a object that represents the type. The method then returns the object that provides information for formatting the `value` parameter, such as the negative sign symbol, the group separator symbol, or the decimal point symbol. There are three ways to use the `provider` parameter to supply formatting information to the method: + +- You can pass a object that represents the culture that supplies formatting information. Its method returns the object that provides numeric formatting information for that culture. + +- You can pass the actual object that provides numeric formatting information. (Its implementation of just returns itself.) + +- You can pass a custom object that implements . Its method instantiates and returns the object that provides formatting information. + + If `provider` is `null`, the formatting of the returned string is based on the object of the current culture. + + + +## Examples + The following example initializes a value, and displays it to the console using a standard format string and a object that defines the tilde (~) as a negative sign. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/ToString/ToString1.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ToString/vb/ToString1.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.ToString/vb/ToString1.vb" id="Snippet4"::: + ]]> @@ -11488,40 +11371,40 @@ The integer value `33022` can be exported in four different arrays: if was converted successfully; otherwise, . - method is like the method, except that it does not throw an exception if the conversion fails. This method eliminates the need to use exception handling to test for a if `value` is invalid and cannot be successfully parsed. - - The `value` parameter should be the string representation of a decimal number in the following form: - - [*ws*][*sign*]*digits*[*ws*] - - Elements in square brackets ([ and ]) are optional. The following table describes each element. - -|Element|Description| -|-------------|-----------------| -|*ws*|Optional white space.| -|*sign*|An optional sign. Valid sign characters are determined by the and properties of the current culture.| -|*digits*|A sequence of decimal digits ranging from 0 to 9.| - + method is like the method, except that it does not throw an exception if the conversion fails. This method eliminates the need to use exception handling to test for a if `value` is invalid and cannot be successfully parsed. + + The `value` parameter should be the string representation of a decimal number in the following form: + + [*ws*][*sign*]*digits*[*ws*] + + Elements in square brackets ([ and ]) are optional. The following table describes each element. + +|Element|Description| +|-------------|-----------------| +|*ws*|Optional white space.| +|*sign*|An optional sign. Valid sign characters are determined by the and properties of the current culture.| +|*digits*|A sequence of decimal digits ranging from 0 to 9.| + > [!NOTE] -> The string specified by the `value` parameter cannot contain any group separators or decimal separator, and it cannot have a decimal portion. - - The `value` parameter is interpreted by using the style. In addition to the decimal digits, only leading and trailing spaces with a leading sign are allowed. To explicitly define the style elements with the culture-specific formatting information that can be present in `value`, call the method. - - The `value` parameter is parsed by using the formatting information in a object for the current culture. For more information, see . - - This overload interprets all digits in the `value` parameter as decimal digits. To parse the string representation of a hexadecimal number, call the overload instead. - - - -## Examples - The following example uses the method to instantiate two objects. If the conversions succeed, it multiplies each object by another number and then calls the method to determine the relationship between the two objects. - +> The string specified by the `value` parameter cannot contain any group separators or decimal separator, and it cannot have a decimal portion. + + The `value` parameter is interpreted by using the style. In addition to the decimal digits, only leading and trailing spaces with a leading sign are allowed. To explicitly define the style elements with the culture-specific formatting information that can be present in `value`, call the method. + + The `value` parameter is parsed by using the formatting information in a object for the current culture. For more information, see . + + This overload interprets all digits in the `value` parameter as decimal digits. To parse the string representation of a hexadecimal number, call the overload instead. + + + +## Examples + The following example uses the method to instantiate two objects. If the conversions succeed, it multiplies each object by another number and then calls the method to determine the relationship between the two objects. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/TryParse/System.Numeric.BigInteger.TryParse.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.TryParse/vb/System.Numeric.BigInteger.TryParse.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.TryParse/vb/System.Numeric.BigInteger.TryParse.vb" id="Snippet1"::: + ]]> @@ -11741,10 +11624,10 @@ If `provider` is `null`, the object ]]> - is not a value. - - -or- - + is not a value. + + -or- + includes the or flag along with another value. @@ -11811,99 +11694,99 @@ If `provider` is `null`, the object if the parameter was converted successfully; otherwise, . - method is like the method, except that it does not throw an exception if the conversion fails. This method eliminates the need to use exception handling to test for a if `value` is invalid and cannot be parsed successfully. - - The `style` parameter defines the style elements (such as white space or a positive or negative sign) that are allowed in the `value` parameter for the parse operation to succeed. It must be a combination of bit flags from the enumeration. Depending on the value of `style`, the `value` parameter may include the following elements: - - [*ws*][*$*][*sign*][*digits*,]*digits*[.*fractional_digits*][E[*sign*]*exponential_digits*][*ws*] - - If the `style` parameter includes , the `value` parameter may include the following elements: - - [*ws*]*hexdigits*[*ws*] - - Elements in square brackets ([ and ]) are optional. The following table describes each element. - -|Element|Description| -|-------------|-----------------| -|*ws*|Optional white space. White space can appear at the start of `value` if `style` includes the flag, or at the end of `value` if `style` includes the flag.| -|*$*|A culture-specific currency symbol. Its position in the string is defined by the property of the object returned by the method of the `provider` parameter. The currency symbol can appear in `value` if `style` includes the flag.| -|*sign*|An optional sign. The sign can appear at the start of `value` if `style` includes the flag, and it can appear at the end of `value` if `style` includes the flag. Parentheses can be used in `value` to indicate a negative value if `style` includes the flag.| -|*digits*|A sequence of digits from 0 through 9.| -|*,*|A culture-specific group separator. The group separator of the culture specified by `provider` can appear in `value` if `style` includes the flag.| -|*.*|A culture-specific decimal point symbol. The decimal point symbol of the culture specified by `provider` can appear in `value` if `style` includes the flag.| -|*fractional_digits*|One or more occurrences of the digit 0. Fractional digits can appear in `value` only if `style` includes the flag.| -|E|The "e" or "E" character, which indicates that the value is represented in exponential (scientific) notation. The `value` parameter can represent a number in exponential notation if `style` includes the flag.| -|*exponential_digits*|A sequence of digits from 0 through 9. The `value` parameter can represent a number in exponential notation if `style` includes the flag.| -|*hexdigits*|A sequence of hexadecimal digits from 0 through f, or 0 through F.| - + method is like the method, except that it does not throw an exception if the conversion fails. This method eliminates the need to use exception handling to test for a if `value` is invalid and cannot be parsed successfully. + + The `style` parameter defines the style elements (such as white space or a positive or negative sign) that are allowed in the `value` parameter for the parse operation to succeed. It must be a combination of bit flags from the enumeration. Depending on the value of `style`, the `value` parameter may include the following elements: + + [*ws*][*$*][*sign*][*digits*,]*digits*[.*fractional_digits*][E[*sign*]*exponential_digits*][*ws*] + + If the `style` parameter includes , the `value` parameter may include the following elements: + + [*ws*]*hexdigits*[*ws*] + + Elements in square brackets ([ and ]) are optional. The following table describes each element. + +|Element|Description| +|-------------|-----------------| +|*ws*|Optional white space. White space can appear at the start of `value` if `style` includes the flag, or at the end of `value` if `style` includes the flag.| +|*$*|A culture-specific currency symbol. Its position in the string is defined by the property of the object returned by the method of the `provider` parameter. The currency symbol can appear in `value` if `style` includes the flag.| +|*sign*|An optional sign. The sign can appear at the start of `value` if `style` includes the flag, and it can appear at the end of `value` if `style` includes the flag. Parentheses can be used in `value` to indicate a negative value if `style` includes the flag.| +|*digits*|A sequence of digits from 0 through 9.| +|*,*|A culture-specific group separator. The group separator of the culture specified by `provider` can appear in `value` if `style` includes the flag.| +|*.*|A culture-specific decimal point symbol. The decimal point symbol of the culture specified by `provider` can appear in `value` if `style` includes the flag.| +|*fractional_digits*|One or more occurrences of the digit 0. Fractional digits can appear in `value` only if `style` includes the flag.| +|E|The "e" or "E" character, which indicates that the value is represented in exponential (scientific) notation. The `value` parameter can represent a number in exponential notation if `style` includes the flag.| +|*exponential_digits*|A sequence of digits from 0 through 9. The `value` parameter can represent a number in exponential notation if `style` includes the flag.| +|*hexdigits*|A sequence of hexadecimal digits from 0 through f, or 0 through F.| + > [!NOTE] > Any terminating NUL (U+0000) characters in `s` are ignored by the parsing operation, regardless of the value of the `style` argument. - A string with decimal digits only (which corresponds to the flag) always parses successfully. Most of the remaining members control elements that may be present, but are not required to be present, in this input string. The following table indicates how individual members affect the elements that may be present in `value`. - -|Non-composite `NumberStyles` values|Elements permitted in value in addition to digits| -|------------------------------------------|-------------------------------------------------------| -||Decimal digits only.| -||The decimal point (*.*) and *fractional_digits* elements. However, *fractional_digits* must consist of only one or more 0 digits, or the method returns `false`.| -||The "e" or "E" character, which indicates exponential notation, along with *exponential_digits*. If `value` represents a number in exponential notation, it cannot have a non-zero, fractional component.| -||The *ws* element at the start of `value`.| -||The *ws* element at the end of `value`.| -||The *sign* element before *digits*.| -||The *sign* element after *digits*.| -||The *sign* element in the form of parentheses enclosing the numeric value.| -||The group separator (*,*) element.| -||The currency (*$*) element.| -||All elements. However, `value` cannot represent a hexadecimal number or a number in exponential notation.| -||The *ws* element at the start or end of `value`, *sign* at the start of `value`, and the decimal point (*.*) symbol. The `value` parameter can also use exponential notation.| -||The *ws*, *sign*, group separator (*,*), and decimal point (*.*) elements.| -||All elements. However, `value` cannot represent a hexadecimal number.| - + A string with decimal digits only (which corresponds to the flag) always parses successfully. Most of the remaining members control elements that may be present, but are not required to be present, in this input string. The following table indicates how individual members affect the elements that may be present in `value`. + +|Non-composite `NumberStyles` values|Elements permitted in value in addition to digits| +|------------------------------------------|-------------------------------------------------------| +||Decimal digits only.| +||The decimal point (*.*) and *fractional_digits* elements. However, *fractional_digits* must consist of only one or more 0 digits, or the method returns `false`.| +||The "e" or "E" character, which indicates exponential notation, along with *exponential_digits*. If `value` represents a number in exponential notation, it cannot have a non-zero, fractional component.| +||The *ws* element at the start of `value`.| +||The *ws* element at the end of `value`.| +||The *sign* element before *digits*.| +||The *sign* element after *digits*.| +||The *sign* element in the form of parentheses enclosing the numeric value.| +||The group separator (*,*) element.| +||The currency (*$*) element.| +||All elements. However, `value` cannot represent a hexadecimal number or a number in exponential notation.| +||The *ws* element at the start or end of `value`, *sign* at the start of `value`, and the decimal point (*.*) symbol. The `value` parameter can also use exponential notation.| +||The *ws*, *sign*, group separator (*,*), and decimal point (*.*) elements.| +||All elements. However, `value` cannot represent a hexadecimal number.| + > [!IMPORTANT] -> If you use the method to round-trip the string representation of a value that was output by the method, you should use the method with the "R" format specifier to generate the string representation of the value. Otherwise, the string representation of the preserves only the 50 most significant digits of the original value, and data may be lost when you use the method to restore the value. - - If the flag is used, `value` must be a hexadecimal value. The only other flags that can be present in `style` are and . (The enumeration has a composite style, , that includes both white-space flags.) - +> If you use the method to round-trip the string representation of a value that was output by the method, you should use the method with the "R" format specifier to generate the string representation of the value. Otherwise, the string representation of the preserves only the 50 most significant digits of the original value, and data may be lost when you use the method to restore the value. + + If the flag is used, `value` must be a hexadecimal value. The only other flags that can be present in `style` are and . (The enumeration has a composite style, , that includes both white-space flags.) + > [!NOTE] -> If `value` is the string representation of a hexadecimal number, it cannot be preceded by any decoration (such as `0x` or `&h`) that differentiates it as a hexadecimal number. This causes the conversion to fail. - - If `value` is a hexadecimal string, the method interprets `value` as a negative number stored by using two's complement representation if its first two hexadecimal digits are greater than or equal to `0x80`. In other words, the method interprets the highest-order bit of the first byte in `value` as the sign bit. To make sure that a hexadecimal string is correctly interpreted as a positive number, the first digit in `value` must have a value of zero. For example, the method interprets `0x80` as a negative value, but it interprets either `0x080` or `0x0080` as a positive value. The following example illustrates the difference between hexadecimal strings that represent negative and positive values. - +> If `value` is the string representation of a hexadecimal number, it cannot be preceded by any decoration (such as `0x` or `&h`) that differentiates it as a hexadecimal number. This causes the conversion to fail. + + If `value` is a hexadecimal string, the method interprets `value` as a negative number stored by using two's complement representation if its first two hexadecimal digits are greater than or equal to `0x80`. In other words, the method interprets the highest-order bit of the first byte in `value` as the sign bit. To make sure that a hexadecimal string is correctly interpreted as a positive number, the first digit in `value` must have a value of zero. For example, the method interprets `0x80` as a negative value, but it interprets either `0x080` or `0x0080` as a positive value. The following example illustrates the difference between hexadecimal strings that represent negative and positive values. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/TryParse/TryParseHex1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.TryParse/vb/TryParseHex1.vb" id="Snippet1"::: - - The `provider` parameter is an implementation. Its method returns a object that provides culture-specific information about the format of `value`. The `provider` parameter can be any one of the following: - -- A object that represents the culture that supplies formatting information. Its method returns the object that provides numeric formatting information for that culture. - -- A object that provides numeric formatting information. (Its implementation of just returns itself.) - -- A custom object that implements . Its method instantiates and returns the object that provides formatting information. - - If `provider` is `null`, the object for the current culture is used. - - - -## Examples - The following example makes some calls to the method using various combinations of values for the `style` and `provider` parameters. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.TryParse/vb/TryParseHex1.vb" id="Snippet1"::: + + The `provider` parameter is an implementation. Its method returns a object that provides culture-specific information about the format of `value`. The `provider` parameter can be any one of the following: + +- A object that represents the culture that supplies formatting information. Its method returns the object that provides numeric formatting information for that culture. + +- A object that provides numeric formatting information. (Its implementation of just returns itself.) + +- A custom object that implements . Its method instantiates and returns the object that provides formatting information. + + If `provider` is `null`, the object for the current culture is used. + + + +## Examples + The following example makes some calls to the method using various combinations of values for the `style` and `provider` parameters. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/TryParse/TryParse1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.TryParse/vb/TryParse1.vb" id="Snippet2"::: - - A number of the individual calls to the method pass an instance of the following `BigIntegerFormatProvider` class, which defines a tilde (~) as the negative sign. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.TryParse/vb/TryParse1.vb" id="Snippet2"::: + + A number of the individual calls to the method pass an instance of the following `BigIntegerFormatProvider` class, which defines a tilde (~) as the negative sign. + :::code language="csharp" source="~/snippets/csharp/System.Numerics/BigInteger/TryParse/TryParse1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.TryParse/vb/TryParse1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.TryParse/vb/TryParse1.vb" id="Snippet3"::: + ]]> - is not a value. - - -or- - + is not a value. + + -or- + includes the or flag along with another value. @@ -12002,11 +11885,11 @@ If `provider` is `null`, the object Gets a value that represents the number 0 (zero). An integer whose value is 0 (zero). - object returned by this property provides a convenient source of a zero value for use in assignments and comparisons. - + object returned by this property provides a convenient source of a zero value for use in assignments and comparisons. + ]]> diff --git a/xml/System.Numerics/Complex.xml b/xml/System.Numerics/Complex.xml index 9de78f1a6c3..529d8c67678 100644 --- a/xml/System.Numerics/Complex.xml +++ b/xml/System.Numerics/Complex.xml @@ -170,105 +170,7 @@ Represents a complex number. - - 2 = -1. The real part of the complex number is represented by *x*, and the imaginary part of the complex number is represented by *y*. - - The type uses the Cartesian coordinate system (real, imaginary) when instantiating and manipulating complex numbers. A complex number can be represented as a point in a two-dimensional coordinate system, which is known as the complex plane. The real part of the complex number is positioned on the x-axis (the horizontal axis), and the imaginary part is positioned on the y-axis (the vertical axis). - - Any point in the complex plane can also be expressed based on its absolute value, by using the polar coordinate system. In polar coordinates, a point is characterized by two numbers: - -- Its magnitude, which is the distance of the point from the origin (that is, 0,0, or the point at which the x-axis and the y-axis intersect). - -- Its phase, which is the angle between the real axis and the line drawn from the origin to the point. - -## Instantiating a Complex Number - You can assign a value to a complex number in one of the following ways: - -- By passing two values to its constructor. The first value represents the real part of the complex number, and the second value represents its imaginary part. These values represent the position of the complex number in the two-dimensional Cartesian coordinate system. - -- By calling the static (`Shared` in Visual Basic) method to create a complex number from its polar coordinates. - -- By assigning a , , , , , , , , , or value to a object. The value becomes the real part of the complex number, and its imaginary part equals 0. - -- By casting (in C#) or converting (in Visual Basic) a or value to a object. The value becomes the real part of the complex number, and its imaginary part equals 0. - -- By assigning the complex number that is returned by a method or operator to a object. For example, is a static method that returns a complex number that is the sum of two complex numbers, and the operator adds two complex numbers and returns the result. - - The following example demonstrates each of these five ways of assigning a value to a complex number. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/Complex/Overview/create1.cs" interactive="try-dotnet" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.class/vb/create1.vb" id="Snippet2"::: - -## Operations with Complex Numbers - The structure in the .NET Framework includes members that provide the following functionality: - -- Methods to compare two complex numbers to determine whether they are equal. - -- Operators to perform arithmetic operations on complex numbers. operators enable you to perform addition, subtraction, multiplication, division, and unary negation with complex numbers. - -- Methods to perform other numerical operations on complex numbers. In addition to the four basic arithmetic operations, you can raise a complex number to a specified power, find the square root of a complex number, and get the absolute value of a complex number. - -- Methods to perform trigonometric operations on complex numbers. For example, you can calculate the tangent of an angle represented by a complex number. - - Note that, because the and properties are read-only, you cannot modify the value of an existing object. All methods that perform an operation on a number, if their return value is of type , return a new number. - -## Precision and Complex Numbers - The real and imaginary parts of a complex number are represented by two double-precision floating-point values. This means that values, like double-precision floating-point values, can lose precision as a result of numerical operations. This means that strict comparisons for equality of two values may fail, even if the difference between the two values is due to a loss of precision. For more information, see . - - For example, performing exponentiation on the logarithm of a number should return the original number. However, in some cases, the loss of precision of floating-point values can cause slight differences between the two values, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/Complex/Overview/precision1.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.class/vb/precision1.vb" id="Snippet5"::: - - Similarly, the following example, which calculates the square root of a number, produces slightly different results on the 32-bit and IA64 versions of the .NET Framework. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/Complex/Overview/precision1.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.class/vb/precision1.vb" id="Snippet6"::: - -## Complex Numbers, Infinity, and NaN - The real and imaginary parts of a complex number are represented by values. In addition to ranging from to , the real or imaginary part of a complex number can have a value of , , or . , , and all propagate in any arithmetic or trigonometric operation. - - In the following example, division by produces a complex number whose real and imaginary parts are both . As a result, performing multiplication with this value also produces a complex number whose real and imaginary parts are . Similarly, performing a multiplication that overflows the range of the type produces a complex number whose real part is and whose imaginary part is . Subsequently performing division with this complex number returns a complex number whose real part is and whose imaginary part is . - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/Complex/Overview/nan1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.class/vb/nan1.vb" id="Snippet3"::: - - Mathematical operations with complex numbers that are invalid or that overflow the range of the data type do not throw an exception. Instead, they return a , , or under the following conditions: - -- The division of a positive number by zero returns . - -- Any operation that overflows the upper bound of the data type returns . - -- The division of a negative number by zero returns . - -- Any operation that overflows the lower bound of the data type returns . - -- The division of a zero by zero returns . - -- Any operation that is performed on operands whose values are , , or returns , , or , depending on the specific operation. - - Note that this applies to any intermediate calculations performed by a method. For example, the multiplication of `new Complex(9e308, 9e308) and new Complex(2.5, 3.5)` uses the formula (ac - bd) + (ad + bc)i. The calculation of the real component that results from the multiplication evaluates the expression 9e308 * 2.5 - 9e308 * 3.5. Each intermediate multiplication in this expression returns , and the attempt to subtract from returns . - -## Formatting a Complex Number - By default, the string representation of a complex number takes the form `(`*real*`,` *imaginary*`)`, where *real* and *imaginary* are the string representations of the values that form the complex number's real and imaginary components. Some overloads of the method allow customization of the string representations of these values to reflect the formatting conventions of a particular culture or to appear in a particular format defined by a standard or custom numeric format string. (For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings).) - - One of the more common ways of expressing the string representation of a complex number takes the form a + bi, where a is the complex number's real component, and b is the complex number's imaginary component. In electrical engineering, a complex number is most commonly expressed as a + bj. You can return the string representation of a complex number in either of these two forms. To do this, define a custom format provider by implementing the and interfaces, and then call the method. - - The following example defines a `ComplexFormatter` class that represents a complex number as a string in the form of either a + bi or a + bj. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/Complex/Overview/customfmt1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.class/vb/customfmt1.vb" id="Snippet1"::: - - The following example then uses this custom formatter to display the string representation of a complex number. - - :::code language="csharp" source="~/snippets/csharp/System.Numerics/Complex/Overview/customfmt1.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.class/vb/customfmt1.vb" id="Snippet4"::: - - ]]> - + For more information about this API, see Supplemental API remarks for Complex. diff --git a/xml/System.Reflection.Emit/AssemblyBuilder.xml b/xml/System.Reflection.Emit/AssemblyBuilder.xml index a9f33e6d329..14ed94ce0d5 100644 --- a/xml/System.Reflection.Emit/AssemblyBuilder.xml +++ b/xml/System.Reflection.Emit/AssemblyBuilder.xml @@ -79,56 +79,17 @@ Defines and represents a dynamic assembly. - + For more information about this API, see Supplemental API remarks for AssemblyBuilder. + to generate dynamic assemblies in memory and execute their code during the same application run. A dynamic assembly can reference types defined in another dynamic or static assembly. - -To get an object, use the method. - -Dynamic assemblies can be created using one of the following access modes: - -- - - The dynamic assembly represented by an can be used to execute the emitted code. - -- - - The dynamic assembly represented by an can be used to execute the emitted code and is automatically reclaimed by garbage collector. - - -The access mode must be specified by providing the appropriate value in the call to the method when the dynamic assembly is defined and cannot be changed later. The runtime uses the access mode of a dynamic assembly to optimize the assembly's internal representation. - -In .NET Framework, you can save dynamic assemblies to files. This feature is not available in .NET Core and .NET 5 and later versions. For an alternative way to generate assembly files, see . - -In .NET Framework, a dynamic assembly can consist of one or more dynamic modules. If a dynamic assembly contains more than one dynamic module, the assembly's manifest file name should match the module's name that is specified as the first argument to the method. In .NET Core and .NET 5+, a dynamic assembly can only consist of one dynamic module. - -### Persistable dynamic assemblies in .NET Framework - -In .NET Framework, dynamic assemblies and modules can be saved to files. To support this feature, the enumeration declares two additional fields: and . The dynamic assembly created using one of these access modes is called a *persistable* assembly, while the regular memory-only assembly is called *transient*. - -The dynamic modules in the persistable dynamic assembly are saved when the dynamic assembly is saved using the method. To generate an executable, the method must be called to identify the method that is the entry point to the assembly. Assemblies are saved as DLLs by default, unless the method requests the generation of a console application or a Windows-based application. - -Some methods on the base class, such as `GetModules` and `GetLoadedModules`, will not work correctly when called from objects. You can load the defined dynamic assembly and call the methods on the loaded assembly. For example, to ensure that resource modules are included in the returned module list, call `GetModules` on the loaded object. - -The signing of a dynamic assembly using is not effective until the assembly is saved to disk. So, strong names will not work with transient dynamic assemblies. - -Dynamic assemblies can reference types defined in another assembly. A transient dynamic assembly can safely reference types defined in another transient dynamic assembly, a persistable dynamic assembly, or a static assembly. However, the common language runtime does not allow a persistable dynamic module to reference a type defined in a transient dynamic module. This is because when the persisted dynamic module is loaded after being saved to disk, the runtime cannot resolve the references to types defined in the transient dynamic module. - -### Restrictions on emitting to remote application domains in .NET Framework - Some scenarios require a dynamic assembly to be created and executed in a remote application domain. Reflection emit does not allow a dynamic assembly to be emitted directly to a remote application domain. The solution is to emit the dynamic assembly in the current application domain, save the emitted dynamic assembly to disk, and then load the dynamic assembly into the remote application domain. The remoting and application domains are supported only in .NET Framework. - -## Examples The following code example shows how to define and use a dynamic assembly. The example assembly contains one type, `MyDynamicType`, that has a private field, a property that gets and sets the private field, constructors that initialize the private field, and a method that multiplies a user-supplied number by the private field value and returns the result. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyBuilderClass/cpp/24895.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/AssemblyBuilder/Overview/24895.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Reflection.Emit/AssemblyBuilder/Overview/24895.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyBuilderClass/vb/24895.vb" id="Snippet1"::: - - ]]> - +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyBuilderClass/cpp/24895.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/AssemblyBuilder/Overview/24895.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System.Reflection.Emit/AssemblyBuilder/Overview/24895.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyBuilderClass/vb/24895.vb" id="Snippet1"::: + ]]> + Emitting Dynamic Methods and Assemblies diff --git a/xml/System.Reflection.Emit/DynamicMethod.xml b/xml/System.Reflection.Emit/DynamicMethod.xml index d26fd573554..e276baa43b8 100644 --- a/xml/System.Reflection.Emit/DynamicMethod.xml +++ b/xml/System.Reflection.Emit/DynamicMethod.xml @@ -53,73 +53,16 @@ Defines and represents a dynamic method that can be compiled, executed, and discarded. Discarded methods are available for garbage collection. - - class to generate and execute a method at run time, without having to generate a dynamic assembly and a dynamic type to contain the method. The executable code created by the just-in-time (JIT) compiler is reclaimed when the object is reclaimed. Dynamic methods are the most efficient way to generate and execute small amounts of code. - - A dynamic method can be anonymously hosted, or it can be logically associated with a module or with a type. - -- If the dynamic method is anonymously hosted, it is located in a system-provided assembly, and therefore is isolated from other code. By default, it does not have access to any non-public data. An anonymously hosted dynamic method can have restricted ability to skip the JIT compiler's visibility checks, if it has been granted with the flag. The trust level of the assembly whose non-public members are accessed by the dynamic method must be equal to, or a subset of, the trust level of the call stack that emitted the dynamic method. For more information about anonymously hosted dynamic methods, see [Walkthrough: Emitting Code in Partial Trust Scenarios](/dotnet/framework/reflection-and-codedom/walkthrough-emitting-code-in-partial-trust-scenarios). - -- If the dynamic method is associated with a module that you specify, the dynamic method is effectively global to that module. It can access all types in the module and all `internal` (`Friend` in Visual Basic) members of the types. You can associate a dynamic method with any module, regardless of whether you created the module, provided that a demand for with the flag can be satisfied by the call stack that includes your code. If the flag is included in the grant, the dynamic method can skip the JIT compiler's visibility checks and access the private data of all types declared in the module or in any other module in any assembly. - - > [!NOTE] - > When you specify the module with which a dynamic method is associated, that module must not be in the system-provided assembly that is used for anonymous hosting. - -- If the dynamic method is associated with a type that you specify, it has access to all members of the type, regardless of access level. In addition, JIT visibility checks can be skipped. This gives the dynamic method access to the private data of other types declared in the same module or in any other module in any assembly. You can associate a dynamic method with any type, but your code must be granted with both the and flags. - - The following table shows which types and members are accessible to an anonymously hosted dynamic method, with and without JIT visibility checks, depending on whether with the flag is granted. - -||Without |With | -|-|-|-| -|Without skipping JIT visibility checks|Public members of public types in any assembly.|Public members of public types in any assembly.| -|Skipping JIT visibility checks, with restrictions|Public members of public types in any assembly.|All members of all types, only in assemblies whose trust levels are equal to or less than the trust level of the assembly that emitted the dynamic method.| - -> [!NOTE] -> .NET Framework 2.0 allows code to be emitted in partial trust scenarios without issuing any security demands, because generating code is not inherently a privileged operation. That is, the generated code has no more permissions than the assembly that emits it. This allows libraries that emit code to be security transparent and removes the need to assert , which simplifies the task of writing a secure library. To use this feature, your application should target .NET Framework 3.5 or later. - - The following table shows which types and members are accessible to a dynamic method that is associated with a module or with a type in a module. - -||Associated with module|Associated with type| -|-|-|-| -|Without skipping JIT visibility checks|Public and internal members of public, internal, and private types in the module.

Public members of public types in any assembly.|All members of the associated type. Public and internal members of all the other types in the module.

Public members of public types in any assembly.| -|Skipping JIT visibility checks|All members of all types in any assembly.|All members of all types in any assembly.| - - A dynamic method that is associated with a module has the permissions of that module. A dynamic method that is associated with a type has the permissions of the module containing that type. - - Dynamic methods and their parameters do not have to be named, but you can specify names to assist in debugging. Custom attributes are not supported on dynamic methods or their parameters. - - Although dynamic methods are `static` methods (`Shared` methods in Visual Basic), the relaxed rules for delegate binding introduced in the .NET Framework 2.0 allow a dynamic method to be bound to an object, so that it acts like an instance method when called using that delegate instance. An example that demonstrates this is provided for the method overload. - -> [!NOTE] -> In the .NET Framework 2.0, dynamic methods do not support symbol information, that is, local variable names and line-number mapping. This limitation might be removed in a future version. You can use during development to simplify debugging the generated Microsoft intermediate language (MSIL), and then switch to dynamic methods during final deployment, because the calls are the same in both cases. - -## Verification - The following list summarizes the conditions under which dynamic methods can contain unverifiable code. (For example, a dynamic method is unverifiable if its property is set to `false`.) - -- A dynamic method that is associated with a security-critical assembly is also security-critical, and can skip verification. For example, an assembly without security attributes that is run as a desktop application is treated as security-critical by the runtime. If you associate a dynamic method with the assembly, the dynamic method can contain unverifiable code. - -- If a dynamic method that contains unverifiable code is associated with an assembly that has level 1 transparency, the just-in-time (JIT) compiler injects a security demand. The demand succeeds only if the dynamic method is executed by fully trusted code. See [Security-Transparent Code, Level 1](/dotnet/framework/misc/security-transparent-code-level-1). - -- If a dynamic method that contains unverifiable code is associated with an assembly that has level 2 transparency (such as mscorlib.dll), it throws an exception (injected by the JIT compiler) instead of making a security demand. See [Security-Transparent Code, Level 2](/dotnet/framework/misc/security-transparent-code-level-2). - -- An anonymously hosted dynamic method that contains unverifiable code always throws an exception. It can never skip verification, even if it is created and executed by fully trusted code. - - The exception that is thrown for unverifiable code varies depending on the way the dynamic method is invoked. If you invoke a dynamic method by using a delegate returned from the method, a is thrown. If you invoke the dynamic method by using the method, a is thrown with an inner . - - - -## Examples - The following code example creates a dynamic method that takes two parameters. The example emits a simple function body that prints the first parameter to the console, and the example uses the second parameter as the return value of the method. The example completes the method by creating a delegate, invokes the delegate with different parameters, and finally invokes the dynamic method using the method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Reflection.DynamicMethod.All/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/DynamicMethod/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet1"::: - - ]]> - + For more information about this API, see Supplemental API remarks for DynamicMethod. + + method. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Reflection.DynamicMethod.All/cpp/source.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/DynamicMethod/Overview/source.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet1"::: + ]]> + How to: Define and Execute Dynamic Methods Security Issues in Reflection Emit Walkthrough: Emitting Code in Partial Trust Scenarios @@ -200,20 +143,20 @@ An array of objects specifying the types of the parameters of the dynamic method, or if the method has no parameters. Initializes an anonymously hosted dynamic method, specifying the method name, return type, and parameter types. - constructor. - - When an anonymously hosted dynamic method is constructed, the call stack of the emitting assembly is included. When the method is invoked, the permissions of the emitting assembly are used instead of the permissions of the actual caller. Thus, the dynamic method cannot execute at a higher level of privilege than that of the assembly that emitted it, even if it is passed to and executed by an assembly that has a higher trust level. - - This constructor specifies the method attributes and , and the calling convention . - + constructor. + + When an anonymously hosted dynamic method is constructed, the call stack of the emitting assembly is included. When the method is invoked, the permissions of the emitting assembly are used instead of the permissions of the actual caller. Thus, the dynamic method cannot execute at a higher level of privilege than that of the assembly that emitted it, even if it is passed to and executed by an assembly that has a higher trust level. + + This constructor specifies the method attributes and , and the calling convention . + > [!NOTE] -> This constructor was introduced in the .NET Framework 3.5 or later. - +> This constructor was introduced in the .NET Framework 3.5 or later. + ]]> An element of is or . @@ -294,33 +237,33 @@ to skip JIT visibility checks on types and members accessed by the MSIL of the dynamic method, with this restriction: the trust level of the assemblies that contain those types and members must be equal to or less than the trust level of the call stack that emits the dynamic method; otherwise, . Initializes an anonymously hosted dynamic method, specifying the method name, return type, parameter types, and whether just-in-time (JIT) visibility checks should be skipped for types and members accessed by the Microsoft intermediate language (MSIL) of the dynamic method. - with the flag. This is always true when the code is executed with full trust. For partially trusted code, it is true only if the host explicitly grants the permission. - + with the flag. This is always true when the code is executed with full trust. For partially trusted code, it is true only if the host explicitly grants the permission. + > [!IMPORTANT] - > If the permission has not been granted, a security exception is thrown when is called or when the dynamic method is invoked, not when this constructor is called. No special permissions are required to emit the dynamic method. - - For example, a dynamic method that is created with `restrictedSkipVisibility` set to `true` can access a private member of any assembly on the call stack if the call stack has been granted restricted member access. If the dynamic method is created with partially trusted code on the call stack, it cannot access a private member of a type in a .NET Framework assembly, because such assemblies are fully trusted. - - If `restrictedSkipVisibility` is `false`, JIT visibility checks are enforced. The code in the dynamic method has access to public methods of public classes, and exceptions are thrown if it tries to access types or members that are `private`, `protected`, or `internal`. - - When an anonymously hosted dynamic method is constructed, the call stack of the emitting assembly is included. When the method is invoked, the permissions of the emitting call stack are used instead of the permissions of the actual caller. Thus, the dynamic method cannot execute at a higher level of privilege than that of the assembly that emitted it, even if it is passed to and executed by an assembly that has a higher trust level. - - This constructor specifies the method attributes and , and the calling convention . - + > If the permission has not been granted, a security exception is thrown when is called or when the dynamic method is invoked, not when this constructor is called. No special permissions are required to emit the dynamic method. + + For example, a dynamic method that is created with `restrictedSkipVisibility` set to `true` can access a private member of any assembly on the call stack if the call stack has been granted restricted member access. If the dynamic method is created with partially trusted code on the call stack, it cannot access a private member of a type in a .NET Framework assembly, because such assemblies are fully trusted. + + If `restrictedSkipVisibility` is `false`, JIT visibility checks are enforced. The code in the dynamic method has access to public methods of public classes, and exceptions are thrown if it tries to access types or members that are `private`, `protected`, or `internal`. + + When an anonymously hosted dynamic method is constructed, the call stack of the emitting assembly is included. When the method is invoked, the permissions of the emitting call stack are used instead of the permissions of the actual caller. Thus, the dynamic method cannot execute at a higher level of privilege than that of the assembly that emitted it, even if it is passed to and executed by an assembly that has a higher trust level. + + This constructor specifies the method attributes and , and the calling convention . + > [!NOTE] -> This constructor was introduced in the .NET Framework 3.5 or later. - +> This constructor was introduced in the .NET Framework 3.5 or later. + ]]> An element of is or . @@ -400,35 +343,35 @@ A representing the module with which the dynamic method is to be logically associated. Creates a dynamic method that is global to a module, specifying the method name, return type, parameter types, and module. - and , calling convention , and does not skip just-in-time (JIT) visibility checks. - + and , calling convention , and does not skip just-in-time (JIT) visibility checks. + The dynamic method created with this constructor has access to public and `internal` (`Friend` in Visual Basic) members of all the types contained in module `m`. > [!NOTE] > For backward compatibility, this constructor demands with the flag if the following conditions are both true: `m` is a module other than the calling module, and the demand for with the flag has failed. If the demand for succeeds, the operation is allowed. - -## Examples - The following code example creates a dynamic method that takes two parameters. The example emits a simple function body that prints the first parameter to the console, and the example uses the second parameter as the return value of the method. The example completes the method by creating a delegate, invokes the delegate with different parameters, and finally invokes the dynamic method using the method. - + +## Examples + The following code example creates a dynamic method that takes two parameters. The example emits a simple function body that prints the first parameter to the console, and the example uses the second parameter as the return value of the method. The example completes the method by creating a delegate, invokes the delegate with different parameters, and finally invokes the dynamic method using the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Reflection.DynamicMethod.ctor1/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/DynamicMethod/.ctor/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.ctor1/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.ctor1/VB/source.vb" id="Snippet1"::: + ]]> - An element of is or . - - -or- - + An element of is or . + + -or- + is a module that provides anonymous hosting for dynamic methods. - is . - - -or- - + is . + + -or- + is . .NET Framework and .NET Core versions older than 2.1: is a type for which returns . @@ -503,48 +446,48 @@ A with which the dynamic method is logically associated. The dynamic method has access to all members of the type. Creates a dynamic method, specifying the method name, return type, parameter types, and the type with which the dynamic method is logically associated. - and , calling convention , and does not skip just-in-time (JIT) visibility checks. - + and , calling convention , and does not skip just-in-time (JIT) visibility checks. + > [!NOTE] > For backward compatibility, this constructor demands with the flag if the following conditions are both true: `owner` is in a module other than the calling module, and the demand for with the flag has failed. If the demand for succeeds, the operation is allowed. - -## Examples - The following code example creates a that is logically associated with a type. This association gives it access to the private members of that type. - - The code example defines a class named `Example` with a private field, a class named `DerivedFromExample` that derives from the first class, a delegate type named `UseLikeStatic` that returns and has parameters of type `Example` and , and a delegate type named `UseLikeInstance` that returns and has one parameter of type . - - The example code then creates a that changes the private field of an instance of `Example` and returns the previous value. - + +## Examples + The following code example creates a that is logically associated with a type. This association gives it access to the private members of that type. + + The code example defines a class named `Example` with a private field, a class named `DerivedFromExample` that derives from the first class, a delegate type named `UseLikeStatic` that returns and has parameters of type `Example` and , and a delegate type named `UseLikeInstance` that returns and has one parameter of type . + + The example code then creates a that changes the private field of an instance of `Example` and returns the previous value. + > [!NOTE] -> In general, changing the internal fields of classes is not good object-oriented coding practice. - - The example code creates an instance of `Example` and then creates two delegates. The first is of type `UseLikeStatic`, which has the same parameters as the dynamic method. The second is of type `UseLikeInstance`, which lacks the first parameter (of type `Example`). This delegate is created using the method overload; the second parameter of that method overload is an instance of `Example`, in this case the instance just created, which is bound to the newly created delegate. Whenever that delegate is invoked, the dynamic method acts on the bound instance of `Example`. - +> In general, changing the internal fields of classes is not good object-oriented coding practice. + + The example code creates an instance of `Example` and then creates two delegates. The first is of type `UseLikeStatic`, which has the same parameters as the dynamic method. The second is of type `UseLikeInstance`, which lacks the first parameter (of type `Example`). This delegate is created using the method overload; the second parameter of that method overload is an instance of `Example`, in this case the instance just created, which is bound to the newly created delegate. Whenever that delegate is invoked, the dynamic method acts on the bound instance of `Example`. + > [!NOTE] -> This is an example of the relaxed rules for delegate binding introduced in the .NET Framework 2.0, along with new overloads of the method. For more information, see the class. - - The `UseLikeStatic` delegate is invoked, passing in the instance of `Example` that is bound to the `UseLikeInstance` delegate. Then the `UseLikeInstance` delegate is invoked, so that both delegates act on the same instance of `Example`. The changes in the values of the internal field are displayed after each call. Finally, a `UseLikeInstance` delegate is bound to an instance of `DerivedFromExample`, and the delegate calls are repeated. - +> This is an example of the relaxed rules for delegate binding introduced in the .NET Framework 2.0, along with new overloads of the method. For more information, see the class. + + The `UseLikeStatic` delegate is invoked, passing in the instance of `Example` that is bound to the `UseLikeInstance` delegate. Then the `UseLikeInstance` delegate is invoked, so that both delegates act on the same instance of `Example`. The changes in the values of the internal field are displayed after each call. Finally, a `UseLikeInstance` delegate is bound to an instance of `DerivedFromExample`, and the delegate calls are repeated. + :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/DynamicMethod/.ctor/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.ClosedOver/vb/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.ClosedOver/vb/source.vb" id="Snippet1"::: + ]]> - An element of is or . - - -or- - + An element of is or . + + -or- + is an interface, an array, an open generic type, or a type parameter of a generic type or method. - is . - - -or- - + is . + + -or- + is . .NET Framework and .NET Core versions older than 2.1: is a type for which returns . @@ -622,28 +565,28 @@ to skip JIT visibility checks on types and members accessed by the MSIL of the dynamic method. Creates a dynamic method that is global to a module, specifying the method name, return type, parameter types, module, and whether just-in-time (JIT) visibility checks should be skipped for types and members accessed by the Microsoft intermediate language (MSIL) of the dynamic method. - and , and calling convention . - - The dynamic method created with this constructor has access to public and `internal` (`Friend` in Visual Basic) members of all the types in contained module `m`. Skipping the JIT compiler's visibility checks allows the dynamic method to access private and protected members of all other types as well. This is useful, for example, when writing code to serialize objects. - + and , and calling convention . + + The dynamic method created with this constructor has access to public and `internal` (`Friend` in Visual Basic) members of all the types in contained module `m`. Skipping the JIT compiler's visibility checks allows the dynamic method to access private and protected members of all other types as well. This is useful, for example, when writing code to serialize objects. + > [!NOTE] > For backward compatibility, this constructor demands with the flag if the following conditions are both true: `m` is a module other than the calling module, and the demand for with the flag has failed. If the demand for succeeds, the operation is allowed. - + ]]> - An element of is or . - - -or- - + An element of is or . + + -or- + is a module that provides anonymous hosting for dynamic methods. - is . - - -or- - + is . + + -or- + is . .NET Framework and .NET Core versions older than 2.1: is a type for which returns . @@ -721,28 +664,28 @@ to skip JIT visibility checks on types and members accessed by the MSIL of the dynamic method; otherwise, . Creates a dynamic method, specifying the method name, return type, parameter types, the type with which the dynamic method is logically associated, and whether just-in-time (JIT) visibility checks should be skipped for types and members accessed by the Microsoft intermediate language (MSIL) of the dynamic method. - and , and calling convention . - + and , and calling convention . + > [!NOTE] > For backward compatibility, this constructor demands with the flag if the following conditions are both true: `owner` is in a module other than the calling module, and the demand for with the flag has failed. If the demand for succeeds, the operation is allowed. - + ]]> - An element of is or . - - -or- - + An element of is or . + + -or- + is an interface, an array, an open generic type, or a type parameter of a generic type or method. - is . - - -or- - + is . + + -or- + is . .NET Framework and .NET Core versions older than 2.1: is a type for which returns . @@ -824,38 +767,38 @@ to skip JIT visibility checks on types and members accessed by the MSIL of the dynamic method; otherwise, . Creates a dynamic method that is global to a module, specifying the method name, attributes, calling convention, return type, parameter types, module, and whether just-in-time (JIT) visibility checks should be skipped for types and members accessed by the Microsoft intermediate language (MSIL) of the dynamic method. - [!NOTE] > For backward compatibility, this constructor demands with the flag if the following conditions are both true: `m` is a module other than the calling module, and the demand for with the flag has failed. If the demand for succeeds, the operation is allowed. - + ]]> - An element of is or . - - -or- - + An element of is or . + + -or- + is a module that provides anonymous hosting for dynamic methods. - is . - - -or- - + is . + + -or- + is . - is a combination of flags other than and . - - -or- - - is not . - - -or- - + is a combination of flags other than and . + + -or- + + is not . + + -or- + is a type for which returns . How to: Define and Execute Dynamic Methods Security Issues in Reflection Emit @@ -935,38 +878,38 @@ to skip JIT visibility checks on types and members accessed by the MSIL of the dynamic method; otherwise, . Creates a dynamic method, specifying the method name, attributes, calling convention, return type, parameter types, the type with which the dynamic method is logically associated, and whether just-in-time (JIT) visibility checks should be skipped for types and members accessed by the Microsoft intermediate language (MSIL) of the dynamic method. - [!NOTE] > For backward compatibility, this constructor demands with the flag if the following conditions are both true: `owner` is in a module other than the calling module, and the demand for with the flag has failed. If the demand for succeeds, the operation is allowed. - + ]]> - An element of is or . - - -or- - + An element of is or . + + -or- + is an interface, an array, an open generic type, or a type parameter of a generic type or method. - is . - - -or- - + is . + + -or- + is . - is a combination of flags other than and . - - -or- - - is not . - - -or- - + is a combination of flags other than and . + + -or- + + is not . + + -or- + is a type for which returns . How to: Define and Execute Dynamic Methods Security Issues in Reflection Emit @@ -1008,20 +951,20 @@ Gets the attributes specified when the dynamic method was created. A bitwise combination of the values representing the attributes for the method. - and . - - - -## Examples - The following code example displays the method attributes of a dynamic method. This code example is part of a larger example provided for the class. - + and . + + + +## Examples + The following code example displays the method attributes of a dynamic method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Reflection.DynamicMethod.All/cpp/source.cpp" id="Snippet21"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/DynamicMethod/Overview/source.cs" id="Snippet21"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet21"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet21"::: + ]]> @@ -1062,20 +1005,20 @@ Gets the calling convention specified when the dynamic method was created. One of the values that indicates the calling convention of the method. - . - - - -## Examples - The following code example displays the calling convention of a dynamic method. This code example is part of a larger example provided for the class. - + . + + + +## Examples + The following code example displays the calling convention of a dynamic method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Reflection.DynamicMethod.All/cpp/source.cpp" id="Snippet22"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/DynamicMethod/Overview/source.cs" id="Snippet22"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet22"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet22"::: + ]]> @@ -1145,22 +1088,22 @@ Completes the dynamic method and creates a delegate that can be used to execute it. A delegate of the specified type, which can be used to execute the dynamic method. - method or the method completes the dynamic method. Any further attempt to alter the dynamic method, such as modifying parameter definitions or emitting more Microsoft intermediate language (MSIL), is ignored; no exception is thrown. - - To create a method body for a dynamic method when you have your own MSIL generator, call the method to obtain a object. If you do not have your own MSIL generator, call the method to obtain an object that can be used to generate the method body. - - - -## Examples - The following code example creates a dynamic method that takes two parameters. The example emits a simple function body that prints the first parameter to the console, and the example uses the second parameter as the return value of the method. The example completes the method by creating a delegate, invokes the delegate with different parameters, and finally invokes the dynamic method using the method. - + method or the method completes the dynamic method. Any further attempt to alter the dynamic method, such as modifying parameter definitions or emitting more Microsoft intermediate language (MSIL), is ignored; no exception is thrown. + + To create a method body for a dynamic method when you have your own MSIL generator, call the method to obtain a object. If you do not have your own MSIL generator, call the method to obtain an object that can be used to generate the method body. + + + +## Examples + The following code example creates a dynamic method that takes two parameters. The example emits a simple function body that prints the first parameter to the console, and the example uses the second parameter as the return value of the method. The example completes the method by creating a delegate, invokes the delegate with different parameters, and finally invokes the dynamic method using the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Reflection.DynamicMethod.ctor1/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/DynamicMethod/.ctor/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.ctor1/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.ctor1/VB/source.vb" id="Snippet1"::: + ]]> The dynamic method has no method body. @@ -1234,47 +1177,47 @@ Completes the dynamic method and creates a delegate that can be used to execute it, specifying the delegate type and an object the delegate is bound to. A delegate of the specified type, which can be used to execute the dynamic method with the specified target object. - , , and , then `delegateType` has the parameters and ; `target` is of type . - - Calling the method or the method completes the dynamic method. Any further attempt to alter the dynamic method, such as modifying parameter definitions or emitting more Microsoft intermediate language (MSIL), is ignored; no exception is thrown. - - To create a method body for a dynamic method when you have your own MSIL generator, call the method to obtain a object. If you do not have your own MSIL generator, call the method to obtain an object that can be used to generate the method body. - - - -## Examples - The following code example creates delegate that binds a to an instance of a type, so that the method acts on the same instance each time it is invoked. - - The code example defines a class named `Example` with a private field, a class named `DerivedFromExample` that derives from the first class, a delegate type named `UseLikeStatic` that returns and has parameters of type `Example` and , and a delegate type named `UseLikeInstance` that returns and has one parameter of type . - - The example code then creates a that changes the private field of an instance of `Example` and returns the previous value. - + , , and , then `delegateType` has the parameters and ; `target` is of type . + + Calling the method or the method completes the dynamic method. Any further attempt to alter the dynamic method, such as modifying parameter definitions or emitting more Microsoft intermediate language (MSIL), is ignored; no exception is thrown. + + To create a method body for a dynamic method when you have your own MSIL generator, call the method to obtain a object. If you do not have your own MSIL generator, call the method to obtain an object that can be used to generate the method body. + + + +## Examples + The following code example creates delegate that binds a to an instance of a type, so that the method acts on the same instance each time it is invoked. + + The code example defines a class named `Example` with a private field, a class named `DerivedFromExample` that derives from the first class, a delegate type named `UseLikeStatic` that returns and has parameters of type `Example` and , and a delegate type named `UseLikeInstance` that returns and has one parameter of type . + + The example code then creates a that changes the private field of an instance of `Example` and returns the previous value. + > [!NOTE] -> In general, changing the internal fields of classes is not good object-oriented coding practice. - - The example code creates an instance of `Example` and then creates two delegates. The first is of type `UseLikeStatic`, which has the same parameters as the dynamic method. The second is of type `UseLikeInstance`, which lacks the first parameter (of type `Example`). This delegate is created using the method overload; the second parameter of that method overload is an instance of `Example`, in this case the instance just created, which is bound to the newly created delegate. Whenever that delegate is invoked, the dynamic method acts on the bound instance of `Example`. - +> In general, changing the internal fields of classes is not good object-oriented coding practice. + + The example code creates an instance of `Example` and then creates two delegates. The first is of type `UseLikeStatic`, which has the same parameters as the dynamic method. The second is of type `UseLikeInstance`, which lacks the first parameter (of type `Example`). This delegate is created using the method overload; the second parameter of that method overload is an instance of `Example`, in this case the instance just created, which is bound to the newly created delegate. Whenever that delegate is invoked, the dynamic method acts on the bound instance of `Example`. + > [!NOTE] -> This is an example of the relaxed rules for delegate binding introduced in the .NET Framework 2.0, along with new overloads of the method. For more information, see the class. - - The `UseLikeStatic` delegate is invoked, passing in the instance of `Example` that is bound to the `UseLikeInstance` delegate. Then the `UseLikeInstance` delegate is invoked, so that both delegates act on the same instance of `Example`. The changes in the values of the internal field are displayed after each call. Finally, a `UseLikeInstance` delegate is bound to an instance of `DerivedFromExample`, and the delegate calls are repeated. - +> This is an example of the relaxed rules for delegate binding introduced in the .NET Framework 2.0, along with new overloads of the method. For more information, see the class. + + The `UseLikeStatic` delegate is invoked, passing in the instance of `Example` that is bound to the `UseLikeInstance` delegate. Then the `UseLikeInstance` delegate is invoked, so that both delegates act on the same instance of `Example`. The changes in the values of the internal field are displayed after each call. Finally, a `UseLikeInstance` delegate is bound to an instance of `DerivedFromExample`, and the delegate calls are repeated. + :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/DynamicMethod/.ctor/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.ClosedOver/vb/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.ClosedOver/vb/source.vb" id="Snippet1"::: + ]]> The dynamic method has no method body. - is not the same type as the first parameter of the dynamic method, and is not assignable to that type. - - -or- - + is not the same type as the first parameter of the dynamic method, and is not assignable to that type. + + -or- + has the wrong number of parameters or the wrong parameter types. @@ -1325,20 +1268,20 @@ Gets the type that declares the method, which is always for dynamic methods. Always . - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Reflection.DynamicMethod.All/cpp/source.cpp" id="Snippet23"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/DynamicMethod/Overview/source.cs" id="Snippet23"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet23"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet23"::: + ]]> @@ -1392,32 +1335,32 @@ Defines a parameter of the dynamic method. Always returns . - method refers to the return value. Setting parameter information has no effect on the return value. - - If the dynamic method has already been completed, by calling the or method, the method has no effect. No exception is thrown. - - - -## Examples - The following code example shows how to define parameter information for a dynamic method. This code example is part of a larger example provided for the class. - + method refers to the return value. Setting parameter information has no effect on the return value. + + If the dynamic method has already been completed, by calling the or method, the method has no effect. No exception is thrown. + + + +## Examples + The following code example shows how to define parameter information for a dynamic method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Reflection.DynamicMethod.All/cpp/source.cpp" id="Snippet33"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/DynamicMethod/Overview/source.cs" id="Snippet33"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet33"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet33"::: + ]]> - The method has no parameters. - - -or- - - is less than 0. - - -or- - + The method has no parameters. + + -or- + + is less than 0. + + -or- + is greater than the number of the method's parameters. @@ -1457,11 +1400,11 @@ Returns the base implementation for the method. The base implementation of the method. - @@ -1516,14 +1459,14 @@ Returns all the custom attributes defined for the method. An array of objects representing all the custom attributes of the method. - [!NOTE] -> Custom attributes are not currently supported on dynamic methods. The only attribute returned is ; you can get the method implementation flags more easily using the method. - +> Custom attributes are not currently supported on dynamic methods. The only attribute returned is ; you can get the method implementation flags more easily using the method. + ]]> @@ -1571,14 +1514,14 @@ Returns the custom attributes of the specified type that have been applied to the method. An array of objects representing the attributes of the method that are of type or derive from type . - [!NOTE] -> Custom attributes are not currently supported on dynamic methods. The only attribute returned is ; you can get the method implementation flags more easily using the method. - +> Custom attributes are not currently supported on dynamic methods. The only attribute returned is ; you can get the method implementation flags more easily using the method. + ]]> @@ -1627,11 +1570,11 @@ Returns a object that can be used to generate a method body from metadata tokens, scopes, and Microsoft intermediate language (MSIL) streams. A object that can be used to generate a method body from metadata tokens, scopes, and MSIL streams. - class is provided to support unmanaged code generation. - + class is provided to support unmanaged code generation. + ]]> @@ -1684,23 +1627,23 @@ Returns a Microsoft intermediate language (MSIL) generator for the method with a default MSIL stream size of 64 bytes. An object for the method. - or method, any further attempt to add MSIL is ignored. No exception is thrown. - + or method, any further attempt to add MSIL is ignored. No exception is thrown. + > [!NOTE] -> There are restrictions on unverifiable code in dynamic methods, even in some full-trust scenarios. See the "Verification" section in Remarks for . - - - -## Examples - The following code example creates a dynamic method that takes two parameters. The example emits a simple function body that prints the first parameter to the console, and the example uses the second parameter as the return value of the method. The example completes the method by creating a delegate, invokes the delegate with different parameters, and finally invokes the dynamic method using the method. - +> There are restrictions on unverifiable code in dynamic methods, even in some full-trust scenarios. See the "Verification" section in Remarks for . + + + +## Examples + The following code example creates a dynamic method that takes two parameters. The example emits a simple function body that prints the first parameter to the console, and the example uses the second parameter as the return value of the method. The example completes the method by creating a delegate, invokes the delegate with different parameters, and finally invokes the dynamic method using the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Reflection.DynamicMethod.ctor1/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/DynamicMethod/.ctor/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.ctor1/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.ctor1/VB/source.vb" id="Snippet1"::: + ]]> How to: Define and Execute Dynamic Methods @@ -1752,23 +1695,23 @@ Returns a Microsoft intermediate language (MSIL) generator for the method with the specified MSIL stream size. An object for the method, with the specified MSIL stream size. - or method, any further attempt to add MSIL is ignored. No exception is thrown. - + or method, any further attempt to add MSIL is ignored. No exception is thrown. + > [!NOTE] -> There are restrictions on unverifiable code in dynamic methods, even in some full-trust scenarios. See the "Verification" section in Remarks for . - - - -## Examples - The following code example demonstrates this method overload. This code example is part of a larger example provided for the class. - +> There are restrictions on unverifiable code in dynamic methods, even in some full-trust scenarios. See the "Verification" section in Remarks for . + + + +## Examples + The following code example demonstrates this method overload. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Reflection.DynamicMethod.All/cpp/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/DynamicMethod/Overview/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet2"::: + ]]> How to: Define and Execute Dynamic Methods @@ -1810,11 +1753,11 @@ Returns the implementation flags for the method. A bitwise combination of values representing the implementation flags for the method. - and . - + and . + ]]> @@ -1856,20 +1799,20 @@ Returns the parameters of the dynamic method. An array of objects that represent the parameters of the dynamic method. - objects returned by this method are for information only. Use the method to set or change the characteristics of the parameters. - - - -## Examples - The following code example displays the parameters of a dynamic method. This code example is part of a larger example provided for the class. - + objects returned by this method are for information only. Use the method to set or change the characteristics of the parameters. + + + +## Examples + The following code example displays the parameters of a dynamic method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Reflection.DynamicMethod.All/cpp/source.cpp" id="Snippet34"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/DynamicMethod/Overview/source.cs" id="Snippet34"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet34"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet34"::: + ]]> @@ -1912,20 +1855,20 @@ if the local variables in the method are zero-initialized; otherwise, . The default is . - property of a dynamic method. This code example is part of a larger example provided for the class. - + property of a dynamic method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Reflection.DynamicMethod.All/cpp/source.cpp" id="Snippet24"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/DynamicMethod/Overview/source.cs" id="Snippet24"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet24"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet24"::: + ]]> @@ -1988,49 +1931,49 @@ Invokes the dynamic method using the specified parameters, under the constraints of the specified binder, with the specified culture information. A containing the return value of the invoked method. - method is more efficient than executing it with the method. - - Calling the method or the method completes the dynamic method. Any further attempt to alter the dynamic method, such as modifying parameter definitions or emitting more Microsoft intermediate language (MSIL), is ignored; no exception is thrown. - - All dynamic methods are static, so the `obj` parameter is always ignored. To treat a dynamic method as if it were an instance method, use the overload that takes an object instance. - - If the dynamic method has no parameters, the value of `parameters` should be `null`. Otherwise the number, type, and order of elements in the parameters array should be identical to the number, type, and order of parameters of the dynamic method. - + + Executing a dynamic method with a delegate created by the method is more efficient than executing it with the method. + + Calling the method or the method completes the dynamic method. Any further attempt to alter the dynamic method, such as modifying parameter definitions or emitting more Microsoft intermediate language (MSIL), is ignored; no exception is thrown. + + All dynamic methods are static, so the `obj` parameter is always ignored. To treat a dynamic method as if it were an instance method, use the overload that takes an object instance. + + If the dynamic method has no parameters, the value of `parameters` should be `null`. Otherwise the number, type, and order of elements in the parameters array should be identical to the number, type, and order of parameters of the dynamic method. + > [!NOTE] -> This method overload is called by the method overload inherited from the class, so the preceding remarks apply to both overloads. - - This method does not demand permissions directly, but invoking the dynamic method can result in security demands, depending on the method. For example, no demands are made for anonymously hosted dynamic methods that are created with the `restrictedSkipVisibility` parameter set to `false`. On the other hand, if you create a method with `restrictedSkipVisibility` set to `true` so it can access a hidden member of a target assembly, the method will cause a demand for the permissions of the target assembly plus with the flag. - +> This method overload is called by the method overload inherited from the class, so the preceding remarks apply to both overloads. + + This method does not demand permissions directly, but invoking the dynamic method can result in security demands, depending on the method. For example, no demands are made for anonymously hosted dynamic methods that are created with the `restrictedSkipVisibility` parameter set to `false`. On the other hand, if you create a method with `restrictedSkipVisibility` set to `true` so it can access a hidden member of a target assembly, the method will cause a demand for the permissions of the target assembly plus with the flag. + > [!NOTE] -> Prior to .NET Framework 2.0, this method required with the flag. - - - -## Examples - The following code example invokes a dynamic method with exact binding, using the US-English culture. This code example is part of a larger example provided for the class. - +> Prior to .NET Framework 2.0, this method required with the flag. + + + +## Examples + The following code example invokes a dynamic method with exact binding, using the US-English culture. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Reflection.DynamicMethod.All/cpp/source.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/DynamicMethod/Overview/source.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet4"::: + ]]> The calling convention is not supported. The number of elements in does not match the number of parameters in the dynamic method. The type of one or more elements of does not match the type of the corresponding parameter of the dynamic method. - The dynamic method is associated with a module, is not anonymously hosted, and was constructed with set to , but the dynamic method accesses members that are not or ( in Visual Basic). - - -or- - - The dynamic method is anonymously hosted and was constructed with set to , but it accesses members that are not . - - -or- - + The dynamic method is associated with a module, is not anonymously hosted, and was constructed with set to , but the dynamic method accesses members that are not or ( in Visual Basic). + + -or- + + The dynamic method is anonymously hosted and was constructed with set to , but it accesses members that are not . + + -or- + The dynamic method contains unverifiable code. See the "Verification" section in Remarks for . @@ -2078,14 +2021,14 @@ if the specified custom attribute type is defined; otherwise, . - [!NOTE] -> Custom attributes are not currently supported on dynamic methods. - +> Custom attributes are not currently supported on dynamic methods. + ]]> @@ -2129,41 +2072,41 @@ if the current dynamic method is security-critical or security-safe-critical; if it is transparent. - , , and properties report the transparency level of the dynamic method as determined by the common language runtime (CLR). The combinations of these properties are shown in the following table: - -|Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| -|--------------------|------------------------|----------------------------|---------------------------| -|Critical|`true`|`false`|`false`| -|Safe critical|`true`|`true`|`false`| -|Transparent|`false`|`false`|`true`| - - Using these properties is much simpler than examining the security annotations of an assembly and its types, checking the current trust level, and attempting to duplicate the runtime's rules. - - The transparency of a dynamic method depends on the module it is associated with. If the dynamic method is associated with a type rather than a module, its transparency depends on the module that contains the type. Dynamic methods do not have security annotations, so they are assigned the default transparency for the associated module. - -- Anonymously hosted dynamic methods are always transparent, because the system-provided module that contains them is transparent. - -- The transparency of a dynamic method that is associated with a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is described in the following table. - - |Assembly annotation|Level 1 transparency|Level 2 transparency| - |-------------------------|--------------------------|--------------------------| - |Fully transparent|Transparent|Transparent| - |Fully critical|Critical|Critical| - |Mixed transparency|Transparent|Transparent| - |Security-agnostic|Safe-critical|Critical| - - For example, if you associate a dynamic method with a type that is in mscorlib.dll, which has level 2 mixed transparency, the dynamic method is transparent and cannot execute critical code. For information about transparency levels, see [Security-Transparent Code, Level 1](/dotnet/framework/misc/security-transparent-code-level-1) and [Security-Transparent Code, Level 2](/dotnet/framework/misc/security-transparent-code-level-2). - + , , and properties report the transparency level of the dynamic method as determined by the common language runtime (CLR). The combinations of these properties are shown in the following table: + +|Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| +|--------------------|------------------------|----------------------------|---------------------------| +|Critical|`true`|`false`|`false`| +|Safe critical|`true`|`true`|`false`| +|Transparent|`false`|`false`|`true`| + + Using these properties is much simpler than examining the security annotations of an assembly and its types, checking the current trust level, and attempting to duplicate the runtime's rules. + + The transparency of a dynamic method depends on the module it is associated with. If the dynamic method is associated with a type rather than a module, its transparency depends on the module that contains the type. Dynamic methods do not have security annotations, so they are assigned the default transparency for the associated module. + +- Anonymously hosted dynamic methods are always transparent, because the system-provided module that contains them is transparent. + +- The transparency of a dynamic method that is associated with a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is described in the following table. + + |Assembly annotation|Level 1 transparency|Level 2 transparency| + |-------------------------|--------------------------|--------------------------| + |Fully transparent|Transparent|Transparent| + |Fully critical|Critical|Critical| + |Mixed transparency|Transparent|Transparent| + |Security-agnostic|Safe-critical|Critical| + + For example, if you associate a dynamic method with a type that is in mscorlib.dll, which has level 2 mixed transparency, the dynamic method is transparent and cannot execute critical code. For information about transparency levels, see [Security-Transparent Code, Level 1](/dotnet/framework/misc/security-transparent-code-level-1) and [Security-Transparent Code, Level 2](/dotnet/framework/misc/security-transparent-code-level-2). + > [!NOTE] - > Associating a dynamic method with a module in a trusted level 1 assembly that is security-agnostic, such as System.dll, does not permit elevation of trust. If the grant set of the code that calls the dynamic method does not include the grant set of System.dll (that is, full trust), is thrown when the dynamic method is called. - -- The transparency of a dynamic method that is associated with a partially trusted assembly depends on how the assembly is loaded. If the assembly is loaded with partial trust (for example, into a sandboxed application domain), the runtime ignores the security annotations of the assembly. The assembly and all its types and members, including dynamic methods, are treated as transparent. The runtime pays attention to security annotations only if the partial-trust assembly is loaded with full trust (for example, into the default application domain of a desktop application). In that case, the runtime assigns the dynamic method the default transparency for methods according to the assembly's annotations. - - For more information about reflection emit and transparency, see [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit). For information about transparency, see [Security Changes](/dotnet/framework/security/security-changes). - + > Associating a dynamic method with a module in a trusted level 1 assembly that is security-agnostic, such as System.dll, does not permit elevation of trust. If the grant set of the code that calls the dynamic method does not include the grant set of System.dll (that is, full trust), is thrown when the dynamic method is called. + +- The transparency of a dynamic method that is associated with a partially trusted assembly depends on how the assembly is loaded. If the assembly is loaded with partial trust (for example, into a sandboxed application domain), the runtime ignores the security annotations of the assembly. The assembly and all its types and members, including dynamic methods, are treated as transparent. The runtime pays attention to security annotations only if the partial-trust assembly is loaded with full trust (for example, into the default application domain of a desktop application). In that case, the runtime assigns the dynamic method the default transparency for methods according to the assembly's annotations. + + For more information about reflection emit and transparency, see [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit). For information about transparency, see [Security Changes](/dotnet/framework/security/security-changes). + ]]> The dynamic method doesn't have a method body. @@ -2214,41 +2157,41 @@ if the dynamic method is security-safe-critical at the current trust level; if it is security-critical or transparent. - , , and properties report the transparency level of the dynamic method as determined by the common language runtime (CLR). The combinations of these properties are shown in the following table: - -|Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| -|--------------------|------------------------|----------------------------|---------------------------| -|Critical|`true`|`false`|`false`| -|Safe critical|`true`|`true`|`false`| -|Transparent|`false`|`false`|`true`| - - Using these properties is much simpler than examining the security annotations of an assembly and its types, checking the current trust level, and attempting to duplicate the runtime's rules. - - The transparency of a dynamic method depends on the module it is associated with. If the dynamic method is associated with a type rather than a module, its transparency depends on the module that contains the type. Dynamic methods do not have security annotations, so they are assigned the default transparency for the associated module. - -- Anonymously hosted dynamic methods are always transparent, because the system-provided module that contains them is transparent. - -- The transparency of a dynamic method that is associated with a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is described in the following table. - - |Assembly annotation|Level 1 transparency|Level 2 transparency| - |-------------------------|--------------------------|--------------------------| - |Fully transparent|Transparent|Transparent| - |Fully critical|Critical|Critical| - |Mixed transparency|Transparent|Transparent| - |Security-agnostic|Safe-critical|Critical| - - For example, if you associate a dynamic method with a type that is in mscorlib.dll, which has level 2 mixed transparency, the dynamic method is transparent and cannot execute critical code. For information about transparency levels, see [Security-Transparent Code, Level 1](/dotnet/framework/misc/security-transparent-code-level-1) and [Security-Transparent Code, Level 2](/dotnet/framework/misc/security-transparent-code-level-2). - + , , and properties report the transparency level of the dynamic method as determined by the common language runtime (CLR). The combinations of these properties are shown in the following table: + +|Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| +|--------------------|------------------------|----------------------------|---------------------------| +|Critical|`true`|`false`|`false`| +|Safe critical|`true`|`true`|`false`| +|Transparent|`false`|`false`|`true`| + + Using these properties is much simpler than examining the security annotations of an assembly and its types, checking the current trust level, and attempting to duplicate the runtime's rules. + + The transparency of a dynamic method depends on the module it is associated with. If the dynamic method is associated with a type rather than a module, its transparency depends on the module that contains the type. Dynamic methods do not have security annotations, so they are assigned the default transparency for the associated module. + +- Anonymously hosted dynamic methods are always transparent, because the system-provided module that contains them is transparent. + +- The transparency of a dynamic method that is associated with a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is described in the following table. + + |Assembly annotation|Level 1 transparency|Level 2 transparency| + |-------------------------|--------------------------|--------------------------| + |Fully transparent|Transparent|Transparent| + |Fully critical|Critical|Critical| + |Mixed transparency|Transparent|Transparent| + |Security-agnostic|Safe-critical|Critical| + + For example, if you associate a dynamic method with a type that is in mscorlib.dll, which has level 2 mixed transparency, the dynamic method is transparent and cannot execute critical code. For information about transparency levels, see [Security-Transparent Code, Level 1](/dotnet/framework/misc/security-transparent-code-level-1) and [Security-Transparent Code, Level 2](/dotnet/framework/misc/security-transparent-code-level-2). + > [!NOTE] - > Associating a dynamic method with a module in a trusted level 1 assembly that is security-agnostic, such as System.dll, does not permit elevation of trust. If the grant set of the code that calls the dynamic method does not include the grant set of System.dll (that is, full trust), is thrown when the dynamic method is called. - -- The transparency of a dynamic method that is associated with a partially trusted assembly depends on how the assembly is loaded. If the assembly is loaded with partial trust (for example, into a sandboxed application domain), the runtime ignores the security annotations of the assembly. The assembly and all its types and members, including dynamic methods, are treated as transparent. The runtime pays attention to security annotations only if the partial-trust assembly is loaded with full trust (for example, into the default application domain of a desktop application). In that case, the runtime assigns the dynamic method the default transparency for methods according to the assembly's annotations. - - For more information about reflection emit and transparency, see [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit). For information about transparency, see [Security Changes](/dotnet/framework/security/security-changes). - + > Associating a dynamic method with a module in a trusted level 1 assembly that is security-agnostic, such as System.dll, does not permit elevation of trust. If the grant set of the code that calls the dynamic method does not include the grant set of System.dll (that is, full trust), is thrown when the dynamic method is called. + +- The transparency of a dynamic method that is associated with a partially trusted assembly depends on how the assembly is loaded. If the assembly is loaded with partial trust (for example, into a sandboxed application domain), the runtime ignores the security annotations of the assembly. The assembly and all its types and members, including dynamic methods, are treated as transparent. The runtime pays attention to security annotations only if the partial-trust assembly is loaded with full trust (for example, into the default application domain of a desktop application). In that case, the runtime assigns the dynamic method the default transparency for methods according to the assembly's annotations. + + For more information about reflection emit and transparency, see [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit). For information about transparency, see [Security Changes](/dotnet/framework/security/security-changes). + ]]> The dynamic method doesn't have a method body. @@ -2299,41 +2242,41 @@ if the dynamic method is security-transparent at the current trust level; otherwise, . - , , and properties report the transparency level of the dynamic method as determined by the common language runtime (CLR). The combinations of these properties are shown in the following table: - -|Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| -|--------------------|------------------------|----------------------------|---------------------------| -|Critical|`true`|`false`|`false`| -|Safe critical|`true`|`true`|`false`| -|Transparent|`false`|`false`|`true`| - - Using these properties is much simpler than examining the security annotations of an assembly and its types, checking the current trust level, and attempting to duplicate the runtime's rules. - - The transparency of a dynamic method depends on the module it is associated with. If the dynamic method is associated with a type rather than a module, its transparency depends on the module that contains the type. Dynamic methods do not have security annotations, so they are assigned the default transparency for the associated module. - -- Anonymously hosted dynamic methods are always transparent, because the system-provided module that contains them is transparent. - -- The transparency of a dynamic method that is associated with a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is described in the following table. - - |Assembly annotation|Level 1 transparency|Level 2 transparency| - |-------------------------|--------------------------|--------------------------| - |Fully transparent|Transparent|Transparent| - |Fully critical|Critical|Critical| - |Mixed transparency|Transparent|Transparent| - |Security-agnostic|Safe-critical|Critical| - - For example, if you associate a dynamic method with a type that is in mscorlib.dll, which has level 2 mixed transparency, the dynamic method is transparent and cannot execute critical code. For information about transparency levels, see [Security-Transparent Code, Level 1](/dotnet/framework/misc/security-transparent-code-level-1) and [Security-Transparent Code, Level 2](/dotnet/framework/misc/security-transparent-code-level-2). - + , , and properties report the transparency level of the dynamic method as determined by the common language runtime (CLR). The combinations of these properties are shown in the following table: + +|Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| +|--------------------|------------------------|----------------------------|---------------------------| +|Critical|`true`|`false`|`false`| +|Safe critical|`true`|`true`|`false`| +|Transparent|`false`|`false`|`true`| + + Using these properties is much simpler than examining the security annotations of an assembly and its types, checking the current trust level, and attempting to duplicate the runtime's rules. + + The transparency of a dynamic method depends on the module it is associated with. If the dynamic method is associated with a type rather than a module, its transparency depends on the module that contains the type. Dynamic methods do not have security annotations, so they are assigned the default transparency for the associated module. + +- Anonymously hosted dynamic methods are always transparent, because the system-provided module that contains them is transparent. + +- The transparency of a dynamic method that is associated with a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is described in the following table. + + |Assembly annotation|Level 1 transparency|Level 2 transparency| + |-------------------------|--------------------------|--------------------------| + |Fully transparent|Transparent|Transparent| + |Fully critical|Critical|Critical| + |Mixed transparency|Transparent|Transparent| + |Security-agnostic|Safe-critical|Critical| + + For example, if you associate a dynamic method with a type that is in mscorlib.dll, which has level 2 mixed transparency, the dynamic method is transparent and cannot execute critical code. For information about transparency levels, see [Security-Transparent Code, Level 1](/dotnet/framework/misc/security-transparent-code-level-1) and [Security-Transparent Code, Level 2](/dotnet/framework/misc/security-transparent-code-level-2). + > [!NOTE] - > Associating a dynamic method with a module in a trusted level 1 assembly that is security-agnostic, such as System.dll, does not permit elevation of trust. If the grant set of the code that calls the dynamic method does not include the grant set of System.dll (that is, full trust), is thrown when the dynamic method is called. - -- The transparency of a dynamic method that is associated with a partially trusted assembly depends on how the assembly is loaded. If the assembly is loaded with partial trust (for example, into a sandboxed application domain), the runtime ignores the security annotations of the assembly. The assembly and all its types and members, including dynamic methods, are treated as transparent. The runtime pays attention to security annotations only if the partial-trust assembly is loaded with full trust (for example, into the default application domain of a desktop application). In that case, the runtime assigns the dynamic method the default transparency for methods according to the assembly's annotations. - - For more information about reflection emit and transparency, see [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit). For information about transparency, see [Security Changes](/dotnet/framework/security/security-changes). - + > Associating a dynamic method with a module in a trusted level 1 assembly that is security-agnostic, such as System.dll, does not permit elevation of trust. If the grant set of the code that calls the dynamic method does not include the grant set of System.dll (that is, full trust), is thrown when the dynamic method is called. + +- The transparency of a dynamic method that is associated with a partially trusted assembly depends on how the assembly is loaded. If the assembly is loaded with partial trust (for example, into a sandboxed application domain), the runtime ignores the security annotations of the assembly. The assembly and all its types and members, including dynamic methods, are treated as transparent. The runtime pays attention to security annotations only if the partial-trust assembly is loaded with full trust (for example, into the default application domain of a desktop application). In that case, the runtime assigns the dynamic method the default transparency for methods according to the assembly's annotations. + + For more information about reflection emit and transparency, see [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit). For information about transparency, see [Security Changes](/dotnet/framework/security/security-changes). + ]]> The dynamic method doesn't have a method body. @@ -2444,20 +2387,20 @@ Gets the module with which the dynamic method is logically associated. The with which the current dynamic method is associated. - property of a dynamic method. This code example is part of a larger example provided for the class. - + property of a dynamic method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Reflection.DynamicMethod.All/cpp/source.cpp" id="Snippet26"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/DynamicMethod/Overview/source.cs" id="Snippet26"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet26"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet26"::: + ]]> @@ -2498,22 +2441,22 @@ Gets the name of the dynamic method. The simple name of the method. - [!NOTE] -> It is not necessary to name dynamic methods. - - - -## Examples - The following code example displays the name of a dynamic method. This code example is part of a larger example provided for the class. - +> It is not necessary to name dynamic methods. + + + +## Examples + The following code example displays the name of a dynamic method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Reflection.DynamicMethod.All/cpp/source.cpp" id="Snippet27"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/DynamicMethod/Overview/source.cs" id="Snippet27"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet27"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet27"::: + ]]> @@ -2564,20 +2507,20 @@ Gets the class that was used in reflection to obtain the method. Always . - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Reflection.DynamicMethod.All/cpp/source.cpp" id="Snippet28"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/DynamicMethod/Overview/source.cs" id="Snippet28"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet28"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet28"::: + ]]> @@ -2618,11 +2561,11 @@ Gets the return parameter of the dynamic method. Always . - @@ -2663,20 +2606,20 @@ Gets the type of return value for the dynamic method. A representing the type of the return value of the current method; if the method has no return type. - . - - - -## Examples - The following code example displays the return type of a dynamic method. This code example is part of a larger example provided for the class. - + . + + + +## Examples + The following code example displays the return type of a dynamic method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Reflection.DynamicMethod.All/cpp/source.cpp" id="Snippet30"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/DynamicMethod/Overview/source.cs" id="Snippet30"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet30"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet30"::: + ]]> @@ -2716,20 +2659,20 @@ Gets the custom attributes of the return type for the dynamic method. An representing the custom attributes of the return type for the dynamic method. - method is always empty. - - - -## Examples - The following code example shows how to display the custom attributes of the return type of a dynamic method. This code example is part of a larger example provided for the class. - + method is always empty. + + + +## Examples + The following code example shows how to display the custom attributes of the return type of a dynamic method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Reflection.DynamicMethod.All/cpp/source.cpp" id="Snippet31"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/DynamicMethod/Overview/source.cs" id="Snippet31"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet31"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet31"::: + ]]> @@ -2772,20 +2715,20 @@ Returns the signature of the method, represented as a string. A string representing the method signature. - method of a dynamic method. This code example is part of a larger example provided for the class. - + method of a dynamic method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Reflection.DynamicMethod.All/cpp/source.cpp" id="Snippet32"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/DynamicMethod/Overview/source.cs" id="Snippet32"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet32"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection.DynamicMethod.All/VB/source.vb" id="Snippet32"::: + ]]> diff --git a/xml/System.Reflection.Emit/MethodBuilder.xml b/xml/System.Reflection.Emit/MethodBuilder.xml index 704347600ee..5f2b2af737e 100644 --- a/xml/System.Reflection.Emit/MethodBuilder.xml +++ b/xml/System.Reflection.Emit/MethodBuilder.xml @@ -75,61 +75,16 @@ Defines and represents a method (or constructor) on a dynamic class. - - class is used to fully describe a method in Microsoft intermediate language (MSIL), including the name, attributes, signature, and method body. It is used in conjunction with the class to create classes at runtime. - -## Global methods and methods as type members - You can use reflection emit to define global methods and to define methods as type members. The APIs that define methods return objects. - -### Global methods - A global method is defined by using the method, which returns a **MethodBuilder** object. - - Global methods must be static. If a dynamic module contains global methods, the method must be called before persisting the dynamic module or the containing dynamic assembly because the common language runtime postpones fixing up the dynamic module until all global functions have been defined. - - A global native method is defined by using the method. Platform invoke (PInvoke) methods must not be declared abstract or virtual. The runtime sets the attribute for a platform invoke method. - -### Methods as members of types - A method is defined as a type member by using the method, which returns a object. - - The method is used to set the name and parameter attributes of a parameter, or of the return value. The object returned by this method represents a parameter or the return value. The object can be used to set the marshaling, to set the constant value, and to apply custom attributes. - -## Attributes - Members of the enumeration define the precise character of a dynamic method: - -- Static methods are specified using the attribute. - -- Final methods (methods that cannot be overridden) are specified using the attribute. - -- Virtual methods are specified using the attribute. - -- Abstract methods are specified using the attribute. - -- Several attributes determine method visibility. See the description of the enumeration. - -- Methods that implement overloaded operators must set the attribute. - -- Finalizers must set the attribute. - -## Known Issues - -- Although is derived from , some of the abstract methods defined in the class are not fully implemented in . These methods throw the . For example the method is not fully implemented. You can reflect on these methods by retrieving the enclosing type using the or methods. - -- Custom modifiers are supported starting with the .NET Framework version 2.0. They are not supported in earlier versions. - - - -## Examples - The following example uses the class to create a method within a dynamic type. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Reflection.Emit.MethodBuilder Example/CPP/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/MethodBuilder/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.MethodBuilder Example/VB/source.vb" id="Snippet1"::: - - ]]> - + For more information about this API, see Supplemental API remarks for MethodBuilder. + + class to create a method within a dynamic type. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Reflection.Emit.MethodBuilder Example/CPP/source.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/MethodBuilder/Overview/source.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.MethodBuilder Example/VB/source.vb" id="Snippet1"::: + ]]> + @@ -195,34 +150,34 @@ The set of permissions the action applies to. Adds declarative security to this method. - can be called several times, with each call specifying a security action (such as `Demand`, `Assert`, and `Deny`) and a set of permissions that the action applies to. - + can be called several times, with each call specifying a security action (such as `Demand`, `Assert`, and `Deny`) and a set of permissions that the action applies to. + > [!NOTE] -> In the .NET Framework versions 1.0, 1.1, and 2.0, the declarative security attributes applied to a method by using the method are stored in the old XML metadata format. See Emitting Declarative Security Attributes. - - - -## Examples - The code sample below illustrates the contextual use of `AddDeclarativeSecurity` to require the caller of a method to have unrestricted permissions. - +> In the .NET Framework versions 1.0, 1.1, and 2.0, the declarative security attributes applied to a method by using the method are stored in the old XML metadata format. See Emitting Declarative Security Attributes. + + + +## Examples + The code sample below illustrates the contextual use of `AddDeclarativeSecurity` to require the caller of a method to have unrestricted permissions. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Reflection.Emit.MethodBuilder.AddDeclarativeSecurity Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/MethodBuilder/AddDeclarativeSecurity/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.MethodBuilder.AddDeclarativeSecurity Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.MethodBuilder.AddDeclarativeSecurity Example/VB/source.vb" id="Snippet1"::: + ]]> The is invalid (, , and are invalid). - The containing type has been created using . - - -or- - - The permission set contains an action that was added earlier by . - - -or- - + The containing type has been created using . + + -or- + + The permission set contains an action that was added earlier by . + + -or- + For the current method, the property is , but the property is . is . @@ -342,13 +297,13 @@ Not supported for this type. Not supported. - always represents a generic method definition, and thus cannot be invoked. - - For more information, see and . For information on generic types, see . - + always represents a generic method definition, and thus cannot be invoked. + + For more information, see and . For information on generic types, see . + ]]> The invoked method is not supported in the base class. @@ -390,34 +345,34 @@ The number of valid bytes in the MSIL array. This value is ignored if MSIL is . Creates the body of the method using a supplied byte array of Microsoft intermediate language (MSIL) instructions. - [!NOTE] -> This is currently not fully supported. The user cannot supply the location of token fix ups and exception handlers. - - - -## Examples - In the example provided below, a simple method that adds two integers is generated via opcode using `CreateMethodBody`. - +> This is currently not fully supported. The user cannot supply the location of token fix ups and exception handlers. + + + +## Examples + In the example provided below, a simple method that adds two integers is generated via opcode using `CreateMethodBody`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Refelction.Emit.MethodBuilder.CreateMethodBody Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/MethodBuilder/CreateMethodBody/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Refelction.Emit.MethodBuilder.CreateMethodBody Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Refelction.Emit.MethodBuilder.CreateMethodBody Example/VB/source.vb" id="Snippet1"::: + ]]> The is not within the range of indexes of the supplied MSIL instruction array and is not . - The containing type was previously created using . - - -or- - - This method was called previously on this with an argument that was not . - - -or- - + The containing type was previously created using . + + -or- + + This method was called previously on this with an argument that was not . + + -or- + For the current method, the property is , but the property is . @@ -469,15 +424,15 @@ Returns the type that declares this method. Read-only. The type that declares this method. - @@ -532,47 +487,47 @@ Sets the number of generic type parameters for the current method, specifies their names, and returns an array of objects that can be used to define their constraints. An array of objects representing the type parameters of the generic method. - method makes the current method generic. There is no way to undo this change. Calling this method a second time causes an . - - The type parameters of the generic method can be retrieved later by using the method. - - By convention, a type parameter name is a single uppercase letter. - - For more information, see and . For information on generic types, see . - - - -## Examples - The following code example creates a dynamic type, `DemoType`, which contains the dynamic generic method `DemoMethod`. This method has two generic type parameters, one of which is used as a parameter, and the other as the return type. - - When the code is executed, the dynamic assembly is saved as DemoGenericMethod1.dll, and can be examined using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler). - + method makes the current method generic. There is no way to undo this change. Calling this method a second time causes an . + + The type parameters of the generic method can be retrieved later by using the method. + + By convention, a type parameter name is a single uppercase letter. + + For more information, see and . For information on generic types, see . + + + +## Examples + The following code example creates a dynamic type, `DemoType`, which contains the dynamic generic method `DemoMethod`. This method has two generic type parameters, one of which is used as a parameter, and the other as the return type. + + When the code is executed, the dynamic assembly is saved as DemoGenericMethod1.dll, and can be examined using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler). + > [!NOTE] -> This code example generates a simple method body that merely returns a null reference. For a code example with a more fully developed method body that creates and uses generic types, see [How to: Define a Generic Method with Reflection Emit](/dotnet/framework/reflection-and-codedom/how-to-define-a-generic-method-with-reflection-emit). - +> This code example generates a simple method body that merely returns a null reference. For a code example with a more fully developed method body that creates and uses generic types, see [How to: Define a Generic Method with Reflection Emit](/dotnet/framework/reflection-and-codedom/how-to-define-a-generic-method-with-reflection-emit). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/GenericMethodBuilder/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/MethodBuilder/DefineGenericParameters/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/GenericMethodBuilder/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/GenericMethodBuilder/VB/source.vb" id="Snippet1"::: + ]]> - Generic type parameters have already been defined for this method. - - -or- - - The method has been completed already. - - -or- - + Generic type parameters have already been defined for this method. + + -or- + + The method has been completed already. + + -or- + The method has been called for the current method. - is . - - -or- - + is . + + -or- + An element of is . is an empty array. @@ -676,31 +631,31 @@ Sets the parameter attributes and the name of a parameter of this method, or of the return value of this method. Returns a ParameterBuilder that can be used to apply custom attributes. Returns a object that represents a parameter of this method or the return value of this method. - object returned by this method can be used to set the default value for a parameter or to apply custom attributes. - - Parameter numbering begins with 1, so `position` is 1 for the first parameter. If `position` is zero, this method affects the return value. - + object returned by this method can be used to set the default value for a parameter or to apply custom attributes. + + Parameter numbering begins with 1, so `position` is 1 for the first parameter. If `position` is zero, this method affects the return value. + > [!NOTE] -> In the .NET Framework versions 1.0 and 1.1, an exception is thrown if `position` is zero, so this method cannot be used to modify attributes of the return value in those versions. - +> In the .NET Framework versions 1.0 and 1.1, an exception is thrown if `position` is zero, so this method cannot be used to modify attributes of the return value in those versions. + ]]> - The method has no parameters. - - -or- - - is less than zero. - - -or- - + The method has no parameters. + + -or- + + is less than zero. + + -or- + is greater than the number of the method's parameters. - The containing type was previously created using . - - -or- - + The containing type was previously created using . + + -or- + For the current method, the property is , but the property is . @@ -796,11 +751,11 @@ if is an instance of and is equal to this object; otherwise, . - @@ -842,11 +797,11 @@ Return the base implementation for a method. The base implementation of this method. - @@ -986,13 +941,13 @@ Returns an array of objects that represent the type parameters of the method, if it is generic. An array of objects representing the type parameters, if the method is generic, or if the method is not generic. - method that is used to define them. - - For more information, see and . For information on generic types, see . - + method that is used to define them. + + For more information, see and . For information on generic types, see . + ]]> @@ -1037,13 +992,13 @@ Returns this method. The current instance of . - cannot be used to emit a constructed generic method directly. The emitted method is a generic method definition. - - For more information, see and . For information on generic types, see . - + cannot be used to emit a constructed generic method directly. The emitted method is a generic method definition. + + For more information, see and . For information on generic types, see . + ]]> The current method is not generic. That is, the property returns . @@ -1140,21 +1095,21 @@ Returns an for this method with a default Microsoft intermediate language (MSIL) stream size of 64 bytes. Returns an object for this method. - - The method should not have a body because of its or flags, for example because it has the flag. - - -or- - + The method should not have a body because of its or flags, for example because it has the flag. + + -or- + The method is a generic method, but not a generic method definition. That is, the property is , but the property is . @@ -1199,21 +1154,21 @@ Returns an for this method with the specified Microsoft intermediate language (MSIL) stream size. Returns an object for this method. - - The method should not have a body because of its or flags, for example because it has the flag. - - -or- - + The method should not have a body because of its or flags, for example because it has the flag. + + -or- + The method is a generic method, but not a generic method definition. That is, the property is , but the property is . @@ -1314,15 +1269,15 @@ Returns a reference to the module that contains this method. Returns a reference to the module that contains this method. - @@ -1365,15 +1320,15 @@ Returns the parameters of this method. An array of objects that represent the parameters of the method. - This method is not currently supported. Retrieve the method using and call on the returned . @@ -1455,11 +1410,11 @@ if the local variables in this method should be zero initialized; otherwise . - For the current method, the property is , but the property is . (Get or set.) @@ -1545,14 +1500,14 @@ Dynamically invokes the method reflected by this instance on the given object, passing along the specified parameters, and under the constraints of the given binder. Returns an object containing the return value of the invoked method. - [!NOTE] -> Access restrictions are ignored for fully-trusted code. That is, private constructors, methods, fields, and properties can be accessed and invoked using Reflection whenever the code is fully-trusted. - +> Access restrictions are ignored for fully-trusted code. That is, private constructors, methods, fields, and properties can be accessed and invoked using Reflection whenever the code is fully-trusted. + ]]> This method is not currently supported. Retrieve the method using and call on the returned . @@ -1668,20 +1623,20 @@ if the method is generic; otherwise, . - method to add type parameters. This change cannot be reversed. - - - -## Examples - The following code example displays the status of a method. This code is part of a larger example provided for the method. - + method to add type parameters. This change cannot be reversed. + + + +## Examples + The following code example displays the status of a method. This code is part of a larger example provided for the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/GenericMethodBuilder/cpp/source.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/MethodBuilder/DefineGenericParameters/source.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/GenericMethodBuilder/VB/source.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/GenericMethodBuilder/VB/source.vb" id="Snippet7"::: + ]]> How to: Define a Generic Method with Reflection Emit @@ -1724,20 +1679,20 @@ if the current object represents the definition of a generic method; otherwise, . - can only be used to create generic method definitions; it cannot be used to create a constructed generic method directly. However, a subclass of might represent a constructed generic method. - - - -## Examples - The following code example displays the status of a method. This code is part of a larger example provided for the method. - + can only be used to create generic method definitions; it cannot be used to create a constructed generic method directly. However, a subclass of might represent a constructed generic method. + + + +## Examples + The following code example displays the status of a method. This code is part of a larger example provided for the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/GenericMethodBuilder/cpp/source.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/MethodBuilder/DefineGenericParameters/source.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/GenericMethodBuilder/VB/source.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/GenericMethodBuilder/VB/source.vb" id="Snippet7"::: + ]]> How to: Define a Generic Method with Reflection Emit @@ -1774,11 +1729,11 @@ Throws a in all cases. Throws a in all cases. - , call the method on the completed type, and get the property on the resulting . - + , call the method on the completed type, and get the property on the resulting . + ]]> In all cases. This property is not supported in dynamic assemblies. @@ -1815,11 +1770,11 @@ Throws a in all cases. Throws a in all cases. - , call the method on the completed type, and get the property on the resulting . - + , call the method on the completed type, and get the property on the resulting . + ]]> In all cases. This property is not supported in dynamic assemblies. @@ -1856,11 +1811,11 @@ Throws a in all cases. Throws a in all cases. - , call the method on the completed type, and get the property on the resulting . - + , call the method on the completed type, and get the property on the resulting . + ]]> In all cases. This property is not supported in dynamic assemblies. @@ -1923,25 +1878,25 @@ Returns a generic method constructed from the current generic method definition using the specified generic type arguments. A representing the generic method constructed from the current generic method definition using the specified generic type arguments. - , before the enclosing type has been completed. You can use the method to create a for such a constructed method, and use the in the emitted call. - - - -## Examples - The following code example creates a constructed method from an incomplete generic method definition in an incomplete type. - - The example creates a transient assembly and module with a single type, adds a method `M`, and makes the method generic by adding a type parameter T using the method. The type parameter is used as the type of the method's parameter, and also as its return type. The generic method definition is not given a body, and the enclosing type is not completed. The method is then used to make the constructed method `M` (`M(Of String)` in Visual Basic). The example code has no output, because the subclass of returned by the method does not allow reflection over its parameters. - + , before the enclosing type has been completed. You can use the method to create a for such a constructed method, and use the in the emitted call. + + + +## Examples + The following code example creates a constructed method from an incomplete generic method definition in an incomplete type. + + The example creates a transient assembly and module with a single type, adds a method `M`, and makes the method generic by adding a type parameter T using the method. The type parameter is used as the type of the method's parameter, and also as its return type. The generic method definition is not given a body, and the enclosing type is not completed. The method is then used to make the constructed method `M` (`M(Of String)` in Visual Basic). The example code has no output, because the subclass of returned by the method does not allow reflection over its parameters. + > [!NOTE] -> For another code example that uses , see . is also used extensively when emitting code that uses generic types. See [How to: Define a Generic Method with Reflection Emit](/dotnet/framework/reflection-and-codedom/how-to-define-a-generic-method-with-reflection-emit). - +> For another code example that uses , see . is also used extensively when emitting code that uses generic types. See [How to: Define a Generic Method with Reflection Emit](/dotnet/framework/reflection-and-codedom/how-to-define-a-generic-method-with-reflection-emit). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/MethodBuilder.MakeGenericMethod/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/MethodBuilder/MakeGenericMethod/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MethodBuilder.MakeGenericMethod/vb/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MethodBuilder.MakeGenericMethod/vb/source.vb" id="Snippet1"::: + ]]> How to: Define a Generic Method with Reflection Emit @@ -1974,14 +1929,14 @@ Gets a token that identifies the current dynamic module in metadata. An integer token that identifies the current module in metadata. - [!NOTE] > Information about metadata tokens can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - + ]]> @@ -2087,13 +2042,13 @@ Gets the module in which the current method is being defined. The in which the member represented by the current is being defined. - property to get the type in which the method is being declared, and then calling the property of the resulting object. - - This property is also equivalent to calling . - + property to get the type in which the method is being declared, and then calling the property of the resulting object. + + This property is also equivalent to calling . + ]]> @@ -2222,11 +2177,11 @@ Gets a object that contains information about the return type of the method, such as whether the return type has custom modifiers. A object that contains information about the return type. - object returned by this property to discover whether custom modifiers, such as , have been applied to the return type. - + object returned by this property to discover whether custom modifiers, such as , have been applied to the return type. + ]]> The declaring type has not been created. @@ -2270,13 +2225,13 @@ Gets the return type of the method represented by this . The return type of the method. - [!NOTE] -> Starting with the .NET Framework 2.0 and the .NET Compact Framework 2.0, this member is inherited from the base class, . See . - +> Starting with the .NET Framework 2.0 and the .NET Compact Framework 2.0, this member is inherited from the base class, . See . + ]]> @@ -2317,11 +2272,11 @@ Returns the custom attributes of the method's return type. Read-only. The custom attributes of the method's return type. - after the containing has been created and invoked on the . - + after the containing has been created and invoked on the . + ]]> @@ -2382,11 +2337,11 @@ An instance of a helper class to describe the custom attribute. Sets a custom attribute using a custom attribute builder. - method can interact with the method when the two methods are used in combination. See the Remarks section of the method for details. - + method can interact with the method when the two methods are used in combination. See the Remarks section of the method for details. + ]]> @@ -2446,14 +2401,14 @@ A byte blob representing the attributes. Sets a custom attribute using a specified custom attribute blob. - method can interact with the method when the two methods are used in combination. See the Remarks section of the method for details. - + + The method can interact with the method when the two methods are used in combination. See the Remarks section of the method for details. + ]]> @@ -2549,30 +2504,30 @@ For information on how to format `binaryAttribute`, see the metadata specificati The implementation flags to set. Sets the implementation flags for this method. - method in combination with the method, be aware of potential interactions. For example, using the method to add the attribute also sets the flag. If you subsequently call the method, the flag is overwritten. There are two ways to avoid this: - -- Call the method before you call the method. The method always respects existing method implementation flags. - -- When you set implementation flags, call the method to retrieve the existing flags, use bitwise OR to add your flag, and then call the method. - - - -## Examples - The code sample below illustrates the contextual use of the `SetImplementationFlags` method to describe the implementation of MSIL in a method body. - + method in combination with the method, be aware of potential interactions. For example, using the method to add the attribute also sets the flag. If you subsequently call the method, the flag is overwritten. There are two ways to avoid this: + +- Call the method before you call the method. The method always respects existing method implementation flags. + +- When you set implementation flags, call the method to retrieve the existing flags, use bitwise OR to add your flag, and then call the method. + + + +## Examples + The code sample below illustrates the contextual use of the `SetImplementationFlags` method to describe the implementation of MSIL in a method body. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Reflection.Emit.MethodBuilder.SetImplementationFlags Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/MethodBuilder/SetImplementationFlags/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.MethodBuilder.SetImplementationFlags Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.MethodBuilder.SetImplementationFlags Example/VB/source.vb" id="Snippet1"::: + ]]> - The containing type was previously created using . - - -or- - + The containing type was previously created using . + + -or- + For the current method, the property is , but the property is . @@ -2648,21 +2603,21 @@ For information on how to format `binaryAttribute`, see the metadata specificati Marshaling information for the return type of this method. Sets marshaling information for the return type of this method. - - The containing type was previously created using . - - -or- - + The containing type was previously created using . + + -or- + For the current method, the property is , but the property is . @@ -2707,19 +2662,19 @@ For information on how to format `binaryAttribute`, see the metadata specificati is . - is negative. - - -or- - - One of specifies an offset outside of . - - -or- - + is negative. + + -or- + + One of specifies an offset outside of . + + -or- + One of specifies an offset that is outside the array. - The containing type was previously created using the method. - - -or- - + The containing type was previously created using the method. + + -or- + This method was called previously on this object. @@ -2778,29 +2733,29 @@ For information on how to format `binaryAttribute`, see the metadata specificati An array of objects representing the parameter types. Sets the number and types of parameters for a method. - method that accepts an array of parameter types. However, a generic method can have parameters whose types are specified by one or more of its own generic type parameters, which cannot be defined until after the method has been defined. Use this method to set the parameter types in that case. - - If the return type has optional or required custom modifiers, such as , use the method overload. - - Calling this method replaces any parameter types that were set using the method. - - - -## Examples - The following code example uses the method to make a method generic. The method is used to give the method one parameter, whose type will be specified by the first generic type parameter. The method is used to give the method a return type, specified by the second generic type parameter. - - This code is part of a larger example provided for the method. - + method that accepts an array of parameter types. However, a generic method can have parameters whose types are specified by one or more of its own generic type parameters, which cannot be defined until after the method has been defined. Use this method to set the parameter types in that case. + + If the return type has optional or required custom modifiers, such as , use the method overload. + + Calling this method replaces any parameter types that were set using the method. + + + +## Examples + The following code example uses the method to make a method generic. The method is used to give the method one parameter, whose type will be specified by the first generic type parameter. The method is used to give the method a return type, specified by the second generic type parameter. + + This code is part of a larger example provided for the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/GenericMethodBuilder/cpp/source.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/MethodBuilder/DefineGenericParameters/source.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/GenericMethodBuilder/VB/source.vb" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/GenericMethodBuilder/VB/source.vb" id="Snippet3"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/GenericMethodBuilder/cpp/source.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/MethodBuilder/DefineGenericParameters/source.cs" id="Snippet5"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/GenericMethodBuilder/VB/source.vb" id="Snippet5"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/GenericMethodBuilder/VB/source.vb" id="Snippet5"::: + ]]> The current method is generic, but is not a generic method definition. That is, the property is , but the property is . @@ -2858,27 +2813,27 @@ For information on how to format `binaryAttribute`, see the metadata specificati A object that represents the return type of the method. Sets the return type of the method. - , use the method overload. - - Calling this method replaces a return type established using the method. - - - -## Examples - The following code example uses the method to make a method generic. The method is used to give the method one parameter, whose type will be specified by the first generic type parameter. The method is used to give the method a return type, specified by the second generic type parameter. - - This code is part of a larger example provided for the method. - + , use the method overload. + + Calling this method replaces a return type established using the method. + + + +## Examples + The following code example uses the method to make a method generic. The method is used to give the method one parameter, whose type will be specified by the first generic type parameter. The method is used to give the method a return type, specified by the second generic type parameter. + + This code is part of a larger example provided for the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/GenericMethodBuilder/cpp/source.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/MethodBuilder/DefineGenericParameters/source.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/GenericMethodBuilder/VB/source.vb" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/GenericMethodBuilder/VB/source.vb" id="Snippet3"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/GenericMethodBuilder/cpp/source.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/MethodBuilder/DefineGenericParameters/source.cs" id="Snippet5"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/GenericMethodBuilder/VB/source.vb" id="Snippet5"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/GenericMethodBuilder/VB/source.vb" id="Snippet5"::: + ]]> The current method is generic, but is not a generic method definition. That is, the property is , but the property is . @@ -2981,27 +2936,27 @@ For information on how to format `binaryAttribute`, see the metadata specificati An array of arrays of types. Each array of types represents the optional custom modifiers for the corresponding parameter, such as . If a particular parameter has no optional custom modifiers, specify instead of an array of types. If none of the parameters have optional custom modifiers, specify instead of an array of arrays. Sets the method signature, including the return type, the parameter types, and the required and optional custom modifiers of the return type and parameter types. - method that accepts an array of parameter types. However, a generic method can have parameters whose types are specified by one or more of its own generic type parameters, which cannot be defined until after the method has been defined. Use this method to set the parameter types in that case. - - If neither the return type nor the parameter types have optional or required custom modifiers, such as , you can use the and methods. - - Calling this method replaces the parameters and return type established using the method. - - - -## Examples - The following code example contains source code for a generic class named Sample that has a type parameter `T`. The class has a field named `Field`, of type `T`, and a generic method `GM` with its own type parameter, `U`. Method `GM` creates an instance of Sample, substituting its own type parameter `U` for the type parameter of Sample, and stores its input parameter in `Field`. This source code is compiled but not used; you can view it with the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), and compare it to the code emitted by class `Example`. - - The code in class `Example` demonstrates the use of the method in emitting generic code. The `Main` method of class `Example` creates a dynamic assembly containing a class named `Sample`, and uses the method to make it generic by adding a type parameter named `T`. A parameterless constructor and a field named `Field`, of type `T`, are added to class `Sample`. A method `GM` is added, and turned into a generic method using the method. The type parameter of `GM` is named `U`. Once the type parameter is defined, the signature of `GM` is added, using the method. There is no return type, and no required or custom modifiers, so all the parameters of this method are `null` except `parameterTypes`, which sets the type of the only parameter of the method; this is set to the method's type parameter, `U`. The body of the method creates an instance of the constructed type `Sample` (`Sample(Of U)` in Visual Basic), assigns the method's parameter to `Field`, and then prints the value of `Field`. A dummy type is defined, to hold the entry point method `Main`. In the body of `Main`, the static `GM` method is invoked on the constructed generic type `Sample` (`Sample(Of Integer)` in Visual Basic), with type substituted for `U`. The method is used to create a for the static `GM` method of the constructed generic type `Sample`, and the method is then used to create a that can emitted in a method call. - - When the code example is run, it saves the emitted assembly as TypeBuilderGetFieldExample.exe. You can run TypeBuilderGetFieldExample.exe, and you can use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to compare the emitted code with the code for the `Sample` class that is compiled into the code example itself. - + method that accepts an array of parameter types. However, a generic method can have parameters whose types are specified by one or more of its own generic type parameters, which cannot be defined until after the method has been defined. Use this method to set the parameter types in that case. + + If neither the return type nor the parameter types have optional or required custom modifiers, such as , you can use the and methods. + + Calling this method replaces the parameters and return type established using the method. + + + +## Examples + The following code example contains source code for a generic class named Sample that has a type parameter `T`. The class has a field named `Field`, of type `T`, and a generic method `GM` with its own type parameter, `U`. Method `GM` creates an instance of Sample, substituting its own type parameter `U` for the type parameter of Sample, and stores its input parameter in `Field`. This source code is compiled but not used; you can view it with the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), and compare it to the code emitted by class `Example`. + + The code in class `Example` demonstrates the use of the method in emitting generic code. The `Main` method of class `Example` creates a dynamic assembly containing a class named `Sample`, and uses the method to make it generic by adding a type parameter named `T`. A parameterless constructor and a field named `Field`, of type `T`, are added to class `Sample`. A method `GM` is added, and turned into a generic method using the method. The type parameter of `GM` is named `U`. Once the type parameter is defined, the signature of `GM` is added, using the method. There is no return type, and no required or custom modifiers, so all the parameters of this method are `null` except `parameterTypes`, which sets the type of the only parameter of the method; this is set to the method's type parameter, `U`. The body of the method creates an instance of the constructed type `Sample` (`Sample(Of U)` in Visual Basic), assigns the method's parameter to `Field`, and then prints the value of `Field`. A dummy type is defined, to hold the entry point method `Main`. In the body of `Main`, the static `GM` method is invoked on the constructed generic type `Sample` (`Sample(Of Integer)` in Visual Basic), with type substituted for `U`. The method is used to create a for the static `GM` method of the constructed generic type `Sample`, and the method is then used to create a that can emitted in a method call. + + When the code example is run, it saves the emitted assembly as TypeBuilderGetFieldExample.exe. You can run TypeBuilderGetFieldExample.exe, and you can use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to compare the emitted code with the code for the `Sample` class that is compiled into the code example itself. + :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/MethodBuilder/SetSignature/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/TypeBuilder.GetField_Generic/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/TypeBuilder.GetField_Generic/VB/source.vb" id="Snippet1"::: + ]]> The current method is generic, but is not a generic method definition. That is, the property is , but the property is . @@ -3120,30 +3075,30 @@ For information on how to format `binaryAttribute`, see the metadata specificati The byte blob that represents the value of the symbolic custom attribute. Set a symbolic custom attribute using a blob. - - The containing type was previously created using . - - -or- - - The module that contains this method is not a debug module. - - -or- - + The containing type was previously created using . + + -or- + + The module that contains this method is not a debug module. + + -or- + For the current method, the property is , but the property is . @@ -3226,11 +3181,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati Caller-allocated array that receives the IDs corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - Late-bound access using the COM IDispatch interface is not supported. @@ -3274,11 +3229,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati Receives a pointer to the requested type information object. Retrieves the type information for an object, which can then be used to get the type information for an interface. - Late-bound access using the COM IDispatch interface is not supported. @@ -3318,11 +3273,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati Points to a location that receives the number of type information interfaces provided by the object. Retrieves the number of type information interfaces that an object provides (either 0 or 1). - Late-bound access using the COM IDispatch interface is not supported. @@ -3376,11 +3331,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - Late-bound access using the COM IDispatch interface is not supported. diff --git a/xml/System.Reflection.Emit/TypeBuilder.xml b/xml/System.Reflection.Emit/TypeBuilder.xml index 66b883c298a..cb106ff255c 100644 --- a/xml/System.Reflection.Emit/TypeBuilder.xml +++ b/xml/System.Reflection.Emit/TypeBuilder.xml @@ -86,76 +86,22 @@ Defines and creates new instances of classes during run time. - + For more information about this API, see Supplemental API remarks for TypeBuilder. + is the root class used to control the creation of dynamic classes in the runtime. It provides a set of routines that are used to define classes, add methods and fields, and create the class inside a module. A new can be created from a dynamic module by calling the method, which returns a object. - - Reflection emit provides the following options for defining types: - -- Define a class or interface with the given name. - -- Define a class or interface with the given name and attributes. - -- Define a class with the given name, attributes, and base class. - -- Define a class with the given name, attributes, base class, and the set of interfaces that the class implements. - -- Define a class with the given name, attributes, base class, and packing size. - -- Define a class with the given name, attributes, base class, and the class size as a whole. - -- Define a class with the given name, attributes, base class, packing size, and the class size as a whole. - - To create an array type, pointer type, or byref type for an incomplete type that is represented by a object, use the method, method, or method, respectively. - - Before a type is used, the method must be called. **CreateType** completes the creation of the type. Following the call to **CreateType**, the caller can instantiate the type by using the method, and invoke members of the type by using the method. It is an error to invoke methods that change the implementation of a type after **CreateType** has been called. For example, the common language runtime throws an exception if the caller tries to add new members to a type. - - A class initializer is created by using the method. **DefineTypeInitializer** returns a object. - - Nested types are defined by calling one of the methods. - -## Attributes - The class uses the enumeration to further specify the characteristics of the type to be created: - -- Interfaces are specified using the and attributes. - -- Concrete classes (classes that cannot be extended) are specified using the attribute. +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyBuilderClass/cpp/24895.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/AssemblyBuilder/Overview/24895.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyBuilderClass/vb/24895.vb" id="Snippet1"::: -- Several attributes determine type visibility. See the description of the enumeration. +The following code sample demonstrates how to build a type dynamically by using `TypeBuilder`. -- If is specified, the class loader lays out fields in the order they are read from metadata. The class loader considers the specified packing size but ignores any specified field offsets. The metadata preserves the order in which the field definitions are emitted. Even across a merge, the metadata will not reorder the field definitions. The loader will honor the specified field offsets only if is specified. - -## Known Issues - -- Reflection emit does not verify whether a non-abstract class that implements an interface has implemented all the methods declared in the interface. However, if the class does not implement all the methods declared in an interface, the runtime does not load the class. - -- Although is derived from , some of the abstract methods defined in the class are not fully implemented in the class. Calls to these methods throw a exception. The desired functionality can be obtained by retrieving the created type using the or and reflecting on the retrieved type. - - - -## Examples - This section contains two code examples. The first example shows how to create a dynamic type with a field, constructor, property, and method. The second example builds a method dynamically from user input. - - **Example one** - - The following code example shows how to define and use a dynamic assembly. The example assembly contains one type, `MyDynamicType`, that has a private field, a property that gets and sets the private field, constructors that initialize the private field, and a method that multiplies a user-supplied number by the private field value and returns the result. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyBuilderClass/cpp/24895.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/AssemblyBuilder/Overview/24895.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyBuilderClass/vb/24895.vb" id="Snippet1"::: - - **Example two** - - The following code sample demonstrates how to build a dynamic type by using `TypeBuilder`. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Reflection.Emit ILGenerator Example/CPP/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/MethodBuilder/GetILGenerator/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit ILGenerator Example/VB/source.vb" id="Snippet1"::: - - ]]> - +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Reflection.Emit ILGenerator Example/CPP/source.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/MethodBuilder/GetILGenerator/source.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit ILGenerator Example/VB/source.vb" id="Snippet1"::: + ]]> + How to: Define a Generic Type with Reflection Emit diff --git a/xml/System.Reflection.PortableExecutable/DebugDirectoryEntryType.xml b/xml/System.Reflection.PortableExecutable/DebugDirectoryEntryType.xml index ea3ddbefc36..71cee2570a2 100644 --- a/xml/System.Reflection.PortableExecutable/DebugDirectoryEntryType.xml +++ b/xml/System.Reflection.PortableExecutable/DebugDirectoryEntryType.xml @@ -23,30 +23,7 @@ An enumeration that describes the format of the debugging information of a . - - must have all fields except for zeroed. - - ]]> - + For more information about this API, see Supplemental API remarks for DebugDirectoryEntryType. diff --git a/xml/System.Reflection/ModuleResolveEventHandler.xml b/xml/System.Reflection/ModuleResolveEventHandler.xml index 5cfcca4e05a..be8e619682a 100644 --- a/xml/System.Reflection/ModuleResolveEventHandler.xml +++ b/xml/System.Reflection/ModuleResolveEventHandler.xml @@ -59,42 +59,33 @@ The arguments supplied by the object describing the event. Represents the method that will handle the event of an . The module that satisfies the request. - - If the common language runtime class loader cannot resolve a reference to an internal module of an assembly through normal means, this event is raised. The event handler for this delegate must locate and return a module that satisfies the request. + + [!NOTE] -> The module file Server1.netmodule must be in a subdirectory named "subfolder" for this example to work properly. - - :::code language="csharp" source="~/snippets/csharp/System.Reflection/ModuleResolveEventHandler/Overview/mysample.cs" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System.Reflection/ModuleResolveEventHandler/Overview/server1.cs" id="Snippet2"::: - - ]]> - +> The module file Server1.netmodule must be in a subdirectory named "subfolder" for this example to work properly. + ]]> + diff --git a/xml/System.Resources/MissingManifestResourceException.xml b/xml/System.Resources/MissingManifestResourceException.xml index b4eb7be6688..4253fc89cca 100644 --- a/xml/System.Resources/MissingManifestResourceException.xml +++ b/xml/System.Resources/MissingManifestResourceException.xml @@ -77,50 +77,7 @@ The exception that is thrown if the main assembly does not contain the resources for the neutral culture, and an appropriate satellite assembly is missing. - - is thrown when the attempt to retrieve a resource fails because the resource set for the neutral culture could not be loaded from a particular assembly. Although the exception is thrown when you try to retrieve a particular resource, it is caused by the failure to load the resource set rather than the failure to find the resource. - -> [!NOTE] -> For additional information, see the "Handling a MissingManifestResourceException Exception" section in the class topic. - -The main causes of the exception include the following: - -- The resource set is not identified by its fully qualified name. For example, if the `baseName` parameter in the call to the method specifies the root name of the resource set without a namespace, but the resource set is assigned a namespace when it is stored in its assembly, the call to the method throws this exception. - - If you've embedded the .resources file that contains the default culture's resources in your executable and your app is throwing a , you can use a reflection tool such as the [IL Disassembler (Ildasm.exe)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to determine the fully qualified name of the resource. In ILDasm, double click the executable's **MANIFEST** label to open the **MANIFEST** window. Resources appear as `.mresource` items and are listed after external assembly references and custom assembly-level attributes. You can also compile the following simple utility, which lists the fully qualified names of embedded resources in the assembly whose name is passed to it as a command-line parameter. - - :::code language="csharp" source="~/snippets/csharp/System.Resources/MissingManifestResourceException/Overview/resourcenames.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.class/vb/resourcenames.vb" id="Snippet4"::: - -- You identify the resource set by its resource file name (along with its optional namespace) and its file extension rather than by its namespace and root file name alone. For example, this exception is thrown if the neutral culture's resource set is named `GlobalResources` and you supply a value of `GlobalResources.resources` (instead of `GlobalResources`) to the `baseName` parameter of the constructor. - -- The culture-specific resource set that is identified in a method call cannot be found, and the fallback resource set cannot be loaded. For example, if you create satellite assemblies for the English (United States) and Russia (Russian) cultures but you fail to provide a resource set for the neutral culture, this exception is thrown if your app's current culture is English (United Kingdom). - - uses the HRESULT COR_E_MISSINGMANIFESTRESOURCE, which has the value 0x80131532. - - uses the default implementation, which supports reference equality. - -For a list of initial property values for an instance of , see the constructors. - -> [!NOTE] -> We recommend that you include a neutral set of resources in your main assembly, so your app won't fail if a satellite assembly is unavailable. - -### Universal Windows Platform (UWP) apps - -UWP apps deploy resources for multiple cultures, including the neutral culture, in a single package resource index (.pri) file. As a result, in a UWP app, if resources for the preferred culture cannot be found, the is thrown under either of the following conditions: - -- The app does not include a .pri file, or the .pri file could not be opened. - -- The app's .pri file does not contain a resource set for the given root name. - - ]]> - + For more information about this API, see Supplemental API remarks for MissingManifestResourceException. Handling and throwing exceptions in .NET @@ -174,16 +131,16 @@ UWP apps deploy resources for multiple cultures, including the neutral culture, Initializes a new instance of the class with default properties. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The localized error message for .| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The localized error message for .| + ]]> @@ -230,16 +187,16 @@ UWP apps deploy resources for multiple cultures, including the neutral culture, The error message that explains the reason for the exception. Initializes a new instance of the class with the specified error message. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The `message` string.| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The `message` string.| + ]]> @@ -300,11 +257,11 @@ UWP apps deploy resources for multiple cultures, including the neutral culture, The contextual information about the source or destination of the exception. Initializes a new instance of the class from serialized data. - @@ -353,18 +310,18 @@ UWP apps deploy resources for multiple cultures, including the neutral culture, The exception that is the cause of the current exception. If the parameter is not , 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 `null` 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 `null` 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.Resources/NeutralResourcesLanguageAttribute.xml b/xml/System.Resources/NeutralResourcesLanguageAttribute.xml index bf894e27148..2edd9ddc09d 100644 --- a/xml/System.Resources/NeutralResourcesLanguageAttribute.xml +++ b/xml/System.Resources/NeutralResourcesLanguageAttribute.xml @@ -70,111 +70,7 @@ Informs the resource manager of an app's default culture. This class cannot be inherited. - - attribute informs the resource manager of an app's default culture and the location of its resources. By default, resources are embedded in the main app assembly, and you can use the attribute as follows. This statement specifies that the English (United States) is the app's default culture. - - :::code language="csharp" source="~/snippets/csharp/System.Resources/NeutralResourcesLanguageAttribute/Overview/example1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.neutralresourceslanguageattribute/vb/example1.vb" id="Snippet1"::: - - You can also use the attribute to indicate where can find the resources of the default culture by providing an enumeration value in the attribute statement. This is most commonly done to indicate that the resources reside in a satellite assembly. For example, the following statement specifies that English (United States) is the app's default or neutral culture and that its resources reside in a satellite assembly. The object will look for them in a subdirectory named en-US. - - :::code language="csharp" source="~/snippets/csharp/System.Resources/NeutralResourcesLanguageAttribute/Overview/example2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.neutralresourceslanguageattribute/vb/example2.vb" id="Snippet2"::: - -> [!TIP] -> We recommend that you always use the attribute to define the default culture of your app. - - The attribute performs two roles: - -- If the default culture's resources are embedded in the app's main assembly and has to retrieve resources that belong to the same culture as the default culture, the automatically uses the resources located in the main assembly instead of searching for a satellite assembly. This bypasses the usual assembly probe, improves lookup performance for the first resource you load, and can reduce your working set. See [Packaging and Deploying Resources](/dotnet/framework/resources/packaging-and-deploying-resources-in-desktop-apps) for the process uses to probe for resource files. - -- If the default culture's resources are located in a satellite assembly rather than in the main app assembly, the attribute specifies the culture and the directory from which the runtime can load the resources. - -## Windows 8.x Store Apps - In Windows 8.x Store apps whose resources are loaded and retrieved by using the class, the attribute defines the neutral culture whose resources are used in the event of a failed probe. It does not specify the location of the resources. By default, uses the app's package resource index (PRI) file to locate the resources of the default culture. The neutral culture that is defined by the attribute is added to the end of the UI language list to simulate this effect. - - If you load and retrieve resources by using the Windows Runtime[Windows.ApplicationModel.Resources.ResourceLoader](https://go.microsoft.com/fwlink/p/?LinkId=238182) class or the types in the [Windows.ApplicationModel.Resources.Core](https://go.microsoft.com/fwlink/p/?LinkId=238194) namespace, the attribute is ignored. - - - -## Examples - The following example uses a simple "Hello World" app to illustrate the use of the attribute to define a default or fallback culture. It requires the creation of separate resource files for the English (en), English (United States) (en-US), and French (France) (fr-FR) cultures. The following shows the contents of a text file named ExampleResources.txt for the English culture. - -``` -# Resources for the default (en) culture. -Greeting=Hello -``` - - To use the resource file in an app, you must use the [Resource File Generator (Resgen.exe)](/dotnet/framework/tools/resgen-exe-resource-file-generator) to convert the file from its text (.txt) format to a binary (.resources) format as follows: - -``` -resgen ExampleResources.txt -``` - - When the app is compiled, the binary resource file will be embedded in the main app assembly. - - The following shows the contents of a text file named ExampleResources.en-US.txt that provides resources for the English (United States) culture. - -``` -# Resources for the en-US culture. -Greeting=Hi -``` - - The text file can be converted to a binary resources file by using the [Resource File Generator (ResGen.exe)](/dotnet/framework/tools/resgen-exe-resource-file-generator) at the command line as follows: - -``` -resgen ExampleResources.en-US.txt ExampleResources.en-US.resources -``` - - The binary resource file should then be compiled into an assembly by using [Assembly Linker (Al.exe)](/dotnet/framework/tools/al-exe-assembly-linker) and placed in the en-US subdirectory of the app directory by issuing the following command: - -``` -al /t:lib /embed:ExampleResources.en-US.resources /culture:en-US /out:en-us\Example.resources.dll -``` - - The following shows the contents of a text file named ExampleResources.fr-FR.txt that provides resources for the French (France) culture. - -``` -# Resources for the fr-FR culture. -Greeting=Bonjour -``` - - The text file can be converted to a binary resource file by using ResGen.exe at the command line as follows: - -``` -resgen ExampleResources.fr-FR.txt ExampleResources.fr-FR.resources -``` - - The binary resources file should then be compiled into an assembly by using Assembly Linker and placed in the fr-FR subdirectory of the app directory by issuing the following command: - -``` -al /t:lib /embed:ExampleResources.fr-FR.resources /culture:fr-FR /out:fr-FR\Example.resources.dll -``` - - The following example provides the executable code that sets the current culture, prompts for the user's name, and displays a localized string. - - :::code language="csharp" source="~/snippets/csharp/System.Resources/NeutralResourcesLanguageAttribute/Overview/example.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.neutralresourceslanguageattribute/vb/example.vb" id="Snippet1"::: - - It can be compiled by using the following command in Visual Basic: - -``` -vbc Example.vb /resource:ExampleResources.resources -``` - - or by using the following command in C#: - -``` -csc Example.cs /resource:ExampleResources.resources -``` - - ]]> - + For more information about this API, see Supplemental API remarks for NeutralResourcesLanguageAttribute. Packaging and Deploying Resources @@ -231,12 +127,12 @@ csc Example.cs /resource:ExampleResources.resources The name of the culture that the current assembly's neutral resources were written in. Initializes a new instance of the class. - The parameter is . @@ -284,13 +180,13 @@ For a detailed list of culture names available on Windows systems, see the **Lan One of the enumeration values that indicates the location from which to retrieve neutral fallback resources. Initializes a new instance of the class with the specified ultimate resource fallback location. - constructor with the enumeration to specify whether the class is to retrieve neutral fallback resources from the main app assembly (the default), or from a satellite assembly specified by the and the properties. - - For a detailed list of culture names available on Windows systems, see the **Language tag** column in the [list of language/region names supported by Windows](https://docs.microsoft.com/openspecs/windows_protocols/ms-lcid/a9eac961-e77d-41a6-90a5-ce1a8b0cdb9c). Culture names follow the standard defined by [BCP 47](https://tools.ietf.org/html/bcp47). - + constructor with the enumeration to specify whether the class is to retrieve neutral fallback resources from the main app assembly (the default), or from a satellite assembly specified by the and the properties. + + For a detailed list of culture names available on Windows systems, see the **Language tag** column in the [list of language/region names supported by Windows](https://docs.microsoft.com/openspecs/windows_protocols/ms-lcid/a9eac961-e77d-41a6-90a5-ce1a8b0cdb9c). Culture names follow the standard defined by [BCP 47](https://tools.ietf.org/html/bcp47). + ]]> @@ -343,12 +239,12 @@ For a detailed list of culture names available on Windows systems, see the **Lan Gets the culture name. The name of the default culture for the main assembly. - diff --git a/xml/System.Resources/ResourceManager.xml b/xml/System.Resources/ResourceManager.xml index d7f1483a6dd..ca27a669f63 100644 --- a/xml/System.Resources/ResourceManager.xml +++ b/xml/System.Resources/ResourceManager.xml @@ -71,337 +71,7 @@ Represents a resource manager that provides convenient access to culture-specific resources at run time. - - class retrieves resources from a binary .resources file that is embedded in an assembly or from a standalone .resources file. If an app has been localized and localized resources have been deployed in [satellite assemblies](/dotnet/framework/resources/creating-satellite-assemblies-for-desktop-apps), it looks up culture-specific resources, provides resource fallback when a localized resource does not exist, and supports resource serialization. - - For more information about creating and managing resources in desktop apps and Windows 8.x apps, see the following sections: - -- [Desktop Apps](#desktop) - - - [Creating Resources](#creating_resources) - - - [Instantiating a ResourceManager Object](#instantiating) - - - [ResourceManager and Culture-Specific Resources](#CultureSpecific) - - - [Retrieving Resources](#retrieving) - - - [Handling MissingManifestResourceException and MissingSatelliteAssemblyException Exceptions](#exception) - - - [Resource Versioning](#versioning) - - - [\ Configuration File Node](#config) - -- [Windows Store Apps](#ws) - - -## Desktop Apps - For desktop apps, the class retrieves resources from binary resource (.resources) files. Typically, a language compiler or the [Assembly Linker (AL.exe)](/dotnet/framework/tools/al-exe-assembly-linker) embeds these resource files in an assembly. You can also use a object to retrieve resources directly from a .resources file that is not embedded in an assembly, by calling the method. - -> [!CAUTION] -> Using standalone .resources files in an ASP.NET app will break XCOPY deployment, because the resources remain locked until they are explicitly released by the method. If you want to deploy resources with your ASP.NET apps, you should compile your .resources files into satellite assemblies. - - In a resource-based app, one .resources file contains the resources of the default culture whose resources are used if no culture-specific resources can be found. For example, if an app's default culture is English (en), the English language resources are used whenever localized resources cannot be found for a specific culture, such as English (United States) (en-US) or French (France) (fr-FR). Typically, the resources for the default culture are embedded in the main app assembly, and resources for other localized cultures are embedded in satellite assemblies. Satellite assemblies contain only resources. They have the same root file name as the main assembly and an extension of .resources.dll. For apps whose assemblies are not registered in the global assembly cache, satellite assemblies are stored in an app subdirectory whose name corresponds to the assembly's culture. - - -### Creating Resources - When you develop a resource-based app, you store resource information in text files (files that have a .txt or .restext extension) or XML files (files that have a .resx extension). You then compile the text or XML files with the [Resource File Generator (Resgen.exe)](/dotnet/framework/tools/resgen-exe-resource-file-generator) to create a binary .resources file. You can then embed the resulting .resources file in an executable or library by using a compiler option such as `/resources` for the C# and Visual Basic compilers, or you can embed it in a satellite assembly by using the [Assembly Linker (AI.exe)](/dotnet/framework/tools/al-exe-assembly-linker). If you include a .resx file in your Visual Studio project, Visual Studio handles the compilation and embedding of default and localized resources automatically as part of the build process. - - Ideally, you should create resources for every language your app supports, or at least for a meaningful subset of each language. The binary .resources file names follow the naming convention *basename*.*cultureName*.resources, where *basename* is the name of the app or the name of a class, depending on the level of detail you want. The property is used to determine *cultureName*. A resource for the app's default culture should be named *basename*.resources. - - For example, suppose that an assembly has several resources in a resource file that has the base name MyResources. These resource files should have names such as MyResources.ja-JP.resources for the Japan (Japanese) culture, MyResources.de.resources for the German culture, MyResources.zh-CHS.resources for the simplified Chinese culture, and MyResources.fr-BE.resources for the French (Belgium) culture. The default resource file should be named MyResources.resources. The culture-specific resource files are commonly packaged in satellite assemblies for each culture. The default resource file should be embedded in the app's main assembly. - - Note that [Assembly Linker](/dotnet/framework/tools/al-exe-assembly-linker) allows resources to be marked as private, but you should always mark them as public so they can be accessed by other assemblies. (Because a satellite assembly contains no code, resources that are marked as private are unavailable to your app through any mechanism.) - - For more information about creating, packaging, and deploying resources, see the articles [Creating Resource Files](/dotnet/framework/resources/creating-resource-files-for-desktop-apps), [Creating Satellite Assemblies](/dotnet/framework/resources/creating-satellite-assemblies-for-desktop-apps), and [Packaging and Deploying Resources](/dotnet/framework/resources/packaging-and-deploying-resources-in-desktop-apps). - - -### Instantiating a ResourceManager Object - You instantiate a object that retrieves resources from an embedded .resources file by calling one of its class constructor overloads. This tightly couples a object with a particular .resources file and with any associated localized .resources files in satellite assemblies. - - The two most commonly called constructors are: - -- looks up resources based on two pieces of information that you supply: the base name of the .resources file, and the assembly in which the default .resources file resides. The base name includes the namespace and root name of the .resources file, without its culture or extension. Note that .resources files that are compiled from the command line typically do not include a namespace name, whereas .resources files that are created in the Visual Studio environment do. For example, if a resource file is named MyCompany.StringResources.resources and the constructor is called from a static method named `Example.Main`, the following code instantiates a object that can retrieve resources from the .resources file: - - :::code language="csharp" source="~/snippets/csharp/System.Resources/ResourceManager/Overview/ctor1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/conceptual.resources.retrieving/vb/ctor1.vb" id="Snippet1"::: - -- looks up resources in satellite assemblies based on information from a type object. The type's fully qualified name corresponds to the base name of the .resources file without its file name extension. In desktop apps that are created by using the Visual Studio Resource Designer, Visual Studio creates a wrapper class whose fully qualified name is the same as the root name of the .resources file. For example, if a resource file is named MyCompany.StringResources.resources and there is a wrapper class named `MyCompany.StringResources`, the following code instantiates a object that can retrieve resources from the .resources file: - - :::code language="csharp" source="~/snippets/csharp/System.Resources/ResourceManager/Overview/ctor1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/conceptual.resources.retrieving/vb/ctor1.vb" id="Snippet2"::: - - If the appropriate resources cannot be found, the constructor call creates a valid object. However, the attempt to retrieve a resource throws a exception. For information about dealing with the exception, see the [Handling MissingManifestResourceException and MissingSatelliteAssembly Exceptions](#exception) section later in this article. - - The following example shows how to instantiate a object. It contains the source code for an executable named ShowTime.exe. It also includes the following text file named Strings.txt that contains a single string resource, `TimeHeader`: - -``` -TimeHeader=The current time is -``` - - You can use a batch file to generate the resource file and embed it into the executable. Here's the batch file to generate an executable by using the C# compiler: - -``` - -resgen strings.txt -csc ShowTime.cs /resource:strings.resources - -``` - - For the Visual Basic compiler, you can use the following batch file: - -``` - -resgen strings.txt -vbc ShowTime.vb /resource:strings.resources - -``` - - :::code language="csharp" source="~/snippets/csharp/System.Resources/MissingManifestResourceException/Overview/showtime.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.class/vb/showtime.vb" id="Snippet1"::: - - -### ResourceManager and Culture-Specific Resources - A localized app requires resources to be deployed, as discussed in the article [Packaging and Deploying Resources](/dotnet/framework/resources/packaging-and-deploying-resources-in-desktop-apps). If the assemblies are properly configured, the resource manager determines which resources to retrieve based on the current thread's property. (That property also returns the current thread's UI culture.) For example, if an app is compiled with default English language resources in the main assembly and with French and Russian language resources in two satellite assemblies, and the property is set to fr-FR, the resource manager retrieves the French resources. - - You can set the property explicitly or implicitly. The way you set it determines how the object retrieves resources based on culture: - -- If you explicitly set the property to a specific culture, the resource manager always retrieves the resources for that culture, regardless of the user's browser or operating system language. Consider an app that is compiled with default English language resources and three satellite assemblies that contain resources for English (United States), French (France), and Russian (Russia). If the property is set to fr-FR, the object always retrieves the French (France) resources, even if the user's operating system language is not French. Make sure that this is the desired behavior before you set the property explicitly. - - In ASP.NET apps, you must set the property explicitly, because it is unlikely that the setting on the server will match incoming client requests. An ASP.NET app can set the property explicitly to the user's browser accept language. - - Explicitly setting the property defines the current UI culture for that thread. It does not affect the current UI culture of any other threads in an app. - -- You can set the UI culture of all threads in an app domain by assigning a object that represents that culture to the static property. - -- If you do not explicitly set the current UI culture and you do not define a default culture for the current app domain, the property is set implicitly by the Windows `GetUserDefaultUILanguage` function. This function is provided by the Multilingual User Interface (MUI), which enables the user to set the default language. If the UI language is not set by the user, it defaults to the system-installed language, which is the language of operating system resources. - - The following simple "Hello world" example sets the current UI culture explicitly. It contains resources for three cultures: English (United States) or en-US, French (France) or fr-FR, and Russian (Russia) or ru-RU. The en-US resources are contained in a text file named Greetings.txt: - -``` -HelloString=Hello world! -``` - - The fr-FR resources are contained in a text file named Greetings.fr-FR.txt: - -``` -HelloString=Salut tout le monde! -``` - - The ru-RU resources are contained in a text file named Greetings.ru-RU.txt: - -``` -HelloString=Всем привет! -``` - - Here's the source code for the example (Example.vb for the Visual Basic version or Example.cs for the C# version): - - :::code language="csharp" source="~/snippets/csharp/System.Resources/ResourceManager/Overview/example.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/conceptual.resources.currentculture/vb/example.vb" id="Snippet1"::: - - To compile this example, create a batch (.bat) file that contains the following commands and run it from the command prompt. If you're using C#, specify `csc` instead of `vbc` and `Example.cs` instead of `Example.vb`. - -``` -resgen Greetings.txt -vbc Example.vb /resource:Greetings.resources - -resgen Greetings.fr-FR.txt -Md fr-FR -al /embed:Greetings.fr-FR.resources /culture:fr-FR /out:fr-FR\Example.resources.dll - -resgen Greetings.ru-RU.txt -Md ru-RU -al /embed:Greetings.ru-RU.resources /culture:ru-RU /out:ru-RU\Example.resources.dll -``` - - -### Retrieving Resources - You call the and methods to access a specific resource. You can also call the method to retrieve non-string resources as a byte array. By default, in an app that has localized resources, these methods return the resource for the culture determined by the current UI culture of the thread that made the call. See the previous section, [ResourceManager and Culture-Specific Resources](#CultureSpecific), for more information about how the current UI culture of a thread is defined. If the resource manager cannot find the resource for the current thread's UI culture, it uses a fallback process to retrieve the specified resource. If the resource manager cannot find any localized resources, it uses the resources of the default culture. For more information about resource fallback rules, see the "Resource Fallback Process" section of the article [Packaging and Deploying Resources](/dotnet/framework/resources/packaging-and-deploying-resources-in-desktop-apps). - -> [!NOTE] -> If the .resources file specified in the class constructor cannot be found, the attempt to retrieve a resource throws a or exception. For information about dealing with the exception, see the [Handling MissingManifestResourceException and MissingSatelliteAssemblyException Exceptions](#exception) section later in this topic. - - The following example uses the method to retrieve culture-specific resources. It consists of resources compiled from .txt files for the English (en), French (France) (fr-FR), and Russian (Russia) (ru-RU) cultures. The example changes the current culture and current UI culture to English (United States), French (France), Russian (Russia), and Swedish (Sweden). It then calls the method to retrieve the localized string, which it displays along with the current day and month. Notice that the output displays the appropriate localized string except when the current UI culture is Swedish (Sweden). Because Swedish language resources are unavailable, the app instead uses the resources of the default culture, which is English. - - The example requires the text-based resource files listed in following table. Each has a single string resource named `DateStart`. - -|Culture|File name|Resource name|Resource value| -|-------------|---------------|-------------------|--------------------| -|en-US|DateStrings.txt|`DateStart`|Today is| -|fr-FR|DateStrings.fr-FR.txt|`DateStart`|Aujourd'hui, c'est le| -|ru-RU|DateStrings.ru-RU.txt|`DateStart`|Сегодня| - - Here's the source code for the example (ShowDate.vb for the Visual Basic version or ShowDate.cs for the C# version of the code). - - :::code language="csharp" source="~/snippets/csharp/System.Resources/MissingManifestResourceException/Overview/showdate.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.class/vb/showdate.vb" id="Snippet2"::: - - To compile this example, create a batch file that contains the following commands and run it from the command prompt. If you're using C#, specify `csc` instead of `vbc` and `showdate.cs` instead of `showdate.vb`. - -``` - -resgen DateStrings.txt -vbc showdate.vb /resource:DateStrings.resources - -md fr-FR -resgen DateStrings.fr-FR.txt -al /out:fr-FR\Showdate.resources.dll /culture:fr-FR /embed:DateStrings.fr-FR.resources - -md ru-RU -resgen DateStrings.ru-RU.txt -al /out:ru-RU\Showdate.resources.dll /culture:ru-RU /embed:DateStrings.ru-RU.resources - -``` - - There are two ways to retrieve the resources of a specific culture other than the current UI culture: - -- You can call the , , or method to retrieve a resource for a specific culture. If a localized resource cannot be found, the resource manager uses the resource fallback process to locate an appropriate resource. - -- You can call the method to obtain a object that represents the resources for a particular culture. In the method call, you can determine whether the resource manager probes for parent cultures if it is unable to find localized resources, or whether it simply falls back to the resources of the default culture. You can then use the methods to access the resources (localized for that culture) by name, or to enumerate the resources in the set. - - -### Handling MissingManifestResourceException and MissingSatelliteAssemblyException Exceptions - If you try to retrieve a specific resource, but the resource manager cannot find that resource and either no default culture has been defined or the resources of the default culture cannot be located, the resource manager throws a exception if it expects to find the resources in the main assembly or a if it expects to find the resources in a satellite assembly. Note that the exception is thrown when you call a resource retrieval method such as or , and not when you instantiate a object. - - The exception is typically thrown under the following conditions: - -- The appropriate resource file or satellite assembly does not exist. If the resource manager expects the app's default resources to be embedded in the main app assembly, they are absent. If the attribute indicates that the app's default resources reside in a satellite assembly, that assembly cannot be found. When you compile your app, make sure that resources are embedded in the main assembly or that the necessary satellite assembly is generated and is named appropriately. Its name should take the form *appName*.resources.dll, and it should be located in a directory named after the culture whose resources it contains. - -- Your app doesn't have a default or neutral culture defined. Add the attribute to a source code file or to the project information file (AssemblyInfo.vb for a Visual Basic app or AssemblyInfo.cs for a C# app) file. - -- The `baseName` parameter in the constructor does not specify the name of a .resources file. The name should include the resource file's fully qualified namespace but not its file name extension. Typically, resource files that are created in Visual Studio include namespace names, but resource files that are created and compiled at the command prompt do not. You can determine the names of embedded .resources files by compiling and running the following utility. This is a console app that accepts the name of a main assembly or satellite assembly as a command-line parameter. It displays the strings that should be provided as the `baseName` parameter so that the resource manager can correctly identify the resource. - - :::code language="csharp" source="~/snippets/csharp/System.Resources/MissingManifestResourceException/Overview/resourcenames.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.class/vb/resourcenames.vb" id="Snippet4"::: - - If you are changing the current culture of your application explicitly, you should also remember that the resource manager retrieves a resource set based on the value of the property, and not the property. Typically, if you change one value, you should also change the other. - - -### Resource Versioning - Because the main assembly that contains an app's default resources is separate from the app's satellite assemblies, you can release a new version of your main assembly without redeploying the satellite assemblies. You use the attribute to use existing satellite assemblies and instruct the resource manager not to redeploy them with a new version of your main assembly, - - For more information about versioning support for satellite assemblies, see the article [Retrieving Resources](/dotnet/framework/resources/retrieving-resources-in-desktop-apps). - - -### \ Configuration File Node - -> [!NOTE] -> This section is specific to .NET Framework apps. - - For executables that are deployed and run from a website (HREF .exe files), the object may probe for satellite assemblies over the web, which can hurt your app's performance. To eliminate the performance problem, you can limit this probing to the satellite assemblies that you have deployed with your app. To do this, you create a `` node in your app's configuration file to specify that you have deployed a specific set of cultures for your app, and that the object should not try to probe for any culture that is not listed in that node. - -> [!NOTE] -> The preferred alternative to creating a `` node is to use the [ClickOnce Deployment Manifest](/visualstudio/deployment/clickonce-deployment-manifest) feature. - - In your app's configuration file, create a section similar to the following: - -```xml - - - - - cultureName1 - cultureName2 - cultureName3 - - - -``` - - Edit this configuration information as follows: - -- Specify one or more `` nodes for each main assembly that you deploy, where each node specifies a fully qualified assembly name. Specify the name of your main assembly in place of *MainAssemblyName*, and specify the `Version`, `PublicKeyToken`, and `Culture` attribute values that correspond to your main assembly. - - For the `Version` attribute, specify the version number of your assembly. For example, the first release of your assembly might be version number 1.0.0.0. - - For the `PublicKeyToken` attribute, specify the keyword `null` if you have not signed your assembly with a strong name, or specify your public key token if you have signed your assembly. - - For the `Culture` attribute, specify the keyword `neutral` to designate the main assembly and cause the class to probe only for the cultures listed in the `` nodes. - - For more information about fully qualified assembly names, see the article [Assembly Names](/dotnet/standard/assembly/names). For more information about strong-named assemblies, see the article [Create and use strong-named assemblies](/dotnet/standard/assembly/create-use-strong-named). - -- Specify one or more `` nodes with a specific culture name, such as "fr-FR", or a neutral culture name, such as "fr". - - If resources are needed for any assembly not listed under the `` node, the class probes for cultures using standard probing rules. - - -## Windows 8.x Apps - -> [!IMPORTANT] -> Although the class is supported in Windows 8.x apps, we do not recommend its use. Use this class only when you develop Portable Class Library projects that can be used with Windows 8.x apps. To retrieve resources from Windows 8.x apps, use the [Windows.ApplicationModel.Resources.ResourceLoader](/uwp/api/Windows.ApplicationModel.Resources.ResourceLoader) class instead. - - For Windows 8.x apps, the class retrieves resources from package resource index (PRI) files. A single PRI file (the application package PRI file) contains the resources for both the default culture and any localized cultures. You use the MakePRI utility to create a PRI file from one or more resource files that are in XML resource (.resw) format. For resources that are included in a Visual Studio project, Visual Studio handles the process of creating and packaging the PRI file automatically. You can then use the .NET Framework class to access the app's or library's resources. - - You can instantiate a object for a Windows 8.x app in the same way that you do for a desktop app. - - You can then access the resources for a particular culture by passing the name of the resource to be retrieved to the method. By default, this method returns the resource for the culture determined by the current UI culture of the thread that made the call. You can also retrieve the resources for a specific culture by passing the name of the resource and a object that represents the culture whose resource is to be retrieved to the method. If the resource for the current UI culture or the specified culture cannot be found, the resource manager uses a UI language fallback list to locate a suitable resource. - -## Examples - The following example demonstrates how to use an explicit culture and the implicit current UI culture to obtain string resources from a main assembly and a satellite assembly. For more information, see the "Directory Locations for Satellite Assemblies Not Installed in the Global Assembly Cache" section of the [Creating Satellite Assemblies](/dotnet/framework/resources/creating-satellite-assemblies-for-desktop-apps) topic. - - To run this example: - -1. In the app directory, create a file named rmc.txt that contains the following resource strings: - - ``` - day=Friday - year=2006 - holiday="Cinco de Mayo" - ``` - -2. Use the [Resource File Generator](/dotnet/framework/tools/resgen-exe-resource-file-generator) to generate the rmc.resources resource file from the rmc.txt input file as follows: - - ``` - resgen rmc.txt - ``` - -3. Create a subdirectory of the app directory and name it "es-MX". This is the culture name of the satellite assembly that you will create in the next three steps. - -4. Create a file named rmc.es-MX.txt in the es-MX directory that contains the following resource strings: - - ``` - day=Viernes - year=2006 - holiday="Cinco de Mayo" - ``` - -5. Use the [Resource File Generator](/dotnet/framework/tools/resgen-exe-resource-file-generator) to generate the rmc.es-MX.resources resource file from the rmc.es-MX.txt input file as follows: - - ``` - resgen rmc.es-MX.txt - ``` - -6. Assume that the filename for this example is rmc.vb or rmc.cs. Copy the following source code into a file. Then compile it and embed the main assembly resource file, rmc.resources, in the executable assembly. If you are using the Visual Basic compiler, the syntax is: - - ``` - vbc rmc.vb /resource:rmc.resources - ``` - - The corresponding syntax for the C# compiler is: - - ``` - csc /resource:rmc.resources rmc.cs - ``` - -7. Use the [Assembly Linker](/dotnet/framework/tools/al-exe-assembly-linker) to create a satellite assembly. If the base name of the app is rmc, the satellite assembly name must be rmc.resources.dll. The satellite assembly should be created in the es-MX directory. If es-MX is the current directory, use this command: - - ``` - al /embed:rmc.es-MX.resources /c:es-MX /out:rmc.resources.dll - ``` - -8. Run rmc.exe to obtain and display the embedded resource strings. - - :::code language="csharp" source="~/snippets/csharp/System.Resources/ResourceManager/Overview/rmc.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ResourceManager_Class/vb/rmc.vb" id="Snippet1"::: - - ]]> - + For more information about this API, see Supplemental API remarks for ResourceManager. This type is thread safe. diff --git a/xml/System.Resources/ResourceReader.xml b/xml/System.Resources/ResourceReader.xml index 48da68eea85..933282fd5ee 100644 --- a/xml/System.Resources/ResourceReader.xml +++ b/xml/System.Resources/ResourceReader.xml @@ -83,123 +83,7 @@ Enumerates the resources in a binary resources (.resources) file by reading sequential resource name/value pairs. - - class provides a standard implementation of the interface. A instance represents either a standalone .resources file or a .resources file that is embedded in an assembly. It is used to enumerate the resources in a .resources file and retrieve its name/value pairs. It differs from the class, which is used to retrieve specified named resources from a .resources file that is embedded in an assembly. The class is used to retrieve resources whose names are known in advance, whereas the class is useful for retrieving resources whose number or precise names are not known at compile time. For example, an application may use a resources file to store configuration information that is organized into sections and items in a section, where the number of sections or items in a section is not known in advance. Resources can then be named generically (such as `Section1`, `Section1Item1`, `Section1Item2`, and so on) and retrieved by using a object. - -> [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - - For more information about using the class, see the following sections: - -- [Instantiating a ResourceReader object](#instantiate) -- [Enumerating a ResourceReader object's resources](#enumerate) - - [Retrieving resources by using IDictionaryEnumerator properties](#idictionaryenumerator) - - [Retrieving resources by name with GetResourceData](#getresourcedata) - - -## Instantiating a ResourceReader Object - A .resources file is a binary file that has been compiled from either a text file or an XML .resx file by [Resgen.exe (Resource File Generator)](/dotnet/framework/tools/resgen-exe-resource-file-generator). A object can represent either a standalone .resources file or a .resources file that has been embedded in an assembly. - - To instantiate a object that reads from a standalone .resources file, use the class constructor with either an input stream or a string that contains the .resources file name. The following example illustrates both approaches. The first instantiates a object that represents a .resources file named `Resources1.resources` by using its file name. The second instantiates a object that represents a .resources file named `Resources2.resources` by using a stream created from the file. - - :::code language="csharp" source="~/snippets/csharp/System.Resources/ResourceReader/Overview/ctor1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcereader.class/vb/ctor1.vb" id="Snippet2"::: - - To create a object that represents an embedded .resources file, instantiate an object from the assembly in which the .resources file is embedded. Its method returns a object that can be passed to the constructor. The following example instantiates a object that represents an embedded .resources file. - - :::code language="csharp" source="~/snippets/csharp/System.Resources/ResourceReader/Overview/ctor1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcereader.class/vb/ctor1.vb" id="Snippet3"::: - - -## Enumerating a ResourceReader Object's Resources - To enumerate the resources in a .resources file, you call the method, which returns an object. You call the `IDictionaryEnumerator.MoveNext` method to move from one resource to the next. The method returns `false` when all the resources in the .resources file have been enumerated. - -> [!NOTE] -> Although the class implements the interface and the method, the method does not provide the implementation. Instead, the method returns an interface object that provides access to each resource's name/value pair. - - You can retrieve the individual resources in the collection in two ways: - -- You can iterate each resource in the collection and use properties to retrieve the resource name and value. We recommend this technique when all the resources are of the same type, or you know the data type of each resource. - -- You can retrieve the name of each resource when you iterate the collection and call the method to retrieve the resource's data. We recommend this approach when you do not know the data type of each resource or if the previous approach throws exceptions. - - -### Retrieving Resources by Using IDictionaryEnumerator Properties - The first method of enumerating the resources in a .resources file involves directly retrieving each resource's name/value pair. After you call the `IDictionaryEnumerator.MoveNext` method to move to each resource in the collection, you can retrieve the resource name from the property and the resource data from the property. - - The following example shows how to retrieve the name and value of each resource in a .resources file by using the and properties. To run the example, create the following text file named ApplicationResources.txt to define string resources. - -``` -Title="Contact Information" -Label1="First Name:" -Label2="Middle Name:" -Label3="Last Name:" -Label4="SSN:" -Label5="Street Address:" -Label6="City:" -Label7="State:" -Label8="Zip Code:" -Label9="Home Phone:" -Label10="Business Phone:" -Label11="Mobile Phone:" -Label12="Other Phone:" -Label13="Fax:" -Label14="Email Address:" -Label15="Alternate Email Address:" -``` - - You can then convert the text resource file to a binary file named ApplicationResources.resources by using the following command: - - **resgen ApplicationResources.txt** - - The following example then uses the class to enumerate each resource in the standalone binary .resources file and to display its key name and corresponding value. - - :::code language="csharp" source="~/snippets/csharp/System.Resources/ResourceReader/Overview/class1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcereader.class/vb/class1.vb" id="Snippet1"::: - - The attempt to retrieve resource data from the property can throw the following exceptions: - -- A if the data is not in the expected format. - -- A if the assembly that contains the type to which the data belongs cannot be found. - -- A if the type to which the data belongs cannot be cannot be found. - - Typically, these exceptions are thrown if the .resources file has been modified manually, if the assembly in which a type is defined has either not been included with an application or has been inadvertently deleted, or if the assembly is an older version that predates a type. If one of these exceptions is thrown, you can retrieve resources by enumerating each resource and calling the method, as the following section shows. This approach provides you with some information about the data type that the property attempted to return. - - -### Retrieve Resources by Name with GetResourceData - - The second approach to enumerating resources in a .resources file also involves navigating through the resources in the file by calling the `IDictionaryEnumerator.MoveNext` method. For each resource, you retrieve the resource's name from the property, which is then passed to the method to retrieve the resource's data. This is returned as a byte array in the `resourceData` argument. - - This approach is more awkward than retrieving the resource name and value from the and properties, because it returns the actual bytes that form the resource value. However, if the attempt to retrieve the resource throws an exception, the method can help identify the source of the exception by supplying information about the resource's data type. For more information about the string that indicates the resource's data type, see . - - The following example illustrates how to use this approach to retrieve resources and to handle any exceptions that are thrown. It programmatically creates a binary .resources file that contains four strings, one Boolean, one integer, and one bitmap. To run the example, do the following: - -1. Compile and execute the following source code, which creates a .resources file named ContactResources.resources. - - :::code language="csharp" source="~/snippets/csharp/System.Resources/ResourceReader/Overview/createresourceex1.cs" id="Snippet5"::: - - The source code file is named CreateResources.cs. You can compile it in C# by using the following command: - - ``` - csc CreateResources.cs /r:library.dll - ``` - -2. Compile and run the following code to enumerate the resources in the ContactResources.resources file. - - :::code language="csharp" source="~/snippets/csharp/System.Resources/ResourceReader/Overview/readresourceex1.cs" id="Snippet6"::: - - After modifying the source code (for example, by deliberately throwing a at the end of the `try` block), you can run the example to see how calls to enable you to retrieve or recreate some resource information. - - ]]> - + For more information about this API, see Supplemental API remarks for ResourceReader. @@ -211,12 +95,12 @@ Label15="Alternate Email Address:" Initializes a new instance of the class. - @@ -276,50 +160,50 @@ Label15="Alternate Email Address:" The input stream for reading resources. Initializes a new instance of the class for the specified stream. - constructor instantiates a object that retrieves resources either from a standalone .resources file or from a .resources file that is embedded in an assembly. To read from a standalone .resources file, instantiate a object and pass it to the constructor. To read from an embedded .resources file, call the method with the case-sensitive name of the .resources file, and pass the returned object to the constructor. - + constructor instantiates a object that retrieves resources either from a standalone .resources file or from a .resources file that is embedded in an assembly. To read from a standalone .resources file, instantiate a object and pass it to the constructor. To read from an embedded .resources file, call the method with the case-sensitive name of the .resources file, and pass the returned object to the constructor. + [!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)] - -## Examples - The example in this section uses the following .txt file named `PatientForm.txt` to define the resources used by an application. - -``` - -Title="Top Pet Animal Clinic" -Label1="Patient Number:" -Label2="Pet Name:" -Label3="Species:" -Label4="Breed:" -Label5="Date of Birth:" -Label6="Age:" -Label7="Owner:" -Label8="Address:" -Label9="Home Phone:" -Label10="Work Phone:" -Label11="Mobile Phone:" - -``` - - You can compile the .txt file into a .resources file by issuing the following command: - - **resgen PatientForm.txt** - - The following example assumes that the resource file is embedded in the assembly that contains the application's executable code. It retrieves a resource file named `PatientForm.resources` from the currently executing assemblies and displays the name and value of each of its resources. - + +## Examples + The example in this section uses the following .txt file named `PatientForm.txt` to define the resources used by an application. + +``` + +Title="Top Pet Animal Clinic" +Label1="Patient Number:" +Label2="Pet Name:" +Label3="Species:" +Label4="Breed:" +Label5="Date of Birth:" +Label6="Age:" +Label7="Owner:" +Label8="Address:" +Label9="Home Phone:" +Label10="Work Phone:" +Label11="Mobile Phone:" + +``` + + You can compile the .txt file into a .resources file by issuing the following command: + + **resgen PatientForm.txt** + + The following example assumes that the resource file is embedded in the assembly that contains the application's executable code. It retrieves a resource file named `PatientForm.resources` from the currently executing assemblies and displays the name and value of each of its resources. + :::code language="csharp" source="~/snippets/csharp/System.Resources/ResourceReader/.ctor/stream1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcereader.ctor/vb/stream1.vb" id="Snippet1"::: - - If the C# example is named `Example.cs`, you can compile it by using the following command: - - **csc Example.cs /res:PatientForm.resources** - - If the Visual Basic example is named `Example.vb`, you can compile it by using the following command: - - **vbc Example.vb /res:PatientForm.resources** - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcereader.ctor/vb/stream1.vb" id="Snippet1"::: + + If the C# example is named `Example.cs`, you can compile it by using the following command: + + **csc Example.cs /res:PatientForm.resources** + + If the Visual Basic example is named `Example.vb`, you can compile it by using the following command: + + **vbc Example.vb /res:PatientForm.resources** + ]]> The parameter is not readable. @@ -381,42 +265,42 @@ Label11="Mobile Phone:" The path and name of the resource file to read. filename is not case-sensitive. Initializes a new instance of the class for the specified named resource file. - constructor instantiates a object that retrieves resources from a standalone .resources file. To retrieve resources from an embedded .resources file, use the constructor. + constructor instantiates a object that retrieves resources from a standalone .resources file. To retrieve resources from an embedded .resources file, use the constructor. [!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)] -## Examples - The example in this section uses the following .txt file named `PatientForm.txt` to define the resources used by an application. - -``` - -Title="Top Pet Animal Clinic" -Label1="Patient Number:" -Label2="Pet Name:" -Label3="Species:" -Label4="Breed:" -Label5="Date of Birth:" -Label6="Age:" -Label7="Owner:" -Label8="Address:" -Label9="Home Phone:" -Label10="Work Phone:" -Label11="Mobile Phone:" - -``` - - You can compile this .txt file into a .resources file by issuing the following command: - - **resgen PatientForm.txt** - - The following example enumerates the resources in `PatientForm.resources` and displays the name and value of each. - +## Examples + The example in this section uses the following .txt file named `PatientForm.txt` to define the resources used by an application. + +``` + +Title="Top Pet Animal Clinic" +Label1="Patient Number:" +Label2="Pet Name:" +Label3="Species:" +Label4="Breed:" +Label5="Date of Birth:" +Label6="Age:" +Label7="Owner:" +Label8="Address:" +Label9="Home Phone:" +Label10="Work Phone:" +Label11="Mobile Phone:" + +``` + + You can compile this .txt file into a .resources file by issuing the following command: + + **resgen PatientForm.txt** + + The following example enumerates the resources in `PatientForm.resources` and displays the name and value of each. + :::code language="csharp" source="~/snippets/csharp/System.Resources/ResourceReader/.ctor/stream2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcereader.ctor/vb/stream2.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcereader.ctor/vb/stream2.vb" id="Snippet2"::: + ]]> The parameter is . @@ -471,20 +355,20 @@ Label11="Mobile Phone:" Releases all operating system resources associated with this object. - can be safely called multiple times. - - - -## Examples - The following example moves through a file's resources and displays all the key/value pairs it finds. The code then uses the method to shut down the and to release all resources used by it. - + can be safely called multiple times. + + + +## Examples + The following example moves through a file's resources and displays all the key/value pairs it finds. The code then uses the method to shut down the and to release all resources used by it. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Resources.ResourceReader.GetEnumerator Example/CPP/getenumerator.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Resources/ResourceReader/Close/getenumerator.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Resources.ResourceReader.GetEnumerator Example/VB/getenumerator.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Resources.ResourceReader.GetEnumerator Example/VB/getenumerator.vb" id="Snippet1"::: + ]]> @@ -535,13 +419,13 @@ Label11="Mobile Phone:" Releases all resources used by the current instance of the class. - , call to release all resources used by this instance. You should eliminate further references to this instance so that the garbage collector can reclaim the memory of the instance instead of keeping it alive for finalization. - - calls the private Dispose(Boolean) method, which contains the code to release managed and unmanaged resources. For more information, see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - + , call to release all resources used by this instance. You should eliminate further references to this instance so that the garbage collector can reclaim the memory of the instance instead of keeping it alive for finalization. + + calls the private Dispose(Boolean) method, which contains the code to release managed and unmanaged resources. For more information, see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + ]]> @@ -604,61 +488,61 @@ Label11="Mobile Phone:" Returns an enumerator for this object. An enumerator for this object. - method and then repeatedly calling the method on the returned object until the method returns `false`. The resource name is available from the property; its value from the property. The example illustrates how to enumerate resources in this way. - - The implementation of the property by the class can throw the following exceptions: - -- - - The assembly that contains the type to which the data belongs cannot be found. - -- - - The data is not in the expected format. - -- - - The type to which the data belongs cannot be found. - - You can handle the exception by calling the method to retrieve information about the data type and the byte array assigned to the named resource. For more information, see the "Retrieving Resources by Name with GetResourceData" section in the class topic. - + method and then repeatedly calling the method on the returned object until the method returns `false`. The resource name is available from the property; its value from the property. The example illustrates how to enumerate resources in this way. + + The implementation of the property by the class can throw the following exceptions: + +- + + The assembly that contains the type to which the data belongs cannot be found. + +- + + The data is not in the expected format. + +- + + The type to which the data belongs cannot be found. + + You can handle the exception by calling the method to retrieve information about the data type and the byte array assigned to the named resource. For more information, see the "Retrieving Resources by Name with GetResourceData" section in the class topic. + > [!IMPORTANT] -> The class includes two methods that return enumerators. The method returns an interface object and is the recommended method to call when enumerating resources. - - - -## Examples - The example in this section uses the following .txt file named `PatientForm.txt` to define the resources used by an application. - -``` - -Title="Top Pet Animal Clinic" -Label1="Patient Number:" -Label2="Pet Name:" -Label3="Species:" -Label4="Breed:" -Label5="Date of Birth:" -Label6="Age:" -Label7="Owner:" -Label8="Address:" -Label9="Home Phone:" -Label10="Work Phone:" -Label11="Mobile Phone:" - -``` - - You can compile the .txt file into a .resources file by issuing the following command: - - **resgen PatientForm.txt** - - The following example enumerates the resources in `PatientForm.resources` and displays the name and value of each. - +> The class includes two methods that return enumerators. The method returns an interface object and is the recommended method to call when enumerating resources. + + + +## Examples + The example in this section uses the following .txt file named `PatientForm.txt` to define the resources used by an application. + +``` + +Title="Top Pet Animal Clinic" +Label1="Patient Number:" +Label2="Pet Name:" +Label3="Species:" +Label4="Breed:" +Label5="Date of Birth:" +Label6="Age:" +Label7="Owner:" +Label8="Address:" +Label9="Home Phone:" +Label10="Work Phone:" +Label11="Mobile Phone:" + +``` + + You can compile the .txt file into a .resources file by issuing the following command: + + **resgen PatientForm.txt** + + The following example enumerates the resources in `PatientForm.resources` and displays the name and value of each. + :::code language="csharp" source="~/snippets/csharp/System.Resources/ResourceReader/.ctor/stream2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcereader.ctor/vb/stream2.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcereader.ctor/vb/stream2.vb" id="Snippet2"::: + ]]> The reader has been closed or disposed, and cannot be accessed. @@ -721,29 +605,29 @@ Label11="Mobile Phone:" When this method returns, contains a byte array that is the binary representation of the retrieved type. This parameter is passed uninitialized. Retrieves the type name and data of a named resource from an open resource file or stream. - method retrieves the value of a named resource as a byte array. It is typically used when the property throws an exception when it tries to retrieve the value of a resource. - - `resourceType` is a string that represents the data type of the resource. It can be any of the following values: - -- The string representation of a `ResourceTypeCode` enumeration member that indicates the data type of the resource. `ResourceTypeCode` is a private enumeration that is used by .to indicate that a special binary format is used to store one of 19 common data types. These include the .NET Framework primitive data types (, , , , , , , , , , , , ), as well as , , and , In addition, the `ResourceTypeCode` enumeration includes the values shown in the following table. - - |ResourceTypeCode value|Description| - |----------------------------|-----------------| - |`ResourceTypeCode.ByteArray`|The data is a byte array. This data type commonly results from the call to the method.| - |`ResourceTypeCode.Null`|The data is a null reference. This data type commonly results from the call to the method with an object whose value is `null`.| - |`ResourceTypeCode.Stream`|The data is stored in a stream. This data type commonly results from the call to the or method.| - - Assuming that `resourceData` has not been corrupted, it can usually be converted from a byte array back to its original value by calling a or method. - -- A string that contains the fully qualified name of the type whose serialized data is assigned to the `resourceData` argument (for example, `System.String`). In addition, for types that are not part of the .NET class library, the string includes the name, version, culture, and public key of the assembly that contains the type. For example, the following string indicates that the serialized data represents an instance of the `Person` type in the `Extensions` namespace, which is found in version 1.0 of an assembly named Utility that has no public key and no designated culture. - + method retrieves the value of a named resource as a byte array. It is typically used when the property throws an exception when it tries to retrieve the value of a resource. + + `resourceType` is a string that represents the data type of the resource. It can be any of the following values: + +- The string representation of a `ResourceTypeCode` enumeration member that indicates the data type of the resource. `ResourceTypeCode` is a private enumeration that is used by .to indicate that a special binary format is used to store one of 19 common data types. These include the .NET Framework primitive data types (, , , , , , , , , , , , ), as well as , , and , In addition, the `ResourceTypeCode` enumeration includes the values shown in the following table. + + |ResourceTypeCode value|Description| + |----------------------------|-----------------| + |`ResourceTypeCode.ByteArray`|The data is a byte array. This data type commonly results from the call to the method.| + |`ResourceTypeCode.Null`|The data is a null reference. This data type commonly results from the call to the method with an object whose value is `null`.| + |`ResourceTypeCode.Stream`|The data is stored in a stream. This data type commonly results from the call to the or method.| + + Assuming that `resourceData` has not been corrupted, it can usually be converted from a byte array back to its original value by calling a or method. + +- A string that contains the fully qualified name of the type whose serialized data is assigned to the `resourceData` argument (for example, `System.String`). In addition, for types that are not part of the .NET class library, the string includes the name, version, culture, and public key of the assembly that contains the type. For example, the following string indicates that the serialized data represents an instance of the `Person` type in the `Extensions` namespace, which is found in version 1.0 of an assembly named Utility that has no public key and no designated culture. + `Extensions.Person, Utility, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null` - -- The string used to describe the data type in the method call. - + +- The string used to describe the data type in the method call. + ]]> @@ -804,11 +688,11 @@ Label11="Mobile Phone:" Returns an enumerator for this object. An enumerator for this object. - is an explicit interface implementation. It can be used only when the instance is cast to an interface. The recommended approach to enumerating the resources in a .resources file is to call the method of the object returned by the method. - + is an explicit interface implementation. It can be used only when the instance is cast to an interface. The recommended approach to enumerating the resources in a .resources file is to call the method of the object returned by the method. + ]]> The reader has already been closed and cannot be accessed. @@ -853,10 +737,10 @@ Label11="Mobile Phone:" to be reallocated for other purposes. For more information about Dispose, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). -## Examples +## Examples The following code example moves through a file's resources and prints out all the key/value pairs it finds. The code then uses theIDisposable.Dispose method to shut down the and to release all resources used by it. ```vb @@ -892,9 +776,9 @@ using System; using System.Resources; using System.Collections; -public class ReadResources +public class ReadResources { - public static void Main(string[] args) + public static void Main(string[] args) { // Create a resource reader for items.resources  // and get an enumerator to iterate through the file. @@ -902,7 +786,7 @@ public class ReadResources IDictionaryEnumerator en = reader.GetEnumerator(); // Iterate through the file, printing the key/value pairs.  - while (en.MoveNext()) + while (en.MoveNext()) { Console.WriteLine(); Console.WriteLine("Name: {0}", en.Key); diff --git a/xml/System.Resources/SatelliteContractVersionAttribute.xml b/xml/System.Resources/SatelliteContractVersionAttribute.xml index d704d567438..85535e38c49 100644 --- a/xml/System.Resources/SatelliteContractVersionAttribute.xml +++ b/xml/System.Resources/SatelliteContractVersionAttribute.xml @@ -70,25 +70,7 @@ Instructs a object to ask for a particular version of a satellite assembly. - - attribute establishes a contract between a main assembly and all its satellites. You apply this attribute to your main assembly, and pass it the version number of the satellite assemblies that will work with this version of the main assembly. When the resource manager ( object) looks up resources, it explicitly loads the satellite version specified by this attribute on the main assembly. - - When you update the main assembly, you increment its assembly version number. However, you might not want to ship new copies of your satellite assemblies if the existing ones are compatible with your app. In this case, increment the main assembly's version number but leave the satellite contract version number the same. The resource manager will use your existing satellite assemblies. - - If you want to revise a satellite assembly but not the main assembly, increment the version number on your satellite. In this case, ship a publisher policy assembly along with your satellite assembly stating that your new satellite assembly has backward compatibility with your old satellite assembly. The resource manager will still use the old contract number written into your main assembly based on the attribute; however, the loader will bind to the satellite assembly version that is specified by the policy assembly. - - A vendor of a shared component uses a publisher policy assembly to make a compatibility statement about a particular version of a released assembly. A publisher policy assembly is a strongly named assembly that has a name in the format `policy...`, and is registered in the [Global Assembly Cache (GAC)](/dotnet/framework/app-domains/gac). The publisher policy is generated from an XML configuration file (see the [\ Element](/dotnet/framework/configure-apps/file-schema/runtime/bindingredirect-element)) by using the [Al.exe (Assembly Linker)](/dotnet/framework/tools/al-exe-assembly-linker) tool. The Assembly Linker is used with the `/link` option to link the XML configuration file to a manifest assembly, which is then stored in the global assembly cache. The publisher policy assemblies can be used when a vendor ships a maintenance release (service pack) that contains bug fixes. - -## Windows 8.x Store Apps - This attribute is ignored in Windows 8.x Store apps, because package resource index (PRI) files do not have versioning semantics. In addition, the Windows 8.x Store packaging model requires all resources to ship in the same package, with no possibility of redeploying satellite assemblies or PRI files. - - ]]> - + For more information about this API, see Supplemental API remarks for SatelliteContractVersionAttribute. @@ -132,11 +114,11 @@ A string that specifies the version of the satellite assemblies to load. Initializes a new instance of the class. - property with the `version` parameter. - + property with the `version` parameter. + ]]> The parameter is . @@ -183,11 +165,11 @@ Gets the version of the satellite assemblies with the required resources. A string that contains the version of the satellite assemblies with the required resources. - diff --git a/xml/System.Runtime.CompilerServices/InternalsVisibleToAttribute.xml b/xml/System.Runtime.CompilerServices/InternalsVisibleToAttribute.xml index 94f29cfe4db..93d31839b7a 100644 --- a/xml/System.Runtime.CompilerServices/InternalsVisibleToAttribute.xml +++ b/xml/System.Runtime.CompilerServices/InternalsVisibleToAttribute.xml @@ -57,87 +57,36 @@ Specifies that types that are ordinarily visible only within the current assembly are visible to a specified assembly. - - For more information about this API, see Supplemental API remarks for InternalsVisibleToAttribute. + + attribute makes these types and members also visible to the types in a specified assembly, which is known as a friend assembly. This applies only to `internal` (`Friend` in Visual Basic), `protected internal`(`Protected Friend` in Visual Basic), and `private protected` (`Private Protected` in Visual Basic) members, but not `private` ones. - - > [!NOTE] - > In the case of `private protected` (`Private Protected` in Visual Basic) members, the attribute extends accessibility only to types that derive from the *containing class* of the member. - - The attribute is applied at the assembly level. This means that it can be included at the beginning of a source code file, or it can be included in the AssemblyInfo file in a Visual Studio project. You can use the attribute to specify a single friend assembly that can access the internal types and members of the current assembly. You can define multiple friend assemblies in two ways. They can appear as individual assembly-level attributes, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/multiple1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.internalsvisibletoattribute/vb/multiple1.vb" id="Snippet3"::: - - They can also appear with separate tags but a single `assembly` keyword, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/multiple2.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.internalsvisibletoattribute/vb/multiple2.vb" id="Snippet4"::: - - The friend assembly is identified by the constructor. Both the current assembly and the friend assembly must be unsigned, or both assemblies must be signed with a strong name. - - If both assemblies are unsigned, the `assemblyName` argument consists of the name of the friend assembly, specified without a directory path or file name extension. - - If both assemblies are signed with a strong name, the argument to the constructor must consist of the name of the assembly without its directory path or file name extension, along with the full public key (and not its public key token). To get the full public key of a strong-named assembly, see the [Getting the full public key](#Key) section later in this article. For more information about using with strong-named assemblies, see the constructor. - - Do not include values for the , , or field in the argument; the Visual Basic, C#, and C++ compilers treat this as a compiler error. If you use a compiler that does not treat it as an error (such as the [IL Assembler (ILAsm.exe)](/dotnet/framework/tools/ilasm-exe-il-assembler)) and the assemblies are strong-named, a exception is thrown the first time the specified friend assembly accesses the assembly that contains the attribute. - - For more information about how to use this attribute, see [Friend assemblies](/dotnet/standard/assembly/friend) and [C++ friend assemblies](/cpp/dotnet/friend-assemblies-cpp). - - -## Get the full public key - You can use the [Strong Name Tool (Sn.exe)](/dotnet/framework/tools/sn-exe-strong-name-tool) to retrieve the full public key from a strong-named key (.snk) file. To do this, you perform the following steps: - -1. Extract the public key from the strong-named key file to a separate file: - - **Sn -p** *snk_file* *outfile* - -2. Display the full public key to the console: - - **Sn -tp** *outfile* - -3. Copy and paste the full public key value into your source code. - -## Compile the friend assembly with C# - If you use the C# compiler to compile the friend assembly, you must explicitly specify the name of the output file (.exe or .dll) by using the **/out** compiler option. This is required because the compiler has not yet generated the name for the assembly it is building at the time it is binding to external references. The **/out** compiler option is optional for the Visual Basic compiler, and the corresponding **-out** or **-o** compiler option should not be used when compiling friend assemblies with the F# compiler. - -## Compile the friend assembly with C++ - In C++, in order to make the internal members enabled by the attribute accessible to a friend assembly, you must use the `as_friend` attribute in the C++ directive. For more information, see [Friend Assemblies (C++)](/cpp/dotnet/friend-assemblies-cpp). - -## Examples - **Signed assemblies** - - The following example uses the attribute to make an `internal` method named `AppendDirectorySeparator` in a signed assembly visible to another signed assembly. It defines a `FileUtilities` class that includes an internal `AppendDirectorySeparator` method. The attribute is applied to the assembly that contains the `FileUtilities` class. The attribute allows an assembly named `Friend1` to access this internal member. - - :::code language="csharp" source="~/snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/assembly1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.internalsvisibletoattribute/vb/assembly1.vb" id="Snippet1"::: - - If the following example is compiled into a strong-named assembly named `Friend1`, the `Example.Main` method in `Friend1` can successfully call the `FileUtilities.AppendDirectorySeparator` method, although the method is internal to the `Assembly1` assembly. Note that if you are compiling in C# from the command line, you must use the **/out** compiler switch to ensure that the name of the friend assembly is available when the compiler binds to external references. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.runtime.compilerservices.internalsvisibletoattribute/cpp/friend1.cpp" id="Snippet2"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/friend1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.internalsvisibletoattribute/vb/friend1.vb" id="Snippet2"::: - - **Unsigned assemblies** - - The following example uses the attribute to make an `internal` member of an unsigned assembly visible to another unsigned assembly. The attribute ensures that the `internal` `StringLib.IsFirstLetterUpperCase` method in an assembly named `UtilityLib` is visible to the code in an assembly named `Friend2`. The following is the source code for UtilityLib.dll: - - :::code language="csharp" source="~/snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/utilitylib.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.internalsvisibletoattribute/vb/utilitylib.vb" id="Snippet5"::: - - The following example provides the source code for the `Friend2` assembly. Note that if you are compiling in C# from the command line, you must use the **/out** compiler switch to ensure that the name of the friend assembly is available when the compiler binds to external references. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.runtime.compilerservices.internalsvisibletoattribute/cpp/friend2.cpp" id="Snippet6"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/friend2.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.internalsvisibletoattribute/vb/friend2.vb" id="Snippet6"::: - - ]]> - +The following example uses the attribute to make an `internal` method named `AppendDirectorySeparator` in a signed assembly visible to another signed assembly. It defines a `FileUtilities` class that includes an internal `AppendDirectorySeparator` method. The attribute is applied to the assembly that contains the `FileUtilities` class. The attribute allows an assembly named `Friend1` to access this internal member. + +:::code language="csharp" source="~/snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/assembly1.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.internalsvisibletoattribute/vb/assembly1.vb" id="Snippet1"::: + +If the following example is compiled into a strong-named assembly named `Friend1`, the `Example.Main` method in `Friend1` can successfully call the `FileUtilities.AppendDirectorySeparator` method, although the method is internal to the `Assembly1` assembly. Note that if you are compiling in C# from the command line, you must use the **/out** compiler switch to ensure that the name of the friend assembly is available when the compiler binds to external references. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.runtime.compilerservices.internalsvisibletoattribute/cpp/friend1.cpp" id="Snippet2"::: +:::code language="csharp" source="~/snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/friend1.cs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.internalsvisibletoattribute/vb/friend1.vb" id="Snippet2"::: + +**Unsigned assemblies** + +The following example uses the attribute to make an `internal` member of an unsigned assembly visible to another unsigned assembly. The attribute ensures that the `internal` `StringLib.IsFirstLetterUpperCase` method in an assembly named `UtilityLib` is visible to the code in an assembly named `Friend2`. The following is the source code for UtilityLib.dll: + +:::code language="csharp" source="~/snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/utilitylib.cs" id="Snippet5"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.internalsvisibletoattribute/vb/utilitylib.vb" id="Snippet5"::: + +The following example provides the source code for the `Friend2` assembly. Note that if you are compiling in C# from the command line, you must use the **/out** compiler switch to ensure that the name of the friend assembly is available when the compiler binds to external references. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.runtime.compilerservices.internalsvisibletoattribute/cpp/friend2.cpp" id="Snippet6"::: +:::code language="csharp" source="~/snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/friend2.cs" id="Snippet6"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.internalsvisibletoattribute/vb/friend2.vb" id="Snippet6"::: + ]]> + @@ -180,61 +129,61 @@ The name of a friend assembly. Initializes a new instance of the class with the name of the specified friend assembly. - constructor defines a friend assembly, which is an assembly that has access to the internal and private protected types and members of the current assembly. - - Both the current assembly and the friend assembly must be unsigned, or both must be signed with a strong name. (For more information about strong-named assemblies, see [Create and use strong-named assemblies](/dotnet/standard/assembly/create-use-strong-named).) If both are unsigned, the `assemblyName` argument consists of the name of the friend assembly, specified without a directory path or file extension. If both are signed, `assemblyName` consists of the name of the friend assembly without its directory path or file name extension, along with its full public key (but not its public key token). The other components of a strong name, such as those that provide culture, version, or processor architecture information, cannot be specified in the `assemblyName` argument. - + constructor defines a friend assembly, which is an assembly that has access to the internal and private protected types and members of the current assembly. + + Both the current assembly and the friend assembly must be unsigned, or both must be signed with a strong name. (For more information about strong-named assemblies, see [Create and use strong-named assemblies](/dotnet/standard/assembly/create-use-strong-named).) If both are unsigned, the `assemblyName` argument consists of the name of the friend assembly, specified without a directory path or file extension. If both are signed, `assemblyName` consists of the name of the friend assembly without its directory path or file name extension, along with its full public key (but not its public key token). The other components of a strong name, such as those that provide culture, version, or processor architecture information, cannot be specified in the `assemblyName` argument. + > [!IMPORTANT] -> If you use the C# compiler to compile the friend assembly, you must explicitly specify the name of the output file (.exe or .dll) by using the **/out** compiler option. This is required because the compiler has not yet generated the name for the assembly it is building at the time it is binding to external references. The **/out** compiler option is optional for the Visual Basic compiler, and the corresponding **-out** or **-o** compiler option should not be used when compiling friend assemblies with the F# compiler. - - You can use [Sn.exe (Strong Name Tool)](/dotnet/framework/tools/sn-exe-strong-name-tool) to retrieve the full public key from a strong-named key (.snk) file. To do this, you perform the following steps: - -1. Extract the public key from the strong-named key file to a separate file: - - **Sn -p** *snk_file* *outfile* - -2. Display the full public key to the console: - - **Sn -tp** *outfile* - -3. Copy and paste the full public key value into your source code. - - For more information about how to use the attribute, see the following articles: - -- [Friend Assemblies (C++)](/cpp/dotnet/friend-assemblies-cpp) - +> If you use the C# compiler to compile the friend assembly, you must explicitly specify the name of the output file (.exe or .dll) by using the **/out** compiler option. This is required because the compiler has not yet generated the name for the assembly it is building at the time it is binding to external references. The **/out** compiler option is optional for the Visual Basic compiler, and the corresponding **-out** or **-o** compiler option should not be used when compiling friend assemblies with the F# compiler. + + You can use [Sn.exe (Strong Name Tool)](/dotnet/framework/tools/sn-exe-strong-name-tool) to retrieve the full public key from a strong-named key (.snk) file. To do this, you perform the following steps: + +1. Extract the public key from the strong-named key file to a separate file: + + **Sn -p** *snk_file* *outfile* + +2. Display the full public key to the console: + + **Sn -tp** *outfile* + +3. Copy and paste the full public key value into your source code. + + For more information about how to use the attribute, see the following articles: + +- [Friend Assemblies (C++)](/cpp/dotnet/friend-assemblies-cpp) + - [Friend assemblies](/dotnet/standard/assembly/friend) - -## Examples - **Signed assemblies** - - The following example uses the attribute to make an `internal` method named `AppendDirectorySeparator` in a signed assembly visible to another signed assembly. It defines a `FileUtilities` class that includes an internal `AppendDirectorySeparator` method. The attribute is applied to the assembly that contains the `FileUtilities` class. The attribute allows an assembly named `Friend1` to access this internal member. - + +## Examples + **Signed assemblies** + + The following example uses the attribute to make an `internal` method named `AppendDirectorySeparator` in a signed assembly visible to another signed assembly. It defines a `FileUtilities` class that includes an internal `AppendDirectorySeparator` method. The attribute is applied to the assembly that contains the `FileUtilities` class. The attribute allows an assembly named `Friend1` to access this internal member. + :::code language="csharp" source="~/snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/assembly1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.internalsvisibletoattribute/vb/assembly1.vb" id="Snippet1"::: - - If the following example is compiled into a strong-named assembly named `Friend1`, it can successfully call the `FileUtilities.AppendDirectorySeparator` method, even though the method is internal to the `Assembly1` assembly. Note that if you are compiling in C# from the command line, you must use the **/out** compiler switch to ensure that the name of the friend assembly is available when the compiler binds to external references. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.internalsvisibletoattribute/vb/assembly1.vb" id="Snippet1"::: + + If the following example is compiled into a strong-named assembly named `Friend1`, it can successfully call the `FileUtilities.AppendDirectorySeparator` method, even though the method is internal to the `Assembly1` assembly. Note that if you are compiling in C# from the command line, you must use the **/out** compiler switch to ensure that the name of the friend assembly is available when the compiler binds to external references. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.runtime.compilerservices.internalsvisibletoattribute/cpp/friend1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/friend1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.internalsvisibletoattribute/vb/friend1.vb" id="Snippet2"::: - - The following example uses the attribute to make an `internal` member of an unsigned assembly visible to another unsigned assembly. The attribute ensures that the `internal` `StringLib.IsFirstLetterUpperCase` method in an assembly named `UtilityLib` is visible to the code in an assembly named `Friend2`. The following is the source code for UtilityLib.dll: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.internalsvisibletoattribute/vb/friend1.vb" id="Snippet2"::: + + The following example uses the attribute to make an `internal` member of an unsigned assembly visible to another unsigned assembly. The attribute ensures that the `internal` `StringLib.IsFirstLetterUpperCase` method in an assembly named `UtilityLib` is visible to the code in an assembly named `Friend2`. The following is the source code for UtilityLib.dll: + :::code language="csharp" source="~/snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/utilitylib.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.internalsvisibletoattribute/vb/utilitylib.vb" id="Snippet5"::: - - **Unsigned assemblies** - - The following example provides the source code for the `Friend2` assembly. Note that if you are compiling in C# from the command line, you must use the **/out** compiler switch to ensure that the name of the friend assembly is available when the compiler binds to external references. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.internalsvisibletoattribute/vb/utilitylib.vb" id="Snippet5"::: + + **Unsigned assemblies** + + The following example provides the source code for the `Friend2` assembly. Note that if you are compiling in C# from the command line, you must use the **/out** compiler switch to ensure that the name of the friend assembly is available when the compiler binds to external references. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.runtime.compilerservices.internalsvisibletoattribute/cpp/friend2.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.CompilerServices/InternalsVisibleToAttribute/Overview/friend2.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.internalsvisibletoattribute/vb/friend2.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.internalsvisibletoattribute/vb/friend2.vb" id="Snippet6"::: + ]]> @@ -317,15 +266,15 @@ Gets the name of the friend assembly to which all types and type members that are marked with the keyword are to be made visible. A string that represents the name of the friend assembly. - attribute, see the following topics: - -- [Friend Assemblies (C++)](/cpp/dotnet/friend-assemblies-cpp) - -- [Friend assemblies](/dotnet/standard/assembly/friend) - + attribute, see the following topics: + +- [Friend Assemblies (C++)](/cpp/dotnet/friend-assemblies-cpp) + +- [Friend assemblies](/dotnet/standard/assembly/friend) + ]]> diff --git a/xml/System.Runtime.InteropServices/COMException.xml b/xml/System.Runtime.InteropServices/COMException.xml index 210e09b63a2..1ed3b1ec991 100644 --- a/xml/System.Runtime.InteropServices/COMException.xml +++ b/xml/System.Runtime.InteropServices/COMException.xml @@ -70,35 +70,7 @@ The exception that is thrown when an unrecognized HRESULT is returned from a COM method call. - - class. This all-purpose exception exposes the same members as any exception, and inherits a public property that contains the HRESULT returned by the callee. If an error message is available to the runtime (obtained from the [IErrorInfo](https://docs.microsoft.com/previous-versions/windows/desktop/ms723041(v=vs.85)) interface or the `Err` object in Visual Basic, or in some cases from the operating system), the message is returned to the caller. However, if the COM component developer fails to include an error message, the runtime returns the eight-digit HRESULT in place of a message string. Having an HRESULT allows the caller to determine the cause of the generic exception. - -## Handling a COMException exception - The following are some considerations for troubleshooting a exception. - - Check the property - When the runtime encounters an unfamiliar HRESULT and throws a exception, the property includes either the error message or, if an error message is unavailable, the eight-digit HRESULT value. The error message or the HRESULT value can help you determine the cause of the exception. - - For a list of HRESULT values, see [Common HRESULT Values](/windows/win32/seccrypto/common-hresult-values). - - Late-bound arguments and Microsoft Office objects - When passing late-bound arguments to methods of Microsoft Office objects, a exception may be thrown when the objects are COM objects. The late binder assumes that such method calls involve a `ByRef` parameter and that the property you pass has a `set` accessor. If the property does not, the .NET Framework generates a exception (with a `CORE_E_MISSINGMETHOD` HRESULT ). To work around this behavior, use early-bound objects or pass a variable instead of a property of the object. - - Visual Studio and the hosting process - COM is used to communicate between Visual Studio and the [hosting process](/visualstudio/ide/hosting-process-vshost-exe?view=vs-2015). Because it is used before code runs, a call to [CoInitializeSecurity](/windows/win32/api/combaseapi/nf-combaseapi-coinitializesecurity) causes this exception to be thrown. - - In some cases, running Visual Studio as Administrator may resolve the issue. You can also [disable the hosting process](/visualstudio/ide/how-to-disable-the-hosting-process?view=vs-2015). - -## Throwing a COMException exception - Although you can use the class to return specific HRESULTs to unmanaged clients, throwing a specific .NET Framework exception is better than using a generic exception. Consider that managed clients as well as unmanaged clients can use your .NET Framework object, and throwing an HRESULT to a managed caller is less comprehensible than throwing an exception. - - ]]> - + For more information about this API, see Supplemental API remarks for COMException. Handling and Throwing Exceptions @@ -155,16 +127,16 @@ Initializes a new instance of the class with default values. - inherits from . The following table shows how this constructor sets the properties of the object. - -|Property|Value| -|--------------|-----------| -||`null`.| -||A localized error message string.| - + inherits from . The following table shows how this constructor sets the properties of the object. + +|Property|Value| +|--------------|-----------| +||`null`.| +||A localized error message string.| + ]]> @@ -212,16 +184,16 @@ The message that indicates the reason for the exception. Initializes a new instance of the class with a specified message. - inherits from . The following table shows how this constructor sets the properties of the object. - -|Property|Value| -|--------------|-----------| -||`null`| -||`message`| - + inherits from . The following table shows how this constructor sets the properties of the object. + +|Property|Value| +|--------------|-----------| +||`null`| +||`message`| + ]]> @@ -283,13 +255,13 @@ The object that supplies the contextual information about the source or destination. Initializes a new instance of the class from serialization data. - inherits from . - + inherits from . + ]]> @@ -342,18 +314,18 @@ The exception that is the cause of the current exception. If the parameter is not , 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 `null` if the property does not supply the inner exception value to the constructor. - - The following table shows how this constructor sets the properties of the object. - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows how this constructor sets the properties of the object. + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> @@ -405,18 +377,18 @@ The error code (HRESULT) value associated with this exception. Initializes a new instance of the class with a specified message and error code. - constructor sets the base message with the error code. - - inherits from . The following table shows how this constructor sets the properties of the object. - -|Property|Value| -|--------------|-----------| -||`null`| -||`message`| - + constructor sets the base message with the error code. + + inherits from . The following table shows how this constructor sets the properties of the object. + +|Property|Value| +|--------------|-----------| +||`null`| +||`message`| + ]]> diff --git a/xml/System.Runtime.InteropServices/ComWrappers.xml b/xml/System.Runtime.InteropServices/ComWrappers.xml index bd422bbccbf..e69665da0f6 100644 --- a/xml/System.Runtime.InteropServices/ComWrappers.xml +++ b/xml/System.Runtime.InteropServices/ComWrappers.xml @@ -52,61 +52,7 @@ Class for managing wrappers of COM IUnknown types. - - API provides support for the `IUnknown` ABI, independent of the built-in COM interoperability support. The `ComWrappers` API exposes the minimal runtime support that's needed for developers to replace the built-in version in an efficient manner. - -Traditionally in the runtime, a native proxy to managed object is called a COM Callable Wrapper (CCW), and a managed proxy to a native object is called a Runtime Callable Wrapper (RCW). However, when used here, those terms should not be confused with the built-in features of the same name (that is, [CCW](https://docs.microsoft.com/dotnet/standard/native-interop/com-callable-wrapper) and [RCW](https://docs.microsoft.com/dotnet/standard/native-interop/runtime-callable-wrapper)). Unlike the built-in features, a majority of the responsibility for accurate lifetime management, dispatching methods, and marshalling of arguments and return values is left to the `ComWrappers` implementer. - -"Minimal support" is defined by the following features: - -1. Efficient mapping between a managed object and a native proxy (for example, CCW). -2. Efficient mapping between a native `IUnknown` and its managed proxy (for example, RCW). -3. Integration with the garbage collector through the [IReferenceTrackerHost](/windows/win32/api/windows.ui.xaml.hosting.referencetracker/nn-windows-ui-xaml-hosting-referencetracker-ireferencetrackerhost) interface contract. - - Leveraging this is an advanced scenario. - -### Proxy state - -This section provides descriptions and illustrations of native and managed proxy state after their respective creation. - -In the following illustrations, a strong reference is depicted as a solid line (`===`) and a weak reference is depicted as a dashed line (`= = =`). The terms "strong reference" and "weak reference" should be interpreted as "extending lifetime" and "not extending lifetime", as opposed to implying a specific implementation. - -The following illustration shows the state of the managed object and native proxy after a call to . - -``` - -------------------- ---------------------- -| Managed object | | Native proxy | -| | | Ref count: 1 | -| ---------------- | | ------------------ | -| | Weak reference |=| = = = = = = = >| | Strong reference | | -| | to proxy | |<===============|=| to object | | -| ---------------- | | ------------------ | - -------------------- ---------------------- -``` - -The next illustration shows the state of the native object and managed proxy after a call to . The concept of "identity" follows the [rules for `IUnknown`](https://docs.microsoft.com/windows/win32/com/rules-for-implementing-queryinterface#objects-must-have-identity). - -``` - ------------------ ------------------ -| Native object |< = = = = = =| | -| Ref count: +1 | | Mapping from | - ------------------ | native identity | - ------------------------ | to managed proxy | -| Managed proxy |< = = =| | -| Created by ComWrappers | ------------------ -| implementer. | -| Optional AddRef() on | -| native object. | - ------------------------ -``` -Observe that only weak references exist from the runtime perspective. The `+1` reference count on the native object is assumed to be performed by the managed proxy creator (that is, the `ComWrappers` implementer) to ensure the associated lifetime between the native object and its managed proxy. There is an optional strong reference (that is, `AddRef()`) mentioned in the managed proxy, which is used to support scenario (3) mentioned earlier. See . With this optional strong reference, the reference count would be `+2`. - - ]]> - + For more information about this API, see Supplemental API remarks for ComWrappers. diff --git a/xml/System.Runtime.InteropServices/ICustomMarshaler.xml b/xml/System.Runtime.InteropServices/ICustomMarshaler.xml index 32e5bf798b3..86a2c1466c0 100644 --- a/xml/System.Runtime.InteropServices/ICustomMarshaler.xml +++ b/xml/System.Runtime.InteropServices/ICustomMarshaler.xml @@ -47,151 +47,7 @@ Provides custom wrappers for handling method calls. - - [!NOTE] -> Custom marshalers are not invoked when calling from managed code to unmanaged code on a dispatch-only interface. - -## Defining the Marshaling Type - Before you can build a custom marshaler, you must define the managed and unmanaged interfaces that will be marshaled. These interfaces commonly perform the same function but are exposed differently to managed and unmanaged objects. - - A managed compiler produces a managed interface from metadata, and the resulting interface looks like any other managed interface. The following example shows a typical interface. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.runtime.interopservices.icustommarshaler/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/ICustomMarshaler/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.icustommarshaler/vb/source.vb" id="Snippet1"::: - - You define the unmanaged type in Interface Definition Language (IDL) and compile it with the Microsoft Interface Definition Language (MIDL) compiler. You define the interface within a library statement and assign it an interface ID with the universal unique identifier (UUID) attribute, as the following example demonstrates. - -``` - [uuid(9B2BAADA-0705-11D3-A0CD-00C04FA35826)] -library OldLib { - [uuid(9B2BAADD-0705-11D3-A0CD-00C04FA35826)] - interface IOld : IUnknown - HRESULT OldMethod(); -} -``` - - The MIDL compiler produces several output files. If the interface is defined in Old.idl, the output file Old_i.c defines a `const` variable with the interface identifier (IID) of the interface, as the following example demonstrates. - -``` -const IID IID_IOld = {0x9B2BAADD,0x0705,0x11D3,{0xA0,0xCD,0x00,0xC0,0x4F,0xA3,0x58,0x26}}; -``` - - The Old.h file is also produced by MIDL. It contains a C++ definition of the interface that can be included in your C++ source code. - -## Implementing the ICustomMarshaler Interface - Your custom marshaler must implement the interface to provide the appropriate wrappers to the runtime. - - The following C# code displays the base interface that must be implemented by all custom marshalers. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.runtime.interopservices.icustommarshaler/cpp/source.cpp" id="Snippet2"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/ICustomMarshaler/Overview/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.icustommarshaler/vb/source.vb" id="Snippet2"::: - - The interface includes methods that provide conversion support, cleanup support, and information about the data to be marshaled. - -|Type of operation|ICustomMarshaler method|Description| -|-----------------------|-----------------------------|-----------------| -|Conversion (from native to managed code)||Marshals a pointer to native data into a managed object. This method returns a custom runtime callable wrapper (RCW) that can marshal the unmanaged interface that is passed as an argument. The marshaler should return an instance of the custom RCW for that type.| -|Conversion (from managed to native code)||Marshals a managed object into a pointer to native data. This method returns a custom COM callable wrapper (CCW) that can marshal the managed interface that is passed as an argument. The marshaler should return an instance of the custom CCW for that type.| -|Cleanup (of native code)||Enables the marshaler to clean up the native data (the CCW) that is returned by the method.| -|Cleanup (of managed code)||Enables the marshaler to clean up the managed data (the RCW) that is returned by the method.| -|Information (about native code)||Returns the size of the unmanaged data to be marshaled.| - -### Conversion - - - Marshals a pointer to native data into a managed object. This method returns a custom runtime callable wrapper (RCW) that can marshal the unmanaged interface that is passed as an argument. The marshaler should return an instance of the custom RCW for that type. - - - - Marshals a managed object into a pointer to native data. This method returns a custom COM callable wrapper (CCW) that can marshal the managed interface that is passed as an argument. The marshaler should return an instance of the custom CCW for that type. - -### Cleanup - - - Enables the marshaler to clean up the native data (the CCW) that is returned by the method. - - - - Enables the marshaler to clean up the managed data (the RCW) that is returned by the method. - -### Size Information - - - Returns the size of the unmanaged data to be marshaled. - -> [!NOTE] -> If a custom marshaler calls any methods that set the last P/Invoke error when marshaling from native to managed or when cleaning up, the value returned by and will represent the call in the marshaling or cleanup calls. This can cause errors to be missed when using custom marshalers with P/Invokes with set to `true`. To preserve the last P/Invoke error, use the and methods in the implementation. - -## Implementing the GetInstance Method - In addition to implementing the interface, custom marshalers must implement a `static` method called `GetInstance` that accepts a as a parameter and has a return type of . This `static` method is called by the common language runtime's COM interop layer to instantiate an instance of the custom marshaler. The string that is passed to `GetInstance` is a cookie that the method can use to customize the returned custom marshaler. The following example shows a minimal, but complete, implementation. - - :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/ICustomMarshaler/Overview/source.cs" id="Snippet6"::: - -## Applying MarshalAsAttribute - To use a custom marshaler, you must apply the attribute to the parameter or field that is being marshaled. - - You must also pass the enumeration value to the constructor. In addition, you must specify the field with one of the following named parameters: - -- (required): The assembly-qualified name of the custom marshaler. The name should include the namespace and class of the custom marshaler. If the custom marshaler is not defined in the assembly it is used in, you must specify the name of the assembly in which it is defined. - - > [!NOTE] - > You can use the field instead of the field. takes a type that is easier to specify. - -- (optional): A cookie that is passed to the custom marshaler. You can use the cookie to provide additional information to the marshaler. For example, if the same marshaler is used to provide a number of wrappers, the cookie identifies a specific wrapper. The cookie is passed to the `GetInstance` method of the marshaler. - - The attribute identifies the custom marshaler so it can activate the appropriate wrapper. The common language runtime's interop service then examines the attribute and creates the custom marshaler the first time the argument (parameter or field) needs to be marshaled. - - The runtime then calls the and methods on the custom marshaler to activate the correct wrapper to handle the call. - -## Using a Custom Marshaler - When the custom marshaler is complete, you can use it as a custom wrapper for a particular type. The following example shows the definition of the `IUserData` managed interface: - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.runtime.interopservices.icustommarshaler/cpp/source.cpp" id="Snippet3"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/ICustomMarshaler/Overview/source.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.icustommarshaler/vb/source.vb" id="Snippet3"::: - - In the following example, the `IUserData` interface uses the `NewOldMarshaler` custom marshaler to enable unmanaged client applications to pass an `IOld` interface to the `DoSomeStuff` method. The managed description of the `DoSomeStuff` method takes an `INew` interface, as shown in the previous example, whereas the unmanaged version of `DoSomeStuff` takes an `IOld` interface pointer, as shown in the following example. - -``` -[uuid(9B2BAADA-0705-11D3-A0CD-00C04FA35826)] -library UserLib { - [uuid(9B2BABCD-0705-11D3-A0CD-00C04FA35826)] - interface IUserData : IUnknown - HRESULT DoSomeStuff(IUnknown* pIOld); -} -``` - - The type library that is generated by exporting the managed definition of `IUserData` yields the unmanaged definition shown in this example instead of the standard definition. The attribute applied to the `INew` argument in the managed definition of the `DoSomeStuff` method indicates that the argument uses a custom marshaler, as the following example shows. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.runtime.interopservices.icustommarshaler/cpp/source.cpp" id="Snippet4"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/ICustomMarshaler/Overview/source.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.icustommarshaler/vb/source.vb" id="Snippet4"::: - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.runtime.interopservices.icustommarshaler/cpp/source.cpp" id="Snippet5"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/ICustomMarshaler/Overview/source.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.icustommarshaler/vb/source.vb" id="Snippet5"::: - - In the previous examples, the first parameter provided to the attribute is the enumeration value `UnmanagedType.CustomMarshaler`. - - The second parameter is the field, which provides the assembly-qualified name of the custom marshaler. This name consists of the namespace and class of the custom marshaler (`MarshalType="MyCompany.NewOldMarshaler"`). - - ]]> - + For more information about this API, see Supplemental API remarks for ICustomMarshaler. diff --git a/xml/System.Runtime.InteropServices/SafeHandle.xml b/xml/System.Runtime.InteropServices/SafeHandle.xml index a13d31625c0..66bf8bb3cfc 100644 --- a/xml/System.Runtime.InteropServices/SafeHandle.xml +++ b/xml/System.Runtime.InteropServices/SafeHandle.xml @@ -82,77 +82,26 @@ Represents a wrapper class for operating system handles. This class must be inherited. - + For more information about this API, see Supplemental API remarks for SafeHandle. + . It reads bytes from a file and displays their hexadecimal values. It also contains a fault testing harness that causes the thread to abort, but the handle value is freed. When using an to represent handles, the handle is occasionally leaked due to the asynchronous thread abort. -## Remarks - The class provides critical finalization of handle resources, preventing handles from being reclaimed prematurely by garbage collection and from being recycled by Windows to reference unintended unmanaged objects. - - This topic includes the following sections: - - [Why SafeHandle?](#Why) - [What SafeHandle does](#Does) - [Classes derived from SafeHandle](#Derived) - - -## Why SafeHandle? - Before the .NET Framework version 2.0, all operating system handles could only be encapsulated in the managed wrapper object. While this was a convenient way to interoperate with native code, handles could be leaked by asynchronous exceptions, such as a thread aborting unexpectedly or a stack overflow. These asynchronous exceptions are an obstacle to cleaning up operating system resources, and they can occur almost anywhere in your app. - - Although overrides to the method allow cleanup of unmanaged resources when an object is being garbage collected, in some circumstances, finalizable objects can be reclaimed by garbage collection while executing a method within a platform invoke call. If a finalizer frees the handle passed to that platform invoke call, it could lead to handle corruption. The handle could also be reclaimed while your method is blocked during a platform invoke call, such as while reading a file. - - More critically, because Windows aggressively recycles handles, a handle could be recycled and point to another resource that might contain sensitive data. This is known as a recycle attack and can potentially corrupt data and be a security threat. - - -## What SafeHandle does - The class simplifies several of these object lifetime issues, and is integrated with platform invoke so that operating system resources are not leaked. The class resolves object lifetime issues by assigning and releasing handles without interruption. It contains a critical finalizer that ensures that the handle is closed and is guaranteed to run during unexpected unloads, even in cases when the platform invoke call is assumed to be in a corrupted state. - - Because inherits from , all the noncritical finalizers are called before any of the critical finalizers. The finalizers are called on objects that are no longer live during the same garbage collection pass. For example, a object can run a normal finalizer to flush out existing buffered data without the risk of the handle being leaked or recycled. This very weak ordering between critical and noncritical finalizers is not intended for general use. It exists primarily to assist in the migration of existing libraries by allowing those libraries to use without altering their semantics. Additionally, the critical finalizer and anything it calls, such as the method, must be in a constrained execution region. This imposes constraints on what code can be written within the finalizer's call graph. - - Platform invoke operations automatically increment the reference count of handles encapsulated by a and decrement them upon completion. This ensures that the handle will not be recycled or closed unexpectedly. - - You can specify ownership of the underlying handle when constructing objects by supplying a value to the `ownsHandle` argument in the class constructor. This controls whether the object will release the handle after the object has been disposed. This is useful for handles with peculiar lifetime requirements or for consuming a handle whose lifetime is controlled by someone else. - - -## Classes derived from SafeHandle - is an abstract wrapper class for operating system handles. Deriving from this class is difficult. Instead, use the derived classes in the namespace that provide safe handles for the following: - -- Files (the class). - -- Memory mapped files (the class). +You will need a text file in the same folder as the compiled application. Assuming that you name the application "HexViewer", the command line usage is: -- Pipes (the class). +`HexViewer -Fault` -- Memory views (the class). +Optionally specify `-Fault` to intentionally attempt to leak the handle by aborting the thread in a certain window. Use the Windows Perfmon.exe tool to monitor handle counts while injecting faults. -- Cryptography constructs (the , , , and classes). - -- Processes (the class). - -- Registry keys (the class). - -- Wait handles (the class). - - - -## Examples - The following code example creates a custom safe handle for an operating system file handle, deriving from . It reads bytes from a file and displays their hexadecimal values. It also contains a fault testing harness that causes the thread to abort, but the handle value is freed. When using an to represent handles, the handle is occasionally leaked due to the asynchronous thread abort. - - You will need a text file in the same folder as the compiled application. Assuming that you name the application "HexViewer", the command line usage is: - - `HexViewer -Fault` - - Optionally specify `-Fault` to intentionally attempt to leak the handle by aborting the thread in a certain window. Use the Windows Perfmon.exe tool to monitor handle counts while injecting faults. - - :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/SafeHandle/Overview/program.cs" id="Snippet1"::: - - ]]> - +:::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/SafeHandle/Overview/program.cs" id="Snippet1"::: + ]]> + - To create a class derived from , you must know how to create and free an operating system handle. This process is different for different handle types because some use the [CloseHandle](/windows/win32/api/handleapi/nf-handleapi-closehandle) function, while others use more specific functions such as [UnmapViewOfFile](/windows/win32/api/memoryapi/nf-memoryapi-unmapviewoffile) or [FindClose](/windows/win32/api/fileapi/nf-fileapi-findclose). For this reason, you must create a derived class of for each operating system handle type that you want to wrap in a safe handle. + To create a class derived from , you must know how to create and free an operating system handle. This process is different for different handle types because some use the [CloseHandle](/windows/win32/api/handleapi/nf-handleapi-closehandle) function, while others use more specific functions such as [UnmapViewOfFile](/windows/win32/api/memoryapi/nf-memoryapi-unmapviewoffile) or [FindClose](/windows/win32/api/fileapi/nf-fileapi-findclose). For this reason, you must create a derived class of for each operating system handle type that you want to wrap in a safe handle. - When you inherit from , you must override the following members: and . + When you inherit from , you must override the following members: and . - You should also provide a public parameterless constructor that calls the base constructor with a value that represents an invalid handle value, and a value indicating whether the native handle is owned by the and consequently should be freed when that has been disposed. + You should also provide a public parameterless constructor that calls the base constructor with a value that represents an invalid handle value, and a value indicating whether the native handle is owned by the and consequently should be freed when that has been disposed. diff --git a/xml/System.Runtime.Loader/AssemblyLoadContext.xml b/xml/System.Runtime.Loader/AssemblyLoadContext.xml index b54c227c50f..fb58b57de02 100644 --- a/xml/System.Runtime.Loader/AssemblyLoadContext.xml +++ b/xml/System.Runtime.Loader/AssemblyLoadContext.xml @@ -41,60 +41,7 @@ Represents the runtime's concept of a scope for assembly loading. - - represents a load context. Conceptually, a load context creates a scope for loading, resolving, and potentially unloading a set of assemblies. - -The exists primarily to provide assembly loading isolation. It allows multiple versions of the same assembly to be loaded within a single process. It replaces the isolation mechanisms provided by multiple instances in .NET Framework. - -> [!NOTE] -> - does not provide any security features. All code has full permissions of the process. -> - In .NET Core 2.0 - 2.2 only, is an abstract class. To create a concrete class in these versions, implement the method. - -### Usage in the runtime - -The runtime implements two assembly load contexts: - -* represents the runtime's default context, which is used for the application main assembly and its static dependencies. -* The method isolates the assemblies it loads by instantiating the most basic . It has a simplistic isolation scheme that loads each assembly in its own with no dependency resolution. - -### Application usage - -An application can create its own to create a custom solution for advanced scenarios. The customization focuses on defining dependency resolution mechanisms. - -The provides two extension points to implement managed assembly resolution: - -1. The method provides the first chance for the to resolve, load, and return the assembly. If the method returns `null`, the loader tries to load the assembly into the . -2. If the is unable to resolve the assembly, the original gets a second chance to resolve the assembly. The runtime raises the event. - -Additionally, the virtual method allows customization of the default unmanaged assembly resolution. The default implementation returns `null`, which causes the runtime search to use its default search policy. The default search policy is sufficient for most scenarios. - -### Technical challenges - -* It is not possible to load multiple versions of the runtime in a single process. - - > [!CAUTION] - > Loading multiple copies or different versions of framework assemblies can lead to unexpected and hard-to-diagnose behavior. - - > [!TIP] - > Use process boundaries with remoting or interprocess communication to solve this isolation problem. - -* The timing of assembly loading can make testing and debugging difficult. Assemblies are typically loaded without their dependencies immediately being resolved. The dependencies are loaded as they are needed: - - * When code branches into a dependent assembly. - * When code loads resources. - * When code explicitly loads assemblies. - -* The implementation of can add new dependencies that may need to be isolated to allow different versions to exist. The most natural implementation would place these dependencies in the default context. Careful design can isolate the new dependencies. - -* The same assembly is loaded multiple times into different contexts. - * This can lead to confusing error messages, for example "Unable to cast object of type 'Sample.Plugin' to type 'Sample.Plugin'". - * Marshaling across isolation boundaries is non-trivial. A typical solution is to use an interface defined in an assembly that's only loaded into the default load context. - - ]]> - + For more information about this API, see Supplemental API remarks for AssemblyLoadContext. About AssemblyLoadContext How to use and debug assembly unloadability in .NET Core AssemblyLoadContext CoreCLR design document @@ -657,15 +604,15 @@ Implementations of this method can return an assembly loaded into any . 3. Unless the assembly is loaded or an exception is thrown, the method fires the event. 4. Unless the assembly is loaded or an exception is thrown, the method fires the event. - + > [!NOTE] > is thrown if `assemblyRef` specifies the full assembly name, and the first assembly that matches the simple name has a incompatible version or culture. The loader does not continue probing for other assemblies that match the simple name. - + Each can load only: - + * One version of an executable assembly. * One version of a satellite assembly for each culture. - + ]]> @@ -782,9 +729,9 @@ Each can load only: ## Remarks The native image of a managed assembly is pre-jitted to optimize running on a specific platform. - + The assembly path refers to the path to the IL version of the assembly. It is an optional argument as the IL is typically included in the native image. It can be used by the runtime as a fallback if the native image is not found. - + ]]> The argument is not an absolute path. @@ -940,9 +887,9 @@ Each can load only: ## Remarks The default implementation always returns . When is returned, the runtime loads the library with its default policy. - + This virtual method can be overridden to customize the unmanaged library search algorithm. When overridden the name can be used to identify the library. The loaded library does not need to match the requested name, but can be transformed as needed. This could include adjusting the name for platform specific naming. - + ]]> @@ -982,7 +929,7 @@ Each can load only: Loads an unmanaged library from the specified path. The OS handle for the loaded native library. - class. @@ -1073,14 +1020,14 @@ The OS handle returned by this method can be used with methods of the [!IMPORTANT] > If more than one event handler is registered for this event, the event handlers are called in order until an event handler returns a value that isn't `null`. Subsequent event handlers are ignored. - + For more information about handling events, see [Handle and raise events](/dotnet/standard/events/). - + It is noteworthy that a handler can be added for this event on any , including the default context. - + ]]> Collect detailed assembly loading information @@ -1116,7 +1063,7 @@ The OS handle returned by this method can be used with methods of the Occurs when the resolution of a native library fails. - ). @@ -1158,9 +1105,9 @@ This event is raised if the native library cannot be resolved by the default res The full path to the directory where the optimization profiles are stored. Sets the root path where the optimization profiles for this load context are stored. - . @@ -1209,9 +1156,9 @@ The profile optimization improves the startup performance of the load context on The name of the optimization profile. Starts the profile optimization for the specified profile. - . diff --git a/xml/System.Runtime.Serialization.Formatters.Binary/BinaryFormatter.xml b/xml/System.Runtime.Serialization.Formatters.Binary/BinaryFormatter.xml index a42bfcc7d2d..b6b06455078 100644 --- a/xml/System.Runtime.Serialization.Formatters.Binary/BinaryFormatter.xml +++ b/xml/System.Runtime.Serialization.Formatters.Binary/BinaryFormatter.xml @@ -69,60 +69,7 @@ Serializes and deserializes an object, or an entire graph of connected objects, in binary format. - - and classes implement the interface to support remote procedure calls (RPCs), and the interface (inherited by the ) to support serialization of a graph of objects. The class also supports RPCs with objects, without using the functionality. - - During RPCs, the interface allows the specification of two separate object graphs: the graph of objects to serialize, and an additional graph that contains an array of header objects that convey information about the remote function call (for example, transaction ID or a method signature). - - RPCs that use the separate into two distinct parts: method calls, which are sent to the server with the remote object that contains the method called, and method responses, which are sent from the server to the client with the status and response information from the called method. - - During serialization of a method call the first object of the object graph must support the interface. To deserialize a method call, use the method with the parameter. The remoting infrastructure uses the delegate to produce an object that supports the interface. When the invokes the delegate, it returns the URI of the remote object with the method that is being called. The first object in the graph returned supports the interface. - - The serialization procedure for a method response is identical to that of a method call, except the first object of the object graph must support the interface. To deserialize a method response, use the method. To save time, details about the caller object are not sent to the remote object during the method call. These details are instead obtained from the original method call, which is passed to the method in the parameter. The first object in the graph returned by the method supports the interface. - -> [!IMPORTANT] -> Using binary serialization to deserialize untrusted data can lead to security risks. For more information, see [Validate All Inputs](https://owasp.org/www-project-proactive-controls/v3/en/c5-validate-inputs) and the [BinaryFormatter security guide](/dotnet/standard/serialization/binaryformatter-security-guide). - -## Unpaired Surrogates - Any unpaired surrogate characters are lost in binary serialization. For example, the following string contains a high surrogate Unicode character `(\ud800`) in between the two `Test` words: - - `Test\ud800Test` - - Before serialization, the byte array of the string is as follows: - -|Byte Array Value|Character| -|----------------------|---------------| -|84|T| -|101|e| -|115|s| -|116|t| -|55296|\ud800| -|84|T| -|101|e| -|115|s| -|116|t| - - After deserialization, the high surrogate Unicode character is lost: - -|Byte Array Value|Character| -|----------------------|---------------| -|84|T| -|101|e| -|115|s| -|116|t| -|84|T| -|101|e| -|115|s| -|116|t| - - ]]> - + Warning: BinaryFormatter is insecure and can't be made secure. For more information, see the BinaryFormatter security guide and System.Runtime.Serialization.Formatters.Binary.BinaryFormatter class. diff --git a/xml/System.Runtime.Serialization.Formatters.Soap/SoapFormatter.xml b/xml/System.Runtime.Serialization.Formatters.Soap/SoapFormatter.xml index 4d88c81e88f..beac8cc4465 100644 --- a/xml/System.Runtime.Serialization.Formatters.Soap/SoapFormatter.xml +++ b/xml/System.Runtime.Serialization.Formatters.Soap/SoapFormatter.xml @@ -25,33 +25,30 @@ Serializes and deserializes an object, or an entire graph of connected objects, in SOAP format. - [!NOTE] -> Beginning with the .NET Framework 2.0, this class is obsolete. +> Beginning with .NET Framework 2.0, this class is obsolete. [!INCLUDE[binaryformatter](~/includes/binaryformatter.md)] - - The and classes implement the interface to support remote procedure calls (RPCs), and the interface (inherited by the ) to support serialization of a graph of objects. The class also supports RPCs with objects, without using the functionality. - - During RPCs, the interface allows the specification of two separate object graphs: the graph of objects to serialize, and an additional graph that contains an array of header objects that convey information about the remote function call (for example, transaction ID or a method signature). For proper serialization, the root object of the first graph must be an object that implements either the interface or the interface. - - During deserialization of an RPC, a delegate is specified to the method of the formatter. The remoting infrastructure uses the delegate to produce an object that supports the interface. This object contains the information stored in the headers, and becomes the root of the graph returned by the deserializer. - - The can also handle RPCs that are produced with objects that implement the interface. To create an RPC without using the functionality, place an object that supports the interface at the root of a graph being serialized. To deserialize an RPC created in this manner the property must be set to another object that supports the interface, and contains the relevant remote call information. - -## TimeSpan Serialization - TimeSpan objects are serialized according to the ISO 8601: 1998 section 5.5.3.2.1 "Alternative" standard. - -## Examples - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/SoapFormatter Example/CPP/soapformatter.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Serialization.Formatters.Soap/SoapFormatter/Overview/soapformatter.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/SoapFormatter Example/VB/soapformatter.vb" id="Snippet1"::: - - ]]> + +The and classes implement the interface to support remote procedure calls (RPCs), and the interface (inherited by the ) to support serialization of a graph of objects. The class also supports RPCs with objects, without using the functionality. + +During RPCs, the interface allows the specification of two separate object graphs: the graph of objects to serialize, and an additional graph that contains an array of header objects that convey information about the remote function call (for example, transaction ID or a method signature). For proper serialization, the root object of the first graph must be an object that implements either the interface or the interface. + +During deserialization of an RPC, a delegate is specified to the method of the formatter. The remoting infrastructure uses the delegate to produce an object that supports the interface. This object contains the information stored in the headers, and becomes the root of the graph returned by the deserializer. + +The can also handle RPCs that are produced with objects that implement the interface. To create an RPC without using the functionality, place an object that supports the interface at the root of a graph being serialized. To deserialize an RPC created in this manner the property must be set to another object that supports the interface, and contains the relevant remote call information. + +TimeSpan objects are serialized according to the ISO 8601: 1998 section 5.5.3.2.1 "Alternative" standard. + ]]> + + + @@ -80,23 +77,23 @@ Initializes a new instance of the class with default property values. - . - -|Property|Value| -|--------------|-----------| -||`null`| -||A new initialized to specify that the serialized data can be transmitted to or received from any of the other contexts| - - - -## Examples + . + +|Property|Value| +|--------------|-----------| +||`null`| +||A new initialized to specify that the serialized data can be transmitted to or received from any of the other contexts| + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/SoapFormatter Example/CPP/soapformatter.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Serialization.Formatters.Soap/SoapFormatter/Overview/soapformatter.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/SoapFormatter Example/VB/soapformatter.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/SoapFormatter Example/VB/soapformatter.vb" id="Snippet1"::: + ]]> @@ -124,13 +121,13 @@ The that holds the source and destination of the serialization. If the parameter is , then the defaults to . Initializes a new instance of the class with the specified and . - . - - The serialization or deserialization process uses the specified to search for surrogates that are registered for the object types you want to deserialize. Surrogates are helpers that serialize and deserialize objects of specific classes. The default cannot handle the serialization of objects that derive from the for remoting purposes. In a remoting situation the specified replaces the object derived from with a object that is serialized by the specified surrogate selector. Therefore, if you want to use remote objects, set the `selector` parameter to an instance of . If you do not need surrogates, set the `selector` parameter to be `null`. - + . + + The serialization or deserialization process uses the specified to search for surrogates that are registered for the object types you want to deserialize. Surrogates are helpers that serialize and deserialize objects of specific classes. The default cannot handle the serialization of objects that derive from the for remoting purposes. In a remoting situation the specified replaces the object derived from with a object that is serialized by the specified surrogate selector. Therefore, if you want to use remote objects, set the `selector` parameter to an instance of . If you do not need surrogates, set the `selector` parameter to be `null`. + ]]> @@ -211,11 +208,11 @@ Gets or sets the used with this . The used with this . - provides an enumeration that describes the source and the destination for a given serialized stream, as well as a way for serialization to retain that context and an additional caller-defined context. - + provides an enumeration that describes the source and the destination for a given serialized stream, as well as a way for serialization to retain that context and an additional caller-defined context. + ]]> @@ -229,12 +226,12 @@ Deserializes a stream into an object graph. - @@ -267,18 +264,18 @@ Deserializes the data on the provided stream and reconstitutes the graph of objects. The top object of the deserialized graph (root). - @@ -315,18 +312,18 @@ Deserializes the stream into an object graph with any headers in that stream being handled by the given . The top object of the deserialized graph (root). - parameter is one of two ways to return headers from a stream in SOAP Remote Procedure Call (RPC) format. The other way is to use the property. - - For successful deserialization, the current position in the stream must be at the beginning of the object graph. - -## TimeSpan Serialization - TimeSpan objects are serialized according to the ISO 8601: 1998 section 5.5.3.2.1 "Alternative" standard. + parameter is one of two ways to return headers from a stream in SOAP Remote Procedure Call (RPC) format. The other way is to use the property. + + For successful deserialization, the current position in the stream must be at the beginning of the object graph. + +## TimeSpan Serialization + TimeSpan objects are serialized according to the ISO 8601: 1998 section 5.5.3.2.1 "Alternative" standard. [!INCLUDE [untrusted-data-method-note](~/includes/untrusted-data-method-note.md)] - + ]]> @@ -362,11 +359,11 @@ Gets or sets the of automatic deserialization for .NET Framework remoting. The that represents the current automatic deserialization level. - and (the default). For details about deserialization levels, see [Automatic Deserialization in .NET Remoting](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/5dxse167(v=vs.100)). - + and (the default). For details about deserialization levels, see [Automatic Deserialization in .NET Remoting](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/5dxse167(v=vs.100)). + ]]> @@ -409,18 +406,18 @@ The object, or root of the object graph, to serialize. All child objects of this root object are automatically serialized. Serializes an object or graph of objects with the specified root to the given . - @@ -458,13 +455,13 @@ Remoting headers to include in the serialization. Can be . Serializes an object or graph of objects with the specified root to the given in the SOAP Remote Procedure Call (RPC) format. - @@ -495,11 +492,11 @@ Gets or sets the that controls type substitution during serialization and deserialization. The used with this . - to generate instances for objects. - + to generate instances for objects. + ]]> @@ -525,11 +522,11 @@ Gets or sets the into which the SOAP top object is deserialized. The into which the SOAP top object is deserialized. - diff --git a/xml/System.Runtime.Serialization/DataContractAttribute.xml b/xml/System.Runtime.Serialization/DataContractAttribute.xml index e8a52c6dce7..e9c0a7da143 100644 --- a/xml/System.Runtime.Serialization/DataContractAttribute.xml +++ b/xml/System.Runtime.Serialization/DataContractAttribute.xml @@ -55,53 +55,15 @@ Specifies that the type defines or implements a data contract and is serializable by a serializer, such as the . To make their type serializable, type authors must define a data contract for their type. - - attribute to types (classes, structures, or enumerations) that are used in serialization and deserialization operations by the . If you send or receive messages by using the Windows Communication Foundation (WCF) infrastructure, you should also apply the to any classes that hold and manipulate data sent in messages. For more information about data contracts, see [Using Data Contracts](/dotnet/framework/wcf/feature-details/using-data-contracts). - - You must also apply the to any field, property, or event that holds values you want to serialize. By applying the , you explicitly enable the to serialize and deserialize the data. - -> [!CAUTION] -> You can apply the to private fields. Be aware that the data returned by the field (even if it is private) is serialized and deserialized, and thus can be viewed or intercepted by a malicious user or process. - - For more information about data contracts, see the topics listed in [Using Data Contracts](/dotnet/framework/wcf/feature-details/using-data-contracts). - -## Data Contracts - A *data contract* is an abstract description of a set of fields with a name and data type for each field. The data contract exists outside of any single implementation to allow services on different platforms to interoperate. As long as the data passed between the services conforms to the same contract, all the services can process the data. This processing is also known as a *loosely coupled system*. A data contract is also similar to an interface in that the contract specifies how data must be delivered so that it can be processed by an application. For example, the data contract may call for a data type named "Person" that has two text fields, named "FirstName" and "LastName". To create a data contract, apply the to the class and apply the to any fields or properties that must be serialized. When serialized, the data conforms to the data contract that is implicitly built into the type. - -> [!NOTE] -> A data contract differs significantly from an actual interface in its inheritance behavior. Interfaces are inherited by any derived types. When you apply the to a base class, the derived types do not inherit the attribute or the behavior. However, if a derived type has a data contract, the data members of the base class are serialized. However, you must apply the to new members in a derived class to make them serializable. - -## XML Schema Documents and the SvcUtil Tool - If you are exchanging data with other services, you must describe the data contract. For the current version of the , an XML schema can be used to define data contracts. (Other forms of metadata/description could be used for the same purpose.) To create an XML schema from your application, use the [ServiceModel Metadata Utility Tool (Svcutil.exe)](/dotnet/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe) with the **/dconly** command line option. When the input to the tool is an assembly, by default, the tool generates a set of XML schemas that define all the data contract types found in that assembly. Conversely, you can also use the Svcutil.exe tool to create Visual Basic or C# class definitions that conform to the requirements of XML schemas that use constructs that can be expressed by data contracts. In this case, the **/dconly** command line option is not required. - - If the input to the Svcutil.exe tool is an XML schema, by default, the tool creates a set of classes. If you examine those classes, you find that the has been applied. You can use those classes to create a new application to process data that must be exchanged with other services. - - You can also run the tool against an endpoint that returns a Web Services Description Language (WSDL) document to automatically generate the code and configuration to create an Windows Communication Foundation (WCF) client. The generated code includes types that are marked with the . - -## Reusing Existing Types - A data contract has two basic requirements: a stable name and a list of members. The stable name consists of the namespace uniform resource identifier (URI) and the local name of the contract. By default, when you apply the to a class, it uses the class name as the local name and the class's namespace (prefixed with `"http://schemas.datacontract.org/2004/07/"`) as the namespace URI. You can override the defaults by setting the and properties. You can also change the namespace by applying the to the namespace. Use this capability when you have an existing type that processes data exactly as you require but has a different namespace and class name from the data contract. By overriding the default values, you can reuse your existing type and have the serialized data conform to the data contract. - -> [!NOTE] -> In any code, you can use the word `DataContract` instead of the longer . - -## Versioning - A data contract can also accommodate later versions of itself. That is, when a later version of the contract includes extra data, that data is stored and returned to a sender untouched. To do this, implement the interface. - - For more information about versioning, see [Data Contract Versioning](/dotnet/framework/wcf/feature-details/data-contract-versioning). - - - -## Examples - The following example serializes and deserializes a class named `Person` to which the has been applied. Note that the and properties have been set to values that override the default settings. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/datacontractattribute/cs/overview.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractattribute/vb/overview.vb" id="Snippet1"::: - - ]]> - + For more information about this API, see Supplemental API remarks for DataContractAttribute. + + has been applied. Note that the and properties have been set to values that override the default settings. + +:::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/datacontractattribute/cs/overview.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractattribute/vb/overview.vb" id="Snippet1"::: + ]]> + @@ -266,11 +228,11 @@ to keep object reference data using standard XML; otherwise, . The default is . - to insert XML constructs that preserve object reference information. - + to insert XML constructs that preserve object reference information. + ]]> @@ -355,15 +317,15 @@ Gets or sets the name of the data contract for the type. The local name of a data contract. The default is the name of the class that the attribute is applied to. - property is used to give a name to a data contract, which is the name of the type in XML schema. For more information, see [Data Contract Names](/dotnet/framework/wcf/feature-details/data-contract-names). - - By default, the name of a data contract is the name of the type that the is applied to. However, there may be reasons to change this default name. One reason is to allow an existing type to process data that must conform to an existing data contract. For example, there exists a type named `Person` but the data contract, embodied in an XML schema, requires that the name be `Customer`. The contract can be satisfied by setting the property value to `Customer`. - - A second reason is to allow the generation of names that are invalid as type names. For example, if a data contract demands a name that is not allowable as a type name, set the property value to that disallowed name. For instance, the string "$value" is disallowed as a type name but is allowed as a property value. - + property is used to give a name to a data contract, which is the name of the type in XML schema. For more information, see [Data Contract Names](/dotnet/framework/wcf/feature-details/data-contract-names). + + By default, the name of a data contract is the name of the type that the is applied to. However, there may be reasons to change this default name. One reason is to allow an existing type to process data that must conform to an existing data contract. For example, there exists a type named `Person` but the data contract, embodied in an XML schema, requires that the name be `Customer`. The contract can be satisfied by setting the property value to `Customer`. + + A second reason is to allow the generation of names that are invalid as type names. For example, if a data contract demands a name that is not allowable as a type name, set the property value to that disallowed name. For instance, the string "$value" is disallowed as a type name but is allowed as a property value. + ]]> @@ -407,14 +369,14 @@ Gets or sets the namespace for the data contract for the type. The namespace of the contract. - [!TIP] -> For the data to be successfully transmitted, the name of the data in a data contract must be the same in both the client and the server. Visual Basic projects, by default, add a prefix to the namespace defined in each file (called the "root namespace," named after the project). Adding this prefix causes the client and server namespaces to be different for the same type. The solution is to set the property to "", or to explicitly set the data contract namespace in this property. - +> For the data to be successfully transmitted, the name of the data in a data contract must be the same in both the client and the server. Visual Basic projects, by default, add a prefix to the namespace defined in each file (called the "root namespace," named after the project). Adding this prefix causes the client and server namespaces to be different for the same type. The solution is to set the property to "", or to explicitly set the data contract namespace in this property. + ]]> diff --git a/xml/System.Runtime.Serialization/DataContractSerializer.xml b/xml/System.Runtime.Serialization/DataContractSerializer.xml index 2a43eb05609..72fb6d85090 100644 --- a/xml/System.Runtime.Serialization/DataContractSerializer.xml +++ b/xml/System.Runtime.Serialization/DataContractSerializer.xml @@ -51,58 +51,7 @@ Serializes and deserializes an instance of a type into an XML stream or document using a supplied data contract. This class cannot be inherited. - - class to serialize and deserialize instances of a type into an XML stream or document. For example, you can create a type named `Person` with properties that contain essential data, such as a name and address. You can then create and manipulate an instance of the `Person` class and write all of its property values in an XML document for later retrieval, or in an XML stream for immediate transport. Most important, the is used to serialize and deserialize data sent in Windows Communication Foundation (WCF) messages. Apply the attribute to classes, and the attribute to class members to specify properties and fields that are serialized. - - For a list of types that can be serialized, see [Types Supported by the Data Contract Serializer](/dotnet/framework/wcf/feature-details/types-supported-by-the-data-contract-serializer). - - To use the , first create an instance of a class and an object appropriate to writing or reading the format; for example, an instance of the . Then call the method to persist the data. To retrieve data, create an object appropriate to reading the data format (such as an for an XML document) and call the method. - - For more information about using the , see [Serialization and Deserialization](/dotnet/framework/wcf/feature-details/serialization-and-deserialization). - - You can set the type of a data contract serializer using the [<dataContractSerializer>](/dotnet/framework/configure-apps/file-schema/wcf/datacontractserializer-element) element in a client application configuration file. - -## Preparing Classes for Serialization or Deserialization - The is used in combination with the and classes. To prepare a class for serialization, apply the to the class. For each member of the class that returns data that you want to serialize, apply the . You can serialize fields and properties, regardless of accessibility: private, protected, internal, protected internal, or public. - - For example, your schema specifies a `Customer` with an `ID` property, but you already have an existing application that uses a type named `Person` with a `Name` property. To create a type that conforms to the contract, first apply the to the class. Then apply the to every field or property that you want to serialize. - -> [!NOTE] -> You can apply the to both private and public members. - - The final format of the XML need not be text. Instead, the writes the data as an XML infoset, which allows you to write the data to any format recognized by the and . It is recommended that you use the and classes to read and write, because both are optimized to work with the . - - If you are creating a class that has fields or properties that must be populated before the serialization or deserialization occurs, use callback attributes, as described in [Version-Tolerant Serialization Callbacks](/dotnet/framework/wcf/feature-details/version-tolerant-serialization-callbacks). - -## Adding to the Collection of Known Types - When serializing or deserializing an object, it is required that the type is "known" to the . Begin by creating an instance of a class that implements (such as ) and adding the known types to the collection. Then create an instance of the using one of the overloads that takes the (for example, . - -> [!NOTE] -> Unlike other primitive types, the structure is not a known type by default, so it must be manually added to the list of known types (see [Data Contract Known Types](/dotnet/framework/wcf/feature-details/data-contract-known-types)). - -## Forward Compatibility - The understands data contracts that have been designed to be compatible with future versions of the contract. Such types implement the interface. The interface features the property that returns an object. For more information, see [Forward-Compatible Data Contracts](/dotnet/framework/wcf/feature-details/forward-compatible-data-contracts). - -## Running under Partial Trust - When instantiating the target object during deserialization, the does not call the constructor of the target object. If you author a *[DataContract]* type that is accessible from partial trust (that is, it is public and in an assembly that has the `AllowPartiallyTrustedCallers` attribute applied) and that performs some security-related actions, you must be aware that the constructor is not called. In particular, the following techniques do not work: - -- If you try to restrict partial trust access by making the constructor internal or private, or by adding a `LinkDemand` to the constructor -- neither of these have any effect during deserialization under partial trust. - -- If you code the class that assumes the constructor has run, the class may get into an invalid internal state that is exploitable. - - - -## Examples - The following example code shows a type named `Person` that is serialized by the . The attribute is applied to the class, and the is applied to members to instruct the what to serialize. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/datacontractserializer/cs/source.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractserializer/vb/source.vb" id="Snippet0"::: - - ]]> - + For more information about this API, see Supplemental API remarks for DataContractSerializer. Instances of this class are thread safe except when the instance is used with an implementation of the or . @@ -161,14 +110,14 @@ The type of the instances that are serialized or deserialized. Initializes a new instance of the class to serialize or deserialize an object of the specified type. - that specifies the type to serialize or deserialize. - + that specifies the type to serialize or deserialize. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/datacontractserializer/cs/source.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractserializer/vb/source.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractserializer/vb/source.vb" id="Snippet8"::: + ]]> @@ -221,14 +170,14 @@ An of that contains the types that may be present in the object graph. Initializes a new instance of the class to serialize or deserialize an object of the specified type, and a collection of known types that may be present in the object graph. - that specifies the type to serialize or deserialize and a collection of known types that can be used in the object graph. - + that specifies the type to serialize or deserialize and a collection of known types that can be used in the object graph. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/datacontractserializer/cs/source.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractserializer/vb/source.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractserializer/vb/source.vb" id="Snippet9"::: + ]]> @@ -326,14 +275,14 @@ The namespace of the XML element that encloses the content to serialize or deserialize. Initializes a new instance of the class to serialize or deserialize an object of the specified type using the supplied XML root element and namespace. - that specifies the type to serialize or deserialize as well as the XML name and namespace to read from or write to the XML document. - + that specifies the type to serialize or deserialize as well as the XML name and namespace to read from or write to the XML document. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/datacontractserializer/cs/source.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractserializer/vb/source.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractserializer/vb/source.vb" id="Snippet10"::: + ]]> @@ -380,14 +329,14 @@ An that contains the namespace of the root element. Initializes a new instance of the class to serialize or deserialize an object of the specified type using the XML root element and namespace specified through the parameters of type . - that specifies the type to serialize or deserialize as well as the XML name and namespace (as objects) to read from or write to the XML document. - + that specifies the type to serialize or deserialize as well as the XML name and namespace (as objects) to read from or write to the XML document. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/datacontractserializer/cs/source.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractserializer/vb/source.vb" id="Snippet11"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractserializer/vb/source.vb" id="Snippet11"::: + ]]> @@ -444,14 +393,14 @@ An of that contains the types that may be present in the object graph. Initializes a new instance of the class to serialize or deserialize an object of the specified type. This method also specifies the root XML element and namespace in two string parameters as well as a list of known types that may be present in the object graph. - that specifies the type to serialize or deserialize as well as the XML name and namespace to read from or write to the XML document. The code also creates an instance of a to contain the known types used during serialization or deserialization. - + that specifies the type to serialize or deserialize as well as the XML name and namespace to read from or write to the XML document. The code also creates an instance of a to contain the known types used during serialization or deserialization. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/datacontractserializer/cs/source.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractserializer/vb/source.vb" id="Snippet12"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractserializer/vb/source.vb" id="Snippet12"::: + ]]> @@ -510,14 +459,14 @@ A of that contains the known types that may be present in the object graph. Initializes a new instance of the class to serialize or deserialize an object of the specified type. This method also specifies the root XML element and namespace in two parameters as well as a list of known types that may be present in the object graph. - that specifies the type to serialize or deserialize as well as the XML name and namespace (as objects) to read from or write to the XML document. The code also creates an instance of a to contain the known types used during serialization or deserialization. - + that specifies the type to serialize or deserialize as well as the XML name and namespace (as objects) to read from or write to the XML document. The code also creates an instance of a to contain the known types used during serialization or deserialization. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/datacontractserializer/cs/source.cs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractserializer/vb/source.vb" id="Snippet13"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractserializer/vb/source.vb" id="Snippet13"::: + ]]> @@ -563,14 +512,14 @@ An implementation of the to customize the serialization process. Initializes a new instance of the class to serialize or deserialize an object of the specified type. This method also specifies a list of known types that may be present in the object graph, the maximum number of graph items to serialize, parameters to ignore unexpected data, whether to use non-standard XML constructs to preserve object reference data in the graph, and a surrogate for custom serialization. - that specifies the type to serialize or deserialize and an instance of a to contain the known types used during serialization or deserialization. The code also sets the `ignoreExtensionDataObject` and `preserveObjectReferences` parameters to `true`, and specifies an implementation of the interface to handle legacy types (types that do not have the attribute applied). For more information, see the documentation. - + that specifies the type to serialize or deserialize and an instance of a to contain the known types used during serialization or deserialization. The code also sets the `ignoreExtensionDataObject` and `preserveObjectReferences` parameters to `true`, and specifies an implementation of the interface to handle legacy types (types that do not have the attribute applied). For more information, see the documentation. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/datacontractserializer/cs/source.cs" id="Snippet14"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractserializer/vb/source.vb" id="Snippet14"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractserializer/vb/source.vb" id="Snippet14"::: + ]]> The number of items exceeds the maximum value. @@ -623,13 +572,13 @@ An implementation of the to map declarations to data contract types. Initializes a new instance of the class to serialize or deserialize an object of the specified type. This method also specifies a list of known types that may be present in the object graph, the maximum number of graph items to serialize, parameters to ignore unexpected data, whether to use non-standard XML constructs to preserve object reference data in the graph, a surrogate for custom serialization, and an alternative for mapping declarations at run time. - [!WARNING] -> This method is not available in Windows Store apps. - +> This method is not available in Windows Store apps. + ]]> @@ -677,14 +626,14 @@ An implementation of the to customize the serialization process. Initializes a new instance of the class to serialize or deserialize an object of the specified type. This method also specifies a list of known types that may be present in the object graph, the maximum number of graph items to serialize, parameters to ignore unexpected data, whether to use non-standard XML constructs to preserve object reference data in the graph, a surrogate for custom serialization, and the XML element and namespace that contain the content. - that specifies the type to serialize or deserialize, the root XML element and namespace, and an instance of a that contains the types used during deserialization. The code also sets the `ignoreExtensionDataObject` and `preserveObjectReferences` parameters to `true`, and specifies an implementation of the interface to handle legacy types (types that do not have the attribute applied). For more information, see the documentation. - + that specifies the type to serialize or deserialize, the root XML element and namespace, and an instance of a that contains the types used during deserialization. The code also sets the `ignoreExtensionDataObject` and `preserveObjectReferences` parameters to `true`, and specifies an implementation of the interface to handle legacy types (types that do not have the attribute applied). For more information, see the documentation. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/datacontractserializer/cs/source.cs" id="Snippet15"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractserializer/vb/source.vb" id="Snippet15"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractserializer/vb/source.vb" id="Snippet15"::: + ]]> The number of items exceeds the maximum value. @@ -740,14 +689,14 @@ An implementation of the to customize the serialization process. Initializes a new instance of the class to serialize or deserialize an object of the specified type. This method also specifies a list of known types that may be present in the object graph, the maximum number of graph items to serialize, parameters to ignore unexpected data, whether to use non-standard XML constructs to preserve object reference data in the graph, a surrogate for custom serialization, and parameters of that specify the XML element and namespace that contain the content. - that specifies the type to serialize or deserialize, the root XML element and namespace (as parameters), and an instance of a that contains the types used during deserialization. The code also sets the `ignoreExtensionDataObject` and `preserveObjectReferences` parameters to `true`, and specifies an implementation of the interface to handle legacy types (types that do not have the attribute applied). For more information, see the documentation. - + that specifies the type to serialize or deserialize, the root XML element and namespace (as parameters), and an instance of a that contains the types used during deserialization. The code also sets the `ignoreExtensionDataObject` and `preserveObjectReferences` parameters to `true`, and specifies an implementation of the interface to handle legacy types (types that do not have the attribute applied). For more information, see the documentation. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/datacontractserializer/cs/source.cs" id="Snippet16"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractserializer/vb/source.vb" id="Snippet16"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractserializer/vb/source.vb" id="Snippet16"::: + ]]> The number of items exceeds the maximum value. @@ -897,11 +846,11 @@ Gets the component used to dynamically map declarations to known contract types. An implementation of the class. - is set using a constructor. - + is set using a constructor. + ]]> @@ -933,11 +882,11 @@ Gets a surrogate type that can extend the serialization or deserialization process. An implementation of the class. - can be used to customize how instances of a type are serialized and deserialized. For example, it can be used to enable the serialization of legacy types that are not serializable, that is, types to which the attribute has not been applied. - + can be used to customize how instances of a type are serialized and deserialized. For example, it can be used to enable the serialization of legacy types that are not serializable, that is, types to which the attribute has not been applied. + ]]> @@ -982,11 +931,11 @@ to omit the extension data; otherwise, . - property is used when the class to which a has been applied also implements the interface. In this case, the data added in a future version of the contract is ignored on read and write. For more information, see [Forward-Compatible Data Contracts](/dotnet/framework/wcf/feature-details/forward-compatible-data-contracts). - + property is used when the class to which a has been applied also implements the interface. In this case, the data added in a future version of the contract is ignored on read and write. For more information, see [Forward-Compatible Data Contracts](/dotnet/framework/wcf/feature-details/forward-compatible-data-contracts). + ]]> @@ -1059,19 +1008,19 @@ if the reader is at the start element of the stream to read; otherwise, . - determines whether it can read an object by checking that it is positioned on an XML element. It also examines the name and namespace of the XML element that the reader is positioned at and compares the values to the expected name and namespace. The expected name and namespace can be set with the following: the data contract name and namespace of the type passed into the constructor, or the `rootName` and `rootNamespace` values passed into the constructor (if present). - - - -## Examples - The following example uses the property to determine whether the start of the data has been found. - + determines whether it can read an object by checking that it is positioned on an XML element. It also examines the name and namespace of the XML element that the reader is positioned at and compares the values to the expected name and namespace. The expected name and namespace can be set with the following: the data contract name and namespace of the type passed into the constructor, or the `rootName` and `rootNamespace` values passed into the constructor (if present). + + + +## Examples + The following example uses the property to determine whether the start of the data has been found. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/datacontractserializer/cs/source.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractserializer/vb/source.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractserializer/vb/source.vb" id="Snippet6"::: + ]]> @@ -1169,11 +1118,11 @@ Gets a collection of types that may be present in the object graph serialized using this instance of the . A that contains the expected types passed in as known types to the constructor. - property provides the set of known types that are used for serialization and deserialization. For example, if an instance of the class contains instances of a `Person` class, add the `Person` type to an instance of the class and use the instance to construct an instance of the . If you know of other types to add to the , then add those types to the collection. - + property provides the set of known types that are used for serialization and deserialization. For example, if an instance of the class contains instances of a `Person` class, add the `Person` type to an instance of the class and use the instance to construct an instance of the . If you know of other types to add to the , then add those types to the collection. + ]]> @@ -1217,23 +1166,23 @@ Gets the maximum number of items in an object graph to serialize or deserialize. The maximum number of items to serialize or deserialize. The default is Int32.MaxValue. - -``` - - To set this property imperatively in code find the operation description of the service, then get the operation behavior, finally set the property as shown in the following code. - -``` -OperationDescription operation = host.Description.Endpoints[0].Contract.Operations.Find("MyOperationName");operation.Behaviors.Find().MaxItemsInObjectGraph = 3; -``` - - The property specifies the maximum number of objects that the serializer serializes or deserializes in a single method call. (The method always reads one root object, but this object may have other objects in its data members. Those objects may have other objects, and so on.) The default is . Note that when serializing or deserializing arrays, every array entry counts as a separate object. Also, note that some objects may have a large memory representation and so this quota alone may not be sufficient to prevent Denial of Service attacks. For more information, see [Security Considerations for Data](/dotnet/framework/wcf/feature-details/security-considerations-for-data). If you need to increase this quota beyond its default value, it is important to do so both on the sending (serializing) and receiving (deserializing) sides. It applies both when reading and writing data. - + +``` + + To set this property imperatively in code find the operation description of the service, then get the operation behavior, finally set the property as shown in the following code. + +``` +OperationDescription operation = host.Description.Endpoints[0].Contract.Operations.Find("MyOperationName");operation.Behaviors.Find().MaxItemsInObjectGraph = 3; +``` + + The property specifies the maximum number of objects that the serializer serializes or deserializes in a single method call. (The method always reads one root object, but this object may have other objects in its data members. Those objects may have other objects, and so on.) The default is . Note that when serializing or deserializing arrays, every array entry counts as a separate object. Also, note that some objects may have a large memory representation and so this quota alone may not be sufficient to prevent Denial of Service attacks. For more information, see [Security Considerations for Data](/dotnet/framework/wcf/feature-details/security-considerations-for-data). If you need to increase this quota beyond its default value, it is important to do so both on the sending (serializing) and receiving (deserializing) sides. It applies both when reading and writing data. + ]]> The number of items exceeds the maximum value. @@ -1401,14 +1350,14 @@ OperationDescription operation = host.Description.Endpoints[0].Contract.Operatio Reads the XML stream with an and returns the deserialized object, and also specifies whether a check is made to verify the object name before reading its value. The deserialized object. - The parameter is set to , and the element name and namespace do not correspond to the values set in the constructor. @@ -1642,14 +1591,14 @@ OperationDescription operation = host.Description.Endpoints[0].Contract.Operatio The used to write the stream. Writes the closing XML element using an . - , and an instance of the class. The example uses the , , and methods to write the object data into the XML document. Making these calls is equivalent to making a single call of the method. For example, a user might make the calls separately to insert additional XML attributes into the XML after calling the method. - + , and an instance of the class. The example uses the , , and methods to write the object data into the XML document. Making these calls is equivalent to making a single call of the method. For example, a user might make the calls separately to insert additional XML attributes into the XML after calling the method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/datacontractserializer/cs/source.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractserializer/vb/source.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractserializer/vb/source.vb" id="Snippet7"::: + ]]> The type being serialized does not conform to data contract rules. For example, the attribute has not been applied to the type. @@ -1923,14 +1872,14 @@ OperationDescription operation = host.Description.Endpoints[0].Contract.Operatio The object to write to the stream. Writes the XML content using an . - , and an instance of the class. The example uses the , , and methods to write the object data into the XML document. - + , and an instance of the class. The example uses the , , and methods to write the object data into the XML document. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/datacontractserializer/cs/source.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractserializer/vb/source.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractserializer/vb/source.vb" id="Snippet7"::: + ]]> The type being serialized does not conform to data contract rules. For example, the attribute has not been applied to the type. @@ -2073,14 +2022,14 @@ OperationDescription operation = host.Description.Endpoints[0].Contract.Operatio The object to write. Writes the opening XML element using an . - , and an instance of the class. The example uses the , , and methods to write the object data into the XML document. - + , and an instance of the class. The example uses the , , and methods to write the object data into the XML document. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/datacontractserializer/cs/source.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractserializer/vb/source.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datacontractserializer/vb/source.vb" id="Snippet7"::: + ]]> diff --git a/xml/System.Runtime.Serialization/IExtensibleDataObject.xml b/xml/System.Runtime.Serialization/IExtensibleDataObject.xml index 22448efd888..e5034da5b40 100644 --- a/xml/System.Runtime.Serialization/IExtensibleDataObject.xml +++ b/xml/System.Runtime.Serialization/IExtensibleDataObject.xml @@ -42,36 +42,15 @@ Provides a data structure to store extra data encountered by the during deserialization of a type marked with the attribute. - - interface provides a single property that sets or returns a structure used to store data that is external to a data contract. The extra data is stored in an instance of the class and accessed through the property. In a roundtrip operation where data is received, processed, and sent back, the extra data is sent back to the original sender intact. This is useful to store data received from future versions of the contract. If you do not implement the interface, any extra data is ignored and discarded during a roundtrip operation. - -### To use this versioning feature - -1. Implement the interface in a class. - -2. Add the property to your type. - -3. Add a private member of type to the class. - -4. Implement get and set methods for the property using the new private member. - -5. Apply the attribute to the class. Set the and properties to appropriate values if necessary. - - For more information about versioning of types, see [Data Contract Versioning](/dotnet/framework/wcf/feature-details/data-contract-versioning). For information about creating forward-compatible data contracts, see [Forward-Compatible Data Contracts](/dotnet/framework/wcf/feature-details/forward-compatible-data-contracts). For more information about data contracts, see [Using Data Contracts](/dotnet/framework/wcf/feature-details/using-data-contracts). - - - -## Examples - The following code shows an instance of a type (`PersonVersion2`) that is the second version of a serializable type (`Person`). The second version contains extra data (`ID` field) that is not present in the first version. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/iunknownserializationdata/cs/iunknownserialization.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/iunknownserializationdata/vb/iunknownserialization.vb" id="Snippet1"::: - - ]]> - + For more information about this API, see Supplemental API remarks for IExtensibleDataObject. + + + Data Contract Versioning Using Data Contracts diff --git a/xml/System.Runtime.Serialization/NetDataContractSerializer.xml b/xml/System.Runtime.Serialization/NetDataContractSerializer.xml index 3a5f4949a74..73452ed42ec 100644 --- a/xml/System.Runtime.Serialization/NetDataContractSerializer.xml +++ b/xml/System.Runtime.Serialization/NetDataContractSerializer.xml @@ -22,35 +22,35 @@ Serializes and deserializes an instance of a type into XML stream or document using the supplied .NET Framework types. This class cannot be inherited. - is insecure. For more information, see the [BinaryFormatter security guide](/dotnet/standard/serialization/binaryformatter-security-guide). - -## Remarks - The differs from the in one important way: the includes CLR type information in the serialized XML, whereas the does not. Therefore, the can be used only if both the serializing and deserializing ends share the same CLR types. - - The serializer can serialize types to which either the or attribute has been applied. It also serializes types that implement . - - For more information about serialization, see [Serialization and Deserialization](/dotnet/framework/wcf/feature-details/serialization-and-deserialization). - -## Incompatibility with XElement - The class is used to write XML. However, the `NetDataContractSerializer` cannot serialize an instance of the type. The following code, therefore, fails with the exception: "Root type 'System.Xml.Linq.XElement' is not supported at the top level by NetDataContractSerializer since it is IXmlSerializable with `IsAny`=`true` and must write all its contents including the root element." - + +## Remarks + The differs from the in one important way: the includes CLR type information in the serialized XML, whereas the does not. Therefore, the can be used only if both the serializing and deserializing ends share the same CLR types. + + The serializer can serialize types to which either the or attribute has been applied. It also serializes types that implement . + + For more information about serialization, see [Serialization and Deserialization](/dotnet/framework/wcf/feature-details/serialization-and-deserialization). + +## Incompatibility with XElement + The class is used to write XML. However, the `NetDataContractSerializer` cannot serialize an instance of the type. The following code, therefore, fails with the exception: "Root type 'System.Xml.Linq.XElement' is not supported at the top level by NetDataContractSerializer since it is IXmlSerializable with `IsAny`=`true` and must write all its contents including the root element." + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/netdatacontractserializer/cs/source.cs" id="Snippet15"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/netdatacontractserializer/vb/source.vb" id="Snippet15"::: - - However, if an `XElement` is used as the type of a field or property of a class, the data contained by the field or property is serialized. This is because as a member of a class, the data is not the top level of the class. - - - -## Examples - The following example code shows a type named `Person` that is serialized by the . The attribute is applied to the class, and the is applied to members (including a private member) to instruct the what to serialize. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/netdatacontractserializer/vb/source.vb" id="Snippet15"::: + + However, if an `XElement` is used as the type of a field or property of a class, the data contained by the field or property is serialized. This is because as a member of a class, the data is not the top level of the class. + + + +## Examples + The following example code shows a type named `Person` that is serialized by the . The attribute is applied to the class, and the is applied to members (including a private member) to instruct the what to serialize. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/netdatacontractserializer/cs/source.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/netdatacontractserializer/vb/source.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/netdatacontractserializer/vb/source.vb" id="Snippet0"::: + ]]> @@ -86,12 +86,12 @@ Initializes a new instance of the class. - @@ -117,19 +117,19 @@ A that contains context data. Initializes a new instance of the class with the supplied streaming context data. - class allows you to pass in user-specific context data to use while reading and writing objects. - - - -## Examples - The following example creates an instance of the using a . - + class allows you to pass in user-specific context data to use while reading and writing objects. + + + +## Examples + The following example creates an instance of the using a . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/netdatacontractserializer/cs/source.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/netdatacontractserializer/vb/source.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/netdatacontractserializer/vb/source.vb" id="Snippet9"::: + ]]> @@ -157,14 +157,14 @@ The namespace of the XML element that encloses the content to serialize or deserialize. Initializes a new instance of the class with the supplied XML root element and namespace. - specifying the XML root element and namespace it will expect when deserializing an object. - + specifying the XML root element and namespace it will expect when deserializing an object. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/netdatacontractserializer/cs/source.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/netdatacontractserializer/vb/source.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/netdatacontractserializer/vb/source.vb" id="Snippet10"::: + ]]> @@ -192,19 +192,19 @@ An that contains the namespace of the XML element that encloses the content to serialize or deserialize. Initializes a new instance of the class with two parameters of type that contain the root element and namespace used to specify the content. - can be used to optimize performance when the same set of strings is used across object instances. - - - -## Examples - The following example creates an instance of the specifying the XML root element and namespace (as arguments) it will expect when deserializing an object. - + can be used to optimize performance when the same set of strings is used across object instances. + + + +## Examples + The following example creates an instance of the specifying the XML root element and namespace (as arguments) it will expect when deserializing an object. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/netdatacontractserializer/cs/source.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/netdatacontractserializer/vb/source.vb" id="Snippet11"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/netdatacontractserializer/vb/source.vb" id="Snippet11"::: + ]]> @@ -239,19 +239,19 @@ An implementation of the . Initializes a new instance of the class with the supplied context data; in addition, specifies the maximum number of items in the object to be serialized, and parameters to specify whether extra data is ignored, the assembly loading method, and a surrogate selector. - interface is implemented in the class that is being serialized or deserialized. - - - -## Examples - The following example creates an instance of the using a . The code also sets the `ignoreExtensionDataObject`, and specifies an implementation of the `ISurrogateSelector` interface to handle to assist the serializer when selecting a surrogate (for deserializing legacy types). - + interface is implemented in the class that is being serialized or deserialized. + + + +## Examples + The following example creates an instance of the using a . The code also sets the `ignoreExtensionDataObject`, and specifies an implementation of the `ISurrogateSelector` interface to handle to assist the serializer when selecting a surrogate (for deserializing legacy types). + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/netdatacontractserializer/cs/source.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/netdatacontractserializer/vb/source.vb" id="Snippet12"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/netdatacontractserializer/vb/source.vb" id="Snippet12"::: + ]]> @@ -292,19 +292,19 @@ An implementation of the to handle the legacy type. Initializes a new instance of the class with the supplied context data and root name and namespace; in addition, specifies the maximum number of items in the object to be serialized, and parameters to specify whether extra data is ignored, the assembly loading method, and a surrogate selector. - interface is implemented in the class that is being serialized or deserialized. - - - -## Examples - The following example creates an instance of the specifying the XML element name and namespace to expect when deserializing. The code also sets the `ignoreExtensionDataObject`, and specifies an implementation of the interface to handle to assist the serializer when selecting a surrogate (for deserializing legacy types). - + interface is implemented in the class that is being serialized or deserialized. + + + +## Examples + The following example creates an instance of the specifying the XML element name and namespace to expect when deserializing. The code also sets the `ignoreExtensionDataObject`, and specifies an implementation of the interface to handle to assist the serializer when selecting a surrogate (for deserializing legacy types). + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/netdatacontractserializer/cs/source.cs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/netdatacontractserializer/vb/source.vb" id="Snippet13"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/netdatacontractserializer/vb/source.vb" id="Snippet13"::: + ]]> @@ -345,21 +345,21 @@ An implementation of the to handle the legacy type. Initializes a new instance of the class with the supplied context data, and root name and namespace (as parameters); in addition, specifies the maximum number of items in the object to be serialized, and parameters to specify whether extra data found is ignored, assembly loading method, and a surrogate selector. - can be used to optimize performance when the same set of strings is used across object instances. - - The `ignoreExtensionDataObject` parameter is used when the interface is implemented in the class that is being serialized or deserialized. - - - -## Examples - The following example creates an instance of the specifying the XML element name and namespace (as arguments) to expect when deserializing. The code also sets the `ignoreExtensionDataObject`, and specifies an implementation of the interface to handle to assist the serializer when selecting a surrogate (for deserializing legacy types). - + can be used to optimize performance when the same set of strings is used across object instances. + + The `ignoreExtensionDataObject` parameter is used when the interface is implemented in the class that is being serialized or deserialized. + + + +## Examples + The following example creates an instance of the specifying the XML element name and namespace (as arguments) to expect when deserializing. The code also sets the `ignoreExtensionDataObject`, and specifies an implementation of the interface to handle to assist the serializer when selecting a surrogate (for deserializing legacy types). + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/netdatacontractserializer/cs/source.cs" id="Snippet14"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/netdatacontractserializer/vb/source.vb" id="Snippet14"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/netdatacontractserializer/vb/source.vb" id="Snippet14"::: + ]]> @@ -387,11 +387,11 @@ Gets a value that specifies a method for locating and loading assemblies. A enumeration value that specifies a method for locating and loading assemblies. - or . Specifying `Simple` allows types in one version to be loaded and deserialized from an instance serialized from a different version. - + or . Specifying `Simple` allows types in one version to be loaded and deserialized from an instance serialized from a different version. + ]]> The value being set does not correspond to any of the values. @@ -421,11 +421,11 @@ Gets or sets an object that controls class loading. The used with the current formatter. - @@ -484,13 +484,13 @@ Deserializes an XML document or stream into an object. The deserialized object. - @@ -517,11 +517,11 @@ to ignore the data supplied by an extension of the type; otherwise, . - , data from a future version of a type can be stored by the . During a round trip (where an object is deserialized, altered, and serialized again), the extra data is stored and serialized again. For more information, see [Serialization and Deserialization](/dotnet/framework/wcf/feature-details/serialization-and-deserialization). - + , data from a future version of a type can be stored by the . During a round trip (where an object is deserialized, altered, and serialized again), the extra data is stored and serialized again. For more information, see [Serialization and Deserialization](/dotnet/framework/wcf/feature-details/serialization-and-deserialization). + ]]> @@ -535,11 +535,11 @@ Determines whether the reader is positioned on an object that can be deserialized. - @@ -570,13 +570,13 @@ , if the reader is at the start element of the stream to read; otherwise, . - determines whether it can read an object by examining the name and namespace of the XML element the reader is positioned at, and comparing the values to expected name and namespace. The expected name and namespace can be set with the following: the data contract name and namespace of the type passed into the constructor, or the `rootName` and `rootNamespace` values passed into the constructor (if present). - - You can set the `rootName` and `rootNamespace` in the following constructors: , , and . - + determines whether it can read an object by examining the name and namespace of the XML element the reader is positioned at, and comparing the values to expected name and namespace. The expected name and namespace can be set with the following: the data contract name and namespace of the type passed into the constructor, or the `rootName` and `rootNamespace` values passed into the constructor (if present). + + You can set the `rootName` and `rootNamespace` in the following constructors: , , and . + ]]> the is set to . @@ -632,11 +632,11 @@ Gets the maximum number of items allowed in the object to be serialized. The maximum number of items allowed in the object. The default is Int32.MaxValue. - @@ -650,10 +650,10 @@ Reads the XML stream or document and returns the deserialized object. - @@ -685,12 +685,12 @@ Reads the XML stream or document with an and returns the deserialized object. The deserialized object. - the is set to . @@ -724,15 +724,15 @@ Reads the XML stream or document with an and returns the deserialized object; also checks whether the object data conforms to the name and namespace used to create the serializer. The deserialized object. - , , and . + , , and . [!INCLUDE [untrusted-data-method-note](~/includes/untrusted-data-method-note.md)] - + ]]> the is set to . @@ -766,13 +766,13 @@ Reads the XML stream or document with an and returns the deserialized object; also checks whether the object data conforms to the name and namespace used to create the serializer. The deserialized object. - , , and . - + , , and . + [!INCLUDE [untrusted-data-method-note](~/includes/untrusted-data-method-note.md)] ]]> @@ -835,11 +835,11 @@ Gets or sets an object that assists the formatter when selecting a surrogate for serialization. An for selecting a surrogate. - , see [Data Contract Surrogates](/dotnet/framework/wcf/extending/data-contract-surrogates). - + , see [Data Contract Surrogates](/dotnet/framework/wcf/extending/data-contract-surrogates). + ]]> @@ -855,11 +855,11 @@ Writes the closing XML element using the specified writer. - , , and methods are used in succession to write the complete serialization using the pattern: write start, write content, and write end. The three methods are also called by the method. - + , , and methods are used in succession to write the complete serialization using the pattern: write start, write content, and write end. The three methods are also called by the method. + ]]> @@ -888,14 +888,14 @@ The used to write the XML document or stream. Writes the closing XML element using an . - , and an instance of the class. The example uses the , , and methods to write the object data into the XML document. - + , and an instance of the class. The example uses the , , and methods to write the object data into the XML document. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/netdatacontractserializer/cs/source.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/netdatacontractserializer/vb/source.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/netdatacontractserializer/vb/source.vb" id="Snippet5"::: + ]]> the is set to . @@ -968,11 +968,11 @@ Writes the XML content using the specified writer. - , , and methods are used in succession to write the complete serialization using the pattern: write start, write content, and write end. The three methods are also called by the method. - + , , and methods are used in succession to write the complete serialization using the pattern: write start, write content, and write end. The three methods are also called by the method. + ]]> @@ -1003,14 +1003,14 @@ The object to serialize. All child objects of this root object are automatically serialized. Writes the XML content using an . - , and an instance of the class. The example uses the , , and methods to write the object data into the XML document. - + , and an instance of the class. The example uses the , , and methods to write the object data into the XML document. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/netdatacontractserializer/cs/source.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/netdatacontractserializer/vb/source.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/netdatacontractserializer/vb/source.vb" id="Snippet5"::: + ]]> the type being serialized does not conform to data contract rules. For example, the attribute has not been applied to the type. @@ -1085,14 +1085,14 @@ The object to serialize. All child objects of this root object are automatically serialized. Writes the opening XML element using an . - , and an instance of the class. The example uses the , , and methods to write the object data into the XML document. - + , and an instance of the class. The example uses the , , and methods to write the object data into the XML document. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/netdatacontractserializer/cs/source.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/netdatacontractserializer/vb/source.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/netdatacontractserializer/vb/source.vb" id="Snippet5"::: + ]]> the type being serialized does not conform to data contract rules. For example, the attribute has not been applied to the type. diff --git a/xml/System.Runtime.Serialization/SerializationBinder.xml b/xml/System.Runtime.Serialization/SerializationBinder.xml index deac7eb13f1..b76cff9c7b6 100644 --- a/xml/System.Runtime.Serialization/SerializationBinder.xml +++ b/xml/System.Runtime.Serialization/SerializationBinder.xml @@ -50,25 +50,7 @@ Allows users to control class loading and mandate what class to load. - - can not be used for security. There might be some security exploits when you are trying to deserialize some data from an untrusted source. The binder gives you an opportunity to inspect what types are being loaded in your application domain, but this doesn't guarantee an exploit is not possible. For more information see the [BinaryFormatter security guide](/dotnet/standard/serialization/binaryformatter-security-guide). You can then either maintain list of denied types or a list of allowed types and restrict which types are being loaded and instantiated. In addition, be mindful of what information is being put out on the wire. You may want to use transport or message security when sending type names or other data on the network. - -> [!WARNING] -> Only use if you are completely sure of what information is being serialized. Malicious types can cause unexpected behavior. - - This is an abstract base class. All binders extend this class. - - ]]> - + For more information about this API, see System.Runtime.Serialization.SerializationBinder. When you inherit from , you must override the following member: . @@ -218,11 +200,11 @@ When overridden in a derived class, controls the binding of a serialized object to a type. The type of the object the formatter creates a new instance of. - diff --git a/xml/System.Runtime.Serialization/XsdDataContractExporter.xml b/xml/System.Runtime.Serialization/XsdDataContractExporter.xml index c7ad908ca36..22aa4abea8f 100644 --- a/xml/System.Runtime.Serialization/XsdDataContractExporter.xml +++ b/xml/System.Runtime.Serialization/XsdDataContractExporter.xml @@ -48,43 +48,15 @@ Allows the transformation of a set of .NET types that are used in data contracts into an XML schema file (.xsd). - - class when you have created a Web service that incorporates data represented by common language runtime (CLR) types and when you need to export XML schemas for each type to be consumed by other Web services. That is, transforms a set of CLR types into XML schemas. (For more information about the types that can be used, see [Types Supported by the Data Contract Serializer](/dotnet/framework/wcf/feature-details/types-supported-by-the-data-contract-serializer).) The schemas can then be exposed through a Web Services Description Language (WSDL) document for use by others who need to interoperate with your service. - - Conversely, if you are creating a Web service that must interoperate with an existing Web service, use the to transform XML schemas and create the CLR types that represent the data in a selected programming language. - - The generates an object that contains the collection of schemas. Access the set of schemas through the property. - -> [!NOTE] -> To quickly generate XML schema definition (XSD) files that other Web services can consume, use the . - -## Exporting Schemas Into an XmlSchemaSet - To create an instance of the class that contains XML schema files, you should be aware of the following. - - The set of types you are exporting are recorded as an internal set of data contracts. Thus, you can call the method multiple times to add new types to the schema set without degrading performance because only the new types will be added to the set. During the operation, the existing schemas are compared to the new schemas being added. If there are conflicts, an exception will be thrown. A conflict is usually detected if two types with the same data contract name but different contracts (different members) are exported by the same instance. - -## Using the Exporter - A recommended way of using this class is as follows: - -1. Use one of the overloads to determine whether the specified type or set of types can be exported. Use one of the overloads that is appropriate to your requirements. - -2. Call the corresponding method. - -3. Retrieve the schemas from the property. - - - -## Examples - The following example creates an instance of the and calls the method. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/xsddatacontractexporter/cs/overview.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/xsddatacontractexporter/vb/overview.vb" id="Snippet0"::: - - ]]> - + For more information about this API, see Supplemental API remarks for XsdDataContractExporter. + + and calls the method. + +:::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/xsddatacontractexporter/cs/overview.cs" id="Snippet0"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/xsddatacontractexporter/vb/overview.vb" id="Snippet0"::: + ]]> + Types Supported by the Data Contract Serializer @@ -178,11 +150,11 @@ An that contains the schemas to be exported. Initializes a new instance of the class with the specified set of schemas. - to which you want to add new schemas. After you construct a with this overload, call the method to add new types to the existing set. - + to which you want to add new schemas. After you construct a with this overload, call the method to add new types to the existing set. + ]]> @@ -196,11 +168,11 @@ Gets a value that indicates whether a common language runtime (CLR) type (or set of types) can be exported. - @@ -362,14 +334,14 @@ if the type can be exported; otherwise, . - method before calling the method. - + method before calling the method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/xsddatacontractexporter/cs/overview.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/xsddatacontractexporter/vb/overview.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/xsddatacontractexporter/vb/overview.vb" id="Snippet1"::: + ]]> @@ -383,13 +355,13 @@ Transforms the common language runtime (CLR) type, or set of types, into a set of XML schemas. - overloads to determine whether the specified type or set of types can be exported. - - After calling the method, retrieve the schemas from the property. - + overloads to determine whether the specified type or set of types can be exported. + + After calling the method, retrieve the schemas from the property. + ]]> @@ -549,11 +521,11 @@ The to transform into an XML schema. Transforms the specified .NET Framework type into an XML schema definition language (XSD) schema. - to determine whether the type can be exported. After calling the method, the schema can be retrieved through the property. - + to determine whether the type can be exported. After calling the method, the schema can be retrieved through the property. + ]]> The argument is . @@ -664,11 +636,11 @@ Returns the XML schema type for the specified type. An that contains the XML schema. - . This method returns the definition for such types. The types for which the method returns a valid name, this method returns `null`. - + . This method returns the definition for such types. The types for which the method returns a valid name, this method returns `null`. + ]]> The argument is . diff --git a/xml/System.Runtime.Versioning/ComponentGuaranteesAttribute.xml b/xml/System.Runtime.Versioning/ComponentGuaranteesAttribute.xml index 0f45d18089e..8ef58d6e2e5 100644 --- a/xml/System.Runtime.Versioning/ComponentGuaranteesAttribute.xml +++ b/xml/System.Runtime.Versioning/ComponentGuaranteesAttribute.xml @@ -50,134 +50,7 @@ Defines the compatibility guarantee of a component, type, or type member that may span multiple versions. - - is used by developers of components and class libraries to indicate the level of compatibility that consumers of their libraries can expect across multiple versions. It indicates the level of guarantee that a future version of the library or component will not break an existing client. Clients can then use the as an aid in designing their own interfaces to ensure stability across versions. - -> [!NOTE] -> The common language runtime (CLR) does not use this attribute in any way. Its value lies in formally documenting the intent of the component author. Compile-time tools can also use these declarations to detect compile-time errors that would otherwise break the declared guarantee. - -## Levels of Compatibility - The supports the following levels of compatibility, which are represented by members of the enumeration: - -- No version-to-version compatibility (). The client can expect that future versions will break the existing client. For more information, see the [No Compatibility](#None) section later in this topic. - -- Side-by-side version-to-version compatibility (). The component has been tested to work when more than one version of the assembly is loaded in the same application domain. In general, future versions can break compatibility. However, when breaking changes are made, the old version is not modified but exists alongside the new version. Side-by-side execution is the expected way to make existing clients work when breaking changes are made. For more information, see the [Side-by-Side Compatibility](#SideBySide) section later in this topic. - -- Stable version-to-version compatibility (). Future versions should not break the client, and side-by-side execution should not be needed. However, if the client is inadvertently broken, it may be possible to use side-by-side execution to fix the problem. For more information, see the [Stable Compatibility](#Standard) section. - -- Exchange version-to-version compatibility (). Extraordinary care is taken to ensure that future versions will not break the client. The client should use only these types in the signature of interfaces that are used for communication with other assemblies that are deployed independently of one another. Only one version of these types is expected to be in a given application domain, which means that if a client breaks, side-by-side execution cannot fix the compatibility problem. For more information, see the [Exchange Type Compatibility](#Exchange) section. - - The following sections discuss each level of guarantee in greater detail. - - -### No Compatibility - Marking a component as indicates that the provider makes no guarantees about compatibility. Clients should avoid taking any dependencies on the exposed interfaces. This level of compatibility is useful for types that are experimental or that are publicly exposed but are intended only for components that are always updated at the same time. explicitly indicates that this component should not be used by external components. - - -### Side-by-Side Compatibility - Marking a component as indicates that the component has been tested to work when more than one version of the assembly is loaded into the same application domain. Breaking changes are allowed as long as they are made to the assembly that has the greater version number. Components that are bound to an old version of the assembly are expected to continue to bind to the old version, and other components can bind to the new version. It is also possible to update a component that is declared to be by destructively modifying the old version. - - -### Stable Compatibility - Marking a type as indicates that the type should remain stable across versions. However, it may also be possible for side-by-side versions of a stable type to exist in the same application domain. - - Stable types maintain a high binary compatibility bar. Because of this, providers should avoid making breaking changes to stable types. The following kinds of changes are acceptable: - -- Adding private instance fields to, or removing fields from, a type, as long as this does not break the serialization format. - -- Changing a non-serializable type to a serializable type. (However, a serializable type cannot be changed to a non-serializable type.) - -- Throwing new, more derived exceptions from a method. - -- Improving the performance of a method. - -- Changing the range of return values, as long as the change does not adversely affect the majority of clients. - -- Fixing serious bugs, if the business justification is high and the number of adversely affected clients is low. - - Because new versions of stable components are not expected to break existing clients, generally only one version of a stable component is needed in an application domain. However, this is not a requirement, because stable types are not used as well-known exchange types that all components agree upon. Therefore, if a new version of a stable component does inadvertently break some component, and if other components need the new version, it may be possible to fix the problem by loading both the old and new component. - - provides a stronger version compatibility guarantee than . It is a common default for multi-version components. - - can be combined with , which states that the component will not break compatibility but is tested to work when more than one version is loaded in a given application domain. - - After a type or method is marked as , it can be upgraded to . However, it cannot be downgraded to . - - -### Exchange Type Compatibility - Marking a type as provides a stronger version compatibility guarantee than , and should be applied to the most stable of all types. These types are intended to be used for interchange between independently built components across all component boundaries in both time (any version of the CLR or any version of a component or application) and space (cross-process, cross-CLR in one process, cross-application domain in one CLR). If a breaking change is made to an exchange type, it is impossible to fix the issue by loading multiple versions of the type. - - Exchange types should be changed only when a problem is very serious (such as a severe security issue) or the probability of breakage is very low (that is, if the behavior was already broken in a random way that code could not have conceivably taken a dependency on). You can make the following kinds of changes to an exchange type: - -- Add inheritance of new interface definitions. - -- Add new private methods that implement the methods of newly inherited interface definitions. - -- Add new static fields. - -- Add new static methods. - -- Add new non-virtual instance methods. - - The following are considered breaking changes and are not allowed for primitive types: - -- Changing serialization formats. Version-tolerant serialization is required. - -- Adding or removing private instance fields. This risks changing the serialization format of the type and breaking client code that uses reflection. - -- Changing the serializability of a type. A non-serializable type may not be made serializable, and vice versa. - -- Throwing different exceptions from a method. - -- Changing the range of a method's return values, unless the member definition raises this possibility and clearly indicates how clients should handle unknown values. - -- Fixing most bugs. Consumers of the type will rely on the existing behavior. - - After a component, type, or member is marked with the guarantee, it cannot be changed to either or . - - Typically, exchange types are the basic types (such as and in the .NET Framework) and interfaces (such as , , and ) that are commonly used in public interfaces. - - Exchange types may publicly expose only other types that are also marked with compatibility. In addition, exchange types cannot depend on the behavior of Windows APIs that are prone to change. - -## Component Guarantees: A Summary - The following table indicates how a component's characteristics and usage affect its compatibility guarantee. - -|Component characteristics|Exchange|Stable|Side-by-Side|None| -|-------------------------------|--------------|------------|--------------------|----------| -|Can be used in interfaces between components that version independently.|Y|N|N|N| -|Can be used (privately) by an assembly that versions independently.|Y|Y|Y|N| -|Can have multiple versions in a single application domain.|N|Y|Y|Y| -|Can make breaking changes|N|N|Y|Y| -|Tested to make certain multiple versions of the assembly can be loaded together.|N|N|Y|N| -|Can make breaking changes in place.|N|N|N|Y| -|Can make very safe non-breaking servicing changes in place.|Y|Y|Y|Y| - -## Applying the Attribute - You can apply the to an assembly, a type, or a type member. Its application is hierarchical. That is, by default, the guarantee defined by the property of the attribute at the assembly level defines the guarantee of all types in the assembly and all members in those types. Similarly, if the guarantee is applied to the type, by default it also applies to each member of the type. - - This inherited guarantee can be overridden by applying the to individual types and type members. However, guarantees that override the default can only weaken the guarantee; they cannot strengthen it. For example, if an assembly is marked with the guarantee, its types and members have no compatibility guarantee, and any other guarantee that is applied to types or members in the assembly is ignored. - -## Testing the Guarantee - The property returns a member of the enumeration, which is marked with the attribute. This means that you should test for the flag that you are interested in by masking away potentially unknown flags. For example, the following example tests whether a type is marked as . - - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Versioning/ComponentGuaranteesAttribute/Overview/apply1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.versioning.componentguaranteesattribute.class/vb/apply1.vb" id="Snippet1"::: - - The following example tests whether a type is marked as or . - - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Versioning/ComponentGuaranteesAttribute/Overview/apply1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.versioning.componentguaranteesattribute.class/vb/apply1.vb" id="Snippet2"::: - - The following example tests wither a type is marked as (that is, neither nor ). - - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Versioning/ComponentGuaranteesAttribute/Overview/apply1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.versioning.componentguaranteesattribute.class/vb/apply1.vb" id="Snippet3"::: - - ]]> - + For more information about this API, see Supplemental API remarks for ComponentGuaranteesAttribute. @@ -219,11 +92,11 @@ One of the enumeration values that specifies the level of compatibility that is guaranteed across multiple versions. Initializes a new instance of the class with a value that indicates a library, type, or member's guaranteed level of compatibility across multiple versions. - class is instantiated, the value of the `guarantees` parameter is assigned to the property. - + class is instantiated, the value of the `guarantees` parameter is assigned to the property. + ]]> @@ -266,11 +139,11 @@ Gets a value that indicates the guaranteed level of compatibility of a library, type, or type member that spans multiple versions. One of the enumeration values that specifies the level of compatibility that is guaranteed across multiple versions. - property corresponds to the `guarantees` parameter of the constructor. - + property corresponds to the `guarantees` parameter of the constructor. + ]]> diff --git a/xml/System.Security.Cryptography.Xml/SignedXml.xml b/xml/System.Security.Cryptography.Xml/SignedXml.xml index 6bafdc4511c..3e731bb2972 100644 --- a/xml/System.Security.Cryptography.Xml/SignedXml.xml +++ b/xml/System.Security.Cryptography.Xml/SignedXml.xml @@ -37,160 +37,22 @@ Provides a wrapper on a core XML signature object to facilitate creating XML signatures. - - class is the .NET implementation of the World Wide Web Consortium (W3C) [XML Signature Syntax and Processing Specification](https://www.w3.org/TR/xmldsig-core/), also known as XMLDSIG (XML Digital Signature). XMLDSIG is a standards-based, interoperable way to sign and verify all or part of an XML document or other data that is addressable from a Uniform Resource Identifier (URI). - - Use the class whenever you need to share signed XML data between applications or organizations in a standard way. Any data signed using this class can be verified by any conforming implementation of the W3C specification for XMLDSIG. - - The class allows you to create the following three kinds of XML digital signatures: - -|Signature Type|Description| -|--------------------|-----------------| -|Enveloped signature|The signature is contained within the XML element being signed.| -|Enveloping signature|The signed XML is contained within the `` element.| -|Internal detached signature|The signature and signed XML are in the same document, but neither element contains the other.| - - There is also a fourth kind of signature called an external detached signature which is when the data and signature are in separate XML documents. External detached signatures are not supported by the class. - -## The structure of an XML Signature - -XMLDSIG creates a `` element, which contains a digital signature of an XML document or other data that is addressable from a URI. The `` element can optionally contain information about where to find a key that will verify the signature and which cryptographic algorithm was used for signing. The basic structure is as follows: - -```xml - - - - - - - - - - Base64EncodedValue== - - - AnotherBase64EncodedValue=== - -``` - -The main parts of this structure are: - -- The `` element - - Specifies the rules for rewriting the `Signature` element from XML/text into bytes for signature validation. The default value in .NET is , which identifies a trustworthy algorithm. This element is represented by the property. - -- The `` element - - Specifies the algorithm used for signature generation and validation, which was applied to the `` element to produce the value in ``. In the previous example, the value identifies an RSA PKCS1 SHA-1 signature. Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better. This element is represented by the property. - -- The `` element - - Specifies the cryptographic signature for the `` element. If this signature does not verify, then some portion of the `` block was tampered with, and the document is considered invalid. As long as the `` value is trustworthy, this value is highly resistant to tampering. This element is represented by the property. - -- The `URI` attribute of the `` element - - Specifies a data object using a URI reference. This attribute is represented by the property. - - - Not specifying the `URI` attribute, that is, setting the property to `null`, means that the receiving application is expected to know the identity of the object. In most cases, a `null` URI will result in an exception being thrown. Do not use a `null` URI, unless your application is interoperating with a protocol which requires it. - - - Setting the `URI` attribute to an empty string indicates that the root element of the document is being signed, a form of enveloped signature. - - - If the value of `URI` attribute starts with #, then the value must resolve to an element in the current document. This form can be used with any of the supported signature types (enveloped signature, enveloping signature or internal detached signature). - - - Anything else is considered an external resource detached signature and is not supported by the class. - -- The `` element - - Contains an ordered list of `` elements that describe how the signer obtained the data object that was digested. A transform algorithm is similar to the canonicalization method, but instead of rewriting the `` element, it rewrites the content identified by the `URI` attribute of the `` element. The `` element is represented by the class. - - - Each transform algorithm is defined as taking either XML (an XPath node-set) or bytes as input. If the format of the current data differs from the transform input requirements, conversion rules are applied. - - - Each transform algorithm is defined as producing either XML or bytes as the output. - - - If the output of the last transform algorithm is not defined in bytes (or no transforms were specified), then the [canonicalization method](https://www.w3.org/TR/2001/REC-xml-c14n-20010315) is used as an implicit transform (even if a different algorithm was specified in the `` element). - - - A value of for the transform algorithm encodes a rule which is interpreted as remove the `` element from the document. Otherwise, a verifier of an enveloped signature will digest the document, including the signature, but the signer would have digested the document before the signature was applied, leading to different answers. - -- The `` element - - Identifies the digest (cryptographic hash) method to apply on the transformed content identified by the `URI` attribute of the `` element. This is represented by the property. - -## Choosing a canonicalization method - Unless interoperating with a specification which requires the use of a different value, we recommend that you use the default .NET canonicalization method, which is the XML-C14N 1.0 algorithm, whose value is . The XML-C14N 1.0 algorithm is required to be supported by all implementations of XMLDSIG, particularly as it is an implicit final transform to apply. - - There are versions of canonicalization algorithms which support preserving comments. Comment-preserving canonicalization methods are not recommended because they violate the "sign what is seen" principle. That is, the comments in a `` element will not alter the processing logic for how the signature is performed, merely what the signature value is. When combined with a weak signature algorithm, allowing the comments to be included gives an attacker unnecessary freedom to force a hash collision, making a tampered document appear legitimate. In the .NET Framework, only built-in canonicalizers are supported by default. To support additional or custom canonicalizers, see the property. If the document uses a canonicalization method that is not in the collection represented by the property, then the method will return `false`. - -> [!NOTE] -> An extremely defensive application can remove any values it does not expect signers to use from the collection. - -## Are the Reference values safe from tampering? - Yes, the `` values are safe from tampering. .NET verifies the `` computation before processing any of the `` values and their associated transforms, and will abort early to avoid potentially malicious processing instructions. - -## Choosing the elements to sign - We recommend that you use the value of "" for the `URI` attribute (or set the property to an empty string), if possible. This means the whole document is considered for the digest computation, which means the whole document is protected from tampering. - - It is very common to see `URI` values in the form of anchors such as #foo, referring to an element whose ID attribute is "foo". Unfortunately, it is easy for this to be tampered with because this includes only the content of the target element, not the context. Abusing this distinction is known as XML Signature Wrapping (XSW). - - If your application considers comments to be semantic (which is not common when dealing with XML), then you should use "#xpointer(/)" instead of "", and "#xpointer(id('foo'))" instead of "#foo". The #xpointer versions are interpreted as including comments, while the shortname forms are excluding comments. - - If you need to accept documents which are only partially protected and you want to ensure that you are reading the same content that the signature protected, use the method. - -## Security considerations about the KeyInfo element - The data in the optional `` element (that is, the property), which contains a key to validate the signature, should not be trusted. - - In particular, when the value represents a bare RSA, DSA or ECDSA public key, the document could have been tampered with, despite the method reporting that the signature is valid. This can happen because the entity doing the tampering just has to generate a new key and re-sign the tampered document with that new key. So, unless your application verifies that the public key is an expected value, the document should be treated as if it were tampered with. This requires that your application examine the public key embedded within the document and verify it against a list of known values for the document context. For example, if the document could be understood to be issued by a known user, you'd check the key against a list of known keys used by that user. - - You can also verify the key after processing the document by using the method, instead of using the method. But, for the optimal security, you should verify the key beforehand. - - Alternately, consider trying the user's registered public keys, rather than reading what's in the `` element. - -## Security considerations about the X509Data element - The optional `` element is a child of the `` element and contains one or more X509 certificates or identifiers for X509 certificates. The data in the `` element should also not be inherently trusted. - - When verifying a document with the embedded `` element, .NET verifies only that the data resolves to an X509 certificate whose public key can be successfully used to validate the document signature. Unlike calling the method with the `verifySignatureOnly` parameter set to `false`, no revocation check is performed, no chain trust is checked, and no expiration is verified. Even if your application extracts the certificate itself and passes it to the method with the `verifySignatureOnly` parameter set to `false`, that is still not sufficient validation to prevent document tampering. The certificate still needs to be verified as being appropriate for the document being signed. - - Using an embedded signing certificate can provide useful key rotation strategies, whether in the `` section or in the document content. When using this approach an application should extract the certificate manually and perform validation similar to: - -- The certificate was issued directly or via a chain by a Certificate Authority (CA) whose public certificate is embedded in the application. - - Using the OS-provided trust list without additional checks, such as a known subject name, is not sufficient to prevent tampering in . - -- The certificate is verified to have not been expired at the time of document signing (or "now" for near real-time document processing). - -- For long-lived certificates issued by a CA which supports revocation, verify the certificate was not revoked. - -- The certificate subject is verified as being appropriate to the current document. - -## Choosing the transform algorithm - If you are interoperating with a specification which has dictated specific values (such as XrML), then you need to follow the specification. If you have an enveloped signature (such as when signing the whole document), then you need to use (represented by the class). You can specify the implicit XML-C14N transform as well, but it's not necessary. For an enveloping or detached signature, no transforms are required. The implicit XML-C14N transform takes care of everything. - - With the security updated introduced by the [Microsoft Security Bulletin MS16-035](https://docs.microsoft.com/security-updates/securitybulletins/2016/ms16-035), .NET has restricted what transforms can be used in document verification by default, with untrusted transforms causing to always return `false`. In particular, transforms which require additional input (specified as child elements in the XML) are no longer allowed due to their susceptibility of abuse by malicious users. The W3C advises avoiding the XPath and XSLT transforms, which are the two main transforms affected by these restrictions. - -## The problem with external references - If an application does not verify that external references seem appropriate for the current context, they can be abused in ways that provide for many security vulnerabilities (including Denial of Service, Distributed Reflection Denial of Service, Information Disclosure, Signature Bypass, and Remote Code Execution). Even if an application were to validate the external reference URI, there would remain a problem of the resource being loaded twice: once when your application reads it, and once when reads it. Since there's no guarantee that the application read and document verify steps have the same content, the signature does not provide trustworthiness. - - Given the risks of external references, will throw an exception when an external reference is encountered. For more information about this issue, see [KB article 3148821](https://support.microsoft.com/kb/3148821). - - - -## Examples - The following code example shows how to sign and verify an entire XML document using an enveloped signature. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.XML.SignedXml.ComputeSig-Check-AsymetricAlg-Envelope/CPP/exampleenvelope.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/Overview/exampleenvelope.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML.SignedXml.ComputeSig-Check-AsymetricAlg-Envelope/VB/exampleenvelope.vb" id="Snippet1"::: - - The following code example shows how to sign and verify a single element of an XML document using an enveloping signature. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.SignVerifyEnvelope - Specify Element/CPP/sample.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.SignVerifyEnvelope - Specify Element/VB/sample.vb" id="Snippet1"::: - - ]]> - + For more information about this API, see Supplemental API remarks for SignedXml. + + + XML Signature Best Practices @@ -240,27 +102,27 @@ The main parts of this structure are: Initializes a new instance of the class. - @@ -306,33 +168,33 @@ The main parts of this structure are: The object to use to initialize the new instance of . Initializes a new instance of the class from the specified XML document. - - The parameter is . - - -or- - + The parameter is . + + -or- + The parameter contains a null property. @@ -414,24 +276,24 @@ The main parts of this structure are: The object to add to the list of objects to be signed. Adds a object to the list of objects to be signed. - method adds an `` element that represents an object to be signed to the `` element of an XML digital signature. - - The method internally calls the method of the object encapsulated by the object. You can also add a object by directly calling the method from the property. - - For more information about XML digital signatures, see the [XMLDSIG specification](https://www.w3.org/TR/xmldsig-core/). - - - -## Examples - The following code example computes and XML signature. - + method adds an `` element that represents an object to be signed to the `` element of an XML digital signature. + + The method internally calls the method of the object encapsulated by the object. You can also add a object by directly calling the method from the property. + + For more information about XML digital signatures, see the [XMLDSIG specification](https://www.w3.org/TR/xmldsig-core/). + + + +## Examples + The following code example computes and XML signature. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.XML.SignedXml-AddObject-AddReference/CPP/example.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/AddObject/example.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML.SignedXml-AddObject-AddReference/VB/example.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML.SignedXml-AddObject-AddReference/VB/example.vb" id="Snippet1"::: + ]]> @@ -470,36 +332,36 @@ The main parts of this structure are: The object that describes a digest method, digest value, and transform to use for creating an XML digital signature. Adds a object to the object that describes a digest method, digest value, and transform to use for creating an XML digital signature. - method adds a `` element to the object that describes a digest method, digest value, and transform to use for creating an XML digital signature. The `` element is a subelement of the `` element. - - The method internally calls the method of the object encapsulated by the object. You can also add a object by directly calling the method from the property. - - For more information about XML digital signatures, see the [XMLDSIG specification](https://www.w3.org/TR/xmldsig-core/). - - - -## Examples - The following code example shows how to sign and verify an entire XML document using an enveloped signature. - + method adds a `` element to the object that describes a digest method, digest value, and transform to use for creating an XML digital signature. The `` element is a subelement of the `` element. + + The method internally calls the method of the object encapsulated by the object. You can also add a object by directly calling the method from the property. + + For more information about XML digital signatures, see the [XMLDSIG specification](https://www.w3.org/TR/xmldsig-core/). + + + +## Examples + The following code example shows how to sign and verify an entire XML document using an enveloped signature. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.Signature - Envelope/CPP/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/Reference/.ctor/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.Signature - Envelope/VB/sample.vb" id="Snippet1"::: - - The following code example shows how to sign and verify a Uniform Resource Identifier (URI) addressable object using a detached signature. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.Signature - Envelope/VB/sample.vb" id="Snippet1"::: + + The following code example shows how to sign and verify a Uniform Resource Identifier (URI) addressable object using a detached signature. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/XMLDSIG - Signature - Detached/CPP/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/Signature/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/XMLDSIG - Signature - Detached/VB/sample.vb" id="Snippet1"::: - - The following code example shows how to sign and verify a single element of an XML document using an enveloping signature. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/XMLDSIG - Signature - Detached/VB/sample.vb" id="Snippet1"::: + + The following code example shows how to sign and verify a single element of an XML document using an enveloping signature. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.SignVerifyEnvelope - Specify Element/CPP/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.SignVerifyEnvelope - Specify Element/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.SignVerifyEnvelope - Specify Element/VB/sample.vb" id="Snippet1"::: + ]]> @@ -546,44 +408,44 @@ The main parts of this structure are: if the property verifies; otherwise, . - method will search the "AddressBook" store for certificates suitable for the verification. For example, if the certificate is referenced by a Subject Key Identifier (SKI), the method will select certificates with this SKI and try them one after another until it can verify the certificate. - - - -## Examples - The following code example shows how to sign and verify an entire XML document using an enveloped signature. - + method will search the "AddressBook" store for certificates suitable for the verification. For example, if the certificate is referenced by a Subject Key Identifier (SKI), the method will select certificates with this SKI and try them one after another until it can verify the certificate. + + + +## Examples + The following code example shows how to sign and verify an entire XML document using an enveloped signature. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.XML.SignedXml.ComputeSig-Check-AsymetricAlg-Envelope/CPP/exampleenvelope.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/Overview/exampleenvelope.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML.SignedXml.ComputeSig-Check-AsymetricAlg-Envelope/VB/exampleenvelope.vb" id="Snippet1"::: - - The following code example shows how to sign and verify a Uniform Resource Identifier (URI) addressable object using a detached signature. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML.SignedXml.ComputeSig-Check-AsymetricAlg-Envelope/VB/exampleenvelope.vb" id="Snippet1"::: + + The following code example shows how to sign and verify a Uniform Resource Identifier (URI) addressable object using a detached signature. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.XML.SignedXml.ComputeSig-Check-AsymetricAlg-Detached/CPP/exampledetached.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/CheckSignature/exampledetached.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML.SignedXml.ComputeSig-Check-AsymetricAlg-Detached/VB/exampledetached.vb" id="Snippet1"::: - - The following code example shows how to sign and verify a single element of an XML document using an enveloping signature. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML.SignedXml.ComputeSig-Check-AsymetricAlg-Detached/VB/exampledetached.vb" id="Snippet1"::: + + The following code example shows how to sign and verify a single element of an XML document using an enveloping signature. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.SignVerifyEnvelope - Specify Element/CPP/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.SignVerifyEnvelope - Specify Element/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.SignVerifyEnvelope - Specify Element/VB/sample.vb" id="Snippet1"::: + ]]> - The property of the public key in the signature does not match the property. - - -or- - - The signature description could not be created. - - -or - + The property of the public key in the signature does not match the property. + + -or- + + The signature description could not be created. + + -or + The hash algorithm could not be created. @@ -623,32 +485,32 @@ The main parts of this structure are: if the property verifies for the specified key; otherwise, . - The parameter is . - The property of the parameter does not match the property. - - -or- - - The signature description could not be created. - - -or - + The property of the parameter does not match the property. + + -or- + + The signature description could not be created. + + -or + The hash algorithm could not be created. @@ -688,32 +550,32 @@ The main parts of this structure are: if the property verifies for the specified MAC; otherwise, . - The parameter is . - The property of the specified object is not valid. - - -or- - - The property is . - - -or- - + The property of the specified object is not valid. + + -or- + + The property is . + + -or- + The cryptographic transform used to check the signature could not be created. @@ -763,27 +625,27 @@ The main parts of this structure are: to verify the signature only; to verify both the signature and certificate. Determines whether the property verifies for the specified object and, optionally, whether the certificate is valid. - if the signature is valid; otherwise, . - - -or- - + if the signature is valid; otherwise, . + + -or- + if the signature and certificate are valid; otherwise, . - method will search the "AddressBook" store for certificates suitable for the verification. For example, if the certificate is referenced by a Subject Key Identifier (SKI), the method will select certificates with this SKI and try them one after another until it can verify the certificate. - - - -## Examples - The following code example uses an X.509 certificate from a certificate store to sign and verify an XML document. - + method will search the "AddressBook" store for certificates suitable for the verification. For example, if the certificate is referenced by a Subject Key Identifier (SKI), the method will select certificates with this SKI and try them one after another until it can verify the certificate. + + + +## Examples + The following code example uses an X.509 certificate from a certificate store to sign and verify an XML document. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/CheckSignature/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Security.Cryptography.Xml.SignedXml.CheckSignature/vb/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Security.Cryptography.Xml.SignedXml.CheckSignature/vb/sample.vb" id="Snippet1"::: + ]]> The parameter is . @@ -833,26 +695,26 @@ The main parts of this structure are: if the property verifies using the public key in the signature; otherwise, . - The parameter is null. - The property of the public key in the signature does not match the property. - - -or- - - The signature description could not be created. - - -or - + The property of the public key in the signature does not match the property. + + -or- + + The signature description could not be created. + + -or + The hash algorithm could not be created. @@ -902,38 +764,38 @@ The main parts of this structure are: Computes an XML digital signature. - method creates an XML digital signature and constructs many of the XML elements needed. - - You must set the data to be signed and the property before calling this method. - - - -## Examples - The following code example shows how to sign and verify a Uniform Resource Identifier (URI) addressable object using a detached signature. - + method creates an XML digital signature and constructs many of the XML elements needed. + + You must set the data to be signed and the property before calling this method. + + + +## Examples + The following code example shows how to sign and verify a Uniform Resource Identifier (URI) addressable object using a detached signature. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.XML-XMLDsigDetached/CPP/xmldsigdetach.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/KeyInfo/Overview/xmldsigdetach.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML-XMLDsigDetached/VB/xmldsigdetach.vb" id="Snippet1"::: - - The following code example shows how to sign and verify an entire XML document using an enveloping signature. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML-XMLDsigDetached/VB/xmldsigdetach.vb" id="Snippet1"::: + + The following code example shows how to sign and verify an entire XML document using an enveloping signature. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.XML-XMLDsigEnvelope/CPP/xmldsigenv.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/KeyInfo/Overview/xmldsigenv.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML-XMLDsigEnvelope/VB/xmldsigenv.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML-XMLDsigEnvelope/VB/xmldsigenv.vb" id="Snippet1"::: + ]]> - The property is . - - -or- - - The property is not a object or object. - - -or- - + The property is . + + -or- + + The property is not a object or object. + + -or- + The key could not be loaded. @@ -971,39 +833,39 @@ The main parts of this structure are: A object that holds the MAC to be used to compute the value of the property. Computes an XML digital signature using the specified message authentication code (MAC) algorithm. - method creates an XML digital signature using the specified MAC algorithm and constructs many of the XML elements needed. - - You must set the data to be signed before calling this method. - - - -## Examples - The following code example shows how to sign and verify a Uniform Resource Identifier (URI) addressable object using a detached signature. - + method creates an XML digital signature using the specified MAC algorithm and constructs many of the XML elements needed. + + You must set the data to be signed before calling this method. + + + +## Examples + The following code example shows how to sign and verify a Uniform Resource Identifier (URI) addressable object using a detached signature. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.XML.SignedXml.ComputeSig-Check-KeyedHash-Detached/CPP/xmldsigdetachedkeyedhashalg.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/CheckSignature/xmldsigdetachedkeyedhashalg.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML.SignedXml.ComputeSig-Check-KeyedHash-Detached/VB/xmldsigdetachedkeyedhashalg.vb" id="Snippet1"::: - - The following code example shows how to sign and verify an entire XML document using an enveloping signature. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML.SignedXml.ComputeSig-Check-KeyedHash-Detached/VB/xmldsigdetachedkeyedhashalg.vb" id="Snippet1"::: + + The following code example shows how to sign and verify an entire XML document using an enveloping signature. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.XML.SignedXml.ComputeSig-Check-KeyedHash-Envelope/CPP/xmldsigenvkeyedhashalg.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/CheckSignature/xmldsigenvkeyedhashalg.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML.SignedXml.ComputeSig-Check-KeyedHash-Envelope/VB/xmldsigenvkeyedhashalg.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML.SignedXml.ComputeSig-Check-KeyedHash-Envelope/VB/xmldsigenvkeyedhashalg.vb" id="Snippet1"::: + ]]> The parameter is . The object specified by the parameter is not an instance of or or or . - - -or- - - The property of the specified object is not valid. - - -or- - + + -or- + + The property of the specified object is not valid. + + -or- + The cryptographic transform used to check the signature could not be created. @@ -1145,13 +1007,13 @@ The main parts of this structure are: Returns the public key of a signature. An object that contains the public key of the signature, or if the key cannot be found. - method returns an object that contains a public key that can be used to verify an XML digital signature. - - The key must be either a or an key. - + method returns an object that contains a public key that can be used to verify an XML digital signature. + + The key must be either a or an key. + ]]> The property is . @@ -1189,10 +1051,10 @@ The main parts of this structure are: Returns the XML representation of a object. The XML representation of the object. To be added. - The property is . - - -or- - + The property is . + + -or- + The property is . @@ -1227,30 +1089,30 @@ The main parts of this structure are: Gets or sets the object of the current object. The object of the current object. - property represents the `` element of an XML digital signature using a object contained within the property. The `` element is a subelement of the `` element. - - Use the property to embed key-related information intended to help identify the key necessary for validating an XML document. - - For more information about the `` element, see the [XMLDSIG specification](https://www.w3.org/TR/xmldsig-core/). - - - -## Examples - The following code example uses the object when signing a resource represented by a Universal Resource Identifier (URI). This example saves the signature in a new file. - + property represents the `` element of an XML digital signature using a object contained within the property. The `` element is a subelement of the `` element. + + Use the property to embed key-related information intended to help identify the key necessary for validating an XML document. + + For more information about the `` element, see the [XMLDSIG specification](https://www.w3.org/TR/xmldsig-core/). + + + +## Examples + The following code example uses the object when signing a resource represented by a Universal Resource Identifier (URI). This example saves the signature in a new file. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.XML-XMLDsigDetached/CPP/xmldsigdetach.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/KeyInfo/Overview/xmldsigdetach.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML-XMLDsigDetached/VB/xmldsigdetach.vb" id="Snippet1"::: - - The following code example uses the object when signing an XML document. This example saves the signature in a new file. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML-XMLDsigDetached/VB/xmldsigdetach.vb" id="Snippet1"::: + + The following code example uses the object when signing an XML document. This example saves the signature in a new file. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.XML-XMLDsigEnvelope/CPP/xmldsigenv.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/KeyInfo/Overview/xmldsigenv.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML-XMLDsigEnvelope/VB/xmldsigenv.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML-XMLDsigEnvelope/VB/xmldsigenv.vb" id="Snippet1"::: + ]]> @@ -1299,22 +1161,22 @@ The main parts of this structure are: The XML element to load the state from. Loads a state from an XML element. - method to verify an XML document. - + method to verify an XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.XML-XMLDsigDetached/CPP/xmldsigdetach.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/KeyInfo/Overview/xmldsigdetach.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML-XMLDsigDetached/VB/xmldsigdetach.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML-XMLDsigDetached/VB/xmldsigdetach.vb" id="Snippet3"::: + ]]> The parameter is . - The parameter does not contain a valid property. - - -or- - + The parameter does not contain a valid property. + + -or- + The parameter does not contain a valid property. @@ -1426,11 +1288,11 @@ The main parts of this structure are: Sets the current object. The current object. The defaults is a object. - class resolves external XML resources named by a Uniform Resource Identifier (URI). If you do not trust the source of the XML file, you might not want to allow the XML file to access computer resources named by the URI. You can use the property to control the level of access that XML files have to computer resources by specifying different objects. If you do not want to allow any access, you can set this property to `null` (`Nothing` in Visual Basic). - + class resolves external XML resources named by a Uniform Resource Identifier (URI). If you do not trust the source of the XML file, you might not want to allow the XML file to access computer resources named by the URI. You can use the property to control the level of access that XML files have to computer resources by specifying different objects. If you do not want to allow any access, you can set this property to `null` (`Nothing` in Visual Basic). + ]]> @@ -1464,11 +1326,11 @@ The main parts of this structure are: Gets the names of methods whose canonicalization algorithms are explicitly allowed. A collection of the names of methods that safely produce canonical XML. - [!NOTE] > behaves like a static property. Changes from one instance of will be observed in other instances. Modifying the collection is not a thread-safe operation. @@ -1507,30 +1369,30 @@ The main parts of this structure are: Gets the object of the current object. The object of the current object. - property represents the `` element of an XML digital signature using a object contained within the property. The `` element is the root element used for XML digital signature creation and verification. - - Use the property to retrieve the object used by the object. - + property represents the `` element of an XML digital signature using a object contained within the property. The `` element is the root element used for XML digital signature creation and verification. + + Use the property to retrieve the object used by the object. + For more information about the `` element, see the [XMLDSIG specification](https://www.w3.org/TR/xmldsig-core/). - - - -## Examples - The following code example uses the property to sign and verify an entire XML document using an enveloped signature. - + + + +## Examples + The following code example uses the property to sign and verify an entire XML document using an enveloped signature. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.Signature - Envelope/CPP/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/Reference/.ctor/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.Signature - Envelope/VB/sample.vb" id="Snippet1"::: - - The following code example uses the property to sign and verify a Uniform Resource Identifier (URI) addressable object using a detached signature. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.Signature - Envelope/VB/sample.vb" id="Snippet1"::: + + The following code example uses the property to sign and verify a Uniform Resource Identifier (URI) addressable object using a detached signature. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/XMLDSIG - Signature - Detached/CPP/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/Signature/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/XMLDSIG - Signature - Detached/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/XMLDSIG - Signature - Detached/VB/sample.vb" id="Snippet1"::: + ]]> @@ -1565,17 +1427,17 @@ The main parts of this structure are: if the format is acceptable; otherwise, . - object. - - You can also read the object's current delegate and chain to it if you want. - - If you are setting up a format validator, the delegate you supply will receive as an input parameter the object being verified and returns a Boolean value - `true` if the format is acceptable, `false` if it is not. If the delegate returns `false` for any reason, the object will report that the XML signature is not valid. - + object. + + You can also read the object's current delegate and chain to it if you want. + + If you are setting up a format validator, the delegate you supply will receive as an input parameter the object being verified and returns a Boolean value - `true` if the format is acceptable, `false` if it is not. If the delegate returns `false` for any reason, the object will report that the XML signature is not valid. + ]]> @@ -1666,15 +1528,15 @@ The main parts of this structure are: Gets the signature method of the current object. The signature method of the current object. - property represents the `` element of an XML digital signature using a Uniform Resource Identifier (URI) string contained within the property. The `` element is a subelement of the `` element. - - Use the property to retrieve the `` URI used by the object. This property is read only. For more information about programmatically specifying a URI for the `` element, see the property. - - For more information about the `` element, see the [XMLDSIG specification](https://www.w3.org/TR/xmldsig-core/). - + property represents the `` element of an XML digital signature using a Uniform Resource Identifier (URI) string contained within the property. The `` element is a subelement of the `` element. + + Use the property to retrieve the `` URI used by the object. This property is read only. For more information about programmatically specifying a URI for the `` element, see the property. + + For more information about the `` element, see the [XMLDSIG specification](https://www.w3.org/TR/xmldsig-core/). + ]]> @@ -1721,15 +1583,15 @@ The main parts of this structure are: Gets the signature value of the current object. A byte array that contains the signature value of the current object. - property represents the `` element of an XML digital signature using an array of bytes contained within the property. The `` element is a subelement of the `` element. - - Use the property to retrieve the value of the XML digital signature. This property is automatically populated when you make a successful call to the method. - - For more information about the `` element, see the [XMLDSIG specification](https://www.w3.org/TR/xmldsig-core/). - + property represents the `` element of an XML digital signature using an array of bytes contained within the property. The `` element is a subelement of the `` element. + + Use the property to retrieve the value of the XML digital signature. This property is automatically populated when you make a successful call to the method. + + For more information about the `` element, see the [XMLDSIG specification](https://www.w3.org/TR/xmldsig-core/). + ]]> @@ -1776,15 +1638,15 @@ The main parts of this structure are: Gets the object of the current object. The object of the current object. - property represents the `` element of an XML digital signature using an array of bytes contained within the property. The `` element is a subelement of the `` element. - - Use the property to retrieve the object that is used by the object to create an XML digital signature. - - For more information about the `` element, see the [XMLDSIG specification](https://www.w3.org/TR/xmldsig-core/). - + property represents the `` element of an XML digital signature using an array of bytes contained within the property. The `` element is a subelement of the `` element. + + Use the property to retrieve the object that is used by the object to create an XML digital signature. + + For more information about the `` element, see the [XMLDSIG specification](https://www.w3.org/TR/xmldsig-core/). + ]]> @@ -1835,32 +1697,32 @@ The main parts of this structure are: Gets or sets the asymmetric algorithm key used for signing a object. The asymmetric algorithm key used for signing the object. - property to specify the asymmetric key you want to use to create an XML digital signature. - - - -## Examples - The following code example shows how to sign and verify an entire XML document using an enveloped signature. - + property to specify the asymmetric key you want to use to create an XML digital signature. + + + +## Examples + The following code example shows how to sign and verify an entire XML document using an enveloped signature. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.XML.SignedXml.ComputeSig-Check-AsymetricAlg-Envelope/CPP/exampleenvelope.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/Overview/exampleenvelope.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML.SignedXml.ComputeSig-Check-AsymetricAlg-Envelope/VB/exampleenvelope.vb" id="Snippet1"::: - - The following code example shows how to sign and verify a Uniform Resource Identifier (URI) addressable object using a detached signature. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML.SignedXml.ComputeSig-Check-AsymetricAlg-Envelope/VB/exampleenvelope.vb" id="Snippet1"::: + + The following code example shows how to sign and verify a Uniform Resource Identifier (URI) addressable object using a detached signature. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.XML.SignedXml.ComputeSig-Check-AsymetricAlg-Detached/CPP/exampledetached.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/CheckSignature/exampledetached.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML.SignedXml.ComputeSig-Check-AsymetricAlg-Detached/VB/exampledetached.vb" id="Snippet1"::: - - The following code example shows how to sign and verify a single element of an XML document using an enveloping signature. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.XML.SignedXml.ComputeSig-Check-AsymetricAlg-Detached/VB/exampledetached.vb" id="Snippet1"::: + + The following code example shows how to sign and verify a single element of an XML document using an enveloping signature. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.SignVerifyEnvelope - Specify Element/CPP/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.SignVerifyEnvelope - Specify Element/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.SignVerifyEnvelope - Specify Element/VB/sample.vb" id="Snippet1"::: + ]]> @@ -1942,15 +1804,15 @@ The main parts of this structure are: Represents the Uniform Resource Identifier (URI) for the XML mode decryption transformation. This field is constant. - field is . - - Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. - - For more information, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/2002/07/decrypt#XML). - + field is . + + Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. + + For more information, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/2002/07/decrypt#XML). + ]]> @@ -1984,26 +1846,26 @@ The main parts of this structure are: Represents the Uniform Resource Identifier (URI) for the base 64 transformation. This field is constant. - field is . - - Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. - - The class implements the transform described by the field. - - For more information, see the [World Wide Web Consortium (W3C) schema](https://www.w3.org/2000/09/xmldsig#base64). - - - -## Examples - The following code example demonstrates how to use members of the class. - + field is . + + Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. + + The class implements the transform described by the field. + + For more information, see the [World Wide Web Consortium (W3C) schema](https://www.w3.org/2000/09/xmldsig#base64). + + + +## Examples + The following code example demonstrates how to use members of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.Xml.XmlDsigBase64Transform/CPP/members.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigBase64TransformUrl/members.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.Xml.XmlDsigBase64Transform/VB/members.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.Xml.XmlDsigBase64Transform/VB/members.vb" id="Snippet2"::: + ]]> @@ -2037,28 +1899,28 @@ The main parts of this structure are: Represents the Uniform Resource Identifier (URI) for the Canonical XML transformation. This field is constant. - field is . - - Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. - - The class implements the transform described by the field. - - For more information, see the World Wide Web Consortium (W3C) [Canonical XML](https://www.w3.org/TR/2001/REC-xml-c14n-20010315) specification. - - This field has the same value as the field. - - - -## Examples - The following code example demonstrates how to call members of the class. - + field is . + + Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. + + The class implements the transform described by the field. + + For more information, see the World Wide Web Consortium (W3C) [Canonical XML](https://www.w3.org/TR/2001/REC-xml-c14n-20010315) specification. + + This field has the same value as the field. + + + +## Examples + The following code example demonstrates how to call members of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.Xml.XmlDsigC14NTransform/CPP/members.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigC14NTransformUrl/members.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.Xml.XmlDsigC14NTransform/VB/members.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.Xml.XmlDsigC14NTransform/VB/members.vb" id="Snippet2"::: + ]]> @@ -2092,19 +1954,19 @@ The main parts of this structure are: Represents the Uniform Resource Identifier (URI) for the Canonical XML transformation, with comments. This field is constant. - field is . - - Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. - - The class implements the transform described by the field. - - For more information, see the World Wide Web Consortium (W3C) [Canonical XML](https://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments) specification. - - This field has the same value as the field. - + field is . + + Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. + + The class implements the transform described by the field. + + For more information, see the World Wide Web Consortium (W3C) [Canonical XML](https://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments) specification. + + This field has the same value as the field. + ]]> @@ -2139,19 +2001,19 @@ The main parts of this structure are: Represents the Uniform Resource Identifier (URI) for the standard canonicalization algorithm for XML digital signatures. This field is constant. - field is . - - Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. - - The class implements the transform described by the field. - - For more information, see the World Wide Web Consortium (W3C) [Canonical XML](https://www.w3.org/TR/2001/REC-xml-c14n-20010315) specification. - - This field has the same value as the field. - + field is . + + Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. + + The class implements the transform described by the field. + + For more information, see the World Wide Web Consortium (W3C) [Canonical XML](https://www.w3.org/TR/2001/REC-xml-c14n-20010315) specification. + + This field has the same value as the field. + ]]> @@ -2186,19 +2048,19 @@ The main parts of this structure are: Represents the Uniform Resource Identifier (URI) for the standard canonicalization algorithm for XML digital signatures and includes comments. This field is constant. - field is . - - Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. - - The class implements the transform described by the field. - - For more information, see the World Wide Web Consortium (W3C) [Canonical XML](https://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments) specification. - - This field has the same value as the field. - + field is . + + Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. + + The class implements the transform described by the field. + + For more information, see the World Wide Web Consortium (W3C) [Canonical XML](https://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments) specification. + + This field has the same value as the field. + ]]> @@ -2233,15 +2095,15 @@ The main parts of this structure are: Represents the Uniform Resource Identifier (URI) for the standard algorithm for XML digital signatures. This field is constant. - field is . - - Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. - - For more information, see the [World Wide Web Consortium (W3C) schema](https://www.w3.org/2000/09/xmldsig#dsa-sha1). - + field is . + + Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. + + For more information, see the [World Wide Web Consortium (W3C) schema](https://www.w3.org/2000/09/xmldsig#dsa-sha1). + ]]> @@ -2275,26 +2137,26 @@ The main parts of this structure are: Represents the Uniform Resource Identifier (URI) for enveloped signature transformation. This field is constant. - field is . - - Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. - - The class implements the transform described by the field. - - For more information, see the [World Wide Web Consortium (W3C) schema](https://www.w3.org/2000/09/xmldsig#enveloped-signature). - - - -## Examples - The following code example demonstrates how to use members of the class. - + field is . + + Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. + + The class implements the transform described by the field. + + For more information, see the [World Wide Web Consortium (W3C) schema](https://www.w3.org/2000/09/xmldsig#enveloped-signature). + + + +## Examples + The following code example demonstrates how to use members of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.Xml.XmlDsigEnvelopedSignatureTransform/cpp/members.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigEnvelopedSignatureTransformUrl/members.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.Xml.XmlDsigEnvelopedSignatureTransform/VB/members.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.Xml.XmlDsigEnvelopedSignatureTransform/VB/members.vb" id="Snippet2"::: + ]]> @@ -2328,26 +2190,26 @@ The main parts of this structure are: Represents the Uniform Resource Identifier (URI) for exclusive XML canonicalization. This field is constant. - field is . - - Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. - - The class implements the transform described by the field. - - For more information, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/2001/10/xml-exc-c14n). - - - -## Examples - The following code example shows how to sign and verify an XML document using the class. This sample creates an envelope signature. - + field is . + + Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. + + The class implements the transform described by the field. + + For more information, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/2001/10/xml-exc-c14n). + + + +## Examples + The following code example shows how to sign and verify an XML document using the class. This sample creates an envelope signature. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XmlDsigExcC14NTransform/CPP/example.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigExcC14NTransformUrl/example.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XmlDsigExcC14NTransform/VB/example.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XmlDsigExcC14NTransform/VB/example.vb" id="Snippet1"::: + ]]> @@ -2381,26 +2243,26 @@ The main parts of this structure are: Represents the Uniform Resource Identifier (URI) for exclusive XML canonicalization, with comments. This field is constant. - field is . - - Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. - - The class implements the transform described by the field. - - For more information, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/2001/10/xml-exc-c14n#WithComments). - - - -## Examples - The following code example shows how to sign and verify an XML document using the class. This sample creates an envelope signature. - + field is . + + Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. + + The class implements the transform described by the field. + + For more information, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/2001/10/xml-exc-c14n#WithComments). + + + +## Examples + The following code example shows how to sign and verify an XML document using the class. This sample creates an envelope signature. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XmlDsigExcC14NWithCommentsTransform/CPP/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigExcC14NWithCommentsTransformUrl/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XmlDsigExcC14NWithCommentsTransform/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XmlDsigExcC14NWithCommentsTransform/VB/sample.vb" id="Snippet1"::: + ]]> @@ -2435,17 +2297,17 @@ The main parts of this structure are: Represents the Uniform Resource Identifier (URI) for the standard algorithm for XML digital signatures. This field is constant. - field is . - - Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. - - For more information, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/2000/09/xmldsig#hmac-sha1). + field is . + + Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. + + For more information, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/2000/09/xmldsig#hmac-sha1). Due to collision problems with SHA1, Microsoft recommends a security model based on SHA256 or better. - + ]]> @@ -2480,15 +2342,15 @@ The main parts of this structure are: Represents the Uniform Resource Identifier (URI) for the standard minimal canonicalization algorithm for XML digital signatures. This field is constant. - field is . - - Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. - - For more information, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/2000/09/xmldsig#minimal). - + field is . + + Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. + + For more information, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/2000/09/xmldsig#minimal). + ]]> @@ -2523,15 +2385,15 @@ The main parts of this structure are: Represents the Uniform Resource Identifier (URI) for the standard namespace for XML digital signatures. This field is constant. - field is . - - Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. - - For more information, see the [World Wide Web Consortium (W3C) schema](https://www.w3.org/2000/09/xmldsig). - + field is . + + Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. + + For more information, see the [World Wide Web Consortium (W3C) schema](https://www.w3.org/2000/09/xmldsig). + ]]> @@ -2566,17 +2428,17 @@ The main parts of this structure are: Represents the Uniform Resource Identifier (URI) for the standard signature method for XML digital signatures. This field is constant. - field is . - - Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. - - For more information, see the [World Wide Web Consortium (W3C) schema](https://www.w3.org/2000/09/xmldsig#rsa-sha1). + field is . + + Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. + + For more information, see the [World Wide Web Consortium (W3C) schema](https://www.w3.org/2000/09/xmldsig#rsa-sha1). Due to collision problems with SHA1, Microsoft recommends a security model based on SHA256 or better. - + ]]> @@ -2608,15 +2470,15 @@ The main parts of this structure are: Represents the Uniform Resource Identifier (URI) for the SHA-256 signature method variation for XML digital signatures. This field is constant. - field is . - - Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. - - For more information, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/2001/04/xmldsig-more#rsa-sha256). - + field is . + + Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. + + For more information, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/2001/04/xmldsig-more#rsa-sha256). + ]]> @@ -2648,15 +2510,15 @@ The main parts of this structure are: Represents the Uniform Resource Identifier (URI) for the SHA-384 signature method variation for XML digital signatures. This field is constant. - field is . - - Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. - - For more information, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/2001/04/xmldsig-more#rsa-sha384). - + field is . + + Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. + + For more information, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/2001/04/xmldsig-more#rsa-sha384). + ]]> @@ -2688,15 +2550,15 @@ The main parts of this structure are: Represents the Uniform Resource Identifier (URI) for the SHA-512 signature method variation for XML digital signatures. This field is constant. - field is . - - Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. - - For more information, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/2001/04/xmldsig-more#rsa-sha512). - + field is . + + Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. + + For more information, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/2001/04/xmldsig-more#rsa-sha512). + ]]> @@ -2731,17 +2593,17 @@ The main parts of this structure are: Represents the Uniform Resource Identifier (URI) for the standard digest method for XML digital signatures. This field is constant. - field is . - - Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. - - For more information, see the [World Wide Web Consortium (W3C) schema](https://www.w3.org/2000/09/xmldsig#sha1). + field is . + + Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. + + For more information, see the [World Wide Web Consortium (W3C) schema](https://www.w3.org/2000/09/xmldsig#sha1). Due to collision problems with SHA1, Microsoft recommends a security model based on SHA256 or better. - + ]]> @@ -2773,15 +2635,15 @@ The main parts of this structure are: Represents the Uniform Resource Identifier (URI) for the standard digest method for XML digital signatures. This field is constant. - field is . - - Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. - - For more information, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/2001/04/xmlenc#sha256). - + field is . + + Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. + + For more information, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/2001/04/xmlenc#sha256). + ]]> @@ -2813,15 +2675,15 @@ The main parts of this structure are: Represents the Uniform Resource Identifier (URI) for the standard digest method for XML digital signatures. This field is constant. - field is . - - Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. - - For more information, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/2001/04/xmldsig-more#sha384). - + field is . + + Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. + + For more information, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/2001/04/xmldsig-more#sha384). + ]]> @@ -2853,15 +2715,15 @@ The main parts of this structure are: Represents the Uniform Resource Identifier (URI) for the standard digest method for XML digital signatures. This field is constant. - field is . - - Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. - - For more information, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/2001/04/xmlenc#sha512). - + field is . + + Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. + + For more information, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/2001/04/xmlenc#sha512). + ]]> @@ -2895,25 +2757,25 @@ The main parts of this structure are: Represents the Uniform Resource Identifier (URI) for the XML Path Language (XPath). This field is constant. - field is . - - Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. - - The class implements the transform described by the field. - - For more information, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/TR/1999/REC-xpath-19991116). - - - -## Examples - The following code example demonstrates how to call members of the class. - + field is . + + Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. + + The class implements the transform described by the field. + + For more information, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/TR/1999/REC-xpath-19991116). + + + +## Examples + The following code example demonstrates how to call members of the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigXPathTransformUrl/members.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.Xml.XmlDsigXPathTransform/VB/members.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.Xml.XmlDsigXPathTransform/VB/members.vb" id="Snippet2"::: + ]]> @@ -2947,26 +2809,26 @@ The main parts of this structure are: Represents the Uniform Resource Identifier (URI) for XSLT transformations. This field is constant. - field is . - - Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. - - The class implements the transform described by the field. - - For more information, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/TR/1999/REC-xslt-19991116). - - - -## Examples - The following code example demonstrates how to use members of the class. - + field is . + + Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. + + The class implements the transform described by the field. + + For more information, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/TR/1999/REC-xslt-19991116). + + + +## Examples + The following code example demonstrates how to use members of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.Xml.XmlDsigXsltTransform/CPP/members.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigXsltTransformUrl/members.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.Xml.XmlDsigXsltTransform/VB/members.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.Xml.XmlDsigXsltTransform/VB/members.vb" id="Snippet2"::: + ]]> @@ -3000,15 +2862,15 @@ The main parts of this structure are: Represents the Uniform Resource Identifier (URI) for the license transform algorithm used to normalize XrML licenses for signatures. - field is "urn:mpeg:mpeg21:2003:01-REL-R-NS:licenseTransform" - - Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. - - The class implements the transform described by the field. - + field is "urn:mpeg:mpeg21:2003:01-REL-R-NS:licenseTransform" + + Use this field to conveniently supply a value to one of the URI attributes of an element used for XMLDSIG. + + The class implements the transform described by the field. + ]]> diff --git a/xml/System.Security.Cryptography/RSACryptoServiceProvider.xml b/xml/System.Security.Cryptography/RSACryptoServiceProvider.xml index 4a11e74f61e..7021dd84936 100644 --- a/xml/System.Security.Cryptography/RSACryptoServiceProvider.xml +++ b/xml/System.Security.Cryptography/RSACryptoServiceProvider.xml @@ -69,40 +69,22 @@ Performs asymmetric encryption and decryption using the implementation of the algorithm provided by the cryptographic service provider (CSP). This class cannot be inherited. - + For more information about this API, see Supplemental API remarks for RSACryptoServiceProvider. + class to encrypt a string into an array of bytes and then decrypt the bytes back into a string. -## Remarks - This is the default implementation of . - - The supports key sizes from 384 bits to 16384 bits in increments of 8 bits if you have the Microsoft Enhanced Cryptographic Provider installed. It supports key sizes from 384 bits to 512 bits in increments of 8 bits if you have the Microsoft Base Cryptographic Provider installed. - - Valid key sizes are dependent on the cryptographic service provider (CSP) that is used by the instance. Windows CSPs enable keys sizes of 384 to 16384 bits for Windows versions prior to Windows 8.1, and key sizes of 512 to 16384 bits for Windows 8.1. For more information, see [CryptGenKey](/windows/win32/api/wincrypt/nf-wincrypt-cryptgenkey) function in the Windows documentation. - -## Interoperation with the Microsoft Cryptographic API (CAPI) - Unlike the RSA implementation in unmanaged CAPI, the class reverses the order of an encrypted array of bytes after encryption and before decryption. By default, data encrypted by the class cannot be decrypted by the CAPI `CryptDecrypt` function and data encrypted by the CAPI `CryptEncrypt` method cannot be decrypted by the class. - - If you do not compensate for the reverse ordering when interoperating between APIs, the class throws a . - - To interoperate with CAPI, you must manually reverse the order of encrypted bytes before the encrypted data interoperates with another API. You can easily reverse the order of a managed byte array by calling the method. - - - -## Examples - The following code example uses the class to encrypt a string into an array of bytes and then decrypt the bytes back into a string. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.RSACryptoServiceProvider/CPP/sample.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/RSACryptoServiceProvider/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.RSACryptoServiceProvider/VB/sample.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.RSACryptoServiceProvider/CPP/sample.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/RSACryptoServiceProvider/Overview/sample.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.RSACryptoServiceProvider/VB/sample.vb" id="Snippet1"::: - The following code example exports the key information created using the into an object. +The following code example exports the key information created using the into an object. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.RSACryptoServiceProvider.ExportParameters/CPP/sample.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/RSACryptoServiceProvider/Overview/sample1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.RSACryptoServiceProvider.ExportParameters/VB/sample.vb" id="Snippet1"::: - - ]]> - +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.RSACryptoServiceProvider.ExportParameters/CPP/sample.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/RSACryptoServiceProvider/Overview/sample1.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Cryptography.RSACryptoServiceProvider.ExportParameters/VB/sample.vb" id="Snippet1"::: + ]]> + Cryptographic Services diff --git a/xml/System.Security.Cryptography/RSAParameters.xml b/xml/System.Security.Cryptography/RSAParameters.xml index d4ba735dcce..99613fe4c19 100644 --- a/xml/System.Security.Cryptography/RSAParameters.xml +++ b/xml/System.Security.Cryptography/RSAParameters.xml @@ -66,47 +66,7 @@ Represents the standard parameters for the algorithm. - - class exposes an method that enables you to retrieve the raw RSA key in the form of an structure. Understanding the contents of this structure requires familiarity with how the algorithm works. The next section discusses the algorithm briefly. - -## RSA algorithm - - To generate a key pair, you start by creating two large prime numbers named p and q. These numbers are multiplied and the result is called n. Because p and q are both prime numbers, the only factors of n are 1, p, q, and n. - - If we consider only numbers that are less than n, the count of numbers that are relatively prime to n, that is, have no factors in common with n, equals (p - 1)(q - 1). - - Now you choose a number e, which is relatively prime to the value you calculated. The public key is now represented as {e, n}. - - To create the private key, you must calculate d, which is a number such that (d)(e) mod (p - 1)(q - 1) = 1. In accordance with the Euclidean algorithm, the private key is now {d, n}. - - Encryption of plaintext m to ciphertext c is defined as c = (m ^ e) mod n. Decryption would then be defined as m = (c ^ d) mod n. - -## Summary of fields - - Section A.1.2 of the [PKCS #1: RSA Cryptography Standard](https://datatracker.ietf.org/doc/html/rfc8017#appendix-A.1.2) defines a format for RSA private keys. - - The following table summarizes the fields of the structure. The third column provides the corresponding field in section A.1.2 of [PKCS #1: RSA Cryptography Standard](https://datatracker.ietf.org/doc/html/rfc8017#appendix-A.1.2). - -| field | Contains | Corresponding PKCS #1 field | -| ---------------------------------------------------------- | ----------------------- | --------------------------- | -| | d, the private exponent | privateExponent | -| | d mod (p - 1) | exponent1 | -| | d mod (q - 1) | exponent2 | -| | e, the public exponent | publicExponent | -| | (InverseQ)(q) = 1 mod p | coefficient | -| | n | modulus | -| | p | prime1 | -| | q | prime2 | - - The security of RSA derives from the fact that, given the public key { e, n }, it is computationally infeasible to calculate d, either directly or by factoring n into p and q. Therefore, any part of the key related to d, p, or q must be kept secret. If you call and ask for only the public key information, this is why you will receive only and . The other fields are available only if you have access to the private key, and you request it. - - is not encrypted in any way, so you must be careful when you use it with the private key information. All members of are serialized. If anyone can derive or intercept the private key parameters, the key and all the information encrypted or signed with it are compromised. - - ]]> - + For more information about this API, see Supplemental API remarks for RSAParameters. Cryptographic Services All About RSAParameters (blog post) diff --git a/xml/System.Security.Permissions/WebBrowserPermission.xml b/xml/System.Security.Permissions/WebBrowserPermission.xml index 2f4cf62a0f2..1a7beb905ab 100644 --- a/xml/System.Security.Permissions/WebBrowserPermission.xml +++ b/xml/System.Security.Permissions/WebBrowserPermission.xml @@ -49,19 +49,13 @@ The object controls the ability to create the WebBrowser control. - enumerations. - -## XAML Attribute Usage - This class is not typically used in XAML. - - ]]> - +In Windows Presentation Foundation (WPF), the Web browser control enables frames to navigate HTML. This permission uses the values of the enumerations. + +This class is not typically used in XAML. + ]]> @@ -98,11 +92,11 @@ Initializes a new instance of the class. - property is set to . - + property is set to . + ]]> @@ -136,19 +130,19 @@ An enumerated value of . Initializes a new instance of the class by specifying a permission state. - , the value of the property is set to . If `state` is set to , the value of the property is set to . - - - -## Examples - The following code example shows how to create a with a value. - + , the value of the property is set to . If `state` is set to , the value of the property is set to . + + + +## Examples + The following code example shows how to create a with a value. + :::code language="csharp" source="~/snippets/csharp/System.Security.Permissions/WebBrowserPermission/.ctor/Window1.xaml.cs" id="Snippetwebbrowserpermission1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/WebBrowserPermissionsSnippets/visualbasic/window1.xaml.vb" id="Snippetwebbrowserpermission1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/WebBrowserPermissionsSnippets/visualbasic/window1.xaml.vb" id="Snippetwebbrowserpermission1"::: + ]]> @@ -182,14 +176,14 @@ An enumerated value of . Initializes a new instance of the class by specifying the Web browser permission level. - with a value. - + with a value. + :::code language="csharp" source="~/snippets/csharp/System.Security.Permissions/WebBrowserPermission/.ctor/Window1.xaml.cs" id="Snippetwebbrowserpermission2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/WebBrowserPermissionsSnippets/visualbasic/window1.xaml.vb" id="Snippetwebbrowserpermission2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/WebBrowserPermissionsSnippets/visualbasic/window1.xaml.vb" id="Snippetwebbrowserpermission2"::: + ]]> @@ -224,14 +218,14 @@ Creates and returns an identical copy of the current permission. A copy of the current permission. - @@ -268,13 +262,13 @@ The XML encoding to use to reconstruct the permission. Reconstructs a permission with a specified state from an XML encoding. - @@ -312,13 +306,13 @@ Creates and returns a permission that is the intersection of the current permission and the specified permission. The intersection of two permissions is a permission that describes the state that they both describe in common. Only a demand that passes both original permissions will be valid for the intersected permission. - @@ -357,16 +351,16 @@ if the current permission is a subset of the specified permission; otherwise, . - @@ -405,22 +399,22 @@ if the property is set to ; otherwise, . - method. - + method. + :::code language="csharp" source="~/snippets/csharp/System.Security.Permissions/WebBrowserPermission/.ctor/Window1.xaml.cs" id="Snippetwebbrowserpermission5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/WebBrowserPermissionsSnippets/visualbasic/window1.xaml.vb" id="Snippetwebbrowserpermission5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/WebBrowserPermissionsSnippets/visualbasic/window1.xaml.vb" id="Snippetwebbrowserpermission5"::: + ]]> @@ -460,21 +454,21 @@ Gets or sets the current value of the Web browser permission level. The current value of the Web browser permission level. - value for the . - + value for the . + :::code language="csharp" source="~/snippets/csharp/System.Security.Permissions/WebBrowserPermission/.ctor/Window1.xaml.cs" id="Snippetwebbrowserpermission6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/WebBrowserPermissionsSnippets/visualbasic/window1.xaml.vb" id="Snippetwebbrowserpermission6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/WebBrowserPermissionsSnippets/visualbasic/window1.xaml.vb" id="Snippetwebbrowserpermission6"::: + ]]> @@ -509,13 +503,13 @@ Creates an XML encoding of the permission and its current state. An XML encoding of the permission, including any state information. - @@ -553,13 +547,13 @@ Creates a permission that is the union of the current permission and the specified permission. A new permission that represents the union of the current permission and the specified permission. - diff --git a/xml/System.Security.Permissions/WebBrowserPermissionAttribute.xml b/xml/System.Security.Permissions/WebBrowserPermissionAttribute.xml index 17c0b5239d7..4a9dd7faa9c 100644 --- a/xml/System.Security.Permissions/WebBrowserPermissionAttribute.xml +++ b/xml/System.Security.Permissions/WebBrowserPermissionAttribute.xml @@ -44,29 +44,22 @@ Allows security actions for to be applied to code using declarative security. - controls the ability of a Web browser control to run in a Windows Presentation Foundation (WPF) application. The scope of the declaration that is allowed depends on the that is used. - - The security information declared by a security attribute is stored in the metadata of the attribute target and is accessed by the system at run time. Security attributes are used only for declarative security. For imperative security, use the corresponding permission class, . - -## XAML Attribute Usage + controls the ability of a Web browser control to run in a Windows Presentation Foundation (WPF) application. The scope of the declaration that is allowed depends on the that is used. + +The security information declared by a security attribute is stored in the metadata of the attribute target and is accessed by the system at run time. Security attributes are used only for declarative security. For imperative security, use the corresponding permission class, . This class is not typically used in XAML. - + ## Examples -The following example shows how to demand that the calling code has unrestricted permission to create a Web browser control. - - :::code language="csharp" source="~/snippets/csharp/System.Security.Permissions/WebBrowserPermission/.ctor/Window1.xaml.cs" id="Snippetwebbrowserpermissionattribute3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/WebBrowserPermissionsSnippets/visualbasic/window1.xaml.vb" id="Snippetwebbrowserpermissionattribute3"::: - - ]]> - +The following example shows how to demand that the calling code has unrestricted permission to create a Web browser control. + +:::code language="csharp" source="~/snippets/csharp/System.Security.Permissions/WebBrowserPermission/.ctor/Window1.xaml.cs" id="Snippetwebbrowserpermissionattribute3"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/WebBrowserPermissionsSnippets/visualbasic/window1.xaml.vb" id="Snippetwebbrowserpermissionattribute3"::: + ]]> Extending Metadata Using Attributes @@ -105,22 +98,22 @@ The following example shows how to demand that the calling code has unrestricted One of the values. Initializes a new instance of the class with the specified . - property is . - -## XAML Attribute Usage - Members of this class are either not typically used in XAML, or cannot be used in XAML. - - - -## Examples - The following example shows how to define a . - + property is . + +## XAML Attribute Usage + Members of this class are either not typically used in XAML, or cannot be used in XAML. + + + +## Examples + The following example shows how to define a . + :::code language="csharp" source="~/snippets/csharp/System.Security.Permissions/WebBrowserPermission/.ctor/Window1.xaml.cs" id="Snippetwebbrowserpermissionattribute4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/WebBrowserPermissionsSnippets/visualbasic/window1.xaml.vb" id="Snippetwebbrowserpermissionattribute4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/WebBrowserPermissionsSnippets/visualbasic/window1.xaml.vb" id="Snippetwebbrowserpermissionattribute4"::: + ]]> @@ -155,16 +148,16 @@ The following example shows how to demand that the calling code has unrestricted Creates and returns a new instance of the class. A corresponding to the security declaration. - method is called by the security system, not by application code. - - The security information described by is stored in the metadata of the attribute target, which is the class to which is applied. The system accesses the information at run time. The system uses the returned by to convert the security information of the attribute target to a serializable form stored in metadata. - -## XAML Attribute Usage - Members of this class are either not typically used in XAML, or cannot be used in XAML. - + method is called by the security system, not by application code. + + The security information described by is stored in the metadata of the attribute target, which is the class to which is applied. The system accesses the information at run time. The system uses the returned by to convert the security information of the attribute target to a serializable form stored in metadata. + +## XAML Attribute Usage + Members of this class are either not typically used in XAML, or cannot be used in XAML. + ]]> @@ -204,22 +197,22 @@ The following example shows how to demand that the calling code has unrestricted Gets or sets the current Web browser permission level for the . The state of the current Web browser permission level. - . - -## XAML Attribute Usage - Members of this class are either not typically used in XAML, or cannot be used in XAML. - - - -## Examples - The following example shows how to demand that the calling code has permission to create a Web browser control that runs at a safe level. - + . + +## XAML Attribute Usage + Members of this class are either not typically used in XAML, or cannot be used in XAML. + + + +## Examples + The following example shows how to demand that the calling code has permission to create a Web browser control that runs at a safe level. + :::code language="csharp" source="~/snippets/csharp/System.Security.Permissions/WebBrowserPermission/.ctor/Window1.xaml.cs" id="Snippetwebbrowserpermissionattribute2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/WebBrowserPermissionsSnippets/visualbasic/window1.xaml.vb" id="Snippetwebbrowserpermissionattribute2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/WebBrowserPermissionsSnippets/visualbasic/window1.xaml.vb" id="Snippetwebbrowserpermissionattribute2"::: + ]]> diff --git a/xml/System.Security/SecureString.xml b/xml/System.Security/SecureString.xml index ed2901e51a1..0f0107f2de9 100644 --- a/xml/System.Security/SecureString.xml +++ b/xml/System.Security/SecureString.xml @@ -54,138 +54,15 @@ Represents text that should be kept confidential, such as by deleting it from computer memory when no longer needed. This class cannot be inherited. - - [!IMPORTANT] -> We recommend that you don't use the `SecureString` class for new development on .NET (Core) or when you migrate existing code to .NET (Core). For more information, see [SecureString shouldn't be used](https://github.com/dotnet/platform-compat/blob/master/docs/DE0001.md). - - is a string type that provides a measure of security. It tries to avoid storing potentially sensitive strings in process memory as plain text. (For limitations, however, see the [How secure is SecureString?](#HowSecure) section.) The value of an instance of is automatically protected using a mechanism supported by the underlying platform when the instance is initialized or when the value is modified. Your application can render the instance immutable and prevent further modification by invoking the method. - - The maximum length of a instance is 65,536 characters. - -> [!IMPORTANT] -> This type implements the interface. When you have finished using an instance of the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - - The class and its members are not visible to COM. For more information, see . - - In this section: - - [String vs. SecureString](#vsString) - [SecureString operations](#Ops) - [SecureString and interop](#interop) - [How secure is SecureString?](#HowSecure) - - -## String versus SecureString - An instance of the class is both immutable and, when no longer needed, cannot be programmatically scheduled for garbage collection; that is, the instance is read-only after it is created, and it is not possible to predict when the instance will be deleted from computer memory. Because instances are immutable, operations that appear to modify an existing instance actually create a copy of it to manipulate. Consequently, if a object contains sensitive information such as a password, credit card number, or personal data, there is a risk the information could be revealed after it is used because your application cannot delete the data from computer memory. - - A object is similar to a object in that it has a text value. However, the value of a object is pinned in memory, may use a protection mechanism, such as encryption, provided by the underlying operating system, can be modified until your application marks it as read-only, and can be deleted from computer memory either by your application calling the method or by the .NET Framework garbage collector. - - For a discussion of the limitations of the class, see the [How secure is SecureString?](#HowSecure) section. - - [Back to top](#top) - - -## SecureString operations - The class includes members that allow you to do the following: - - Instantiate a object - You instantiate a object by calling its parameterless constructor. - - Add characters to a object - You can add a single character at a time to a object by calling its or method. - -> [!IMPORTANT] -> A object should never be constructed from a , because the sensitive data is already subject to the memory persistence consequences of the immutable class. The best way to construct a object is from a character-at-a-time unmanaged source, such as the method. - - Remove characters from a object - You can replace an individual character by calling the method, remove an individual character by calling the method, or remove all characters from the instance by calling the method. - - Make the object read-only - Once you have defined the string that the object represents, you call its method to make the string read-only. - - Get information about the object - The class has only two members that provide information about the string: its property, which indicates the number of UTF16-encoded code units in the string; and the , method, which indicates whether the instance is read-only. - - Release the memory allocated to the instance - Because implements the interface, you release its memory by calling the method. - - The class has no members that inspect, compare, or convert the value of a . The absence of such members helps protect the value of the instance from accidental or malicious exposure. Use appropriate members of the class, such as the method, to manipulate the value of a object. - - The .NET Framework Class Library commonly uses instances in the following ways: - -- To provide password information to a process by using the structure or by calling an overload of the method that has a parameter of type . - -- To provide network password information by calling a class constructor that has a parameter of type or by using the property. - -- To provide password information for SQL Server Authentication by calling the constructor or retrieving the value of the property. - -- To pass a string to unmanaged code. For more information, see the [SecureString and interop](#interop) section. - - [Back to top](#top) - - -## SecureString and interop - Because the operating system does not directly support , you must convert the value of the object to the required string type before passing the string to a native method. The class has five methods that do this: - -- , which converts the string value to a binary string (BSTR) recognized by COM. - -- and , which copy the string value to an ANSI string in unmanaged memory. - -- and , which copy the string value to a Unicode string in unmanaged memory. - - Each of these methods creates a clear-text string in unmanaged memory. It is the responsibility of the developer to zero out and free that memory as soon as it is no longer needed. Each of the string conversion and memory allocation methods has a corresponding method to zero out and free the allocated memory: - -|Allocation and conversion method|Zero and free method| -|--------------------------------------|--------------------------| -||| -||| -||| -||| -||| - - [Back to top](#top) - - -## How secure is SecureString? - When created properly, a instance provides more data protection than a . When creating a string from a character-at-a-time source, creates multiple intermediate in memory, whereas creates just a single instance. Garbage collection of objects is non-deterministic. In addition, because its memory is not pinned, the garbage collector will make additional copies of values when moving and compacting memory. In contrast, the memory allocated to a object is pinned, and that memory can be freed by calling the method. - - Although data stored in a instance is more secure than data stored in a instance, there are significant limitations on how secure a instance is. These include: - - Platform - On the Windows operating system, the contents of a instance's internal character array are encrypted. However, whether because of missing APIs or key management issues, encryption is not available on all platforms. Because of this platform dependency, does not encrypt the internal storage on non-Windows platform. Other techniques are used on those platforms to provide additional protection. - - Duration - Even if the implementation is able to take advantage of encryption, the plain text assigned to the instance may be exposed at various times: - -- Because Windows doesn't offer a secure string implementation at the operating system level, the .NET Framework still has to convert the secure string value to its plain text representation in order to use it. - -- Whenever the value of the secure string is modified by methods such as or , it must be decrypted (that is, converted back to plain text), modified, and then encrypted again. - -- If the secure string is used in an interop call, it must be converted to an ANSI string, a Unicode string, or a binary string (BSTR). For more information, see the [SecureString and interop](#interop) section. - - The time interval for which the instance's value is exposed is merely shortened in comparison to the class. - - Storage versus usage - More generally, the class defines a storage mechanism for string values that should be protected or kept confidential. However, outside of the .NET Framework itself, no usage mechanism supports . This means that the secure string must be converted to a usable form (typically a clear text form) that can be recognized by its target, and that decryption and conversion must occur in user space. - - Overall, is more secure than because it limits the exposure of sensitive string data. However, those strings may still be exposed to any process or operation that has access to raw memory, such as a malicious process running on the host computer, a process dump, or a user-viewable swap file. Instead of using to protect passwords, the recommended alternative is to use an opaque handle to credentials that are stored outside of the process. - - [Back to top](#top) - - - -## Examples - The following example demonstrates how to use a to secure a user's password for use as a credential to start a new process. - - :::code language="csharp" source="~/snippets/csharp/System.Security/SecureString/Overview/ctor4.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.SecureString.Ctor/vb/ctor4.vb" id="Snippet4"::: - - ]]> - + For more information about this API, see Supplemental API remarks for SecureString. + + to secure a user's password for use as a credential to start a new process. + +:::code language="csharp" source="~/snippets/csharp/System.Security/SecureString/Overview/ctor4.cs" id="Snippet4"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.SecureString.Ctor/vb/ctor4.vb" id="Snippet4"::: + ]]> + @@ -243,21 +120,21 @@ Initializes a new instance of the class. - object. It then calls the method to add an array of characters to it. - + object. It then calls the method to add an array of characters to it. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.SecureString.Ctor/cpp/Ctor2.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Security/SecureString/Overview/Ctor2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.SecureString.Ctor/vb/ctor2.vb" id="Snippet2"::: - - The following example creates a object from the value of a object. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.SecureString.Ctor/vb/ctor2.vb" id="Snippet2"::: + + The following example creates a object from the value of a object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.SecureString.Ctor/cpp/Ctor3.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Security/SecureString/Overview/Ctor3.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.SecureString.Ctor/vb/Ctor3.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.SecureString.Ctor/vb/Ctor3.vb" id="Snippet3"::: + ]]> An error occurred while protecting or unprotecting the value of this instance. @@ -313,25 +190,25 @@ A pointer to an array of objects. The number of elements of to include in the new instance. - Initializes a new instance of the class from a subarray of objects. - + Initializes a new instance of the class from a subarray of objects. + This constructor is not CLS-compliant. The CLS-compliant alternative is . - object to the number of characters in `value` specified by `length`; the value of the instance is then encrypted. - - In C#, this constructor is defined only in the context of unsafe code. - - - -## Examples - The following example instantiates a new object by passing its constructor a pointer to a character array. - + object to the number of characters in `value` specified by `length`; the value of the instance is then encrypted. + + In C#, this constructor is defined only in the context of unsafe code. + + + +## Examples + The following example instantiates a new object by passing its constructor a pointer to a character array. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.security.securestring.ctor2/cpp/ctor1.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Security/SecureString/.ctor/ctor1.cs" id="Snippet1"::: - + :::code language="csharp" source="~/snippets/csharp/System.Security/SecureString/.ctor/ctor1.cs" id="Snippet1"::: + ]]> @@ -395,26 +272,26 @@ A character to append to this secure string. Appends a character to the end of the current secure string. - , , , , and methods affect the value of a object. - + , , , , and methods affect the value of a object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/SecureString.xAt/CPP/SecureString.xAt.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security/SecureString/AppendChar/xat.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/SecureString.xAt/VB/xat.vb" id="Snippet1"::: - - The following example demonstrates how the and methods can be used to collect the characters in a password. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/SecureString.xAt/VB/xat.vb" id="Snippet1"::: + + The following example demonstrates how the and methods can be used to collect the characters in a password. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/SecureString.xChar/CPP/SecureString.xChar.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security/SecureString/AppendChar/xchar.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/SecureString.xChar/VB/xchar.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/SecureString.xChar/VB/xchar.vb" id="Snippet1"::: + ]]> This secure string has already been disposed. @@ -469,20 +346,20 @@ Deletes the value of the current secure string. - , , , , and methods affect the value of a object. - + , , , , and methods affect the value of a object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/SecureString.xAt/CPP/SecureString.xAt.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security/SecureString/AppendChar/xat.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/SecureString.xAt/VB/xat.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/SecureString.xAt/VB/xat.vb" id="Snippet1"::: + ]]> This secure string has already been disposed. @@ -541,11 +418,11 @@ Creates a copy of the current secure string. A duplicate of this secure string. - is marked read-only, the copy of that instance will not be read-only. - + is marked read-only, the copy of that instance will not be read-only. + ]]> This secure string has already been disposed. @@ -603,13 +480,13 @@ Releases all resources used by the current object. - method writes binary zeroes to the allocated memory that contains the value of this object, then frees the allocated memory. - - For more information, see [Garbage Collection](/dotnet/standard/garbage-collection/). - + method writes binary zeroes to the allocated memory that contains the value of this object, then frees the allocated memory. + + For more information, see [Garbage Collection](/dotnet/standard/garbage-collection/). + ]]> @@ -669,31 +546,31 @@ The character to insert. Inserts a character in this secure string at the specified index position. - method yields the same results as the method, which inserts a character at the end of a secure string, if the `index` parameter of is set to the length of this instance. - - - -## Examples - The following example demonstrates how the , , , , and methods affect the value of a object. - + method yields the same results as the method, which inserts a character at the end of a secure string, if the `index` parameter of is set to the length of this instance. + + + +## Examples + The following example demonstrates how the , , , , and methods affect the value of a object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/SecureString.xAt/CPP/SecureString.xAt.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security/SecureString/AppendChar/xat.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/SecureString.xAt/VB/xat.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/SecureString.xAt/VB/xat.vb" id="Snippet1"::: + ]]> This secure string has already been disposed. This secure string is read-only. - is less than zero, or greater than the length of this secure string. - - -or- - + is less than zero, or greater than the length of this secure string. + + -or- + Performing this operation would make the length of this secure string greater than 65,536 characters. An error occurred while protecting or unprotecting the value of this secure string. @@ -746,11 +623,11 @@ if this secure string is marked read-only; otherwise, . - is marked read-only by the method, any attempt to modify the value of the instance throws an . Use the method to test whether a is read-only before attempting to modify it. - + is marked read-only by the method, any attempt to modify the value of the instance throws an . Use the method to test whether a is read-only before attempting to modify it. + ]]> This secure string has already been disposed. @@ -803,13 +680,13 @@ Gets the number of characters in the current secure string. The number of objects in this secure string. - property returns the number of objects in this instance, not the number of Unicode characters. A Unicode character might be represented by more than one object. - - The maximum length of a instance is 65,536 characters. - + property returns the number of objects in this instance, not the number of Unicode characters. A Unicode character might be represented by more than one object. + + The maximum length of a instance is 65,536 characters. + ]]> This secure string has already been disposed. @@ -861,24 +738,24 @@ Makes the text value of this secure string read-only. - class with the constructors, and modify the value with the , , , , and methods. - - After you have made your final modifications, use the method to make the value of the instance immutable (read-only). After the value is marked as read-only, any further attempt to modify it throws an . - - The effect of invoking is permanent because the class provides no means to make the secure string modifiable again. Use the method to test whether an instance of is read-only. - - - -## Examples - The following example demonstrates how the and methods can be used to collect the characters in a password. After the password is collected, it is made read-only. - + class with the constructors, and modify the value with the , , , , and methods. + + After you have made your final modifications, use the method to make the value of the instance immutable (read-only). After the value is marked as read-only, any further attempt to modify it throws an . + + The effect of invoking is permanent because the class provides no means to make the secure string modifiable again. Use the method to test whether an instance of is read-only. + + + +## Examples + The following example demonstrates how the and methods can be used to collect the characters in a password. After the password is collected, it is made read-only. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/SecureString.xChar/CPP/SecureString.xChar.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security/SecureString/AppendChar/xchar.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/SecureString.xChar/VB/xchar.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/SecureString.xChar/VB/xchar.vb" id="Snippet1"::: + ]]> This secure string has already been disposed. @@ -938,28 +815,28 @@ The index position of a character in this secure string. Removes the character at the specified index position from this secure string. - , , , , and methods affect the value of a object. - + , , , , and methods affect the value of a object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/SecureString.xAt/CPP/SecureString.xAt.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security/SecureString/AppendChar/xat.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/SecureString.xAt/VB/xat.vb" id="Snippet1"::: - - The following example demonstrates how the and methods can be used to collect the characters in a password. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/SecureString.xAt/VB/xat.vb" id="Snippet1"::: + + The following example demonstrates how the and methods can be used to collect the characters in a password. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/SecureString.xChar/CPP/SecureString.xChar.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security/SecureString/AppendChar/xchar.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/SecureString.xChar/VB/xchar.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/SecureString.xChar/VB/xchar.vb" id="Snippet1"::: + ]]> This secure string has already been disposed. @@ -1024,22 +901,22 @@ A character that replaces the existing character. Replaces the existing character at the specified index position with another character. - , , , , and methods affect the value of a object. - + , , , , and methods affect the value of a object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/SecureString.xAt/CPP/SecureString.xAt.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security/SecureString/AppendChar/xat.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/SecureString.xAt/VB/xat.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/SecureString.xAt/VB/xat.vb" id="Snippet1"::: + ]]> This secure string has already been disposed. diff --git a/xml/System.Text.RegularExpressions/Regex.xml b/xml/System.Text.RegularExpressions/Regex.xml index 92f9706e819..bf6fb46c8b4 100644 --- a/xml/System.Text.RegularExpressions/Regex.xml +++ b/xml/System.Text.RegularExpressions/Regex.xml @@ -68,157 +68,7 @@ Represents an immutable regular expression. - - class represents the .NET Framework's regular expression engine. It can be used to quickly parse large amounts of text to find specific character patterns; to extract, edit, replace, or delete text substrings; and to add the extracted strings to a collection to generate a report. - -> [!NOTE] -> If your primary interest is to validate a string by determining whether it conforms to a particular pattern, you can use the class. - - To use regular expressions, you define the pattern that you want to identify in a text stream by using the syntax documented in [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). Next, you can optionally instantiate a object. Finally, you call a method that performs some operation, such as replacing text that matches the regular expression pattern, or identifying a pattern match. - -> [!NOTE] -> For some common regular expression patterns, see [Regular Expression Examples](/dotnet/standard/base-types/regular-expression-examples). There are also a number of online libraries of regular expression patterns, such as the one at [Regular-Expressions.info](https://www.regular-expressions.info/examples.html). - - For more information about using the class, see the following sections in this topic: - -- [Regex vs. String Methods](#regex_vs_string) - -- [Static vs. Instance Methods](#static_vs_instance) - -- [Performing Regular Expression Operations](#regex_ops) - -- [Defining a Time-Out Value](#define_timeout) - - For more information about the regular expression language, see [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference) or download and print one of these brochures: - - [Quick Reference in Word (.docx) format](https://download.microsoft.com/download/D/2/4/D240EBF6-A9BA-4E4F-A63F-AEB6DA0B921C/Regular%20expressions%20quick%20reference.docx) - [Quick Reference in PDF (.pdf) format](https://download.microsoft.com/download/D/2/4/D240EBF6-A9BA-4E4F-A63F-AEB6DA0B921C/Regular%20expressions%20quick%20reference.pdf) - - -## Regex vs. String Methods - The class includes several search and comparison methods that you can use to perform pattern matching with text. For example, the , , and methods determine whether a string instance contains a specified substring; and the , , , and methods return the starting position of a specified substring in a string. Use the methods of the class when you are searching for a specific string. Use the class when you are searching for a specific pattern in a string. For more information and examples, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions). - - [Back to Remarks](#remarks) - - -## Static vs. Instance Methods - After you define a regular expression pattern, you can provide it to the regular expression engine in either of two ways: - -- By instantiating a object that represents the regular expression. To do this, you pass the regular expression pattern to a constructor. A object is immutable; when you instantiate a object with a regular expression, that object's regular expression cannot be changed. - -- By supplying both the regular expression and the text to search to a `static` (`Shared` in Visual Basic) method. This enables you to use a regular expression without explicitly creating a object. - - All pattern identification methods include both static and instance overloads. - - The regular expression engine must compile a particular pattern before the pattern can be used. Because objects are immutable, this is a one-time procedure that occurs when a class constructor or a static method is called. To eliminate the need to repeatedly compile a single regular expression, the regular expression engine caches the compiled regular expressions used in static method calls. As a result, regular expression pattern-matching methods offer comparable performance for static and instance methods. - -> [!IMPORTANT] -> In the .NET Framework versions 1.0 and 1.1, all compiled regular expressions, whether they were used in instance or static method calls, were cached. Starting with the .NET Framework 2.0, only regular expressions used in static method calls are cached. - - However, caching can adversely affect performance in the following two cases: - -- When you use static method calls with a large number of regular expressions. By default, the regular expression engine caches the 15 most recently used static regular expressions. If your application uses more than 15 static regular expressions, some regular expressions must be recompiled. To prevent this recompilation, you can increase the property. - -- When you instantiate new objects with regular expressions that have previously been compiled. For example, the following code defines a regular expression to locate duplicated words in a text stream. Although the example uses a single regular expression, it instantiates a new object to process each line of text. This results in the recompilation of the regular expression with each iteration of the loop. - - :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Overview/caching1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.class.caching/vb/caching1.vb" id="Snippet1"::: - - To prevent recompilation, you should instantiate a single object that is accessible to all code that requires it, as shown in the following rewritten example. - - :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Overview/caching1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.class.caching/vb/caching1.vb" id="Snippet2"::: - - [Back to Remarks](#remarks) - - -## Performing Regular Expression Operations - Whether you decide to instantiate a object and call its methods or call static methods, the class offers the following pattern-matching functionality: - -- Validation of a match. You call the method to determine whether a match is present. - -- Retrieval of a single match. You call the method to retrieve a object that represents the first match in a string or in part of a string. Subsequent matches can be retrieved by calling the method. - -- Retrieval of all matches. You call the method to retrieve a object that represents all the matches found in a string or in part of a string. - -- Replacement of matched text. You call the method to replace matched text. The replacement text can also be defined by a regular expression. In addition, some of the methods include a parameter that enables you to programmatically define the replacement text. - -- Creation of a string array that is formed from parts of an input string. You call the method to split an input string at positions that are defined by the regular expression. - - In addition to its pattern-matching methods, the class includes several special-purpose methods: - -- The method escapes any characters that may be interpreted as regular expression operators in a regular expression or input string. - -- The method removes these escape characters. - -- The method creates an assembly that contains predefined regular expressions. The .NET Framework contains examples of these special-purpose assemblies in the namespace. - - [Back to Remarks](#remarks) - - -## Defining a Time-Out Value - .NET supports a full-featured regular expression language that provides substantial power and flexibility in pattern matching. However, the power and flexibility come at a cost: the risk of poor performance. Regular expressions that perform poorly are surprisingly easy to create. In some cases, regular expression operations that rely on excessive backtracking can appear to stop responding when they process text that nearly matches the regular expression pattern. For more information about the .NET Regular Expression engine, see [Details of Regular Expression Behavior](/dotnet/standard/base-types/details-of-regular-expression-behavior). For more information about excessive backtracking, see [Backtracking](/dotnet/standard/base-types/backtracking-in-regular-expressions). - - Starting with the .NET Framework 4.5, you can define a time-out interval for regular expression matches to limit excessive backtracking. Depending on the regular expression pattern and the input text, the execution time may exceed the specified time-out interval, but it will not spend more time backtracking than the specified time-out interval. If the regular expression engine times out, it throws a exception. In most cases, this prevents the regular expression engine from wasting processing power by trying to match text that nearly matches the regular expression pattern. It also could indicate, however, that the time-out interval has been set too low, or that the current machine load has caused an overall degradation in performance. - - How you handle the exception depends on the cause of the exception. If the exception occurs because the time-out interval is set too low or because of excessive machine load, you can increase the time-out interval and retry the matching operation. If the exception occurs because the regular expression relies on excessive backtracking, you can assume that a match does not exist, and, optionally, you can log information that will help you modify the regular expression pattern. - - You can set a time-out interval by calling the constructor when you instantiate a regular expression object. For static methods, you can set a time-out interval by calling an overload of a matching method that has a `matchTimeout` parameter. If you do not set a time-out value explicitly, the default time-out value is determined as follows: - -- By using the application-wide time-out value, if one exists. This can be any time-out value that applies to the application domain in which the object is instantiated or the static method call is made. You can set the application-wide time-out value by calling the method to assign the string representation of a value to the "REGEX_DEFAULT_MATCH_TIMEOUT" property. - -- By using the value , if no application-wide time-out value has been set. - -> [!IMPORTANT] -> We recommend that you set a time-out value in all regular expression pattern-matching operations. For more information, see [Best Practices for Regular Expressions](/dotnet/standard/base-types/best-practices). - - [Back to Remarks](#remarks) - - - -## Examples - The following example uses a regular expression to check for repeated occurrences of words in a string. The regular expression `\b(?\w+)\s+(\k)\b` can be interpreted as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`\b`|Start the match at a word boundary.| -|`(?\w+)`|Match one or more word characters up to a word boundary. Name this captured group `word`.| -|`\s+`|Match one or more white-space characters.| -|`(\k)`|Match the captured group that is named `word`.| -|`\b`|Match a word boundary.| - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Regex_Words/CPP/words.cpp" id="Snippet0"::: - :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/MatchCollection/Overview/words.cs" interactive="try-dotnet" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Regex_Words/VB/words.vb" id="Snippet0"::: - - The following example illustrates the use of a regular expression to check whether a string either represents a currency value or has the correct format to represent a currency value. In this case, the regular expression is built dynamically from the , , , , and properties for the en-US culture. The resulting regular expression is `^\s*[\+-]?\s?\$?\s?(\d*\.?\d{2}?){1}$`. This regular expression can be interpreted as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`^`|Start at the beginning of the string.| -|`\s*`|Match zero or more white-space characters.| -|`[\+-]?`|Match zero or one occurrence of either the positive sign or the negative sign.| -|`\s?`|Match zero or one white-space character.| -|`\$?`|Match zero or one occurrence of the dollar sign.| -|`\s?`|Match zero or one white-space character.| -|`\d*`|Match zero or more decimal digits.| -|`\.?`|Match zero or one decimal point symbol.| -|`(\d{2})?`|Capturing group 1: Match two decimal digits zero or one time.| -|`(\d*\.?(\d{2})?){1}`|Match the pattern of integral and fractional digits separated by a decimal point symbol at least one time.| -|`$`|Match the end of the string.| - - In this case, the regular expression assumes that a valid currency string does not contain group separator symbols, and that it has either no fractional digits or the number of fractional digits defined by the specified culture's property. - - :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Overview/regex_example1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.class/vb/regex_example1.vb" id="Snippet1"::: - - Because the regular expression in this example is built dynamically, you don't know at design time whether the currency symbol, decimal sign, or positive and negative signs of the specified culture (en-US in this example) might be misinterpreted by the regular expression engine as regular expression language operators. To prevent any misinterpretation, the example passes each dynamically generated string to the method. - - ]]> - + For more information about this API, see Supplemental API remarks for Regex. The class is immutable (read-only) and thread safe. objects can be created on any thread and shared between threads. For more information, see [Thread Safety](/dotnet/standard/base-types/thread-safety-in-regular-expressions). .NET Regular Expressions @@ -284,11 +134,11 @@ Initializes a new instance of the class. - class. - + class. + ]]> @@ -347,27 +197,27 @@ The regular expression pattern to match. Initializes a new instance of the class for the specified regular expression. - constructor is equivalent to calling the constructor with a value of for the `options` argument. - - A object is immutable, which means that it can be used only for the match pattern you define when you create it. However, it can be used any number of times without being recompiled. - - This constructor instantiates a regular expression object that attempts a case-sensitive match of any alphabetical characters defined in `pattern`. For a case-insensitive match, use the constructor. - - - -## Examples - The following example illustrates how to use this constructor to instantiate a regular expression that matches any word that begins with the letters "a" or "t". - + constructor is equivalent to calling the constructor with a value of for the `options` argument. + + A object is immutable, which means that it can be used only for the match pattern you define when you create it. However, it can be used any number of times without being recompiled. + + This constructor instantiates a regular expression object that attempts a case-sensitive match of any alphabetical characters defined in `pattern`. For a case-insensitive match, use the constructor. + + + +## Examples + The following example illustrates how to use this constructor to instantiate a regular expression that matches any word that begins with the letters "a" or "t". + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/.ctor/constructors1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Constructors/vb/constructors1.vb" id="Snippet1"::: - - Note that the regular expression pattern cannot match the word "The" at the beginning of the text, because comparisons are case-sensitive by default. For an example of case-insensitive comparison, see the constructor. - + + Note that the regular expression pattern cannot match the word "The" at the beginning of the text, because comparisons are case-sensitive by default. For an example of case-insensitive comparison, see the constructor. + ]]> A regular expression parsing error occurred. @@ -489,23 +339,23 @@ A bitwise combination of the enumeration values that modify the regular expression. Initializes a new instance of the class for the specified regular expression, with options that modify the pattern. - object is immutable, which means that it can be used only for the match parameters you define when you create it. However, it can be used any number of times without being recompiled. - - - -## Examples - The following example illustrates how to use this constructor to instantiate a regular expression that matches any word that begins with the letters "a" or "t". - + object is immutable, which means that it can be used only for the match parameters you define when you create it. However, it can be used any number of times without being recompiled. + + + +## Examples + The following example illustrates how to use this constructor to instantiate a regular expression that matches any word that begins with the letters "a" or "t". + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/.ctor/Constructors2.cs" interactive="try-dotnet" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Constructors/vb/Constructors2.vb" id="Snippet2"::: - - Note that the match collection includes the word "The" that begins the text because the `options` parameter has defined case-insensitive comparisons. - + + Note that the match collection includes the word "The" that begins the text because the `options` parameter has defined case-insensitive comparisons. + ]]> A regular expression parsing error occurred. @@ -569,59 +419,59 @@ A time-out interval, or to indicate that the method should not time out. Initializes a new instance of the class for the specified regular expression, with options that modify the pattern and a value that specifies how long a pattern matching method should attempt a match before it times out. - object is immutable, which means that it can be used only for the match pattern that you define when you create it. However, it can be used any number of times without being recompiled. - - The `matchTimeout` parameter specifies how long a pattern-matching method should try to find a match before it times out. If no match is found in that time interval, the pattern-matching method throws a exception. `matchTimeout` overrides any default time-out value defined for the application domain in which the object is created. The instance pattern-matching methods that observe the `matchTimeout` time-out interval include the following: - -- - -- - -- - -- - -- - -- - - Setting a time-out interval prevents regular expressions that rely on excessive backtracking from appearing to stop responding when they process input that contains near matches. For more information, see [Best Practices for Regular Expressions](/dotnet/standard/base-types/best-practices) and [Backtracking](/dotnet/standard/base-types/backtracking-in-regular-expressions). To set a reasonable time-out interval, consider the following factors: - -- The length and complexity of the regular expression pattern. Longer and more complex regular expressions require more time than shorter and simpler ones. - -- The expected machine load. Processing takes more time on systems that have high CPU and memory utilization. - - - -## Examples - The following example calls the constructor to instantiate a object with a time-out value of one second. The regular expression pattern `(a+)+$`, which matches one or more sequences of one or more "a" characters at the end of a line, is subject to excessive backtracking. If a is thrown, the example increases the time-out value up to the maximum value of three seconds. Otherwise, it abandons the attempt to match the pattern. + object is immutable, which means that it can be used only for the match pattern that you define when you create it. However, it can be used any number of times without being recompiled. + + The `matchTimeout` parameter specifies how long a pattern-matching method should try to find a match before it times out. If no match is found in that time interval, the pattern-matching method throws a exception. `matchTimeout` overrides any default time-out value defined for the application domain in which the object is created. The instance pattern-matching methods that observe the `matchTimeout` time-out interval include the following: + +- + +- + +- + +- + +- + +- + + Setting a time-out interval prevents regular expressions that rely on excessive backtracking from appearing to stop responding when they process input that contains near matches. For more information, see [Best Practices for Regular Expressions](/dotnet/standard/base-types/best-practices) and [Backtracking](/dotnet/standard/base-types/backtracking-in-regular-expressions). To set a reasonable time-out interval, consider the following factors: + +- The length and complexity of the regular expression pattern. Longer and more complex regular expressions require more time than shorter and simpler ones. + +- The expected machine load. Processing takes more time on systems that have high CPU and memory utilization. + + + +## Examples + The following example calls the constructor to instantiate a object with a time-out value of one second. The regular expression pattern `(a+)+$`, which matches one or more sequences of one or more "a" characters at the end of a line, is subject to excessive backtracking. If a is thrown, the example increases the time-out value up to the maximum value of three seconds. Otherwise, it abandons the attempt to match the pattern. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/.ctor/ctor1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.ctor/vb/ctor1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.ctor/vb/ctor1.vb" id="Snippet1"::: + ]]> A regular expression parsing error occurred. is . - is not a valid value. - - -or- - + is not a valid value. + + -or- + is negative, zero, or greater than approximately 24 days. - We recommend that you set the parameter to an appropriate value, such as two seconds. If you disable time-outs by specifying , the regular expression engine offers slightly better performance. However, you should disable time-outs only under the following conditions: - -- When the input processed by a regular expression is derived from a known and trusted source or consists of static text. This excludes text that has been dynamically input by users. - -- When the regular expression pattern has been thoroughly tested to ensure that it efficiently handles matches, non-matches, and near matches. - + We recommend that you set the parameter to an appropriate value, such as two seconds. If you disable time-outs by specifying , the regular expression engine offers slightly better performance. However, you should disable time-outs only under the following conditions: + +- When the input processed by a regular expression is derived from a known and trusted source or consists of static text. This excludes text that has been dynamically input by users. + +- When the regular expression pattern has been thoroughly tested to ensure that it efficiently handles matches, non-matches, and near matches. + - When the regular expression pattern contains no language elements that are known to cause excessive backtracking when processing a near match. Backtracking in Regular Expressions @@ -673,13 +523,13 @@ Gets or sets the maximum number of entries in the current static cache of compiled regular expressions. The maximum number of entries in the static cache. - class maintains an internal cache of compiled regular expressions used in static method calls. If the value specified in a set operation is less than the current cache size, cache entries are discarded until the cache size is equal to the specified value. - - By default, the cache holds 15 compiled static regular expressions. Your application typically will not have to modify the size of the cache. Use the property only when you want to turn off caching or when you have an unusually large cache. - + class maintains an internal cache of compiled regular expressions used in static method calls. If the value specified in a set operation is less than the current cache size, cache entries are discarded until the cache size is equal to the specified value. + + By default, the cache holds 15 compiled static regular expressions. Your application typically will not have to modify the size of the cache. Use the property only when you want to turn off caching or when you have an unusually large cache. + ]]> The value in a set operation is less than zero. @@ -793,13 +643,13 @@ Gets or sets a dictionary that maps named capturing groups to their index values. A dictionary that maps named capturing groups to their index values. - class. - - A set operation attempts to convert the value assigned to the property to a object; if this conversion fails, it calls the constructor. - + class. + + A set operation attempts to convert the value assigned to the property to a object; if this conversion fails, it calls the constructor. + ]]> The value assigned to the property in a set operation is . @@ -910,13 +760,13 @@ Gets or sets a dictionary that maps numbered capturing groups to their index values. A dictionary that maps numbered capturing groups to their index values. - class. - - A set operation attempts to convert the value assigned to the property to a object; if this conversion fails, it calls the constructor. - + class. + + A set operation attempts to convert the value assigned to the property to a object; if this conversion fails, it calls the constructor. + ]]> The value assigned to the property in a set operation is . @@ -1018,13 +868,13 @@ Compiles regular expressions and saves them to disk in a single assembly. - [!NOTE] > On .NET Core and .NET 5+, calls to the `Regex.CompileToAssembly` method throw a . Writing out an assembly is not supported. - + ]]> @@ -1078,49 +928,49 @@ The file name of the assembly. Compiles one or more specified objects to a named assembly. - method generates a .NET Framework assembly in which each regular expression defined in the `regexinfos` array is represented by a class. Typically, the method is called from a separate application that generates an assembly of compiled regular expressions. Each regular expression included in the assembly has the following characteristics: - -- It is derived from the class. - -- It is assigned the fully qualified name that is defined by the `fullnamespace` and `name` parameters of its corresponding object. - -- It has a default (or parameterless) constructor. - - Ordinarily, the code that instantiates and uses the compiled regular expression is found in an assembly or application that is separate from the code that creates the assembly. - - - -## Examples - The following example creates an assembly named RegexLib.dll. The assembly includes two compiled regular expressions. The first, `Utilities.RegularExpressions.DuplicatedString`, matches two identical contiguous words. The second, `Utilities.RegularExpressions.EmailAddress`, checks whether a string has the correct format to be an email address. - + method generates a .NET Framework assembly in which each regular expression defined in the `regexinfos` array is represented by a class. Typically, the method is called from a separate application that generates an assembly of compiled regular expressions. Each regular expression included in the assembly has the following characteristics: + +- It is derived from the class. + +- It is assigned the fully qualified name that is defined by the `fullnamespace` and `name` parameters of its corresponding object. + +- It has a default (or parameterless) constructor. + + Ordinarily, the code that instantiates and uses the compiled regular expression is found in an assembly or application that is separate from the code that creates the assembly. + + + +## Examples + The following example creates an assembly named RegexLib.dll. The assembly includes two compiled regular expressions. The first, `Utilities.RegularExpressions.DuplicatedString`, matches two identical contiguous words. The second, `Utilities.RegularExpressions.EmailAddress`, checks whether a string has the correct format to be an email address. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/CompileToAssembly/Compile1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.CompileToAssembly/vb/Compile1.vb" id="Snippet1"::: - - The regular expression that checks a string for duplicate words is then instantiated and used by the following example. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.CompileToAssembly/vb/Compile1.vb" id="Snippet1"::: + + The regular expression that checks a string for duplicate words is then instantiated and used by the following example. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/CompileToAssembly/Compile2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.CompileToAssembly/vb/Compile2.vb" id="Snippet2"::: - - Successful compilation of this second example requires a reference to RegexLib.dll (the assembly created by the first example) to be added to the project. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.CompileToAssembly/vb/Compile2.vb" id="Snippet2"::: + + Successful compilation of this second example requires a reference to RegexLib.dll (the assembly created by the first example) to be added to the project. + ]]> - The value of the parameter's property is an empty or null string. - - -or- - + The value of the parameter's property is an empty or null string. + + -or- + The regular expression pattern of one or more objects in contains invalid syntax. or is . .NET Core and .NET 5+ only: Creating an assembly of compiled regular expressions is not supported. - If you are developing on a system that has .NET Framework 4.5 or its point releases installed, you target .NET Framework 4, and you use the method to create an assembly that contains compiled regular expressions. Trying to use one of the regular expressions in that assembly on a system that has .NET Framework 4 throws an exception. To work around this problem, you can do either of the following: - -- Build the assembly that contains the compiled regular expressions on a system that has .NET Framework 4 instead of later versions installed. - + If you are developing on a system that has .NET Framework 4.5 or its point releases installed, you target .NET Framework 4, and you use the method to create an assembly that contains compiled regular expressions. Trying to use one of the regular expressions in that assembly on a system that has .NET Framework 4 throws an exception. To work around this problem, you can do either of the following: + +- Build the assembly that contains the compiled regular expressions on a system that has .NET Framework 4 instead of later versions installed. + - Instead of calling and retrieving the compiled regular expression from an assembly, use either static or instance methods with the option when you instantiate a object or call a regular expression pattern matching method. Compilation and Reuse @@ -1185,65 +1035,65 @@ An array that defines the attributes to apply to the assembly. Compiles one or more specified objects to a named assembly with the specified attributes. - method generates a .NET Framework assembly in which each regular expression defined in the `regexinfos` array is represented by a class. Typically, the method is called from a separate application that generates an assembly of compiled regular expressions. Each regular expression included in the assembly has the following characteristics: - -- It is derived from the class. - -- It is assigned the fully qualified name that is defined by the `fullnamespace` and `name` parameters of its corresponding object. - -- It has a default (or parameterless) constructor. - - Ordinarily, the code that instantiates and uses the compiled regular expression is found in an assembly or application that is separate from the code that creates the assembly. - - Because the method generates a .NET Framework assembly from a method call instead of using a particular language's class definition keyword (such as `class` in C# or `Class`...`End Class` in Visual Basic), it does not allow .NET Framework attributes to be assigned to the assembly by using the development language's standard attribute syntax. The `attributes` parameter provides an alternative method for defining the attributes that apply to the assembly. For each attribute that you want to apply to the assembly, do the following: - -1. Create an array of objects representing the parameter types of the attribute constructor that you want to call. - -2. Retrieve a object representing the attribute class that you want to apply to the new assembly. - -3. Call the method of the attribute object to retrieve a object representing the attribute constructor that you want to call. Pass the method the array of objects that represents the constructor's parameter types. - -4. Create a array that defines the parameters to pass to the attribute's constructor. - -5. Instantiate a object by passing its constructor the object retrieved in step 3 and the array created in step 4. - - You can then pass an array of these objects instead of the `attributes` parameter to the method. - - - -## Examples - The following example creates an assembly named RegexLib.dll and applies the attribute to it. The assembly includes two compiled regular expressions. The first, `Utilities.RegularExpressions.DuplicatedString`, matches two identical contiguous words. The second, `Utilities.RegularExpressions.EmailAddress`, checks whether a string has the correct format to be an email address. - + method generates a .NET Framework assembly in which each regular expression defined in the `regexinfos` array is represented by a class. Typically, the method is called from a separate application that generates an assembly of compiled regular expressions. Each regular expression included in the assembly has the following characteristics: + +- It is derived from the class. + +- It is assigned the fully qualified name that is defined by the `fullnamespace` and `name` parameters of its corresponding object. + +- It has a default (or parameterless) constructor. + + Ordinarily, the code that instantiates and uses the compiled regular expression is found in an assembly or application that is separate from the code that creates the assembly. + + Because the method generates a .NET Framework assembly from a method call instead of using a particular language's class definition keyword (such as `class` in C# or `Class`...`End Class` in Visual Basic), it does not allow .NET Framework attributes to be assigned to the assembly by using the development language's standard attribute syntax. The `attributes` parameter provides an alternative method for defining the attributes that apply to the assembly. For each attribute that you want to apply to the assembly, do the following: + +1. Create an array of objects representing the parameter types of the attribute constructor that you want to call. + +2. Retrieve a object representing the attribute class that you want to apply to the new assembly. + +3. Call the method of the attribute object to retrieve a object representing the attribute constructor that you want to call. Pass the method the array of objects that represents the constructor's parameter types. + +4. Create a array that defines the parameters to pass to the attribute's constructor. + +5. Instantiate a object by passing its constructor the object retrieved in step 3 and the array created in step 4. + + You can then pass an array of these objects instead of the `attributes` parameter to the method. + + + +## Examples + The following example creates an assembly named RegexLib.dll and applies the attribute to it. The assembly includes two compiled regular expressions. The first, `Utilities.RegularExpressions.DuplicatedString`, matches two identical contiguous words. The second, `Utilities.RegularExpressions.EmailAddress`, checks whether a string has the correct format to be an email address. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/CompileToAssembly/Compile3.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.CompileToAssembly/vb/Compile3.vb" id="Snippet3"::: - - You can verify that the attribute has been applied to the assembly by examining its manifest with a reflection utility such as ILDasm. - - The regular expression that checks a string for duplicate words is then instantiated and used by the following example. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.CompileToAssembly/vb/Compile3.vb" id="Snippet3"::: + + You can verify that the attribute has been applied to the assembly by examining its manifest with a reflection utility such as ILDasm. + + The regular expression that checks a string for duplicate words is then instantiated and used by the following example. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/CompileToAssembly/Compile2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.CompileToAssembly/vb/Compile2.vb" id="Snippet2"::: - - Successful compilation of this second example requires a reference to RegexLib.dll (the assembly created by the first example) to be added to the project. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.CompileToAssembly/vb/Compile2.vb" id="Snippet2"::: + + Successful compilation of this second example requires a reference to RegexLib.dll (the assembly created by the first example) to be added to the project. + ]]> - The value of the parameter's property is an empty or null string. - - -or- - + The value of the parameter's property is an empty or null string. + + -or- + The regular expression pattern of one or more objects in contains invalid syntax. or is . .NET Core and .NET 5+ only: Creating an assembly of compiled regular expressions is not supported. - If you are developing on a system that has .NET Framework 4.5 or its point releases installed, you target .NET Framework 4, and you use the method to create an assembly that contains compiled regular expressions. Trying to use one of the regular expressions in that assembly on a system that has .NET Framework 4 throws an exception. To work around this problem, you can do either of the following: - -- Build the assembly that contains the compiled regular expressions on a system that has .NET Framework 4 instead of later versions installed. - + If you are developing on a system that has .NET Framework 4.5 or its point releases installed, you target .NET Framework 4, and you use the method to create an assembly that contains compiled regular expressions. Trying to use one of the regular expressions in that assembly on a system that has .NET Framework 4 throws an exception. To work around this problem, you can do either of the following: + +- Build the assembly that contains the compiled regular expressions on a system that has .NET Framework 4 instead of later versions installed. + - Instead of calling and retrieving the compiled regular expression from an assembly, use either static or instance methods with the option when you instantiate a object or call a regular expression pattern matching method. Compilation and Reuse @@ -1317,39 +1167,39 @@ The name of the Win32 resource file to include in the assembly. Compiles one or more specified objects and a specified resource file to a named assembly with the specified attributes. - method generates a .NET Framework assembly in which each regular expression defined in the `regexinfos` array is represented by a class. Typically, the method is called from a separate application that generates an assembly of compiled regular expressions. Each regular expression included in the assembly has the following characteristics: - -- It is derived from the class. - -- It is assigned the fully qualified name that is defined by the `fullnamespace` and `name` parameters of its corresponding object. - -- It has a default (or parameterless) constructor. - - Ordinarily, the code that instantiates and uses the compiled regular expression is found in an assembly or application that is separate from the code that creates the assembly. - - Because the method generates a .NET Framework assembly from a method call instead of using a particular language's class definition keyword (such as `class` in C# or `Class`...`End Class` in Visual Basic), it does not allow .NET Framework attributes to be assigned to the assembly by using the development language's standard attribute syntax. The `attributes` parameter provides an alternative method for defining the attributes that apply to the assembly. For each attribute that you want to apply to the assembly, do the following: - -1. Create an array of objects representing the parameter types of the attribute constructor that you want to call. - -2. Retrieve a object representing the attribute class that you want to apply to the new assembly. - -3. Call the method of the attribute object to retrieve a object representing the attribute constructor that you want to call. Pass the method the array of objects that represents the constructor's parameter types - -4. Create a array that defines the parameters to pass to the attribute's constructor. - -5. Instantiate a object by passing its constructor the object retrieved in step 3 and the array created in step 4. - - You can then pass an array of these objects instead of the `attributes` parameter to the method. - + method generates a .NET Framework assembly in which each regular expression defined in the `regexinfos` array is represented by a class. Typically, the method is called from a separate application that generates an assembly of compiled regular expressions. Each regular expression included in the assembly has the following characteristics: + +- It is derived from the class. + +- It is assigned the fully qualified name that is defined by the `fullnamespace` and `name` parameters of its corresponding object. + +- It has a default (or parameterless) constructor. + + Ordinarily, the code that instantiates and uses the compiled regular expression is found in an assembly or application that is separate from the code that creates the assembly. + + Because the method generates a .NET Framework assembly from a method call instead of using a particular language's class definition keyword (such as `class` in C# or `Class`...`End Class` in Visual Basic), it does not allow .NET Framework attributes to be assigned to the assembly by using the development language's standard attribute syntax. The `attributes` parameter provides an alternative method for defining the attributes that apply to the assembly. For each attribute that you want to apply to the assembly, do the following: + +1. Create an array of objects representing the parameter types of the attribute constructor that you want to call. + +2. Retrieve a object representing the attribute class that you want to apply to the new assembly. + +3. Call the method of the attribute object to retrieve a object representing the attribute constructor that you want to call. Pass the method the array of objects that represents the constructor's parameter types + +4. Create a array that defines the parameters to pass to the attribute's constructor. + +5. Instantiate a object by passing its constructor the object retrieved in step 3 and the array created in step 4. + + You can then pass an array of these objects instead of the `attributes` parameter to the method. + ]]> - The value of the parameter's property is an empty or null string. - - -or- - + The value of the parameter's property is an empty or null string. + + -or- + The regular expression pattern of one or more objects in contains invalid syntax. or is . @@ -1357,10 +1207,10 @@ The file designated by the parameter cannot be found. .NET Core and .NET 5+ only: Creating an assembly of compiled regular expressions is not supported. - If you are developing on a system that has .NET Framework 4.5 or its point releases installed, you target .NET Framework 4, and you use the method to create an assembly that contains compiled regular expressions. Trying to use one of the regular expressions in that assembly on a system that has .NET Framework 4 throws an exception. To work around this problem, you can do either of the following: - -- Build the assembly that contains the compiled regular expressions on a system that has .NET Framework 4 instead of later versions installed. - + If you are developing on a system that has .NET Framework 4.5 or its point releases installed, you target .NET Framework 4, and you use the method to create an assembly that contains compiled regular expressions. Trying to use one of the regular expressions in that assembly on a system that has .NET Framework 4 throws an exception. To work around this problem, you can do either of the following: + +- Build the assembly that contains the compiled regular expressions on a system that has .NET Framework 4 instead of later versions installed. + - Instead of calling and retrieving the compiled regular expression from an assembly, use either static or instance methods with the option when you instantiate a object or call a regular expression pattern matching method. Compilation and Reuse @@ -2136,34 +1986,34 @@ Each match won't actually happen until Escapes a minimal set of characters (\\, *, +, ?, |, {, [, (,), ^, $, ., #, and white space) by replacing them with their escape codes. This instructs the regular expression engine to interpret these characters literally rather than as metacharacters. A string of characters with metacharacters converted to their escaped form. - converts a string so that the regular expression engine will interpret any metacharacters that it may contain as character literals. For example, consider a regular expression that is designed to extract comments that are delimited by straight opening and closing brackets ([ and ]) from text. In the following example, the regular expression "[(.*?)]" is interpreted as a character class. Rather than matching comments embedded in the input text, the regular expression matches each opening or closing parenthesis, period, asterisk, or question mark. - + converts a string so that the regular expression engine will interpret any metacharacters that it may contain as character literals. For example, consider a regular expression that is designed to extract comments that are delimited by straight opening and closing brackets ([ and ]) from text. In the following example, the regular expression "[(.*?)]" is interpreted as a character class. Rather than matching comments embedded in the input text, the regular expression matches each opening or closing parenthesis, period, asterisk, or question mark. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Escape/Escape1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Escape/vb/Escape1.vb" id="Snippet1"::: - - However, if the opening bracket is escaped by passing it to the method, the regular expression succeeds in matching comments that are embedded in the input string. The following example illustrates this. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Escape/vb/Escape1.vb" id="Snippet1"::: + + However, if the opening bracket is escaped by passing it to the method, the regular expression succeeds in matching comments that are embedded in the input string. The following example illustrates this. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Escape/Escape1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Escape/vb/Escape1.vb" id="Snippet2"::: - - In a regular expression that is defined by using static text, characters that are to be interpreted literally rather than as metacharacters can be escaped by preceding them with a backslash symbol (\\) as well as by calling the method. In a regular expression that is defined dynamically using characters that are not known at design time, calling the method is particularly important to ensure that the regular expression engine interprets individual characters as literals rather than as metacharacters. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Escape/vb/Escape1.vb" id="Snippet2"::: + + In a regular expression that is defined by using static text, characters that are to be interpreted literally rather than as metacharacters can be escaped by preceding them with a backslash symbol (\\) as well as by calling the method. In a regular expression that is defined dynamically using characters that are not known at design time, calling the method is particularly important to ensure that the regular expression engine interprets individual characters as literals rather than as metacharacters. + > [!NOTE] -> If a regular expression pattern includes either the number sign (#) or literal white-space characters, they must be escaped if input text is parsed with the option enabled. - - While the method escapes the straight opening bracket ([) and opening brace ({) characters, it does not escape their corresponding closing characters (] and }). In most cases, escaping these is not necessary. If a closing bracket or brace is not preceded by its corresponding opening character, the regular expression engine interprets it literally. If an opening bracket or brace is interpreted as a metacharacter, the regular expression engine interprets the first corresponding closing character as a metacharacter. If this is not the desired behavior, the closing bracket or brace should be escaped by explicitly prepending the backslash (\\) character. For an illustration, see the Example section. - - - -## Examples - The following example extracts comments from text. It assumes that the comments are delimited by a begin comment symbol and an end comment symbol that is selected by the user. Because the comment symbols are to be interpreted literally, they are passed to the method to ensure that they cannot be misinterpreted as metacharacters. In addition, the example explicitly checks whether the end comment symbol entered by the user is a closing bracket (]) or brace (}). If it is, a backslash character (\\) is prepended to the bracket or brace so that it is interpreted literally. Note that the example also uses the collection to display the comment only, rather than the comment together with its opening and closing comment symbols. - +> If a regular expression pattern includes either the number sign (#) or literal white-space characters, they must be escaped if input text is parsed with the option enabled. + + While the method escapes the straight opening bracket ([) and opening brace ({) characters, it does not escape their corresponding closing characters (] and }). In most cases, escaping these is not necessary. If a closing bracket or brace is not preceded by its corresponding opening character, the regular expression engine interprets it literally. If an opening bracket or brace is interpreted as a metacharacter, the regular expression engine interprets the first corresponding closing character as a metacharacter. If this is not the desired behavior, the closing bracket or brace should be escaped by explicitly prepending the backslash (\\) character. For an illustration, see the Example section. + + + +## Examples + The following example extracts comments from text. It assumes that the comments are delimited by a begin comment symbol and an end comment symbol that is selected by the user. Because the comment symbols are to be interpreted literally, they are passed to the method to ensure that they cannot be misinterpreted as metacharacters. In addition, the example explicitly checks whether the end comment symbol entered by the user is a closing bracket (]) or brace (}). If it is, a backslash character (\\) is prepended to the bracket or brace so that it is interpreted literally. Note that the example also uses the collection to display the comment only, rather than the comment together with its opening and closing comment symbols. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Escape/Escape3.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Escape/vb/Escape3.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Escape/vb/Escape3.vb" id="Snippet3"::: + ]]> @@ -2291,34 +2141,34 @@ Allows an to attempt to free resources and perfor Returns an array of capturing group names for the regular expression. A string array of group names. - property on the array returned by this method to determine the number of groups in a regular expression. - - - -## Examples - The following example defines a general-purpose `ShowMatches` method that displays the names of regular expression groups and their matched text. - + property on the array returned by this method to determine the number of groups in a regular expression. + + + +## Examples + The following example defines a general-purpose `ShowMatches` method that displays the names of regular expression groups and their matched text. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/GetGroupNames/getgroupnames1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.getgroupnames/vb/getgroupnames1.vb" id="Snippet1"::: - - In this case, the regular expression pattern `\b(?\w+)\s?((\w+)\s)*(?\w+)?(?\p{Po})` is intended to parse a simple sentence, and to identify its first word, last word, and ending punctuation mark. The following table shows how the regular expression pattern is interpreted: - -|Pattern|Description| -|-------------|-----------------| -|`\b`|Begin the match at a word boundary.| -|`(?\w+)`|Match one or more word characters. This is the `FirstWord` named group.| -|\s?|Match zero or one white-space characters.| -|(\w+)|Match one or more word characters. This is the second capturing group.| -|\s|Match a white-space character.| -|((\w+)\s)*|Match zero or more occurrences of one or more word characters followed by a white space. This is the first capturing group.| -|(?\\w+)?|Match zero or one occurrence of one or more word characters. This is the `LastWord` named group.| -|(?\\p{Po})|Match a character whose Unicode category is Punctuation, Other. This is the `Punctuation` named group.| - + + In this case, the regular expression pattern `\b(?\w+)\s?((\w+)\s)*(?\w+)?(?\p{Po})` is intended to parse a simple sentence, and to identify its first word, last word, and ending punctuation mark. The following table shows how the regular expression pattern is interpreted: + +|Pattern|Description| +|-------------|-----------------| +|`\b`|Begin the match at a word boundary.| +|`(?\w+)`|Match one or more word characters. This is the `FirstWord` named group.| +|\s?|Match zero or one white-space characters.| +|(\w+)|Match one or more word characters. This is the second capturing group.| +|\s|Match a white-space character.| +|((\w+)\s)*|Match zero or more occurrences of one or more word characters followed by a white space. This is the first capturing group.| +|(?\\w+)?|Match zero or one occurrence of one or more word characters. This is the `LastWord` named group.| +|(?\\p{Po})|Match a character whose Unicode category is Punctuation, Other. This is the `Punctuation` named group.| + ]]> @@ -2367,32 +2217,32 @@ Allows an to attempt to free resources and perfor Returns an array of capturing group numbers that correspond to group names in an array. An integer array of group numbers. - \w+)\s*)+(?[.?!])`, that matches a sentence. The regular expression includes three capturing groups: an unnamed group that captures an individual word along with a space character that may follow it; a group named `word` that captures the individual words in the sentence; and a group named `end` that captures the punctuation that ends the sentence. The example calls the method to get the numbers of all capturing groups, and then displays their captured string. In addition, the method is used to indicate whether a particular numbered group corresponds to a named group. - + \w+)\s*)+(?[.?!])`, that matches a sentence. The regular expression includes three capturing groups: an unnamed group that captures an individual word along with a space character that may follow it; a group named `word` that captures the individual words in the sentence; and a group named `end` that captures the punctuation that ends the sentence. The example calls the method to get the numbers of all capturing groups, and then displays their captured string. In addition, the method is used to indicate whether a particular numbered group corresponds to a named group. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/GetGroupNumbers/getgroupnumbers1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.getgroupnumbers/vb/getgroupnumbers1.vb" id="Snippet1"::: - - The regular expression pattern is interpreted as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`\b`|Begin the match at a word boundary.| -|`(?\w+)`|Match one or more word characters and assign the matched strings to a group named `word`.| -|`\s*`|Match zero or more white-space characters.| -|`((?\w+)\s*)`|Assign the `word` captured group followed by any captured white-space characters to the first captured group.| -|`((?\w+)\s*)+`|Match the pattern of one or more word characters followed by any white-space characters one or more times.| -|`(?[.?!])`|Match a period, question mark, or exclamation point. Assign the matched character to the `end` capturing group.| - + + The regular expression pattern is interpreted as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`\b`|Begin the match at a word boundary.| +|`(?\w+)`|Match one or more word characters and assign the matched strings to a group named `word`.| +|`\s*`|Match zero or more white-space characters.| +|`((?\w+)\s*)`|Assign the `word` captured group followed by any captured white-space characters to the first captured group.| +|`((?\w+)\s*)+`|Match the pattern of one or more word characters followed by any white-space characters one or more times.| +|`(?[.?!])`|Match a period, question mark, or exclamation point. Assign the matched character to the `end` capturing group.| + ]]> @@ -2444,36 +2294,36 @@ Allows an to attempt to free resources and perfor Gets the group name that corresponds to the specified group number. A string that contains the group name associated with the specified group number. If there is no group name that corresponds to , the method returns . - `*subexpression*) or (?'*name*'*subexpression*), where *name* is the name by which the subexpression will be identified. (For more information, see [Grouping Constructs](/dotnet/standard/base-types/grouping-constructs-in-regular-expressions).) The method identifies both named groups and numbered groups by their ordinal positions in the regular expression. Ordinal position zero always represents the entire regular expression. All numbered groups are then counted before named groups, regardless of their actual position in the regular expression pattern. - - If `i` is the number of a named group, the method returns the name of the group. If `i` is the number of an unnamed group, the method returns the string representation of the number. For example, if `i` is 1, the method returns "1". If `i` is not the number of a capturing group, the method returns . - - If a pattern match is found, the value returned by this method can then be used to retrieve the object that represents the captured group from the property. The object is returned by the property. - - - -## Examples - The following example defines a regular expression pattern that matches an address line containing a U.S. city name, state name, and zip code. The example uses the method to retrieve the names of capturing groups. It then uses these names to retrieve the corresponding captured groups for matches. - + `*subexpression*) or (?'*name*'*subexpression*), where *name* is the name by which the subexpression will be identified. (For more information, see [Grouping Constructs](/dotnet/standard/base-types/grouping-constructs-in-regular-expressions).) The method identifies both named groups and numbered groups by their ordinal positions in the regular expression. Ordinal position zero always represents the entire regular expression. All numbered groups are then counted before named groups, regardless of their actual position in the regular expression pattern. + + If `i` is the number of a named group, the method returns the name of the group. If `i` is the number of an unnamed group, the method returns the string representation of the number. For example, if `i` is 1, the method returns "1". If `i` is not the number of a capturing group, the method returns . + + If a pattern match is found, the value returned by this method can then be used to retrieve the object that represents the captured group from the property. The object is returned by the property. + + + +## Examples + The following example defines a regular expression pattern that matches an address line containing a U.S. city name, state name, and zip code. The example uses the method to retrieve the names of capturing groups. It then uses these names to retrieve the corresponding captured groups for matches. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/GroupNameFromNumber/groupnamefromnumberex.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.groupnamefromnumber/vb/groupnamefromnumberex.vb" id="Snippet1"::: - - The regular expression pattern is defined by the following expression: - - `(?[A-Za-z\s]+), (?[A-Za-z]{2}) (?\d{5}(-\d{4})?)` - - The following table shows how the regular expression pattern is interpreted. - -|Pattern|Description| -|-------------|-----------------| -|`(?[A-Za-z\s]+)`|Match one or more alphabetic or white-space character. Assign this captured group the name `city`.| -|`,`|Match a comma (,) followed by a white-space character.| -|`(?[A-Za-z]{2})`|Match two alphabetic characters. Assign this captured group the name `state`. This group should be followed by a white-space character.| -|`(?\d{5}(-\d{4})?)`|Match five numeric digits followed by either zero or one occurrence of a hyphen followed by four digits. Assign this captured group the name `zip`.| - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.groupnamefromnumber/vb/groupnamefromnumberex.vb" id="Snippet1"::: + + The regular expression pattern is defined by the following expression: + + `(?[A-Za-z\s]+), (?[A-Za-z]{2}) (?\d{5}(-\d{4})?)` + + The following table shows how the regular expression pattern is interpreted. + +|Pattern|Description| +|-------------|-----------------| +|`(?[A-Za-z\s]+)`|Match one or more alphabetic or white-space character. Assign this captured group the name `city`.| +|`,`|Match a comma (,) followed by a white-space character.| +|`(?[A-Za-z]{2})`|Match two alphabetic characters. Assign this captured group the name `state`. This group should be followed by a white-space character.| +|`(?\d{5}(-\d{4})?)`|Match five numeric digits followed by either zero or one occurrence of a hyphen followed by four digits. Assign this captured group the name `zip`.| + ]]> @@ -2526,13 +2376,13 @@ Allows an to attempt to free resources and perfor Returns the group number that corresponds to the specified group name. The group number that corresponds to the specified group name, or -1 if is not a valid group name. - `*subexpression*) or (?'*name*'*subexpression*), where *name* is the name by which the subexpression will be identified. (For more information, see [Grouping Constructs](/dotnet/standard/base-types/grouping-constructs-in-regular-expressions).) The method identifies both named groups and numbered groups by their ordinal positions in the regular expression. Ordinal position zero always represents the entire regular expression. All numbered groups are then counted before named groups, regardless of their actual position in the regular expression pattern. - - If `name` is the string representation of a group number that is present in the regular expression pattern, the method returns that number. If `name` corresponds to a named capturing group that is present in the regular expression pattern, the method returns its corresponding number. The comparison of `name` with the group name is case-sensitive. If `name` does not correspond to the name of a capturing group or to the string representation of the number of a capturing group, the method returns -1. - + `*subexpression*) or (?'*name*'*subexpression*), where *name* is the name by which the subexpression will be identified. (For more information, see [Grouping Constructs](/dotnet/standard/base-types/grouping-constructs-in-regular-expressions).) The method identifies both named groups and numbered groups by their ordinal positions in the regular expression. Ordinal position zero always represents the entire regular expression. All numbered groups are then counted before named groups, regardless of their actual position in the regular expression pattern. + + If `name` is the string representation of a group number that is present in the regular expression pattern, the method returns that number. If `name` corresponds to a named capturing group that is present in the regular expression pattern, the method returns its corresponding number. The comparison of `name` with the group name is case-sensitive. If `name` does not correspond to the name of a capturing group or to the string representation of the number of a capturing group, the method returns -1. + ]]> @@ -2580,34 +2430,34 @@ Allows an to attempt to free resources and perfor Specifies that a pattern-matching operation should not time out. - class constructor and a number of static matching methods use the constant to indicate that the attempt to find a pattern match should not time out. - + class constructor and a number of static matching methods use the constant to indicate that the attempt to find a pattern match should not time out. + > [!WARNING] -> Setting the regular expression engine's time-out value to can cause regular expressions that rely on excessive backtracking to appear to stop responding when processing text that nearly matches the regular expression pattern. If you disable time-outs, you should ensure that your regular expression does not rely on excessive backtracking and that it handles text that nearly matches the regular expression pattern. -> -> For more information about handling backtracking, see [Backtracking](/dotnet/standard/base-types/backtracking-in-regular-expressions). - - The constant can be supplied as the value of the `matchTimeout` argument of the following members: - -- - -- - -- - -- - -- - -- - -- - -- - +> Setting the regular expression engine's time-out value to can cause regular expressions that rely on excessive backtracking to appear to stop responding when processing text that nearly matches the regular expression pattern. If you disable time-outs, you should ensure that your regular expression does not rely on excessive backtracking and that it handles text that nearly matches the regular expression pattern. +> +> For more information about handling backtracking, see [Backtracking](/dotnet/standard/base-types/backtracking-in-regular-expressions). + + The constant can be supplied as the value of the `matchTimeout` argument of the following members: + +- + +- + +- + +- + +- + +- + +- + +- + ]]> @@ -2809,41 +2659,41 @@ Allows an to attempt to free resources and perfor if the regular expression finds a match; otherwise, . - method is typically used to validate a string or to ensure that a string conforms to a particular pattern without retrieving that string for subsequent manipulation. If you want to determine whether one or more strings match a regular expression pattern and then retrieve them for subsequent manipulation, call the or method. - - The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown. - - - -## Examples - The following example illustrates the use of the method to determine whether a string is a valid part number. The regular expression assumes that the part number has a specific format that consists of three sets of characters separated by hyphens. The first set, which contains four characters, must consist of an alphanumeric character followed by two numeric characters followed by an alphanumeric character. The second set, which consists of three characters, must be numeric. The third set, which consists of four characters, must have three numeric characters followed by an alphanumeric character. + method is typically used to validate a string or to ensure that a string conforms to a particular pattern without retrieving that string for subsequent manipulation. If you want to determine whether one or more strings match a regular expression pattern and then retrieve them for subsequent manipulation, call the or method. + + The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown. + + + +## Examples + The following example illustrates the use of the method to determine whether a string is a valid part number. The regular expression assumes that the part number has a specific format that consists of three sets of characters separated by hyphens. The first set, which contains four characters, must consist of an alphanumeric character followed by two numeric characters followed by an alphanumeric character. The second set, which consists of three characters, must be numeric. The third set, which consists of four characters, must have three numeric characters followed by an alphanumeric character. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/IsMatch/ismatch2.cs" interactive="try-dotnet" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.ismatch/vb/ismatch2.vb" id="Snippet2"::: - - The regular expression pattern is: - -``` -^[a-zA-Z0-9]\d{2}[a-zA-Z0-9](-\d{3}){2}[A-Za-z0-9]$ -``` - - The following table shows how the regular expression pattern is interpreted. - -|Pattern|Description| -|-------------|-----------------| -|`^`|Begin the match at the beginning of the line.| -|`[a-zA-Z0-9]`|Match a single alphabetic character (`a` through `z` or `A` through `Z`) or numeric character.| -|`\d{2}`|Match two numeric characters.| -|`[a-zA-Z0-9]`|Match a single alphabetic character (`a` through `z` or `A` through `Z`) or numeric character.| -|`-`|Match a hyphen.| -|`\d{3}`|Match exactly three numeric characters.| -|`(-\d{3}){2}`|Find a hyphen followed by three numeric characters, and match two occurrences of this pattern.| -|`[a-zA-Z0-9]`|Match a single alphabetic character (`a` through `z` or `A` through `Z`) or numeric character.| -|`$`|End the match at the end of the line.| - + + The regular expression pattern is: + +``` +^[a-zA-Z0-9]\d{2}[a-zA-Z0-9](-\d{3}){2}[A-Za-z0-9]$ +``` + + The following table shows how the regular expression pattern is interpreted. + +|Pattern|Description| +|-------------|-----------------| +|`^`|Begin the match at the beginning of the line.| +|`[a-zA-Z0-9]`|Match a single alphabetic character (`a` through `z` or `A` through `Z`) or numeric character.| +|`\d{2}`|Match two numeric characters.| +|`[a-zA-Z0-9]`|Match a single alphabetic character (`a` through `z` or `A` through `Z`) or numeric character.| +|`-`|Match a hyphen.| +|`\d{3}`|Match exactly three numeric characters.| +|`(-\d{3}){2}`|Find a hyphen followed by three numeric characters, and match two occurrences of this pattern.| +|`[a-zA-Z0-9]`|Match a single alphabetic character (`a` through `z` or `A` through `Z`) or numeric character.| +|`$`|End the match at the end of the line.| + ]]> @@ -2998,40 +2848,40 @@ Allows an to attempt to free resources and perfor if the regular expression finds a match; otherwise, . - method is typically used to validate a string or to ensure that a string conforms to a particular pattern without retrieving that string for subsequent manipulation. If you want to determine whether one or more strings match a regular expression pattern and then retrieve them for subsequent manipulation, call the or method. For more details about `startat`, see the Remarks section of . - + The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown. - -## Examples - The following example illustrates the use of the method to determine whether a string is a valid part number. It searches for a part number that follows a colon (:) character in a string. The method is used to determine the position of the colon character, which is then passed to the method. The regular expression assumes that the part number has a specific format that consists of three sets of characters separated by hyphens. The first set, which contains four characters, must consist of an alphanumeric character followed by two numeric characters followed by an alphanumeric character. The second set, which consists of three characters, must be numeric. The third set, which consists of four characters, must have three numeric characters followed by an alphanumeric character. - + +## Examples + The following example illustrates the use of the method to determine whether a string is a valid part number. It searches for a part number that follows a colon (:) character in a string. The method is used to determine the position of the colon character, which is then passed to the method. The regular expression assumes that the part number has a specific format that consists of three sets of characters separated by hyphens. The first set, which contains four characters, must consist of an alphanumeric character followed by two numeric characters followed by an alphanumeric character. The second set, which consists of three characters, must be numeric. The third set, which consists of four characters, must have three numeric characters followed by an alphanumeric character. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/IsMatch/ismatch3.cs" interactive="try-dotnet" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.ismatch/vb/ismatch3.vb" id="Snippet3"::: - - The regular expression pattern is: - -``` -[a-zA-Z0-9]\d{2}[a-zA-Z0-9](-\d{3}){2}[A-Za-z0-9]$ -``` - - The following table shows how the regular expression pattern is interpreted. - -|Pattern|Description| -|-------------|-----------------| -|`[a-zA-Z0-9]`|Match a single alphabetic character (`a` through `z` or `A` through `Z`) or numeric character.| -|`\d{2}`|Match two numeric characters.| -|`[a-zA-Z0-9]`|Match a single alphabetic character (`a` through `z` or `A` through `Z`) or numeric character.| -|`-`|Match a hyphen.| -|`\d{3}`|Match exactly three numeric characters.| -|`(-\d{3}){2}`|Find a hyphen followed by three numeric characters, and match two occurrences of this pattern.| -|`[a-zA-Z0-9]`|Match a single alphabetic character (`a` through `z` or `A` through `Z`) or numeric character.| -|`$`|End the match at the end of the line.| - + + The regular expression pattern is: + +``` +[a-zA-Z0-9]\d{2}[a-zA-Z0-9](-\d{3}){2}[A-Za-z0-9]$ +``` + + The following table shows how the regular expression pattern is interpreted. + +|Pattern|Description| +|-------------|-----------------| +|`[a-zA-Z0-9]`|Match a single alphabetic character (`a` through `z` or `A` through `Z`) or numeric character.| +|`\d{2}`|Match two numeric characters.| +|`[a-zA-Z0-9]`|Match a single alphabetic character (`a` through `z` or `A` through `Z`) or numeric character.| +|`-`|Match a hyphen.| +|`\d{3}`|Match exactly three numeric characters.| +|`(-\d{3}){2}`|Find a hyphen followed by three numeric characters, and match two occurrences of this pattern.| +|`[a-zA-Z0-9]`|Match a single alphabetic character (`a` through `z` or `A` through `Z`) or numeric character.| +|`$`|End the match at the end of the line.| + ]]> @@ -3097,45 +2947,45 @@ For more details about `startat`, see the Remarks section of if the regular expression finds a match; otherwise, . - method is typically used to validate a string or to ensure that a string conforms to a particular pattern without retrieving that string for subsequent manipulation. If you want to determine whether one or more strings match a regular expression pattern and then retrieve them for subsequent manipulation, call the or method. - - The static method is equivalent to constructing a object with the regular expression pattern specified by `pattern` and calling the instance method. This regular expression pattern is cached for rapid retrieval by the regular expression engine. - - The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). - - The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. - - - -## Examples - The following example illustrates the use of the method to determine whether a string is a valid part number. The regular expression assumes that the part number has a specific format that consists of three sets of characters separated by hyphens. The first set, which contains four characters, must consist of an alphanumeric character followed by two numeric characters followed by an alphanumeric character. The second set, which consists of three characters, must be numeric. The third set, which consists of four characters, must have three numeric characters followed by an alphanumeric character. + method is typically used to validate a string or to ensure that a string conforms to a particular pattern without retrieving that string for subsequent manipulation. If you want to determine whether one or more strings match a regular expression pattern and then retrieve them for subsequent manipulation, call the or method. + + The static method is equivalent to constructing a object with the regular expression pattern specified by `pattern` and calling the instance method. This regular expression pattern is cached for rapid retrieval by the regular expression engine. + + The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). + + The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. + + + +## Examples + The following example illustrates the use of the method to determine whether a string is a valid part number. The regular expression assumes that the part number has a specific format that consists of three sets of characters separated by hyphens. The first set, which contains four characters, must consist of an alphanumeric character followed by two numeric characters followed by an alphanumeric character. The second set, which consists of three characters, must be numeric. The third set, which consists of four characters, must have three numeric characters followed by an alphanumeric character. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/IsMatch/ismatch1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.ismatch/vb/ismatch1.vb" id="Snippet1"::: - - The regular expression pattern is: - -``` -^[a-zA-Z0-9]\d{2}[a-zA-Z0-9](-\d{3}){2}[A-Za-z0-9]$ -``` - - The following table shows how the regular expression pattern is interpreted. - -|Pattern|Description| -|-------------|-----------------| -|`^`|Begin the match at the beginning of the line.| -|`[a-zA-Z0-9]`|Match a single alphabetic character (`a` through `z` or `A` through `Z`) or numeric character.| -|`\d{2}`|Match two numeric characters.| -|`[a-zA-Z0-9]`|Match a single alphabetic character (`a` through `z` or `A` through `Z`) or numeric character.| -|`-`|Match a hyphen.| -|`\d{3}`|Match exactly three numeric characters.| -|`(-\d{3}){2}`|Find a hyphen followed by three numeric characters, and match two occurrences of this pattern.| -|`[a-zA-Z0-9]`|Match a single alphabetic character (`a` through `z` or `A` through `Z`) or numeric character.| -|`$`|End the match at the end of the line.| - + + The regular expression pattern is: + +``` +^[a-zA-Z0-9]\d{2}[a-zA-Z0-9](-\d{3}){2}[A-Za-z0-9]$ +``` + + The following table shows how the regular expression pattern is interpreted. + +|Pattern|Description| +|-------------|-----------------| +|`^`|Begin the match at the beginning of the line.| +|`[a-zA-Z0-9]`|Match a single alphabetic character (`a` through `z` or `A` through `Z`) or numeric character.| +|`\d{2}`|Match two numeric characters.| +|`[a-zA-Z0-9]`|Match a single alphabetic character (`a` through `z` or `A` through `Z`) or numeric character.| +|`-`|Match a hyphen.| +|`\d{3}`|Match exactly three numeric characters.| +|`(-\d{3}){2}`|Find a hyphen followed by three numeric characters, and match two occurrences of this pattern.| +|`[a-zA-Z0-9]`|Match a single alphabetic character (`a` through `z` or `A` through `Z`) or numeric character.| +|`$`|End the match at the end of the line.| + ]]> A regular expression parsing error occurred. @@ -3265,58 +3115,58 @@ For more details about `startat`, see the Remarks section of if the regular expression finds a match; otherwise, . - method is typically used to validate a string or to ensure that a string conforms to a particular pattern without retrieving that string for subsequent manipulation. If you want to determine whether one or more strings match a regular expression pattern and then retrieve them for subsequent manipulation, call the or method. - - The static method is equivalent to constructing a object with the regular expression pattern specified by `pattern` and the regular expression options specified by `options` and calling the instance method. This regular expression pattern is cached for rapid retrieval by the regular expression engine. - - The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). - - The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. - - - -## Examples - The following example illustrates the use of the method to determine whether a string is a valid part number. The regular expression assumes that the part number has a specific format that consists of three sets of characters separated by hyphens. The first set, which contains four characters, must consist of an alphanumeric character followed by two numeric characters followed by an alphanumeric character. The second set, which consists of three characters, must be numeric. The third set, which consists of four characters, must have three numeric characters followed by an alphanumeric character. + method with the `options` parameter set to is equivalent to defining the following regular expression: - -``` -[a-zA-Z0-9]\d{2}[a-zA-Z0-9](-\d{3}){2}[A-Za-z0-9] -``` - - For comparison, see the example for the method. - - ]]> - - A regular expression parsing error occurred. - - or is . +## Remarks + The method is typically used to validate a string or to ensure that a string conforms to a particular pattern without retrieving that string for subsequent manipulation. If you want to determine whether one or more strings match a regular expression pattern and then retrieve them for subsequent manipulation, call the or method. + + The static method is equivalent to constructing a object with the regular expression pattern specified by `pattern` and the regular expression options specified by `options` and calling the instance method. This regular expression pattern is cached for rapid retrieval by the regular expression engine. + + The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). + + The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. + + + +## Examples + The following example illustrates the use of the method to determine whether a string is a valid part number. The regular expression assumes that the part number has a specific format that consists of three sets of characters separated by hyphens. The first set, which contains four characters, must consist of an alphanumeric character followed by two numeric characters followed by an alphanumeric character. The second set, which consists of three characters, must be numeric. The third set, which consists of four characters, must have three numeric characters followed by an alphanumeric character. + + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/IsMatch/ismatch4.cs" interactive="try-dotnet" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.ismatch/vb/ismatch4.vb" id="Snippet4"::: + + The regular expression pattern is: + +``` +^[A-Z0-9]\d{2}[A-Z0-9](-\d{3}){2}[A-Z0-9]$ +``` + + The following table shows how the regular expression pattern is interpreted. + +|Pattern|Description| +|-------------|-----------------| +|`^`|Begin the match at the beginning of the string.| +|`[A-Z0-9]`|Match any single alphabetic character from `A` through `Z`, or any numeric character.| +|`\d{2}`|Match two numeric characters.| +|`[A-Z0-9]`|Match any single alphabetic character from `A` through `Z`, or any numeric character.| +|`-`|Match a hyphen.| +|`\d{3}`|Match exactly three numeric characters.| +|`(-\d{3}){2}`|Find a hyphen followed by three numeric characters, and match two occurrences of this pattern..| +|`[A-Z0-9]`|Match any single alphabetic character from `A` through `Z`, or any numeric character.| +|`$`|End the match at the end of the string.| + + Calling the method with the `options` parameter set to is equivalent to defining the following regular expression: + +``` +[a-zA-Z0-9]\d{2}[a-zA-Z0-9](-\d{3}){2}[A-Za-z0-9] +``` + + For comparison, see the example for the method. + + ]]> + + A regular expression parsing error occurred. + + or is . is not a valid value. A time-out occurred. For more information about time-outs, see the Remarks section. @@ -3446,72 +3296,72 @@ For more details about `startat`, see the Remarks section of if the regular expression finds a match; otherwise, . - method is typically used to validate a string or to ensure that a string conforms to a particular pattern without retrieving that string for subsequent manipulation. If you want to determine whether one or more strings match a regular expression pattern and then retrieve them for subsequent manipulation, call the or method. - - The static method is equivalent to constructing a object with the regular expression pattern specified by `pattern` and the regular expression options specified by `options` and calling the instance method. This regular expression pattern is cached for rapid retrieval by the regular expression engine. - - The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). - - The `matchTimeout` parameter specifies how long a pattern matching method should try to find a match before it times out. Setting a time-out interval prevents regular expressions that rely on excessive backtracking from appearing to stop responding when they process input that contains near matches. For more information, see [Best Practices for Regular Expressions](/dotnet/standard/base-types/best-practices) and [Backtracking](/dotnet/standard/base-types/backtracking-in-regular-expressions). If no match is found in that time interval, the method throws a exception. `matchTimeout` overrides any default time-out value defined for the application domain in which the method executes. - - - -## Examples - The following example illustrates the use of the method to determine whether a string is a valid part number. The regular expression assumes that the part number has a specific format that consists of three sets of characters separated by hyphens. The first set, which contains four characters, must consist of an alphanumeric character followed by two numeric characters followed by an alphanumeric character. The second set, which consists of three characters, must be numeric. The third set, which consists of four characters, must have three numeric characters followed by an alphanumeric character. Matching the regular expression pattern should involve minimal searching through the input string, so the method sets a time-out interval of 500 milliseconds. + method is typically used to validate a string or to ensure that a string conforms to a particular pattern without retrieving that string for subsequent manipulation. If you want to determine whether one or more strings match a regular expression pattern and then retrieve them for subsequent manipulation, call the or method. + + The static method is equivalent to constructing a object with the regular expression pattern specified by `pattern` and the regular expression options specified by `options` and calling the instance method. This regular expression pattern is cached for rapid retrieval by the regular expression engine. + + The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). + + The `matchTimeout` parameter specifies how long a pattern matching method should try to find a match before it times out. Setting a time-out interval prevents regular expressions that rely on excessive backtracking from appearing to stop responding when they process input that contains near matches. For more information, see [Best Practices for Regular Expressions](/dotnet/standard/base-types/best-practices) and [Backtracking](/dotnet/standard/base-types/backtracking-in-regular-expressions). If no match is found in that time interval, the method throws a exception. `matchTimeout` overrides any default time-out value defined for the application domain in which the method executes. + + + +## Examples + The following example illustrates the use of the method to determine whether a string is a valid part number. The regular expression assumes that the part number has a specific format that consists of three sets of characters separated by hyphens. The first set, which contains four characters, must consist of an alphanumeric character followed by two numeric characters followed by an alphanumeric character. The second set, which consists of three characters, must be numeric. The third set, which consists of four characters, must have three numeric characters followed by an alphanumeric character. Matching the regular expression pattern should involve minimal searching through the input string, so the method sets a time-out interval of 500 milliseconds. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/IsMatch/ismatch5.cs" interactive="try-dotnet" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.ismatch/vb/ismatch5.vb" id="Snippet5"::: - - The regular expression pattern is: - -``` -^[A-Z0-9]\d{2}[A-Z0-9](-\d{3}){2}[A-Z0-9]$ -``` - - The following table shows how the regular expression pattern is interpreted. - -|Pattern|Description| -|-------------|-----------------| -|`^`|Begin the match at the beginning of the string.| -|`[A-Z0-9]`|Match any single alphabetic character from `A` through `Z`, or any numeric character.| -|`\d{2}`|Match two numeric characters.| -|`[A-Z0-9]`|Match any single alphabetic character from `A` through `Z`, or any numeric character.| -|`-`|Match a hyphen.| -|`\d{3}`|Match exactly three numeric characters.| -|`(-\d{3}){2}`|Find a hyphen followed by three numeric characters, and match two occurrences of this pattern.| -|`[A-Z0-9]`|Match any single alphabetic character from `A` through `Z`, or any numeric character.| -|`$`|End the match at the end of the string.| - - Calling the method with the `options` parameter set to is equivalent to defining the following regular expression: - -``` -[a-zA-Z0-9]\d{2}[a-zA-Z0-9](-\d{3}){2}[A-Za-z0-9] -``` - - For comparison, see the example for the method. - + + The regular expression pattern is: + +``` +^[A-Z0-9]\d{2}[A-Z0-9](-\d{3}){2}[A-Z0-9]$ +``` + + The following table shows how the regular expression pattern is interpreted. + +|Pattern|Description| +|-------------|-----------------| +|`^`|Begin the match at the beginning of the string.| +|`[A-Z0-9]`|Match any single alphabetic character from `A` through `Z`, or any numeric character.| +|`\d{2}`|Match two numeric characters.| +|`[A-Z0-9]`|Match any single alphabetic character from `A` through `Z`, or any numeric character.| +|`-`|Match a hyphen.| +|`\d{3}`|Match exactly three numeric characters.| +|`(-\d{3}){2}`|Find a hyphen followed by three numeric characters, and match two occurrences of this pattern.| +|`[A-Z0-9]`|Match any single alphabetic character from `A` through `Z`, or any numeric character.| +|`$`|End the match at the end of the string.| + + Calling the method with the `options` parameter set to is equivalent to defining the following regular expression: + +``` +[a-zA-Z0-9]\d{2}[a-zA-Z0-9](-\d{3}){2}[A-Za-z0-9] +``` + + For comparison, see the example for the method. + ]]> A regular expression parsing error occurred. or is . - is not a valid value. - - -or- - + is not a valid value. + + -or- + is negative, zero, or greater than approximately 24 days. A time-out occurred. - We recommend that you set the parameter to an appropriate value, such as two seconds. If you disable time-outs by specifying , the regular expression engine offers slightly better performance. However, you should disable time-outs only under the following conditions: - -- When the input processed by a regular expression is derived from a known and trusted source or consists of static text. This excludes text that has been dynamically input by users. - -- When the regular expression pattern has been thoroughly tested to ensure that it efficiently handles matches, non-matches, and near matches. - + We recommend that you set the parameter to an appropriate value, such as two seconds. If you disable time-outs by specifying , the regular expression engine offers slightly better performance. However, you should disable time-outs only under the following conditions: + +- When the input processed by a regular expression is derived from a known and trusted source or consists of static text. This excludes text that has been dynamically input by users. + +- When the regular expression pattern has been thoroughly tested to ensure that it efficiently handles matches, non-matches, and near matches. + - When the regular expression pattern contains no language elements that are known to cause excessive backtracking when processing a near match. Regular Expression Language Elements @@ -3576,34 +3426,34 @@ For more details about `startat`, see the Remarks section of Searches the specified input string for the first occurrence of the regular expression specified in the constructor. An object that contains information about the match. - method returns the first substring that matches a regular expression pattern in an input string. For information about the language elements used to build a regular expression pattern, see [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). - - You can determine whether the regular expression pattern has been found in the input string by checking the value of the returned object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . - - This method returns the first substring in `input` that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can also retrieve all matches in a single method call by calling the method. - - The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown. - - - -## Examples - The following example finds regular expression pattern matches in a string, then lists the matched groups, captures, and capture positions. + method returns the first substring that matches a regular expression pattern in an input string. For information about the language elements used to build a regular expression pattern, see [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). + + You can determine whether the regular expression pattern has been found in the input string by checking the value of the returned object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . + + This method returns the first substring in `input` that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can also retrieve all matches in a single method call by calling the method. + + The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown. + + + +## Examples + The following example finds regular expression pattern matches in a string, then lists the matched groups, captures, and capture positions. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/regex match, nextmatch, groups, captures/cpp/snippet8.cpp" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Match/Groups/snippet8.cs" interactive="try-dotnet" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/regex match, nextmatch, groups, captures/vb/snippet8.vb" id="Snippet8"::: - - The regular expression pattern `(\w+)\s+(car)` matches occurrences of the word "car" along with the word that precedes it. It is interpreted as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`(\w+)`|Match one or more word characters. This is the first capturing group.| -|`\s+`|Match one or more white-space characters.| -|(car)|Match the literal string "car". This is the second capturing group.| - + + The regular expression pattern `(\w+)\s+(car)` matches occurrences of the word "car" along with the word that precedes it. It is interpreted as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`(\w+)`|Match one or more word characters. This is the first capturing group.| +|`\s+`|Match one or more white-space characters.| +|(car)|Match the literal string "car". This is the second capturing group.| + ]]> @@ -3660,14 +3510,14 @@ For more details about `startat`, see the Remarks section of Searches the input string for the first occurrence of a regular expression, beginning at the specified starting position in the string. An object that contains information about the match. - method returns the first substring that matches a regular expression pattern, starting at or after the `startat` character position, in an input string. The regular expression pattern for which the method searches is defined by the call to one of the class constructors. For information about the language elements used to build a regular expression pattern, see [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). ### The `startat` parameter - + You can optionally specify a starting position in the string by using the `startat` parameter. Any matches starting before `startat` in the string are ignored. If you don't specify a starting position, the search begins at the default position, which is the left end of `input` in a left-to-right search, and the right end of `input` in a right-to-left search. Despite starting at `startat`, the index of any returned match is relative to the start of the string. Although the regular expression engine doesn't return any match starting before `startat`, it doesn't ignore the string before `startat`. This means that assertions such as [anchors](/dotnet/standard/base-types/anchors-in-regular-expressions) or [lookbehind assertions](/dotnet/standard/base-types/backtracking-in-regular-expressions#lookbehind-assertions) still apply to the input as a whole. For example, the following code includes a pattern with a lookbehind assertion that's satisfied even though it occurs before the `startat` index of 5 in the input string. @@ -3691,17 +3541,17 @@ A right-to-left search, that is, when the regular expression pattern is construc For more information about right-to-left searches, see [Right-to-left mode](/dotnet/standard/base-types/regular-expression-options#right-to-left-mode). ### Determine whether a match is found - + You can determine whether the regular expression pattern has been found in the input string by checking the value of the returned object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . ### First or multiple matches - + This method returns the first substring found at or after the `startat` character position in `input` that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can also retrieve all matches in a single method call by calling the method. ### Time-out exceptions - - The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown. - + + The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown. + ]]> @@ -3767,39 +3617,39 @@ For more information about right-to-left searches, see [Right-to-left mode](/dot Searches the specified input string for the first occurrence of the specified regular expression. An object that contains information about the match. - method returns the first substring that matches a regular expression pattern in an input string. For information about the language elements used to build a regular expression pattern, see [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). - - The static method is equivalent to constructing a object with the specified regular expression pattern and calling the instance method. In this case, the regular expression engine caches the regular expression pattern. - - The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). - - You can determine whether the regular expression pattern has been found in the input string by checking the value of the returned object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . - - This method returns the first substring in `input` that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can also retrieve all matches in a single method call by calling the method. - - The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. - - - -## Examples - The following example calls the method to find the first word that contains at least one `z` character, and then calls the method to find any additional matches. - + method returns the first substring that matches a regular expression pattern in an input string. For information about the language elements used to build a regular expression pattern, see [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). + + The static method is equivalent to constructing a object with the specified regular expression pattern and calling the instance method. In this case, the regular expression engine caches the regular expression pattern. + + The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). + + You can determine whether the regular expression pattern has been found in the input string by checking the value of the returned object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . + + This method returns the first substring in `input` that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can also retrieve all matches in a single method call by calling the method. + + The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. + + + +## Examples + The following example calls the method to find the first word that contains at least one `z` character, and then calls the method to find any additional matches. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Match/match1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.match/vb/match1.vb" id="Snippet1"::: - - The regular expression pattern `\b\w*z+\w*\b` is interpreted as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`\b`|Begin the match at a word boundary.| -|`\w*`|Match zero, one, or more word characters.| -|`z+`|Match one or more occurrences of the `z` character.| -|`\w*`|Match zero, one, or more word characters.| -|`\b`|End the match at a word boundary.| - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.match/vb/match1.vb" id="Snippet1"::: + + The regular expression pattern `\b\w*z+\w*\b` is interpreted as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`\b`|Begin the match at a word boundary.| +|`\w*`|Match zero, one, or more word characters.| +|`z+`|Match one or more occurrences of the `z` character.| +|`\w*`|Match zero, one, or more word characters.| +|`\b`|End the match at a word boundary.| + ]]> A regular expression parsing error occurred. @@ -3862,36 +3712,36 @@ For more information about right-to-left searches, see [Right-to-left mode](/dot Searches the input string for the first occurrence of a regular expression, beginning at the specified starting position and searching only the specified number of characters. An object that contains information about the match. - method returns the first substring that matches a regular expression pattern in a portion of an input string. For information about the language elements used to build a regular expression pattern, see [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). - - The regular expression pattern for which the method searches is defined by the call to one of the class constructors. For more information about the elements that can form a regular expression pattern, see [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). - - The method searches the portion of `input` defined by the `beginning` and `length` parameters for the regular expression pattern. `beginning` always defines the index of the leftmost character to include in the search, and `length` defines the maximum number of characters to search. Together, they define the range of the search. The behavior is exactly as if the `input` was effectively `input.Substring(beginning, length)`, except that the index of any match is counted relative to the start of `input`. This means that any anchors or zero-width assertions at the start or end of the pattern behave as if there is no `input` outside of this range. For example the anchors `^`, `\G`, and `\A` will be satisfied at `beginning` and `$` and `\z` will be satisfied at `beginning + length - 1`. + method returns the first substring that matches a regular expression pattern in a portion of an input string. For information about the language elements used to build a regular expression pattern, see [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). + + The regular expression pattern for which the method searches is defined by the call to one of the class constructors. For more information about the elements that can form a regular expression pattern, see [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). + + The method searches the portion of `input` defined by the `beginning` and `length` parameters for the regular expression pattern. `beginning` always defines the index of the leftmost character to include in the search, and `length` defines the maximum number of characters to search. Together, they define the range of the search. The behavior is exactly as if the `input` was effectively `input.Substring(beginning, length)`, except that the index of any match is counted relative to the start of `input`. This means that any anchors or zero-width assertions at the start or end of the pattern behave as if there is no `input` outside of this range. For example the anchors `^`, `\G`, and `\A` will be satisfied at `beginning` and `$` and `\z` will be satisfied at `beginning + length - 1`. If the search proceeds from left to right (the default), the regular expression engine searches from the character at index `beginning` to the character at index `beginning + length - 1`. If the regular expression engine was instantiated by using the option so that the search proceeds from right to left, the regular expression engine searches from the character at index `beginning + length - 1` to the character at index `beginning`. - This method returns the first match that it finds within this range. You can retrieve subsequent matches by repeatedly calling the returned object's method. - - You can determine whether the regular expression pattern has been found in the input string by checking the value of the returned object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . - - The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified by the constructor. If you do not set a time-out value when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown. - + This method returns the first match that it finds within this range. You can retrieve subsequent matches by repeatedly calling the returned object's method. + + You can determine whether the regular expression pattern has been found in the input string by checking the value of the returned object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . + + The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified by the constructor. If you do not set a time-out value when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown. + ]]> is . - is less than zero or greater than the length of . - - -or- - - is less than zero or greater than the length of . - - -or- - + is less than zero or greater than the length of . + + -or- + + is less than zero or greater than the length of . + + -or- + identifies a position that is outside the range of . A time-out occurred. For more information about time-outs, see the Remarks section. @@ -3954,38 +3804,38 @@ For more information about right-to-left searches, see [Right-to-left mode](/dot Searches the input string for the first occurrence of the specified regular expression, using the specified matching options. An object that contains information about the match. - method returns the first substring that matches a regular expression pattern in an input string. For information about the language elements used to build a regular expression pattern, see [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). - - The static method is equivalent to constructing a object with the constructor and calling the instance method. - - The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). - - You can determine whether the regular expression pattern has been found in the input string by checking the value of the returned object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . - - This method returns the first substring found in `input` that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can also retrieve all matches in a single method call by calling the method. - - The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. - - - -## Examples - The following example defines a regular expression that matches words beginning with the letter "a". It uses the option to ensure that the regular expression locates words beginning with both an uppercase "a" and a lowercase "a". + method returns the first substring that matches a regular expression pattern in an input string. For information about the language elements used to build a regular expression pattern, see [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). + + The static method is equivalent to constructing a object with the constructor and calling the instance method. + + The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). + + You can determine whether the regular expression pattern has been found in the input string by checking the value of the returned object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . + + This method returns the first substring found in `input` that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can also retrieve all matches in a single method call by calling the method. + + The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. + + + +## Examples + The following example defines a regular expression that matches words beginning with the letter "a". It uses the option to ensure that the regular expression locates words beginning with both an uppercase "a" and a lowercase "a". :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Match/match2.cs" interactive="try-dotnet" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.match/vb/match2.vb" id="Snippet2"::: - - The regular expression pattern `\ba\w*\b` is interpreted as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`\b`|Begin the match at a word boundary.| -|`a`|Match the character "a".| -|`\w*`|Match zero, one, or more word characters.| -|`\b`|End the match at a word boundary.| - + + The regular expression pattern `\ba\w*\b` is interpreted as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`\b`|Begin the match at a word boundary.| +|`a`|Match the character "a".| +|`\w*`|Match zero, one, or more word characters.| +|`\b`|End the match at a word boundary.| + ]]> A regular expression parsing error occurred. @@ -4057,40 +3907,40 @@ For more information about right-to-left searches, see [Right-to-left mode](/dot Searches the input string for the first occurrence of the specified regular expression, using the specified matching options and time-out interval. An object that contains information about the match. - method returns the first substring that matches a regular expression pattern in an input string. For information about the language elements used to build a regular expression pattern, see [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). - - The static method is equivalent to constructing a object with the constructor and calling the instance method. - - The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). - - You can determine whether the regular expression pattern has been found in the input string by checking the value of the returned object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . - - This method returns the first substring found in `input` that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can also retrieve all matches in a single method call by calling the method. - - The `matchTimeout` parameter specifies how long a pattern matching method should try to find a match before it times out. Setting a time-out interval prevents regular expressions that rely on excessive backtracking from appearing to stop responding when they process input that contains near matches. For more information, see [Best Practices for Regular Expressions](/dotnet/standard/base-types/best-practices) and [Backtracking](/dotnet/standard/base-types/backtracking-in-regular-expressions). If no match is found in that time interval, the method throws a exception. `matchTimeout` overrides any default time-out value defined for the application domain in which the method executes. - + method returns the first substring that matches a regular expression pattern in an input string. For information about the language elements used to build a regular expression pattern, see [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). + + The static method is equivalent to constructing a object with the constructor and calling the instance method. + + The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). + + You can determine whether the regular expression pattern has been found in the input string by checking the value of the returned object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . + + This method returns the first substring found in `input` that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can also retrieve all matches in a single method call by calling the method. + + The `matchTimeout` parameter specifies how long a pattern matching method should try to find a match before it times out. Setting a time-out interval prevents regular expressions that rely on excessive backtracking from appearing to stop responding when they process input that contains near matches. For more information, see [Best Practices for Regular Expressions](/dotnet/standard/base-types/best-practices) and [Backtracking](/dotnet/standard/base-types/backtracking-in-regular-expressions). If no match is found in that time interval, the method throws a exception. `matchTimeout` overrides any default time-out value defined for the application domain in which the method executes. + ]]> A regular expression parsing error occurred. or is . - is not a valid bitwise combination of values. - - -or- - + is not a valid bitwise combination of values. + + -or- + is negative, zero, or greater than approximately 24 days. A time-out occurred. For more information about time-outs, see the Remarks section. - We recommend that you set the parameter to an appropriate value, such as two seconds. If you disable time-outs by specifying , the regular expression engine offers slightly better performance. However, you should disable time-outs only under the following conditions: - -- When the input processed by a regular expression is derived from a known and trusted source or consists of static text. This excludes text that has been dynamically input by users. - -- When the regular expression pattern has been thoroughly tested to ensure that it efficiently handles matches, non-matches, and near matches. - + We recommend that you set the parameter to an appropriate value, such as two seconds. If you disable time-outs by specifying , the regular expression engine offers slightly better performance. However, you should disable time-outs only under the following conditions: + +- When the input processed by a regular expression is derived from a known and trusted source or consists of static text. This excludes text that has been dynamically input by users. + +- When the regular expression pattern has been thoroughly tested to ensure that it efficiently handles matches, non-matches, and near matches. + - When the regular expression pattern contains no language elements that are known to cause excessive backtracking when processing a near match. Regular Expression Language - Quick Reference @@ -4108,10 +3958,10 @@ For more information about right-to-left searches, see [Right-to-left mode](/dot Searches an input string for all occurrences of a regular expression and returns all the matches. - When a match attempt is repeated by calling the method, the regular expression engine gives empty matches special treatment. Usually, the regular expression engine begins the search for the next match exactly where the previous match left off. However, after an empty match, the regular expression engine advances by one character before trying the next match. This behavior guarantees that the regular expression engine will progress through the string. Otherwise, because an empty match does not result in any forward movement, the next match would start in exactly the same place as the previous match, and it would match the same empty string repeatedly. - - In the following example, the regular expression pattern a* searches for zero or more occurrences of the letter "a" in the string "abaabb". As the output from the example shows, the resulting object contains six objects. The first match attempt finds the first "a". The second match starts exactly where the first match ends, before the first b; it finds zero occurrences of "a" and returns an empty string. The third match does not begin exactly where the second match ended, because the second match returned an empty string. Instead, it begins one character later, after the first "b". The third match finds two occurrences of "a" and returns "aa". The fourth match attempt begins where the third match ended, before the second "b", and returns an empty string. The fifth match attempt again advances one character so that it begins before the third "b" and returns an empty string. The sixth match begins after the last "b" and returns an empty string again. - + When a match attempt is repeated by calling the method, the regular expression engine gives empty matches special treatment. Usually, the regular expression engine begins the search for the next match exactly where the previous match left off. However, after an empty match, the regular expression engine advances by one character before trying the next match. This behavior guarantees that the regular expression engine will progress through the string. Otherwise, because an empty match does not result in any forward movement, the next match would start in exactly the same place as the previous match, and it would match the same empty string repeatedly. + + In the following example, the regular expression pattern a* searches for zero or more occurrences of the letter "a" in the string "abaabb". As the output from the example shows, the resulting object contains six objects. The first match attempt finds the first "a". The second match starts exactly where the first match ends, before the first b; it finds zero occurrences of "a" and returns an empty string. The third match does not begin exactly where the second match ended, because the second match returned an empty string. Instead, it begins one character later, after the first "b". The third match finds two occurrences of "a" and returns "aa". The fourth match attempt begins where the third match ended, before the second "b", and returns an empty string. The fifth match attempt again advances one character so that it begins before the third "b" and returns an empty string. The sixth match begins after the last "b" and returns an empty string again. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Matches/emptymatches1.cs" id="Snippet9"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.matches/vb/emptymatches1.vb" id="Snippet9"::: @@ -4163,39 +4013,39 @@ For more information about right-to-left searches, see [Right-to-left mode](/dot Searches the specified input string for all occurrences of a regular expression. A collection of the objects found by the search. If no matches are found, the method returns an empty collection object. - method is similar to the method, except that it returns information about all the matches found in the input string, instead of a single match. It is equivalent to the following code: - + method is similar to the method, except that it returns information about all the matches found in the input string, instead of a single match. It is equivalent to the following code: + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Matches/matchespattern.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.matches/vb/matchespattern.vb" id="Snippet5"::: - - The collection includes only matches and terminates at the first non-match. - - The regular expression pattern for which the method searches is defined by the call to one of the class constructors. For more information about the elements that can form a regular expression pattern, see [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). - - The method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`...`Next` in Visual Basic. - - Because of its lazy evaluation, calling the method does not throw a exception. However, the exception is thrown when an operation is performed on the object returned by this method, if the property is not and a matching operation exceeds the time-out interval. - - - -## Examples - The following example uses the method to identify any words in a sentence that end in "es". + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.matches/vb/matchespattern.vb" id="Snippet5"::: + + The collection includes only matches and terminates at the first non-match. + + The regular expression pattern for which the method searches is defined by the call to one of the class constructors. For more information about the elements that can form a regular expression pattern, see [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). + + The method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`...`Next` in Visual Basic. + + Because of its lazy evaluation, calling the method does not throw a exception. However, the exception is thrown when an operation is performed on the object returned by this method, if the property is not and a matching operation exceeds the time-out interval. + + + +## Examples + The following example uses the method to identify any words in a sentence that end in "es". :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Matches/matches1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.matches/vb/matches1.vb" id="Snippet1"::: - - The regular expression pattern `\b\w+es\b` is defined as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`\b`|Begin the match at a word boundary.| -|`\w+`|Match one or more word characters.| -|`es`|Match the literal string "es".| -|`\b`|End the match at a word boundary.| - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.matches/vb/matches1.vb" id="Snippet1"::: + + The regular expression pattern `\b\w+es\b` is defined as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`\b`|Begin the match at a word boundary.| +|`\w+`|Match one or more word characters.| +|`es`|Match the literal string "es".| +|`\b`|End the match at a word boundary.| + ]]> @@ -4250,39 +4100,39 @@ For more information about right-to-left searches, see [Right-to-left mode](/dot Searches the specified input string for all occurrences of a regular expression, beginning at the specified starting position in the string. A collection of the objects found by the search. If no matches are found, the method returns an empty collection object. - method is similar to the method, except that it returns information about all the matches found in the input string, instead of a single match. It is equivalent to the following code: - + method is similar to the method, except that it returns information about all the matches found in the input string, instead of a single match. It is equivalent to the following code: + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Matches/matchespattern.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.matches/vb/matchespattern.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.matches/vb/matchespattern.vb" id="Snippet6"::: + The regular expression pattern for which the method searches is defined by the call to one of the class constructors. For more information about the elements that can form a regular expression pattern, see [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). -For more details about `startat`, see the Remarks section of . - - The method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`...`Next` in Visual Basic. - - Because of its lazy evaluation, calling the method does not throw a exception. However, the exception is thrown when an operation is performed on the object returned by this method, if the property is not and a matching operation exceeds the time-out interval. - - - -## Examples - The following example uses the method to find the first word in a sentence that ends in "es", and then calls the method to identify any additional words that end in "es". - +For more details about `startat`, see the Remarks section of . + + The method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`...`Next` in Visual Basic. + + Because of its lazy evaluation, calling the method does not throw a exception. However, the exception is thrown when an operation is performed on the object returned by this method, if the property is not and a matching operation exceeds the time-out interval. + + + +## Examples + The following example uses the method to find the first word in a sentence that ends in "es", and then calls the method to identify any additional words that end in "es". + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Matches/matches3.cs" interactive="try-dotnet" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.matches/vb/matches3.vb" id="Snippet3"::: - - The regular expression pattern `\b\w+es\b` is defined as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`\b`|Begin the match at a word boundary.| -|`\w+`|Match one or more word characters.| -|`es`|Match the literal string "es".| -|`\b`|End the match at a word boundary.| - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.matches/vb/matches3.vb" id="Snippet3"::: + + The regular expression pattern `\b\w+es\b` is defined as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`\b`|Begin the match at a word boundary.| +|`\w+`|Match one or more word characters.| +|`es`|Match the literal string "es".| +|`\b`|End the match at a word boundary.| + ]]> @@ -4346,39 +4196,39 @@ For more details about `startat`, see the Remarks section of Searches the specified input string for all occurrences of a specified regular expression. A collection of the objects found by the search. If no matches are found, the method returns an empty collection object. - method is similar to the method, except that it returns information about all the matches found in the input string, instead of a single match. It is equivalent to the following code: - + method is similar to the method, except that it returns information about all the matches found in the input string, instead of a single match. It is equivalent to the following code: + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Matches/matchespattern.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.matches/vb/matchespattern.vb" id="Snippet7"::: - - The static `Matches` methods are equivalent to constructing a object with the specified regular expression pattern and calling the instance method `Matches`. - - The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). - - The method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`...`Next` in Visual Basic. - - Because of its lazy evaluation, calling the method does not throw a exception. However, the exception is thrown when an operation is performed on the object returned by this method, if a time-out interval is defined by the "REGEX_DEFAULT_MATCH_TIMEOUT" property of the current application domain and a matching operation exceeds this time-out interval. - - - -## Examples - The following example uses the method to identify any word in a sentence that ends in "es". + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.matches/vb/matchespattern.vb" id="Snippet7"::: + + The static `Matches` methods are equivalent to constructing a object with the specified regular expression pattern and calling the instance method `Matches`. + + The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). + + The method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`...`Next` in Visual Basic. + + Because of its lazy evaluation, calling the method does not throw a exception. However, the exception is thrown when an operation is performed on the object returned by this method, if a time-out interval is defined by the "REGEX_DEFAULT_MATCH_TIMEOUT" property of the current application domain and a matching operation exceeds this time-out interval. + + + +## Examples + The following example uses the method to identify any word in a sentence that ends in "es". :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Matches/matches2.cs" interactive="try-dotnet" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.matches/vb/matches2.vb" id="Snippet2"::: - - The regular expression pattern `\b\w+es\b` is defined as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`\b`|Begin the match at a word boundary.| -|`\w+`|Match one or more word characters.| -|`es`|Match the literal string "es".| -|`\b`|End the match at a word boundary.| - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.matches/vb/matches2.vb" id="Snippet2"::: + + The regular expression pattern `\b\w+es\b` is defined as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`\b`|Begin the match at a word boundary.| +|`\w+`|Match one or more word characters.| +|`es`|Match the literal string "es".| +|`\b`|End the match at a word boundary.| + ]]> A regular expression parsing error occurred. @@ -4446,39 +4296,39 @@ For more details about `startat`, see the Remarks section of Searches the specified input string for all occurrences of a specified regular expression, using the specified matching options. A collection of the objects found by the search. If no matches are found, the method returns an empty collection object. - method is similar to the method, except that it returns information about all the matches found in the input string, instead of a single match. It is equivalent to the following code: - + method is similar to the method, except that it returns information about all the matches found in the input string, instead of a single match. It is equivalent to the following code: + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Matches/matchespattern.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.matches/vb/matchespattern.vb" id="Snippet8"::: - - The static `Matches` methods are equivalent to constructing a object with the specified regular expression pattern and calling the instance method `Matches`. - - The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). - - The method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`...`Next` in Visual Basic. - - Because of its lazy evaluation, calling the method does not throw a exception. However, the exception is thrown when an operation is performed on the object returned by this method, if a time-out interval is defined by the "REGEX_DEFAULT_MATCH_TIMEOUT" property of the current application domain and a matching operation exceeds this time-out interval. - - - -## Examples - The following example calls the method to identify any word in a sentence that ends in "es", and then calls the method to perform a case-insensitive comparison of the pattern with the input string. As the output shows, the two methods return different results. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.matches/vb/matchespattern.vb" id="Snippet8"::: + + The static `Matches` methods are equivalent to constructing a object with the specified regular expression pattern and calling the instance method `Matches`. + + The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). + + The method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`...`Next` in Visual Basic. + + Because of its lazy evaluation, calling the method does not throw a exception. However, the exception is thrown when an operation is performed on the object returned by this method, if a time-out interval is defined by the "REGEX_DEFAULT_MATCH_TIMEOUT" property of the current application domain and a matching operation exceeds this time-out interval. + + + +## Examples + The following example calls the method to identify any word in a sentence that ends in "es", and then calls the method to perform a case-insensitive comparison of the pattern with the input string. As the output shows, the two methods return different results. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Matches/matches4.cs" interactive="try-dotnet" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.matches/vb/matches4.vb" id="Snippet4"::: - - The regular expression pattern `\b\w+es\b` is defined as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`\b`|Begin the match at a word boundary.| -|`\w+`|Match one or more word characters.| -|`es`|Match the literal string "es".| -|`\b`|End the match at a word boundary.| - + + The regular expression pattern `\b\w+es\b` is defined as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`\b`|Begin the match at a word boundary.| +|`\w+`|Match one or more word characters.| +|`es`|Match the literal string "es".| +|`\b`|End the match at a word boundary.| + ]]> A regular expression parsing error occurred. @@ -4548,57 +4398,57 @@ For more details about `startat`, see the Remarks section of Searches the specified input string for all occurrences of a specified regular expression, using the specified matching options and time-out interval. A collection of the objects found by the search. If no matches are found, the method returns an empty collection object. - method is similar to the method, except that it returns information about all the matches found in the input string, instead of a single match. It is equivalent to the following code: - + method is similar to the method, except that it returns information about all the matches found in the input string, instead of a single match. It is equivalent to the following code: + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Matches/matchespattern.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.matches/vb/matchespattern.vb" id="Snippet10"::: - - The static `Matches` methods are equivalent to constructing a object with the specified regular expression pattern and calling the instance method `Matches`. - - The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). - - The method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`...`Next` in Visual Basic. - - Because of its lazy evaluation, calling the method does not throw a exception. However, an exception is thrown when an operation is performed on the object returned by this method, if a matching operation exceeds this time-out interval specified by the`matchTimeout` parameter. - - - -## Examples - The following example calls the method to perform a case-sensitive comparison that matches any word in a sentence that ends in "es". It then calls the method to perform a case-insensitive comparison of the pattern with the input string. In both cases, the time-out interval is set to one second. As the output shows, the two methods return different results. + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.matches/vb/matchespattern.vb" id="Snippet10"::: + + The static `Matches` methods are equivalent to constructing a object with the specified regular expression pattern and calling the instance method `Matches`. + + The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). + + The method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`...`Next` in Visual Basic. + + Because of its lazy evaluation, calling the method does not throw a exception. However, an exception is thrown when an operation is performed on the object returned by this method, if a matching operation exceeds this time-out interval specified by the`matchTimeout` parameter. + + + +## Examples + The following example calls the method to perform a case-sensitive comparison that matches any word in a sentence that ends in "es". It then calls the method to perform a case-insensitive comparison of the pattern with the input string. In both cases, the time-out interval is set to one second. As the output shows, the two methods return different results. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Matches/matches5.cs" interactive="try-dotnet" id="Snippet11"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.matches/vb/matches5.vb" id="Snippet11"::: - - The regular expression pattern `\b\w+es\b` is defined as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`\b`|Begin the match at a word boundary.| -|`\w+`|Match one or more word characters.| -|`es`|Match the literal string "es".| -|`\b`|End the match at a word boundary.| - + + The regular expression pattern `\b\w+es\b` is defined as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`\b`|Begin the match at a word boundary.| +|`\w+`|Match one or more word characters.| +|`es`|Match the literal string "es".| +|`\b`|End the match at a word boundary.| + ]]> A regular expression parsing error occurred. or is . - is not a valid bitwise combination of values. - - -or- - + is not a valid bitwise combination of values. + + -or- + is negative, zero, or greater than approximately 24 days. - We recommend that you set the parameter to an appropriate value, such as two seconds. If you disable time-outs by specifying , the regular expression engine offers slightly better performance. However, you should disable time-outs only under the following conditions: - -- When the input processed by a regular expression is derived from a known and trusted source or consists of static text. This excludes text that has been dynamically input by users. - -- When the regular expression pattern has been thoroughly tested to ensure that it efficiently handles matches, non-matches, and near matches. - + We recommend that you set the parameter to an appropriate value, such as two seconds. If you disable time-outs by specifying , the regular expression engine offers slightly better performance. However, you should disable time-outs only under the following conditions: + +- When the input processed by a regular expression is derived from a known and trusted source or consists of static text. This excludes text that has been dynamically input by users. + +- When the regular expression pattern has been thoroughly tested to ensure that it efficiently handles matches, non-matches, and near matches. + - When the regular expression pattern contains no language elements that are known to cause excessive backtracking when processing a near match. Regular Expression Language Elements @@ -4643,18 +4493,18 @@ For more details about `startat`, see the Remarks section of Gets the time-out interval of the current instance. The maximum time interval that can elapse in a pattern-matching operation before a is thrown, or if time-outs are disabled. - property defines the approximate maximum time interval for a instance to execute a single matching operation before the operation times out. The regular expression engine throws a exception during its next timing check after the time-out interval has elapsed. This prevents the regular expression engine from processing input strings that require excessive backtracking. For more information, see [Backtracking](/dotnet/standard/base-types/backtracking-in-regular-expressions) and [Best Practices for Regular Expressions](/dotnet/standard/base-types/best-practices). - - This property is read-only. You can set its value explicitly for an individual object by calling the constructor; and you can set its value for all matching operations in an application domain by calling the method and providing a value for the "REGEX_DEFAULT_MATCH_TIMEOUT" property, as the following example illustrates. - + property defines the approximate maximum time interval for a instance to execute a single matching operation before the operation times out. The regular expression engine throws a exception during its next timing check after the time-out interval has elapsed. This prevents the regular expression engine from processing input strings that require excessive backtracking. For more information, see [Backtracking](/dotnet/standard/base-types/backtracking-in-regular-expressions) and [Best Practices for Regular Expressions](/dotnet/standard/base-types/best-practices). + + This property is read-only. You can set its value explicitly for an individual object by calling the constructor; and you can set its value for all matching operations in an application domain by calling the method and providing a value for the "REGEX_DEFAULT_MATCH_TIMEOUT" property, as the following example illustrates. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/MatchTimeout/regexmatchtimeout1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.matchtimeout/vb/regexmatchtimeout1.vb" id="Snippet1"::: - - If you do not explicitly set a time-out interval, the default value is used, and matching operations do not time out. - + + If you do not explicitly set a time-out interval, the default value is used, and matching operations do not time out. + ]]> @@ -4706,13 +4556,13 @@ For more details about `startat`, see the Remarks section of Gets the options that were passed into the constructor. One or more members of the enumeration that represent options that were passed to the constructor. - property consists of one or more members of the enumeration. If no options were defined in the class constructor, its value is . The available options are discussed in detail in the [Regular Expression Options](/dotnet/standard/base-types/regular-expression-options) topic. - - Note that the property does not reflect inline options defined in the regular expression pattern itself. - + property consists of one or more members of the enumeration. If no options were defined in the class constructor, its value is . The available options are discussed in detail in the [Regular Expression Options](/dotnet/standard/base-types/regular-expression-options) topic. + + Note that the property does not reflect inline options defined in the regular expression pattern itself. + ]]> @@ -4836,46 +4686,46 @@ For more details about `startat`, see the Remarks section of In a specified input string, replaces all strings that match a regular expression pattern with a specified replacement string. A new string that is identical to the input string, except that the replacement string takes the place of each matched string. If the regular expression pattern is not matched in the current instance, the method returns the current instance unchanged. - object. - - The `replacement` parameter specifies the string that is to replace each match in `input`. `replacement` can consist of any combination of literal text and [substitutions](/dotnet/standard/base-types/substitutions-in-regular-expressions). For example, the replacement pattern `a*${test}b` inserts the string "a*" followed by the substring that is matched by the `test` capturing group, if any, followed by the string "b". The * character is not recognized as a metacharacter within a replacement pattern. - + object. + + The `replacement` parameter specifies the string that is to replace each match in `input`. `replacement` can consist of any combination of literal text and [substitutions](/dotnet/standard/base-types/substitutions-in-regular-expressions). For example, the replacement pattern `a*${test}b` inserts the string "a*" followed by the substring that is matched by the `test` capturing group, if any, followed by the string "b". The * character is not recognized as a metacharacter within a replacement pattern. + > [!NOTE] -> Substitutions are the only regular expression language elements that are recognized in a replacement pattern. All other regular expression language elements, including [character escapes](/dotnet/standard/base-types/character-escapes-in-regular-expressions), are allowed in regular expression patterns only and are not recognized in replacement patterns. - - The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown - - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. - - - -## Examples - The following example defines a regular expression, `\s+`, that matches one or more white-space characters. The replacement string, " ", replaces them with a single space character. - +> Substitutions are the only regular expression language elements that are recognized in a replacement pattern. All other regular expression language elements, including [character escapes](/dotnet/standard/base-types/character-escapes-in-regular-expressions), are allowed in regular expression patterns only and are not recognized in replacement patterns. + + The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown + + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + + + +## Examples + The following example defines a regular expression, `\s+`, that matches one or more white-space characters. The replacement string, " ", replaces them with a single space character. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/replaceexample5.cs" interactive="try-dotnet" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/replaceexample5.vb" id="Snippet5"::: - - The following example defines a regular expression, `(\p{Sc}\s?)?(\d+\.?((?<=\.)\d+)?)(?(1)|\s?\p{Sc})?`, and a replacement pattern, `$2`, that removes either a leading or a trailing currency symbol from a numeric value. - + + The following example defines a regular expression, `(\p{Sc}\s?)?(\d+\.?((?<=\.)\d+)?)(?(1)|\s?\p{Sc})?`, and a replacement pattern, `$2`, that removes either a leading or a trailing currency symbol from a numeric value. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/replaceexample7.cs" interactive="try-dotnet" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/replaceexample7.vb" id="Snippet7"::: - - The regular expression is interpreted as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`\p{Sc}`|Match a currency symbol. `{Sc}` denotes any character that is a member of the Unicode Symbol, Currency category.| -|`\s?`|Match zero or one white-space character.| -|`(\p{Sc}\s?)?`|Match zero or one occurrence of the combination of a currency symbol followed by zero or one white-space character. This is the first capturing group.| -|`\d+`|Match one or more decimal digits.| -|`\.?`|Match zero or one occurrence of a period (used as a decimal separator character).| -|`((?<=\.)\d+)?`|If a period is the previous character, match one or more decimal digits. This pattern can be matched either zero or one time.| -|`(\d+\.?((?<=\.)\d+)?)`|Match the pattern of one or more decimal digits followed by an optional period and additional decimal digits. This is the second capturing group. The call to the method replaces the entire match with the value of this captured group.| -|(?(1)|\s?\p{Sc})?|If the first captured group exists, match an empty string. Otherwise, match zero or one white-space character followed by a currency symbol.| - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/replaceexample7.vb" id="Snippet7"::: + + The regular expression is interpreted as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`\p{Sc}`|Match a currency symbol. `{Sc}` denotes any character that is a member of the Unicode Symbol, Currency category.| +|`\s?`|Match zero or one white-space character.| +|`(\p{Sc}\s?)?`|Match zero or one occurrence of the combination of a currency symbol followed by zero or one white-space character. This is the first capturing group.| +|`\d+`|Match one or more decimal digits.| +|`\.?`|Match zero or one occurrence of a period (used as a decimal separator character).| +|`((?<=\.)\d+)?`|If a period is the previous character, match one or more decimal digits. This pattern can be matched either zero or one time.| +|`(\d+\.?((?<=\.)\d+)?)`|Match the pattern of one or more decimal digits followed by an optional period and additional decimal digits. This is the second capturing group. The call to the method replaces the entire match with the value of this captured group.| +|(?(1)|\s?\p{Sc})?|If the first captured group exists, match an empty string. Otherwise, match zero or one white-space character followed by a currency symbol.| + ]]> @@ -4932,40 +4782,40 @@ For more details about `startat`, see the Remarks section of In a specified input string, replaces all strings that match a specified regular expression with a string returned by a delegate. A new string that is identical to the input string, except that a replacement string takes the place of each matched string. If the regular expression pattern is not matched in the current instance, the method returns the current instance unchanged. - method is useful for replacing a regular expression match if any of the following conditions is true: - -- The replacement string cannot readily be specified by a regular expression replacement pattern. - -- The replacement string results from some processing done on the matched string. - -- The replacement string results from conditional processing. - - The method is equivalent to calling the method and passing each object in the returned collection to the `evaluator` delegate. - - The regular expression is the pattern defined by the constructor for the current object. - - The `evaluator` parameter is the delegate for a custom method that you define and that examines each match. The custom method must have the following signature to match the delegate. - + method is useful for replacing a regular expression match if any of the following conditions is true: + +- The replacement string cannot readily be specified by a regular expression replacement pattern. + +- The replacement string results from some processing done on the matched string. + +- The replacement string results from conditional processing. + + The method is equivalent to calling the method and passing each object in the returned collection to the `evaluator` delegate. + + The regular expression is the pattern defined by the constructor for the current object. + + The `evaluator` parameter is the delegate for a custom method that you define and that examines each match. The custom method must have the following signature to match the delegate. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/syntax1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/syntax1.vb" id="Snippet1"::: - - Your custom method returns a string that replaces the matched input. - - The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown - - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. - - - -## Examples - The following code example displays an original string, matches each word in the original string, converts the first character of each match to uppercase, then displays the converted string. + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/syntax1.vb" id="Snippet1"::: + + Your custom method returns a string that replaces the matched input. + + The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown + + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + + + +## Examples + The following code example displays an original string, matches each word in the original string, converts the first character of each match to uppercase, then displays the converted string. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/sample.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Regex.Replace-Instance/vb/sample.vb" id="Snippet1"::: - + ]]> @@ -5025,29 +4875,29 @@ For more details about `startat`, see the Remarks section of In a specified input string, replaces a specified maximum number of strings that match a regular expression pattern with a specified replacement string. A new string that is identical to the input string, except that the replacement string takes the place of each matched string. If the regular expression pattern is not matched in the current instance, the method returns the current instance unchanged. - object. If `count` is negative, replacements continue to the end of the string. If `count` exceeds the number of matches, all matches are replaced. - - The `replacement` parameter specifies the string that is to replace the first `count` matches in `input`. `replacement` can consist of any combination of literal text and [substitutions](/dotnet/standard/base-types/substitutions-in-regular-expressions). For example, the replacement pattern `a*${test}b` inserts the string "a*" followed by the substring that is matched by the `test` capturing group, if any, followed by the string "b". The * character is not recognized as a metacharacter within a replacement pattern. - -> [!NOTE] -> Substitutions are the only regular expression language elements that are recognized in a replacement pattern. All other regular expression language elements, including [character escapes](/dotnet/standard/base-types/character-escapes-in-regular-expressions), are allowed in regular expression patterns only and are not recognized in replacement patterns. - - The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown - - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. - - - -## Examples - The following example replaces the first five occurrences of duplicated characters with a single character. The regular expression pattern `(\w)\1` matches consecutive occurrences of a single character and assigns the first occurrence to the first capturing group. The replacement pattern `$1` replaces the entire match with the first captured group. - - :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/replaceexample8.cs" interactive="try-dotnet" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/replaceexample8.vb" id="Snippet8"::: - - ]]> + object. If `count` is negative, replacements continue to the end of the string. If `count` exceeds the number of matches, all matches are replaced. + + The `replacement` parameter specifies the string that is to replace the first `count` matches in `input`. `replacement` can consist of any combination of literal text and [substitutions](/dotnet/standard/base-types/substitutions-in-regular-expressions). For example, the replacement pattern `a*${test}b` inserts the string "a*" followed by the substring that is matched by the `test` capturing group, if any, followed by the string "b". The * character is not recognized as a metacharacter within a replacement pattern. + +> [!NOTE] +> Substitutions are the only regular expression language elements that are recognized in a replacement pattern. All other regular expression language elements, including [character escapes](/dotnet/standard/base-types/character-escapes-in-regular-expressions), are allowed in regular expression patterns only and are not recognized in replacement patterns. + + The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown + + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + + + +## Examples + The following example replaces the first five occurrences of duplicated characters with a single character. The regular expression pattern `(\w)\1` matches consecutive occurrences of a single character and assigns the first occurrence to the first capturing group. The replacement pattern `$1` replaces the entire match with the first captured group. + + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/replaceexample8.cs" interactive="try-dotnet" id="Snippet8"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/replaceexample8.vb" id="Snippet8"::: + + ]]> or is . @@ -5112,52 +4962,52 @@ For more details about `startat`, see the Remarks section of In a specified input string, replaces all strings that match a specified regular expression with a specified replacement string. A new string that is identical to the input string, except that the replacement string takes the place of each matched string. If is not matched in the current instance, the method returns the current instance unchanged. - object with the specified regular expression pattern and calling the instance method `Replace`. - - The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). The search for matches starts at the beginning of the `input` string. - - The `replacement` parameter specifies the string that is to replace each match in `input`. `replacement` can consist of any combination of literal text and [substitutions](/dotnet/standard/base-types/substitutions-in-regular-expressions). For example, the replacement pattern `a*${test}b` inserts the string "a*" followed by the substring that is matched by the `test` capturing group, if any, followed by the string "b". The * character is not recognized as a metacharacter within a replacement pattern. - + object with the specified regular expression pattern and calling the instance method `Replace`. + + The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). The search for matches starts at the beginning of the `input` string. + + The `replacement` parameter specifies the string that is to replace each match in `input`. `replacement` can consist of any combination of literal text and [substitutions](/dotnet/standard/base-types/substitutions-in-regular-expressions). For example, the replacement pattern `a*${test}b` inserts the string "a*" followed by the substring that is matched by the `test` capturing group, if any, followed by the string "b". The * character is not recognized as a metacharacter within a replacement pattern. + > [!NOTE] -> Substitutions are the only regular expression language elements that are recognized in a replacement pattern. All other regular expression language elements, including [character escapes](/dotnet/standard/base-types/character-escapes-in-regular-expressions), are allowed in regular expression patterns only and are not recognized in replacement patterns. - - The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. - - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. - - - -## Examples - The following example defines a regular expression, `\s+`, that matches one or more white-space characters. The replacement string, " ", replaces them with a single space character. - +> Substitutions are the only regular expression language elements that are recognized in a replacement pattern. All other regular expression language elements, including [character escapes](/dotnet/standard/base-types/character-escapes-in-regular-expressions), are allowed in regular expression patterns only and are not recognized in replacement patterns. + + The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. + + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + + + +## Examples + The following example defines a regular expression, `\s+`, that matches one or more white-space characters. The replacement string, " ", replaces them with a single space character. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/replaceexample6.cs" interactive="try-dotnet" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/replaceexample6.vb" id="Snippet6"::: - - The following example uses the method to replace the local machine and drive names in a UNC path with a local file path. The regular expression uses the property to include the name of the local computer, and the method to include the names of the logical drives. To run the example successfully, you should replace the literal string "MyMachine" with your local machine name. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/replaceexample6.vb" id="Snippet6"::: + + The following example uses the method to replace the local machine and drive names in a UNC path with a local file path. The regular expression uses the property to include the name of the local computer, and the method to include the names of the logical drives. To run the example successfully, you should replace the literal string "MyMachine" with your local machine name. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/replace3.cs" interactive="try-dotnet" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/replace3.vb" id="Snippet3"::: - - The regular expression pattern is defined by the following expression: - - `"\\\\(?i:" + Environment.MachineName + ")(?:\.\w+)*\\((?i:[" + driveNames + "]))\$"` - - The following table shows how the regular expression pattern is interpreted. - -|Pattern|Description| -|-------------|-----------------| -|`\\\\`|Match two consecutive backslash (`\`) characters. Because the backslash character is interpreted as the escape character, each backslash must be escaped with another backslash.| -|`(?i:" + Environment.MachineName + ")`|Perform a case-insensitive match of the string that is returned by the property.| -|`(?:\.\w+)*`|Match the period (`.`) character followed by one or more word characters. This match can occur zero or more times. The matched subexpression is not captured.| -|`\\`|Match a backslash (`\`) character.| -|`((?i:[" + driveNames + "]))`|Perform a case-insensitive match of the character class that consists of the individual drive letters. This match is the first captured subexpression.| -|`\$`|Match the literal dollar sign (`$`) character.| - - The replacement pattern `$1` replaces the entire match with the first captured subexpression. That is, it replaces the UNC machine and drive name with the drive letter. - + + The regular expression pattern is defined by the following expression: + + `"\\\\(?i:" + Environment.MachineName + ")(?:\.\w+)*\\((?i:[" + driveNames + "]))\$"` + + The following table shows how the regular expression pattern is interpreted. + +|Pattern|Description| +|-------------|-----------------| +|`\\\\`|Match two consecutive backslash (`\`) characters. Because the backslash character is interpreted as the escape character, each backslash must be escaped with another backslash.| +|`(?i:" + Environment.MachineName + ")`|Perform a case-insensitive match of the string that is returned by the property.| +|`(?:\.\w+)*`|Match the period (`.`) character followed by one or more word characters. This match can occur zero or more times. The matched subexpression is not captured.| +|`\\`|Match a backslash (`\`) character.| +|`((?i:[" + driveNames + "]))`|Perform a case-insensitive match of the character class that consists of the individual drive letters. This match is the first captured subexpression.| +|`\$`|Match the literal dollar sign (`$`) character.| + + The replacement pattern `$1` replaces the entire match with the first captured subexpression. That is, it replaces the UNC machine and drive name with the drive letter. + ]]> A regular expression parsing error occurred. @@ -5227,40 +5077,40 @@ For more details about `startat`, see the Remarks section of In a specified input string, replaces all strings that match a specified regular expression with a string returned by a delegate. A new string that is identical to the input string, except that a replacement string takes the place of each matched string. If is not matched in the current instance, the method returns the current instance unchanged. - method is useful for replacing a regular expression match if any of the following conditions is true: - -- The replacement string cannot readily be specified by a regular expression replacement pattern. - -- The replacement string results from some processing done on the matched string. - -- The replacement string results from conditional processing. - - The method is equivalent to calling the method and passing each object in the returned collection to the `evaluator` delegate. - - The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). - - The `evaluator` parameter is the delegate for a custom method that you define and that examines each match. The custom method must have the following signature to match the delegate. - + method is useful for replacing a regular expression match if any of the following conditions is true: + +- The replacement string cannot readily be specified by a regular expression replacement pattern. + +- The replacement string results from some processing done on the matched string. + +- The replacement string results from conditional processing. + + The method is equivalent to calling the method and passing each object in the returned collection to the `evaluator` delegate. + + The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). + + The `evaluator` parameter is the delegate for a custom method that you define and that examines each match. The custom method must have the following signature to match the delegate. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/syntax1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/syntax1.vb" id="Snippet1"::: - - Your custom method returns a string that replaces the matched input. - - The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. - - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. - - - -## Examples - The following example uses a regular expression to extract the individual words from a string, and then uses a delegate to call a method named `WordScramble` that scrambles the individual letters in the word. To do this, the `WordScramble` method creates an array that contains the characters in the match. It also creates a parallel array that it populates with random floating-point numbers. The arrays are sorted by calling the method, and the sorted array is provided as an argument to a class constructor. This newly created string is then returned by the `WordScramble` method. The regular expression pattern `\w+` matches one or more word characters; the regular expression engine will continue to add characters to the match until it encounters a non-word character, such as a white-space character. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/syntax1.vb" id="Snippet1"::: + + Your custom method returns a string that replaces the matched input. + + The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. + + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + + + +## Examples + The following example uses a regular expression to extract the individual words from a string, and then uses a delegate to call a method named `WordScramble` that scrambles the individual letters in the word. To do this, the `WordScramble` method creates an array that contains the characters in the match. It also creates a parallel array that it populates with random floating-point numbers. The arrays are sorted by calling the method, and the sorted array is provided as an argument to a class constructor. This newly created string is then returned by the `WordScramble` method. The regular expression pattern `\w+` matches one or more word characters; the regular expression engine will continue to add characters to the match until it encounters a non-word character, such as a white-space character. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/replace5.cs" interactive="try-dotnet" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/replace5.vb" id="Snippet2"::: - + ]]> A regular expression parsing error occurred. @@ -5324,50 +5174,50 @@ For more details about `startat`, see the Remarks section of In a specified input string, replaces a specified maximum number of strings that match a regular expression pattern with a string returned by a delegate. A new string that is identical to the input string, except that a replacement string takes the place of each matched string. If the regular expression pattern is not matched in the current instance, the method returns the current instance unchanged. - method is useful for replacing a regular expression match if any of the following conditions is true: - -- The replacement string cannot readily be specified by a regular expression replacement pattern. - -- The replacement string results from some processing done on the matched string. - -- The replacement string results from conditional processing. - - The method is equivalent to calling the method and passing the first `count` objects in the returned collection to the `evaluator` delegate. - - The regular expression is the pattern defined by the constructor for the current object. - - The `evaluator` parameter is the delegate for a custom method that you define and that examines each match. The custom method must have the following signature to match the delegate. + method is useful for replacing a regular expression match if any of the following conditions is true: + +- The replacement string cannot readily be specified by a regular expression replacement pattern. + +- The replacement string results from some processing done on the matched string. + +- The replacement string results from conditional processing. + + The method is equivalent to calling the method and passing the first `count` objects in the returned collection to the `evaluator` delegate. + + The regular expression is the pattern defined by the constructor for the current object. + + The `evaluator` parameter is the delegate for a custom method that you define and that examines each match. The custom method must have the following signature to match the delegate. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/syntax1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/syntax1.vb" id="Snippet1"::: - - Your custom method returns a string that replaces the matched input. - - The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown - - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. - - - -## Examples - The following example uses a regular expression to deliberately misspell half of the words in a list. It uses the regular expression `\w*(ie|ei)\w*` to match words that include the characters "ie" or "ei". It passes the first half of the matching words to the `ReverseLetter` method, which, in turn, uses the method to reverse "i" and "e" in the matched string. The remaining words remain unchanged. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/syntax1.vb" id="Snippet1"::: + + Your custom method returns a string that replaces the matched input. + + The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown + + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + + + +## Examples + The following example uses a regular expression to deliberately misspell half of the words in a list. It uses the regular expression `\w*(ie|ei)\w*` to match words that include the characters "ie" or "ei". It passes the first half of the matching words to the `ReverseLetter` method, which, in turn, uses the method to reverse "i" and "e" in the matched string. The remaining words remain unchanged. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/replace7.cs" interactive="try-dotnet" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/replace7.vb" id="Snippet11"::: - - The regular expression `\w*(ie|ei)\w*` is defined as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`\w*`|Match zero or more word characters.| -|(ie|ei)|Match either "ie" or "ei".| -|`\w*`|Match zero or more word characters.| - - The regular expression pattern `([ie])([ie])` in the `ReverseLetter` method matches the first "i" or "e" in the diphthong "ie" or "ei" and assigns the letter to the first capturing group. It matches the second "i" or "e" and assigns the letter to the second capturing group. The two characters are then reversed by calling the method with the replacement pattern `$2$1`. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/replace7.vb" id="Snippet11"::: + + The regular expression `\w*(ie|ei)\w*` is defined as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`\w*`|Match zero or more word characters.| +|(ie|ei)|Match either "ie" or "ei".| +|`\w*`|Match zero or more word characters.| + + The regular expression pattern `([ie])([ie])` in the `ReverseLetter` method matches the first "i" or "e" in the diphthong "ie" or "ei" and assigns the letter to the first capturing group. It matches the second "i" or "e" and assigns the letter to the second capturing group. The two characters are then reversed by calling the method with the replacement pattern `$2$1`. + ]]> @@ -5429,40 +5279,40 @@ For more details about `startat`, see the Remarks section of In a specified input substring, replaces a specified maximum number of strings that match a regular expression pattern with a specified replacement string. A new string that is identical to the input string, except that the replacement string takes the place of each matched string. If the regular expression pattern is not matched in the current instance, the method returns the current instance unchanged. - object. If `count` is negative, replacements continue to the end of the string. If `count` exceeds the number of matches, all matches are replaced. -For more details about `startat`, see the Remarks section of . - - The `replacement` parameter specifies the string that is to replace each match in `input`. `replacement` can consist of any combination of literal text and [substitutions](/dotnet/standard/base-types/substitutions-in-regular-expressions). For example, the replacement pattern `a*${test}b` inserts the string "a*" followed by the substring that is matched by the `test` capturing group, if any, followed by the string "b". The * character is not recognized as a metacharacter within a replacement pattern. - +For more details about `startat`, see the Remarks section of . + + The `replacement` parameter specifies the string that is to replace each match in `input`. `replacement` can consist of any combination of literal text and [substitutions](/dotnet/standard/base-types/substitutions-in-regular-expressions). For example, the replacement pattern `a*${test}b` inserts the string "a*" followed by the substring that is matched by the `test` capturing group, if any, followed by the string "b". The * character is not recognized as a metacharacter within a replacement pattern. + > [!NOTE] -> Substitutions are the only regular expression language elements that are recognized in a replacement pattern. All other regular expression language elements, including [character escapes](/dotnet/standard/base-types/character-escapes-in-regular-expressions), are allowed in regular expression patterns only and are not recognized in replacement patterns. - - The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown - - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. - - - -## Examples - The following example double-spaces all but the first line of a string. It defines a regular expression pattern, `^.*$`, that matches a line of text, calls the method to match the first line of the string, and uses the `Match.Index` and `Match.Count` properties to determine the starting position of the second line. - +> Substitutions are the only regular expression language elements that are recognized in a replacement pattern. All other regular expression language elements, including [character escapes](/dotnet/standard/base-types/character-escapes-in-regular-expressions), are allowed in regular expression patterns only and are not recognized in replacement patterns. + + The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown + + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + + + +## Examples + The following example double-spaces all but the first line of a string. It defines a regular expression pattern, `^.*$`, that matches a line of text, calls the method to match the first line of the string, and uses the `Match.Index` and `Match.Count` properties to determine the starting position of the second line. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/replaceexample9.cs" interactive="try-dotnet" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/replaceexample9.vb" id="Snippet9"::: - - The regular expression pattern `^.*$` is defined as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`^`|Match the start of a line. (Note that the object was instantiated by using the option; otherwise, this character class would only match the beginning of the input string.)| -|`.*`|Match any character zero or more times.| -|`$`|Match the end of a line. (Note that the object was instantiated by using the option; otherwise, this character class would only match the beginning of the input string.)| - - The replacement string (`vbCrLf + "$&"` in Visual Basic, `"\n$&"` in C#) adds a new line before the matched string. Note that `\n` in the C# example is interpreted as the newline character by the C# compiler; it does not represent a regular expression character escape. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/replaceexample9.vb" id="Snippet9"::: + + The regular expression pattern `^.*$` is defined as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`^`|Match the start of a line. (Note that the object was instantiated by using the option; otherwise, this character class would only match the beginning of the input string.)| +|`.*`|Match any character zero or more times.| +|`$`|Match the end of a line. (Note that the object was instantiated by using the option; otherwise, this character class would only match the beginning of the input string.)| + + The replacement string (`vbCrLf + "$&"` in Visual Basic, `"\n$&"` in C#) adds a new line before the matched string. Note that `\n` in the C# example is interpreted as the newline character by the C# compiler; it does not represent a regular expression character escape. + ]]> @@ -5532,47 +5382,47 @@ For more details about `startat`, see the Remarks section of In a specified input string, replaces all strings that match a specified regular expression with a specified replacement string. Specified options modify the matching operation. A new string that is identical to the input string, except that the replacement string takes the place of each matched string. If is not matched in the current instance, the method returns the current instance unchanged. - object with the specified regular expression pattern and calling the instance method `Replace`. - - The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). If you specify for the `options` parameter, the search for matches begins at the end of the input string and moves left; otherwise, the search begins at the start of the input string and moves right. - - The `replacement` parameter specifies the string that is to replace each match in `input`. `replacement` can consist of any combination of literal text and [substitutions](/dotnet/standard/base-types/substitutions-in-regular-expressions). For example, the replacement pattern `a*${test}b` inserts the string "a*" followed by the substring that is matched by the `test` capturing group, if any, followed by the string "b". The * character is not recognized as a metacharacter within a replacement pattern. - + object with the specified regular expression pattern and calling the instance method `Replace`. + + The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). If you specify for the `options` parameter, the search for matches begins at the end of the input string and moves left; otherwise, the search begins at the start of the input string and moves right. + + The `replacement` parameter specifies the string that is to replace each match in `input`. `replacement` can consist of any combination of literal text and [substitutions](/dotnet/standard/base-types/substitutions-in-regular-expressions). For example, the replacement pattern `a*${test}b` inserts the string "a*" followed by the substring that is matched by the `test` capturing group, if any, followed by the string "b". The * character is not recognized as a metacharacter within a replacement pattern. + > [!NOTE] -> Substitutions are the only regular expression language elements that are recognized in a replacement pattern. All other regular expression language elements, including [character escapes](/dotnet/standard/base-types/character-escapes-in-regular-expressions), are allowed in regular expression patterns only and are not recognized in replacement patterns. - - The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. - - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. - - - -## Examples - The following example uses the method to replace the local machine and drive names in a UNC path with a local file path. The regular expression uses the property to include the name of the local computer, and the method to include the names of the logical drives. All regular expression string comparisons are case-insensitive. To run the example successfully, you should replace the literal string "MyMachine" with your local machine name. +> Substitutions are the only regular expression language elements that are recognized in a replacement pattern. All other regular expression language elements, including [character escapes](/dotnet/standard/base-types/character-escapes-in-regular-expressions), are allowed in regular expression patterns only and are not recognized in replacement patterns. + + The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. + + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + + + +## Examples + The following example uses the method to replace the local machine and drive names in a UNC path with a local file path. The regular expression uses the property to include the name of the local computer, and the method to include the names of the logical drives. All regular expression string comparisons are case-insensitive. To run the example successfully, you should replace the literal string "MyMachine" with your local machine name. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/replace4.cs" interactive="try-dotnet" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/replace4.vb" id="Snippet4"::: - - The regular expression pattern is defined by the following expression: - - `"\\\\" + Environment.MachineName + "(?:\.\w+)*\\([" + driveNames + "])\$"` - - The following table shows how the regular expression pattern is interpreted. - -|Pattern|Description| -|-------------|-----------------| -|`\\\\`|Match two consecutive backslash (`\`) characters. Because the backslash character is interpreted as the escape character, each backslash must be escaped with another backslash.| -|`+ Environment.MachineName +`|Match the string that is returned by the property.| -|`(?:\.\w+)*`|Match the period (`.`) character followed by one or more word characters. This match can occur zero or more times. The matched subexpression is not captured.| -|`\\`|Match a backslash (`\`) character.| -|`([" + driveNames + "])`|Match the character class that consists of the individual drive letters. This match is the first captured subexpression.| -|`\$`|Match the literal dollar sign (`$`) character.| - - The replacement pattern `$1` replaces the entire match with the first captured subexpression. That is, it replaces the UNC machine and drive name with the drive letter. - + + The regular expression pattern is defined by the following expression: + + `"\\\\" + Environment.MachineName + "(?:\.\w+)*\\([" + driveNames + "])\$"` + + The following table shows how the regular expression pattern is interpreted. + +|Pattern|Description| +|-------------|-----------------| +|`\\\\`|Match two consecutive backslash (`\`) characters. Because the backslash character is interpreted as the escape character, each backslash must be escaped with another backslash.| +|`+ Environment.MachineName +`|Match the string that is returned by the property.| +|`(?:\.\w+)*`|Match the period (`.`) character followed by one or more word characters. This match can occur zero or more times. The matched subexpression is not captured.| +|`\\`|Match a backslash (`\`) character.| +|`([" + driveNames + "])`|Match the character class that consists of the individual drive letters. This match is the first captured subexpression.| +|`\$`|Match the literal dollar sign (`$`) character.| + + The replacement pattern `$1` replaces the entire match with the first captured subexpression. That is, it replaces the UNC machine and drive name with the drive letter. + ]]> A regular expression parsing error occurred. @@ -5647,42 +5497,42 @@ For more details about `startat`, see the Remarks section of In a specified input string, replaces all strings that match a specified regular expression with a string returned by a delegate. Specified options modify the matching operation. A new string that is identical to the input string, except that a replacement string takes the place of each matched string. If is not matched in the current instance, the method returns the current instance unchanged. - method is useful for replacing a regular expression match in if any of the following conditions is true: - -- The replacement string cannot readily be specified by a regular expression replacement pattern. - -- The replacement string results from some processing done on the matched string. - -- The replacement string results from conditional processing. - - The method is equivalent to calling the method and passing each object in the returned collection to the `evaluator` delegate. - - The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). - - The `evaluator` parameter is the delegate for a custom method that you define and that examines each match. The custom method must have the following signature to match the delegate. - + method is useful for replacing a regular expression match in if any of the following conditions is true: + +- The replacement string cannot readily be specified by a regular expression replacement pattern. + +- The replacement string results from some processing done on the matched string. + +- The replacement string results from conditional processing. + + The method is equivalent to calling the method and passing each object in the returned collection to the `evaluator` delegate. + + The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). + + The `evaluator` parameter is the delegate for a custom method that you define and that examines each match. The custom method must have the following signature to match the delegate. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/syntax1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/syntax1.vb" id="Snippet1"::: - - Your custom method returns a string that replaces the matched input. - - If you specify for the `options` parameter, the search for matches begins at the end of the input string and moves left; otherwise, the search begins at the start of the input string and moves right. - - The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. - - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. - - - -## Examples - The following example uses a regular expression to extract the individual words from a string, and then uses a delegate to call a method named `WordScramble` that scrambles the individual letters in the word. To do this, the `WordScramble` method creates an array that contains the characters in the match. It also creates a parallel array that it populates with random floating-point numbers. The arrays are sorted by calling the method, and the sorted array is provided as an argument to a class constructor. This newly created string is then returned by the `WordScramble` method. The regular expression pattern `\w+` matches one or more word characters; the regular expression engine will continue to add characters to the match until it encounters a non-word character, such as a white-space character. The call to the method includes the option so that the comment in the regular expression pattern `\w+ # Matches all the characters in a word.` is ignored by the regular expression engine. + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/syntax1.vb" id="Snippet1"::: + + Your custom method returns a string that replaces the matched input. + + If you specify for the `options` parameter, the search for matches begins at the end of the input string and moves left; otherwise, the search begins at the start of the input string and moves right. + + The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. + + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + + + +## Examples + The following example uses a regular expression to extract the individual words from a string, and then uses a delegate to call a method named `WordScramble` that scrambles the individual letters in the word. To do this, the `WordScramble` method creates an array that contains the characters in the match. It also creates a parallel array that it populates with random floating-point numbers. The arrays are sorted by calling the method, and the sorted array is provided as an argument to a class constructor. This newly created string is then returned by the `WordScramble` method. The regular expression pattern `\w+` matches one or more word characters; the regular expression engine will continue to add characters to the match until it encounters a non-word character, such as a white-space character. The call to the method includes the option so that the comment in the regular expression pattern `\w+ # Matches all the characters in a word.` is ignored by the regular expression engine. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/replace6.cs" interactive="try-dotnet" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/replace6.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/replace6.vb" id="Snippet10"::: + ]]> A regular expression parsing error occurred. @@ -5748,32 +5598,32 @@ For more details about `startat`, see the Remarks section of In a specified input substring, replaces a specified maximum number of strings that match a regular expression pattern with a string returned by a delegate. A new string that is identical to the input string, except that a replacement string takes the place of each matched string. If the regular expression pattern is not matched in the current instance, the method returns the current instance unchanged. - method is useful for replacing a regular expression match if any of the following conditions is true: - -- The replacement string cannot readily be specified by a regular expression replacement pattern. -- The replacement string results from some processing done on the matched string. + method is useful for replacing a regular expression match if any of the following conditions is true: + +- The replacement string cannot readily be specified by a regular expression replacement pattern. +- The replacement string results from some processing done on the matched string. - The replacement string results from conditional processing. - + The method is equivalent to calling the method and passing the first `count` objects in the returned collection to the `evaluator` delegate. For more details about `startat`, see the Remarks section of . - - The regular expression is the pattern defined by the constructor for the current object. - - The `evaluator` parameter is the delegate for a custom method that you define and that examines each match. The custom method must have the following signature to match the delegate. - + + The regular expression is the pattern defined by the constructor for the current object. + + The `evaluator` parameter is the delegate for a custom method that you define and that examines each match. The custom method must have the following signature to match the delegate. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/syntax1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/syntax1.vb" id="Snippet1"::: - - Your custom method returns a string that replaces the matched input. - - The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown - - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/syntax1.vb" id="Snippet1"::: + + Your custom method returns a string that replaces the matched input. + + The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown + + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + ]]> @@ -5844,66 +5694,66 @@ For more details about `startat`, see the Remarks section of In a specified input string, replaces all strings that match a specified regular expression with a specified replacement string. Additional parameters specify options that modify the matching operation and a time-out interval if no match is found. A new string that is identical to the input string, except that the replacement string takes the place of each matched string. If is not matched in the current instance, the method returns the current instance unchanged. - object with the specified regular expression pattern and calling the instance method `Replace`. - - The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). If you specify for the `options` parameter, the search for matches begins at the end of the input string and moves left; otherwise, the search begins at the start of the input string and moves right. - - The `replacement` parameter specifies the string that is to replace each match in `input`. `replacement` can consist of any combination of literal text and [substitutions](/dotnet/standard/base-types/substitutions-in-regular-expressions). For example, the replacement pattern `a*${test}b` inserts the string "a*" followed by the substring that is matched by the `test` capturing group, if any, followed by the string "b". The * character is not recognized as a metacharacter within a replacement pattern. - + object with the specified regular expression pattern and calling the instance method `Replace`. + + The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). If you specify for the `options` parameter, the search for matches begins at the end of the input string and moves left; otherwise, the search begins at the start of the input string and moves right. + + The `replacement` parameter specifies the string that is to replace each match in `input`. `replacement` can consist of any combination of literal text and [substitutions](/dotnet/standard/base-types/substitutions-in-regular-expressions). For example, the replacement pattern `a*${test}b` inserts the string "a*" followed by the substring that is matched by the `test` capturing group, if any, followed by the string "b". The * character is not recognized as a metacharacter within a replacement pattern. + > [!NOTE] -> Substitutions are the only regular expression language elements that are recognized in a replacement pattern. All other regular expression language elements, including [character escapes](/dotnet/standard/base-types/character-escapes-in-regular-expressions), are allowed in regular expression patterns only and are not recognized in replacement patterns. - - The `matchTimeout` parameter specifies how long a pattern matching method should try to find a match before it times out. Setting a time-out interval prevents regular expressions that rely on excessive backtracking from appearing to stop responding when they process input that contains near matches. For more information, see [Best Practices for Regular Expressions](/dotnet/standard/base-types/best-practices) and [Backtracking](/dotnet/standard/base-types/backtracking-in-regular-expressions). If no match is found in that time interval, the method throws a exception. `matchTimeout` overrides any default time-out value defined for the application domain in which the method executes. - - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. - - - -## Examples - The following example uses the method to replace the local machine and drive names in a UNC path with a local file path. The regular expression uses the property to include the name of the local computer and the method to include the names of the logical drives. All regular expression string comparisons are case-insensitive, and any single replacement operation times out if a match cannot be found in 0.5 second. To run the example successfully, you should replace the literal string "MyMachine" with your local machine name. +> Substitutions are the only regular expression language elements that are recognized in a replacement pattern. All other regular expression language elements, including [character escapes](/dotnet/standard/base-types/character-escapes-in-regular-expressions), are allowed in regular expression patterns only and are not recognized in replacement patterns. + + The `matchTimeout` parameter specifies how long a pattern matching method should try to find a match before it times out. Setting a time-out interval prevents regular expressions that rely on excessive backtracking from appearing to stop responding when they process input that contains near matches. For more information, see [Best Practices for Regular Expressions](/dotnet/standard/base-types/best-practices) and [Backtracking](/dotnet/standard/base-types/backtracking-in-regular-expressions). If no match is found in that time interval, the method throws a exception. `matchTimeout` overrides any default time-out value defined for the application domain in which the method executes. + + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + + + +## Examples + The following example uses the method to replace the local machine and drive names in a UNC path with a local file path. The regular expression uses the property to include the name of the local computer and the method to include the names of the logical drives. All regular expression string comparisons are case-insensitive, and any single replacement operation times out if a match cannot be found in 0.5 second. To run the example successfully, you should replace the literal string "MyMachine" with your local machine name. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/replace12.cs" interactive="try-dotnet" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/replace12.vb" id="Snippet12"::: - - The regular expression pattern is defined by the following expression: - - `"\\\\" + Environment.MachineName + "(?:\.\w+)*\\([" + driveNames + "])\$"` - - The following table shows how the regular expression pattern is interpreted. - -|Pattern|Description| -|-------------|-----------------| -|`\\\\`|Match two consecutive backslash (`\`) characters. Because the backslash character is interpreted as the escape character, each backslash must be escaped with another backslash.| -|`+ Environment.MachineName +`|Match the string that is returned by the property.| -|`(?:\.\w+)*`|Match the period (`.`) character followed by one or more word characters. This match can occur zero or more times. The matched subexpression is not captured.| -|`\\`|Match a backslash (`\`) character.| -|`([" + driveNames + "])`|Match the character class that consists of the individual drive letters. This match is the first captured subexpression.| -|`\$`|Match the literal dollar sign (`$`) character.| - - The replacement pattern `$1` replaces the entire match with the first captured subexpression. That is, it replaces the UNC machine and drive name with the drive letter. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/replace12.vb" id="Snippet12"::: + + The regular expression pattern is defined by the following expression: + + `"\\\\" + Environment.MachineName + "(?:\.\w+)*\\([" + driveNames + "])\$"` + + The following table shows how the regular expression pattern is interpreted. + +|Pattern|Description| +|-------------|-----------------| +|`\\\\`|Match two consecutive backslash (`\`) characters. Because the backslash character is interpreted as the escape character, each backslash must be escaped with another backslash.| +|`+ Environment.MachineName +`|Match the string that is returned by the property.| +|`(?:\.\w+)*`|Match the period (`.`) character followed by one or more word characters. This match can occur zero or more times. The matched subexpression is not captured.| +|`\\`|Match a backslash (`\`) character.| +|`([" + driveNames + "])`|Match the character class that consists of the individual drive letters. This match is the first captured subexpression.| +|`\$`|Match the literal dollar sign (`$`) character.| + + The replacement pattern `$1` replaces the entire match with the first captured subexpression. That is, it replaces the UNC machine and drive name with the drive letter. + ]]> A regular expression parsing error occurred. , , or is . - is not a valid bitwise combination of values. - - -or- - + is not a valid bitwise combination of values. + + -or- + is negative, zero, or greater than approximately 24 days. A time-out occurred. For more information about time-outs, see the Remarks section. - We recommend that you set the parameter to an appropriate value, such as two seconds. If you disable time-outs by specifying , the regular expression engine offers slightly better performance. However, you should disable time-outs only under the following conditions: - -- When the input processed by a regular expression is derived from a known and trusted source or consists of static text. This excludes text that has been dynamically input by users. - -- When the regular expression pattern has been thoroughly tested to ensure that it efficiently handles matches, non-matches, and near matches. - + We recommend that you set the parameter to an appropriate value, such as two seconds. If you disable time-outs by specifying , the regular expression engine offers slightly better performance. However, you should disable time-outs only under the following conditions: + +- When the input processed by a regular expression is derived from a known and trusted source or consists of static text. This excludes text that has been dynamically input by users. + +- When the regular expression pattern has been thoroughly tested to ensure that it efficiently handles matches, non-matches, and near matches. + - When the regular expression pattern contains no language elements that are known to cause excessive backtracking when processing a near match. @@ -5971,61 +5821,61 @@ For more details about `startat`, see the Remarks section of In a specified input string, replaces all substrings that match a specified regular expression with a string returned by a delegate. Additional parameters specify options that modify the matching operation and a time-out interval if no match is found. A new string that is identical to the input string, except that the replacement string takes the place of each matched string. If is not matched in the current instance, the method returns the current instance unchanged. - method is useful for replacing a regular expression match if any of the following conditions is true: - -- If the replacement string cannot readily be specified by a regular expression replacement pattern. - -- If the replacement string results from some processing performed on the matched string. - -- If the replacement string results from conditional processing. - - The method is equivalent to calling the method and passing each object in the returned collection to the `evaluator` delegate. - - The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). - - The `evaluator` parameter is the delegate for a custom method that you define and that examines each match. The custom method must have the following signature to match the delegate. - + method is useful for replacing a regular expression match if any of the following conditions is true: + +- If the replacement string cannot readily be specified by a regular expression replacement pattern. + +- If the replacement string results from some processing performed on the matched string. + +- If the replacement string results from conditional processing. + + The method is equivalent to calling the method and passing each object in the returned collection to the `evaluator` delegate. + + The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). + + The `evaluator` parameter is the delegate for a custom method that you define and that examines each match. The custom method must have the following signature to match the delegate. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/syntax1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/syntax1.vb" id="Snippet1"::: - - Your custom method returns a string that replaces the matched input. - - If you specify for the `options` parameter, the search for matches begins at the end of the input string and moves left; otherwise, the search begins at the start of the input string and moves right. - - The `matchTimeout` parameter specifies how long a pattern matching method should try to find a match before it times out. Setting a time-out interval prevents regular expressions that rely on excessive backtracking from appearing to "stop responding when they process input that contains near matches. For more information, see [Best Practices for Regular Expressions](/dotnet/standard/base-types/best-practices) and [Backtracking](/dotnet/standard/base-types/backtracking-in-regular-expressions). If no match is found in that time interval, the method throws a exception. `matchTimeout` overrides any default time-out value defined for the application domain in which the method executes. - - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. - - - -## Examples - The following example uses a regular expression to extract the individual words from a string, and then uses a delegate to call a method named `WordScramble` that scrambles the individual letters in the word. To do this, the `WordScramble` method creates an array that contains the characters in the match. It also creates a parallel array that it populates with random floating-point numbers. The arrays are sorted by calling the method, and the sorted array is provided as an argument to a class constructor. This newly created string is then returned by the `WordScramble` method. The regular expression pattern `\w+` matches one or more word characters; the regular expression engine will continue to add characters to the match until it encounters a non-word character, such as a white-space character. The call to the method includes the option so that the comment in the regular expression pattern `\w+ # Matches all the characters in a word.` is ignored by the regular expression engine. + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/syntax1.vb" id="Snippet1"::: + + Your custom method returns a string that replaces the matched input. + + If you specify for the `options` parameter, the search for matches begins at the end of the input string and moves left; otherwise, the search begins at the start of the input string and moves right. + + The `matchTimeout` parameter specifies how long a pattern matching method should try to find a match before it times out. Setting a time-out interval prevents regular expressions that rely on excessive backtracking from appearing to "stop responding when they process input that contains near matches. For more information, see [Best Practices for Regular Expressions](/dotnet/standard/base-types/best-practices) and [Backtracking](/dotnet/standard/base-types/backtracking-in-regular-expressions). If no match is found in that time interval, the method throws a exception. `matchTimeout` overrides any default time-out value defined for the application domain in which the method executes. + + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + + + +## Examples + The following example uses a regular expression to extract the individual words from a string, and then uses a delegate to call a method named `WordScramble` that scrambles the individual letters in the word. To do this, the `WordScramble` method creates an array that contains the characters in the match. It also creates a parallel array that it populates with random floating-point numbers. The arrays are sorted by calling the method, and the sorted array is provided as an argument to a class constructor. This newly created string is then returned by the `WordScramble` method. The regular expression pattern `\w+` matches one or more word characters; the regular expression engine will continue to add characters to the match until it encounters a non-word character, such as a white-space character. The call to the method includes the option so that the comment in the regular expression pattern `\w+ # Matches all the characters in a word.` is ignored by the regular expression engine. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Replace/replace13.cs" interactive="try-dotnet" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/replace13.vb" id="Snippet13"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/replace13.vb" id="Snippet13"::: + ]]> A regular expression parsing error occurred. , , or is . - is not a valid bitwise combination of values. - - -or- - + is not a valid bitwise combination of values. + + -or- + is negative, zero, or greater than approximately 24 days. A time-out occurred. For more information about time-outs, see the Remarks section. - We recommend that you set the parameter to an appropriate value, such as two seconds. If you disable time-outs by specifying , the regular expression engine offers slightly better performance. However, you should disable time-outs only under the following conditions: - -- When the input processed by a regular expression is derived from a known and trusted source or consists of static text. This excludes text that has been dynamically input by users. - -- When the regular expression pattern has been thoroughly tested to ensure that it efficiently handles matches, non-matches, and near matches. - + We recommend that you set the parameter to an appropriate value, such as two seconds. If you disable time-outs by specifying , the regular expression engine offers slightly better performance. However, you should disable time-outs only under the following conditions: + +- When the input processed by a regular expression is derived from a known and trusted source or consists of static text. This excludes text that has been dynamically input by users. + +- When the regular expression pattern has been thoroughly tested to ensure that it efficiently handles matches, non-matches, and near matches. + - When the regular expression pattern contains no language elements that are known to cause excessive backtracking when processing a near match. @@ -6083,11 +5933,11 @@ For more details about `startat`, see the Remarks section of if the regular expression searches from right to left; otherwise, . - is `true` if the instance was created with the option. - + is `true` if the instance was created with the option. + ]]> @@ -6191,40 +6041,40 @@ For more details about `startat`, see the Remarks section of Splits an input string into an array of substrings at the positions defined by a regular expression pattern specified in the constructor. An array of strings. - methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The string is split as many times as possible. If no delimiter is found, the return value contains one element whose value is the original input string. - - If multiple matches are adjacent to one another, an empty string is inserted into the array. For example, splitting a string on a single hyphen causes the returned array to include an empty string in the position where two adjacent hyphens are found, as the following code shows. - + methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The string is split as many times as possible. If no delimiter is found, the return value contains one element whose value is the original input string. + + If multiple matches are adjacent to one another, an empty string is inserted into the array. For example, splitting a string on a single hyphen causes the returned array to include an empty string in the position where two adjacent hyphens are found, as the following code shows. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split1.vb" id="Snippet1"::: - - If a match is found at the beginning or the end of the input string, an empty string is included at the beginning or the end of the returned array. The following example uses the regular expression pattern `\d+` to split an input string on numeric characters. Because the string begins and ends with matching numeric characters, the value of the first and last element of the returned array is . + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split1.vb" id="Snippet1"::: + + If a match is found at the beginning or the end of the input string, an empty string is included at the beginning or the end of the returned array. The following example uses the regular expression pattern `\d+` to split an input string on numeric characters. Because the string begins and ends with matching numeric characters, the value of the first and last element of the returned array is . :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split21.cs" interactive="try-dotnet" id="Snippet21"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split21.vb" id="Snippet21"::: - - If capturing parentheses are used in a expression, any captured text is included in the resulting string array. For example, if you split the string "plum-pear" on a hyphen placed within capturing parentheses, the returned array includes a string element that contains the hyphen. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split21.vb" id="Snippet21"::: + + If capturing parentheses are used in a expression, any captured text is included in the resulting string array. For example, if you split the string "plum-pear" on a hyphen placed within capturing parentheses, the returned array includes a string element that contains the hyphen. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split2.cs" interactive="try-dotnet" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split2.vb" id="Snippet2"::: - - However, when the regular expression pattern includes multiple sets of capturing parentheses, the behavior of this method depends on the version of the .NET Framework. In the .NET Framework 1.0 and 1.1, if a match is not found within the first set of capturing parentheses, captured text from additional capturing parentheses is not included in the returned array. Starting with the .NET Framework 2.0, all captured text is also added to the returned array. For example, the following code uses two sets of capturing parentheses to extract the elements of a date, including the date delimiters, from a date string. The first set of capturing parentheses captures the hyphen, and the second set captures the forward slash. If the example code is compiled and run under the .NET Framework 1.0 or 1.1, it excludes the slash characters; if it is compiled and run under the .NET Framework 2.0 or later versions, it includes them. - + + However, when the regular expression pattern includes multiple sets of capturing parentheses, the behavior of this method depends on the version of the .NET Framework. In the .NET Framework 1.0 and 1.1, if a match is not found within the first set of capturing parentheses, captured text from additional capturing parentheses is not included in the returned array. Starting with the .NET Framework 2.0, all captured text is also added to the returned array. For example, the following code uses two sets of capturing parentheses to extract the elements of a date, including the date delimiters, from a date string. The first set of capturing parentheses captures the hyphen, and the second set captures the forward slash. If the example code is compiled and run under the .NET Framework 1.0 or 1.1, it excludes the slash characters; if it is compiled and run under the .NET Framework 2.0 or later versions, it includes them. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split3.cs" interactive="try-dotnet" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split3.vb" id="Snippet3"::: - - If the regular expression can match the empty string, will split the string into an array of single-character strings because the empty string delimiter can be found at every location. For example: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split3.vb" id="Snippet3"::: + + If the regular expression can match the empty string, will split the string into an array of single-character strings because the empty string delimiter can be found at every location. For example: + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split11.cs" interactive="try-dotnet" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split11.vb" id="Snippet11"::: - - Note that the returned array also includes an empty string at the beginning and end of the array. - - The exception is thrown if the execution time of the split operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split11.vb" id="Snippet11"::: + + Note that the returned array also includes an empty string at the beginning and end of the array. + + The exception is thrown if the execution time of the split operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown + ]]> @@ -6280,32 +6130,32 @@ For more details about `startat`, see the Remarks section of Splits an input string a specified maximum number of times into an array of substrings, at the positions defined by a regular expression specified in the constructor. An array of strings. - methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The `count` parameter specifies the maximum number of substrings into which the `input` string can be split; the last string contains the unsplit remainder of the string. A `count` value of zero provides the default behavior of splitting as many times as possible. - - If multiple matches are adjacent to one another or if a match is found at the beginning or end of `input`, and the number of matches found is at least two less than `count`, an empty string is inserted into the array. That is, empty strings that result from adjacent matches or from matches at the beginning or end of the input string are counted in determining whether the number of matched substrings equals `count`. In the following example, the regular expression `/d+` is used to split an input string that includes one or more decimal digits into a maximum of three substrings. Because the beginning of the input string matches the regular expression pattern, the first array element contains , the second contains the first set of alphabetic characters in the input string, and the third contains the remainder of the string that follows the third match. - + methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The `count` parameter specifies the maximum number of substrings into which the `input` string can be split; the last string contains the unsplit remainder of the string. A `count` value of zero provides the default behavior of splitting as many times as possible. + + If multiple matches are adjacent to one another or if a match is found at the beginning or end of `input`, and the number of matches found is at least two less than `count`, an empty string is inserted into the array. That is, empty strings that result from adjacent matches or from matches at the beginning or end of the input string are counted in determining whether the number of matched substrings equals `count`. In the following example, the regular expression `/d+` is used to split an input string that includes one or more decimal digits into a maximum of three substrings. Because the beginning of the input string matches the regular expression pattern, the first array element contains , the second contains the first set of alphabetic characters in the input string, and the third contains the remainder of the string that follows the third match. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split25.cs" interactive="try-dotnet" id="Snippet25"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split25.vb" id="Snippet25"::: - - If capturing parentheses are used in a regular expression, any captured text is included in the array of split strings. However, any array elements that contain captured text are not counted in determining whether the number of matches has reached `count`. For example, splitting the string "apple-apricot-plum-pear-banana" into a maximum of four substrings results in a seven-element array, as the following code shows. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split25.vb" id="Snippet25"::: + + If capturing parentheses are used in a regular expression, any captured text is included in the array of split strings. However, any array elements that contain captured text are not counted in determining whether the number of matches has reached `count`. For example, splitting the string "apple-apricot-plum-pear-banana" into a maximum of four substrings results in a seven-element array, as the following code shows. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split4.cs" interactive="try-dotnet" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split4.vb" id="Snippet4"::: - - However, when the regular expression pattern includes multiple sets of capturing parentheses, the behavior of this method depends on the version of the .NET Framework. In the .NET Framework 1.0 and 1.1, only captured text from the first set of capturing parentheses is included in the returned array. Starting with the .NET Framework 2.0, all captured text is added to the returned array. However, elements in the returned array that contain captured text are not counted in determining whether the number of matched substrings equals `count`. For example, in the following code, a regular expression uses two sets of capturing parentheses to extract the elements of a date from a date string. The first set of capturing parentheses captures the hyphen, and the second set captures the forward slash. The call to the method then specifies a maximum of two elements in the returned array. If the example code is compiled and run under the .NET Framework 1.0 or 1.1, the method returns a two-element string array. If it is compiled and run under the .NET Framework 2.0 or later versions, the method returns a three-element string array. - + + However, when the regular expression pattern includes multiple sets of capturing parentheses, the behavior of this method depends on the version of the .NET Framework. In the .NET Framework 1.0 and 1.1, only captured text from the first set of capturing parentheses is included in the returned array. Starting with the .NET Framework 2.0, all captured text is added to the returned array. However, elements in the returned array that contain captured text are not counted in determining whether the number of matched substrings equals `count`. For example, in the following code, a regular expression uses two sets of capturing parentheses to extract the elements of a date from a date string. The first set of capturing parentheses captures the hyphen, and the second set captures the forward slash. The call to the method then specifies a maximum of two elements in the returned array. If the example code is compiled and run under the .NET Framework 1.0 or 1.1, the method returns a two-element string array. If it is compiled and run under the .NET Framework 2.0 or later versions, the method returns a three-element string array. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split5.cs" interactive="try-dotnet" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split5.vb" id="Snippet5"::: - - If the regular expression can match the empty string, will split the string into an array of single-character strings because the empty string delimiter can be found at every location. The following example splits the string "characters" into as many elements as there are in the input string. Because the null string matches the beginning of the input string, a null string is inserted at the beginning of the returned array. This causes the tenth element to consist of the two characters at the end of the input string. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split12.vb" id="Snippet12"::: - - The exception is thrown if the execution time of the split operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown - + + If the regular expression can match the empty string, will split the string into an array of single-character strings because the empty string delimiter can be found at every location. The following example splits the string "characters" into as many elements as there are in the input string. Because the null string matches the beginning of the input string, a null string is inserted at the beginning of the returned array. This causes the tenth element to consist of the two characters at the end of the input string. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split12.vb" id="Snippet12"::: + + The exception is thrown if the execution time of the split operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown + ]]> @@ -6368,45 +6218,45 @@ For more details about `startat`, see the Remarks section of Splits an input string into an array of substrings at the positions defined by a regular expression pattern. An array of strings. - methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The `input` string is split as many times as possible. If `pattern` is not found in the `input` string, the return value contains one element whose value is the original `input` string. - - The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). - + methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The `input` string is split as many times as possible. If `pattern` is not found in the `input` string, the return value contains one element whose value is the original `input` string. + + The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). + > [!IMPORTANT] -> Compiled regular expressions used in calls to static methods are automatically cached. To manage the lifetime of compiled regular expressions yourself, use the instance methods. - - If multiple matches are adjacent to one another, an empty string is inserted into the array. For example, splitting a string on a single hyphen causes the returned array to include an empty string in the position where two adjacent hyphens are found, as the following code shows. - +> Compiled regular expressions used in calls to static methods are automatically cached. To manage the lifetime of compiled regular expressions yourself, use the instance methods. + + If multiple matches are adjacent to one another, an empty string is inserted into the array. For example, splitting a string on a single hyphen causes the returned array to include an empty string in the position where two adjacent hyphens are found, as the following code shows. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split8.cs" interactive="try-dotnet" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split8.vb" id="Snippet8"::: - - If a match is found at the beginning or the end of the input string, an empty string is included at the beginning or the end of the returned array. The following example uses the regular expression pattern `\d+` to split an input string on numeric characters. Because the string begins and ends with matching numeric characters, the value of the first and last element of the returned array is . - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split8.vb" id="Snippet8"::: + + If a match is found at the beginning or the end of the input string, an empty string is included at the beginning or the end of the returned array. The following example uses the regular expression pattern `\d+` to split an input string on numeric characters. Because the string begins and ends with matching numeric characters, the value of the first and last element of the returned array is . + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split22.cs" interactive="try-dotnet" id="Snippet22"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split22.vb" id="Snippet22"::: - - If capturing parentheses are used in a expression, any captured text is included in the resulting string array. For example, if you split the string "plum-pear" on a hyphen placed within capturing parentheses, the returned array includes a string element that contains the hyphen. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split22.vb" id="Snippet22"::: + + If capturing parentheses are used in a expression, any captured text is included in the resulting string array. For example, if you split the string "plum-pear" on a hyphen placed within capturing parentheses, the returned array includes a string element that contains the hyphen. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split9.cs" interactive="try-dotnet" id="Snippet9"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split9.vb" id="Snippet9"::: - - However, when the regular expression pattern includes multiple sets of capturing parentheses, the behavior of this method depends on the version of the .NET Framework. In the .NET Framework 1.0 and 1.1, if a match is not found within the first set of capturing parentheses, captured text from additional capturing parentheses is not included in the returned array. Starting with the .NET Framework 2.0, all captured text is also added to the returned array. For example, the following code uses two sets of capturing parentheses to extract the elements of a date, including the date delimiters, from a date string. The first set of capturing parentheses captures the hyphen, and the second set captures the forward slash. If the example code is compiled and run under the .NET Framework 1.0 or 1.1, it excludes the slash characters; if it is compiled and run under the .NET Framework 2.0 or later versions, it includes them. - + + However, when the regular expression pattern includes multiple sets of capturing parentheses, the behavior of this method depends on the version of the .NET Framework. In the .NET Framework 1.0 and 1.1, if a match is not found within the first set of capturing parentheses, captured text from additional capturing parentheses is not included in the returned array. Starting with the .NET Framework 2.0, all captured text is also added to the returned array. For example, the following code uses two sets of capturing parentheses to extract the elements of a date, including the date delimiters, from a date string. The first set of capturing parentheses captures the hyphen, and the second set captures the forward slash. If the example code is compiled and run under the .NET Framework 1.0 or 1.1, it excludes the slash characters; if it is compiled and run under the .NET Framework 2.0 or later versions, it includes them. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split10.cs" interactive="try-dotnet" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split10.vb" id="Snippet10"::: - - If the regular expression can match the empty string, will split the string into an array of single-character strings because the empty string delimiter can be found at every location. For example: - + + If the regular expression can match the empty string, will split the string into an array of single-character strings because the empty string delimiter can be found at every location. For example: + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split13.cs" interactive="try-dotnet" id="Snippet13"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split13.vb" id="Snippet13"::: - - Note that the returned array also includes an empty string at the beginning and end of the array. - - The exception is thrown if the execution time of the split operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. - + + Note that the returned array also includes an empty string at the beginning and end of the array. + + The exception is thrown if the execution time of the split operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. + ]]> A regular expression parsing error occurred. @@ -6468,37 +6318,37 @@ For more details about `startat`, see the Remarks section of Splits an input string a specified maximum number of times into an array of substrings, at the positions defined by a regular expression specified in the constructor. The search for the regular expression pattern starts at a specified character position in the input string. An array of strings. - methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The `count` parameter specifies the maximum number of substrings into which the `input` string is split; the last string contains the unsplit remainder of the string. A `count` value of zero provides the default behavior of splitting as many times as possible. The `startat` parameter defines the point at which the search for the first delimiter begins (this can be used for skipping leading white space). + methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The `count` parameter specifies the maximum number of substrings into which the `input` string is split; the last string contains the unsplit remainder of the string. A `count` value of zero provides the default behavior of splitting as many times as possible. The `startat` parameter defines the point at which the search for the first delimiter begins (this can be used for skipping leading white space). For more details about `startat`, see the Remarks section of . - - If no matches are found from the `count`+1 position in the string, the method returns a one-element array that contains the `input` string. If one or more matches are found, the first element of the returned array contains the first portion of the string from the first character up to one character before the match. - - If multiple matches are adjacent to one another and the number of matches found is at least two less than `count`, an empty string is inserted into the array. Similarly, if a match is found at `startat`, which is the first character in the string, the first element of the returned array is an empty string. That is, empty strings that result from adjacent matches are counted in determining whether the number of matched substrings equals `count`. In the following example, the regular expression `\d+` is used to find the starting position of the first substring of numeric characters in a string, and then to split the string a maximum of three times starting at that position. Because the regular expression pattern matches the beginning of the input string, the returned string array consists of an empty string, a five-character alphabetic string, and the remainder of the string, - + + If no matches are found from the `count`+1 position in the string, the method returns a one-element array that contains the `input` string. If one or more matches are found, the first element of the returned array contains the first portion of the string from the first character up to one character before the match. + + If multiple matches are adjacent to one another and the number of matches found is at least two less than `count`, an empty string is inserted into the array. Similarly, if a match is found at `startat`, which is the first character in the string, the first element of the returned array is an empty string. That is, empty strings that result from adjacent matches are counted in determining whether the number of matched substrings equals `count`. In the following example, the regular expression `\d+` is used to find the starting position of the first substring of numeric characters in a string, and then to split the string a maximum of three times starting at that position. Because the regular expression pattern matches the beginning of the input string, the returned string array consists of an empty string, a five-character alphabetic string, and the remainder of the string, + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split26.cs" interactive="try-dotnet" id="Snippet26"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split26.vb" id="Snippet26"::: - - If capturing parentheses are used in a regular expression, any captured text is included in the array of split strings. However, any array elements that contain captured text are not counted in determining whether the number of matches has reached `count`. For example, splitting the string '"apple-apricot-plum-pear-pomegranate-pineapple-peach" into a maximum of four substrings beginning at character 15 in the string results in a seven-element array, as the following code shows. + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split26.vb" id="Snippet26"::: - :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split6.cs" interactive="try-dotnet" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split6.vb" id="Snippet6"::: - - However, when the regular expression pattern includes multiple sets of capturing parentheses, the behavior of this method depends on the version of the .NET Framework. In .NET Framework 1.0 and 1.1, if a match is not found within the first set of capturing parentheses, captured text from additional capturing parentheses is not included in the returned array. Starting with the .NET Framework 2.0, all captured text is also added to the returned array. For example, the following code uses two sets of capturing parentheses to extract the individual words in a string. The first set of capturing parentheses captures the hyphen, and the second set captures the vertical bar. If the example code is compiled and run under the .NET Framework 1.0 or 1.1, it excludes the vertical bar characters; if it is compiled and run under the .NET Framework 2.0 or later versions, it includes them. + If capturing parentheses are used in a regular expression, any captured text is included in the array of split strings. However, any array elements that contain captured text are not counted in determining whether the number of matches has reached `count`. For example, splitting the string '"apple-apricot-plum-pear-pomegranate-pineapple-peach" into a maximum of four substrings beginning at character 15 in the string results in a seven-element array, as the following code shows. + + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split6.cs" interactive="try-dotnet" id="Snippet6"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split6.vb" id="Snippet6"::: + + However, when the regular expression pattern includes multiple sets of capturing parentheses, the behavior of this method depends on the version of the .NET Framework. In .NET Framework 1.0 and 1.1, if a match is not found within the first set of capturing parentheses, captured text from additional capturing parentheses is not included in the returned array. Starting with the .NET Framework 2.0, all captured text is also added to the returned array. For example, the following code uses two sets of capturing parentheses to extract the individual words in a string. The first set of capturing parentheses captures the hyphen, and the second set captures the vertical bar. If the example code is compiled and run under the .NET Framework 1.0 or 1.1, it excludes the vertical bar characters; if it is compiled and run under the .NET Framework 2.0 or later versions, it includes them. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split7.cs" interactive="try-dotnet" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split7.vb" id="Snippet7"::: - - If the regular expression can match the empty string, will split the string into an array of single-character strings because the empty string delimiter can be found at every location. The following example splits the string "characters" into as many elements as the input string contains, starting with the character "a". Because the null string matches the end of the input string, a null string is inserted at the end of the returned array. + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split7.vb" id="Snippet7"::: + + If the regular expression can match the empty string, will split the string into an array of single-character strings because the empty string delimiter can be found at every location. The following example splits the string "characters" into as many elements as the input string contains, starting with the character "a". Because the null string matches the end of the input string, a null string is inserted at the end of the returned array. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split14.cs" interactive="try-dotnet" id="Snippet14"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split14.vb" id="Snippet14"::: - - The exception is thrown if the execution time of the split operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split14.vb" id="Snippet14"::: + + The exception is thrown if the execution time of the split operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown + ]]> @@ -6565,37 +6415,37 @@ For more details about `startat`, see the Remarks section of Splits an input string into an array of substrings at the positions defined by a specified regular expression pattern. Specified options modify the matching operation. An array of strings. - methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The string is split as many times as possible. If no delimiter is found, the return value contains one element whose value is the original `input` string. - - The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). - + methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The string is split as many times as possible. If no delimiter is found, the return value contains one element whose value is the original `input` string. + + The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). + > [!IMPORTANT] -> Compiled regular expressions used in calls to static methods are automatically cached. To manage the lifetime of compiled regular expressions yourself, use the instance methods. - - If multiple matches are adjacent to one another, an empty string is inserted into the array. For example, splitting a string on a single hyphen causes the returned array to include an empty string in the position where two adjacent hyphens are found. - - If a match is found at the beginning or the end of the input string, an empty string is included at the beginning or the end of the returned array. The following example uses the regular expression pattern `[a-z]+` to split an input string on any uppercase or lowercase alphabetic character. Because the string begins and ends with matching alphabetic characters, the value of the first and last element of the returned array is . - +> Compiled regular expressions used in calls to static methods are automatically cached. To manage the lifetime of compiled regular expressions yourself, use the instance methods. + + If multiple matches are adjacent to one another, an empty string is inserted into the array. For example, splitting a string on a single hyphen causes the returned array to include an empty string in the position where two adjacent hyphens are found. + + If a match is found at the beginning or the end of the input string, an empty string is included at the beginning or the end of the returned array. The following example uses the regular expression pattern `[a-z]+` to split an input string on any uppercase or lowercase alphabetic character. Because the string begins and ends with matching alphabetic characters, the value of the first and last element of the returned array is . + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split24.cs" interactive="try-dotnet" id="Snippet24"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split24.vb" id="Snippet24"::: - - If capturing parentheses are used in a expression, any captured text is included in the resulting string array. For example, if you split the string "plum-pear" on a hyphen placed within capturing parentheses, the returned array includes a string element that contains the hyphen. + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split24.vb" id="Snippet24"::: + + If capturing parentheses are used in a expression, any captured text is included in the resulting string array. For example, if you split the string "plum-pear" on a hyphen placed within capturing parentheses, the returned array includes a string element that contains the hyphen. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split9.cs" interactive="try-dotnet" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split9.vb" id="Snippet9"::: - - However, when the regular expression pattern includes multiple sets of capturing parentheses, the behavior of this method depends on the version of the .NET Framework. In the .NET Framework 1.0 and 1.1, if a match is not found within the first set of capturing parentheses, captured text from additional capturing parentheses is not included in the returned array. Starting with the .NET Framework 2.0, all captured text is also added to the returned array. For example, the following code uses two sets of capturing parentheses to extract the elements of a date, including the date delimiters, from a date string. The first set of capturing parentheses captures the hyphen, and the second set captures the forward slash. If the example code is compiled and run under the .NET Framework 1.0 or 1.1, it excludes the slash characters; if it is compiled and run under the .NET Framework 2.0 or later versions, it includes them. + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split9.vb" id="Snippet9"::: + + However, when the regular expression pattern includes multiple sets of capturing parentheses, the behavior of this method depends on the version of the .NET Framework. In the .NET Framework 1.0 and 1.1, if a match is not found within the first set of capturing parentheses, captured text from additional capturing parentheses is not included in the returned array. Starting with the .NET Framework 2.0, all captured text is also added to the returned array. For example, the following code uses two sets of capturing parentheses to extract the elements of a date, including the date delimiters, from a date string. The first set of capturing parentheses captures the hyphen, and the second set captures the forward slash. If the example code is compiled and run under the .NET Framework 1.0 or 1.1, it excludes the slash characters; if it is compiled and run under the .NET Framework 2.0 or later versions, it includes them. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split10.cs" interactive="try-dotnet" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split10.vb" id="Snippet10"::: - - If the regular expression can match the empty string, will split the string into an array of single-character strings because the empty string delimiter can be found at every location. - - The exception is thrown if the execution time of the split operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split10.vb" id="Snippet10"::: + + If the regular expression can match the empty string, will split the string into an array of single-character strings because the empty string delimiter can be found at every location. + + The exception is thrown if the execution time of the split operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. + ]]> A regular expression parsing error occurred. @@ -6666,56 +6516,56 @@ For more details about `startat`, see the Remarks section of Splits an input string into an array of substrings at the positions defined by a specified regular expression pattern. Additional parameters specify options that modify the matching operation and a time-out interval if no match is found. A string array. - methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The string is split as many times as possible. If no delimiter is found, the return value contains one element whose value is the original `input` string. - - The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). - + methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The string is split as many times as possible. If no delimiter is found, the return value contains one element whose value is the original `input` string. + + The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions) and [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). + > [!IMPORTANT] -> Compiled regular expressions used in calls to static methods are automatically cached. To manage the lifetime of compiled regular expressions yourself, use the instance methods. - - If multiple matches are adjacent to one another, an empty string is inserted into the array. For example, splitting a string on a single hyphen causes the returned array to include an empty string in the position where two adjacent hyphens are found. - - If a match is found at the beginning or the end of the input string, an empty string is included at the beginning or the end of the returned array. The following example uses the regular expression pattern `[a-z]+` to split an input string on any uppercase or lowercase alphabetic character. Because the string begins and ends with matching alphabetic characters, the value of the first and last element of the returned array is . +> Compiled regular expressions used in calls to static methods are automatically cached. To manage the lifetime of compiled regular expressions yourself, use the instance methods. + + If multiple matches are adjacent to one another, an empty string is inserted into the array. For example, splitting a string on a single hyphen causes the returned array to include an empty string in the position where two adjacent hyphens are found. + + If a match is found at the beginning or the end of the input string, an empty string is included at the beginning or the end of the returned array. The following example uses the regular expression pattern `[a-z]+` to split an input string on any uppercase or lowercase alphabetic character. Because the string begins and ends with matching alphabetic characters, the value of the first and last element of the returned array is . :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split23.cs" interactive="try-dotnet" id="Snippet23"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split23.vb" id="Snippet23"::: - - If capturing parentheses are used in a expression, any captured text is included in the resulting string array. For example, if you split the string "plum-pear" on a hyphen placed within capturing parentheses, the returned array includes a string element that contains the hyphen. - + + If capturing parentheses are used in a expression, any captured text is included in the resulting string array. For example, if you split the string "plum-pear" on a hyphen placed within capturing parentheses, the returned array includes a string element that contains the hyphen. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split9.cs" interactive="try-dotnet" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split9.vb" id="Snippet9"::: - - However, when the regular expression pattern includes multiple sets of capturing parentheses, the behavior of this method depends on the version of the .NET Framework. In the .NET Framework 1.0 and 1.1, if a match is not found within the first set of capturing parentheses, captured text from additional capturing parentheses is not included in the returned array. Starting with the .NET Framework 2.0, all captured text is also added to the returned array. For example, the following code uses two sets of capturing parentheses to extract the elements of a date, including the date delimiters, from a date string. The first set of capturing parentheses captures the hyphen, and the second set captures the forward slash. If the example code is compiled and run under the .NET Framework 1.0 or 1.1, it excludes the slash characters; if it is compiled and run under the .NET Framework 2.0 or later versions, it includes them. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split9.vb" id="Snippet9"::: + + However, when the regular expression pattern includes multiple sets of capturing parentheses, the behavior of this method depends on the version of the .NET Framework. In the .NET Framework 1.0 and 1.1, if a match is not found within the first set of capturing parentheses, captured text from additional capturing parentheses is not included in the returned array. Starting with the .NET Framework 2.0, all captured text is also added to the returned array. For example, the following code uses two sets of capturing parentheses to extract the elements of a date, including the date delimiters, from a date string. The first set of capturing parentheses captures the hyphen, and the second set captures the forward slash. If the example code is compiled and run under the .NET Framework 1.0 or 1.1, it excludes the slash characters; if it is compiled and run under the .NET Framework 2.0 or later versions, it includes them. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Split/split10.cs" interactive="try-dotnet" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split10.vb" id="Snippet10"::: - - If the regular expression can match the empty string, will split the string into an array of single-character strings because the empty string delimiter can be found at every location. - - The `matchTimeout` parameter specifies how long a pattern matching method should try to find a match before it times out. Setting a time-out interval prevents regular expressions that rely on excessive backtracking from appearing to stop responding when they process input that contains near matches. For more information, see [Best Practices for Regular Expressions](/dotnet/standard/base-types/best-practices) and [Backtracking](/dotnet/standard/base-types/backtracking-in-regular-expressions). If no match is found in that time interval, the method throws a exception. `matchTimeout` overrides any default time-out value defined for the application domain in which the method executes. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split10.vb" id="Snippet10"::: + + If the regular expression can match the empty string, will split the string into an array of single-character strings because the empty string delimiter can be found at every location. + + The `matchTimeout` parameter specifies how long a pattern matching method should try to find a match before it times out. Setting a time-out interval prevents regular expressions that rely on excessive backtracking from appearing to stop responding when they process input that contains near matches. For more information, see [Best Practices for Regular Expressions](/dotnet/standard/base-types/best-practices) and [Backtracking](/dotnet/standard/base-types/backtracking-in-regular-expressions). If no match is found in that time interval, the method throws a exception. `matchTimeout` overrides any default time-out value defined for the application domain in which the method executes. + ]]> A regular expression parsing error occurred. or is . - is not a valid bitwise combination of values. - - -or- - + is not a valid bitwise combination of values. + + -or- + is negative, zero, or greater than approximately 24 days. A time-out occurred. For more information about time-outs, see the Remarks section. - We recommend that you set the parameter to an appropriate value, such as two seconds. If you disable time-outs by specifying , the regular expression engine offers slightly better performance. However, you should disable time-outs only under the following conditions: - -- When the input processed by a regular expression is derived from a known and trusted source or consists of static text. This excludes text that has been dynamically input by users. - -- When the regular expression pattern has been thoroughly tested to ensure that it efficiently handles matches, non-matches, and near matches. - + We recommend that you set the parameter to an appropriate value, such as two seconds. If you disable time-outs by specifying , the regular expression engine offers slightly better performance. However, you should disable time-outs only under the following conditions: + +- When the input processed by a regular expression is derived from a known and trusted source or consists of static text. This excludes text that has been dynamically input by users. + +- When the regular expression pattern has been thoroughly tested to ensure that it efficiently handles matches, non-matches, and near matches. + - When the regular expression pattern contains no language elements that are known to cause excessive backtracking when processing a near match. Regular Expression Language Elements @@ -6772,9 +6622,9 @@ For more details about `startat`, see the Remarks section of are automatically tracked and serialized by the formatter. - > [!NOTE] - > It is not guaranteed that this method will be called only once per object instance during serialization. Therefore, the method should be implemented in such a way that its behavior will be the same regardless of the number of times it is called. - + > [!NOTE] + > It is not guaranteed that this method will be called only once per object instance during serialization. Therefore, the method should be implemented in such a way that its behavior will be the same regardless of the number of times it is called. + ]]> @@ -6821,11 +6671,11 @@ Any objects that are included in the Returns the regular expression pattern that was passed into the constructor. The parameter that was passed into the constructor. - @@ -6879,20 +6729,20 @@ Any objects that are included in the Converts any escaped characters in the input string. A string of characters with any escaped characters converted to their unescaped form. - method performs one of the following two transformations: - -- It reverses the transformation performed by the method by removing the escape character ("\\") from each character escaped by the method. These include the \\, *, +, ?, |, {, [, (,), ^, $, ., #, and white space characters. In addition, the method unescapes the closing bracket (]) and closing brace (}) characters. - + method performs one of the following two transformations: + +- It reverses the transformation performed by the method by removing the escape character ("\\") from each character escaped by the method. These include the \\, *, +, ?, |, {, [, (,), ^, $, ., #, and white space characters. In addition, the method unescapes the closing bracket (]) and closing brace (}) characters. + > [!NOTE] -> cannot reverse an escaped string perfectly because it cannot deduce precisely which characters were escaped, - +> cannot reverse an escaped string perfectly because it cannot deduce precisely which characters were escaped, + - It replaces the hexadecimal values in verbatim string literals with the actual printable characters. For example, it replaces @"\x07" with "\a", or @"\x0A" with "\n". It converts to supported escape characters such as \a, \b, \e, \n, \r, \f, \t, \v, and alphanumeric characters. - - If the method encounters other escape sequences that it cannot convert, such as \w or \s, it throws an . - + + If the method encounters other escape sequences that it cannot convert, such as \w or \s, it throws an . + ]]> diff --git a/xml/System.Text/Decoder.xml b/xml/System.Text/Decoder.xml index a814951ecf2..8d4b80ddfa3 100644 --- a/xml/System.Text/Decoder.xml +++ b/xml/System.Text/Decoder.xml @@ -65,29 +65,22 @@ Converts a sequence of encoded bytes into a set of characters. class, call the method of an implementation. -## Remarks - To obtain an instance of an implementation of the class, the application should use the method of an implementation. - - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. There are several versions of both of these methods available in the class. For more information, see . A object maintains state information between successive calls to `GetChars` or methods so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations because those operations often deal with blocks of data instead of a complete data stream. +The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. There are several versions of both of these methods available in the class. For more information, see . A object maintains state information between successive calls to `GetChars` or methods so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations because those operations often deal with blocks of data instead of a complete data stream. > [!NOTE] -> When the application is done with a stream of data, it should make sure that the state information is flushed by setting the `flush` parameter to `true` in the appropriate method call. If an exception occurs or if the application switches streams, it should call to clear the internal state of the `Decoder` object. - -## Version Considerations - A or object can be serialized during a conversion operation. The state of the object is retained if it is deserialized in the same version of the .NET Framework, but lost if it is deserialized in another version. - - - -## Examples - The following example demonstrates the use of a to convert two different byte arrays into a character array. One of the character's bytes spans the arrays. This is similar to what a object does internally when reading a stream. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Decoder Example/CPP/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Decoder/Overview/source.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Decoder Example/VB/source.vb" id="Snippet1"::: +> When the application is done with a stream of data, it should make sure that the state information is flushed by setting the `flush` parameter to `true` in the appropriate method call. If an exception occurs or if the application switches streams, it should call to clear the internal state of the `Decoder` object. + ]]> + + to convert two different byte arrays into a character array. One of the character's bytes spans the arrays. This is similar to what a object does internally when reading a stream. - ]]> - +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Decoder Example/CPP/source.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System.Text/Decoder/Overview/source.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Decoder Example/VB/source.vb" id="Snippet1"::: + ]]> + When your application inherits from this class, it must override all the members. @@ -181,13 +174,13 @@ ## Remarks -Remember that the object saves state between calls to . -When the application is done with a stream of data, it should set the `flush` parameter to `true` to make sure that the state information is flushed. With this setting, the decoder ignores invalid bytes at the end of the data block and clears the internal buffer. +Remember that the object saves state between calls to . +When the application is done with a stream of data, it should set the `flush` parameter to `true` to make sure that the state information is flushed. With this setting, the decoder ignores invalid bytes at the end of the data block and clears the internal buffer. Any remaining processed data that is part of a logical unit, such as the high surrogate of a surrogate pair, is converted according to the current fallback settings. -The `Convert` method is designed to be used in a loop to decode an arbitrary amount of input, such as data read from a file or stream. +The `Convert` method is designed to be used in a loop to decode an arbitrary amount of input, such as data read from a file or stream. It stores the output of the decoding operation in a fixed-size buffer. - will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the bytes read and chars written, provided the output array allows for at least two characters. + will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the bytes read and chars written, provided the output array allows for at least two characters. Also see for more comments. ]]> diff --git a/xml/System.Text/Encoder.xml b/xml/System.Text/Encoder.xml index 6a634ae9c59..d9d9db68d0c 100644 --- a/xml/System.Text/Encoder.xml +++ b/xml/System.Text/Encoder.xml @@ -65,31 +65,24 @@ Converts a set of characters into a sequence of bytes. class, the application should use the method of an implementation. -## Remarks - To obtain an instance of an implementation of the class, the application should use the method of an implementation. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. There are several versions of both of these methods available in the class. For more information, see . +The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. There are several versions of both of these methods available in the class. For more information, see . - A object maintains state information between successive calls to `GetBytes` or methods so that it can correctly encode character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. +A object maintains state information between successive calls to `GetBytes` or methods so that it can correctly encode character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. > [!NOTE] -> When the application is done with a stream of data it should make sure that the state information is flushed by setting the `flush` parameter to `true` in the appropriate method call. If an exception occurs or if the application switches streams, it should call to clear the internal state of the `Encoder` object. - -## Version Considerations - A or object can be serialized during a conversion operation. The state of the object is retained if it is deserialized in the same version of the .NET Framework, but lost if it is deserialized in another version. - - - -## Examples - The following example demonstrates how to convert an array of Unicode characters into blocks of bytes using a specified encoding. For comparison, the array of characters is first encoded using . Next, the array of characters is encoded using an . - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoder Example/CPP/snippet.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoder/Overview/snippet.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoder Example/VB/snippet.vb" id="Snippet1"::: +> When the application is done with a stream of data it should make sure that the state information is flushed by setting the `flush` parameter to `true` in the appropriate method call. If an exception occurs or if the application switches streams, it should call to clear the internal state of the `Encoder` object. + ]]> + + . Next, the array of characters is encoded using an . - ]]> - +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoder Example/CPP/snippet.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System.Text/Encoder/Overview/snippet.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoder Example/VB/snippet.vb" id="Snippet1"::: + ]]> + When your application inherits from this class, it must override all the members. diff --git a/xml/System.Text/Encoding.xml b/xml/System.Text/Encoding.xml index 5e85ce1195f..6fd05e4501b 100644 --- a/xml/System.Text/Encoding.xml +++ b/xml/System.Text/Encoding.xml @@ -1,419 +1,212 @@ - - - - - - - - - - - - - - - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - - - - - - - - - - - - - - System.Object - - - - System.ICloneable - - - - - [System.Runtime.CompilerServices.Nullable(0)] - [<System.Runtime.CompilerServices.Nullable(0)>] - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - [System.Serializable] - [<System.Serializable>] - - - [System.Runtime.InteropServices.ComVisible(true)] - [<System.Runtime.InteropServices.ComVisible(true)>] - - - - Represents a character encoding. - + + + + + + + + + + + + + + + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + + + + + + + + + + + + + + System.Object + + + + System.ICloneable + + + + + [System.Runtime.CompilerServices.Nullable(0)] + [<System.Runtime.CompilerServices.Nullable(0)>] + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + [System.Serializable] + [<System.Serializable>] + + + [System.Runtime.InteropServices.ComVisible(true)] + [<System.Runtime.InteropServices.ComVisible(true)>] + + + + Represents a character encoding. + For more information about this API, see Supplemental API remarks for Encoding. + , see [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding). - -Note that is intended to operate on Unicode characters instead of arbitrary binary data, such as byte arrays. If you must encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . - -.NET provides the following implementations of the class to support current Unicode encodings and other encodings: - -- encodes Unicode characters as single 7-bit ASCII characters. This encoding only supports character values between U+0000 and U+007F. Code page 20127. Also available through the property. - -- encodes Unicode characters using the UTF-7 encoding. This encoding supports all Unicode character values. Code page 65000. Also available through the property. - -- encodes Unicode characters using the UTF-8 encoding. This encoding supports all Unicode character values. Code page 65001. Also available through the property. - -- encodes Unicode characters using the UTF-16 encoding. Both little endian and big endian byte orders are supported. Also available through the property and the property. - -- encodes Unicode characters using the UTF-32 encoding. Both little endian (code page 12000) and big endian (code page 12001) byte orders are supported. Also available through the property. - -The class is primarily intended to convert between different encodings and Unicode. Often one of the derived Unicode classes is the correct choice for your app. - -Use the method to obtain other encodings, and call the method to get a list of all encodings. - -### List of encodings - -The following table lists the encodings supported by .NET. It lists each encoding's code page number and the values of the encoding's and properties. A check mark in the **.NET Framework support**, **.NET Core support**, or **.NET 5 and later support** column indicates that the code page is natively supported by that .NET implementation, regardless of the underlying platform. For .NET Framework, the availability of other encodings listed in the table depends on the operating system. For .NET Core and .NET 5 and later versions, other encodings are available by using the class or by deriving from the class. - -> [!NOTE] -> Code pages whose property corresponds to an international standard do not necessarily comply in full with that standard. - -|Code page|Name|Display name|.NET Framework support| .NET Core support | .NET 5 and later support | -|---------|----|------------|----------------------|-------------------|----------------------------| -|37|IBM037|IBM EBCDIC (US-Canada)|||| -|437|IBM437|OEM United States|||| -|500|IBM500|IBM EBCDIC (International)|||| -|708|ASMO-708|Arabic (ASMO 708)|||| -|720|DOS-720|Arabic (DOS)|||| -|737|ibm737|Greek (DOS)|||| -|775|ibm775|Baltic (DOS)|||| -|850|ibm850|Western European (DOS)|||| -|852|ibm852|Central European (DOS)|||| -|855|IBM855|OEM Cyrillic|||| -|857|ibm857|Turkish (DOS)|||| -|858|IBM00858|OEM Multilingual Latin I|||| -|860|IBM860|Portuguese (DOS)|||| -|861|ibm861|Icelandic (DOS)|||| -|862|DOS-862|Hebrew (DOS)|||| -|863|IBM863|French Canadian (DOS)|||| -|864|IBM864|Arabic (864)|||| -|865|IBM865|Nordic (DOS)|||| -|866|cp866|Cyrillic (DOS)|||| -|869|ibm869|Greek, Modern (DOS)|||| -|870|IBM870|IBM EBCDIC (Multilingual Latin-2)|||| -|874|windows-874|Thai (Windows)|||| -|875|cp875|IBM EBCDIC (Greek Modern)|||| -|932|shift_jis|Japanese (Shift-JIS)|||| -|936|gb2312|Chinese Simplified (GB2312)|✓||| -|949|ks_c_5601-1987|Korean|||| -|950|big5|Chinese Traditional (Big5)|||| -|1026|IBM1026|IBM EBCDIC (Turkish Latin-5)|||| -|1047|IBM01047|IBM Latin-1|||| -|1140|IBM01140|IBM EBCDIC (US-Canada-Euro)|||| -|1141|IBM01141|IBM EBCDIC (Germany-Euro)|||| -|1142|IBM01142|IBM EBCDIC (Denmark-Norway-Euro)|||| -|1143|IBM01143|IBM EBCDIC (Finland-Sweden-Euro)|||| -|1144|IBM01144|IBM EBCDIC (Italy-Euro)|||| -|1145|IBM01145|IBM EBCDIC (Spain-Euro)|||| -|1146|IBM01146|IBM EBCDIC (UK-Euro)|||| -|1147|IBM01147|IBM EBCDIC (France-Euro)|||| -|1148|IBM01148|IBM EBCDIC (International-Euro)|||| -|1149|IBM01149|IBM EBCDIC (Icelandic-Euro)|||| -|1200|utf-16|Unicode|✓|✓|✓| -|1201|unicodeFFFE|Unicode (Big endian)|✓|✓|✓| -|1250|windows-1250|Central European (Windows)|||| -|1251|windows-1251|Cyrillic (Windows)|||| -|1252|Windows-1252|Western European (Windows)|✓|||| -|1253|windows-1253|Greek (Windows)|||| -|1254|windows-1254|Turkish (Windows)|||| -|1255|windows-1255|Hebrew (Windows)|||| -|1256|windows-1256|Arabic (Windows)|||| -|1257|windows-1257|Baltic (Windows)|||| -|1258|windows-1258|Vietnamese (Windows)|||| -|1361|Johab|Korean (Johab)|||| -|10000|macintosh|Western European (Mac)|||| -|10001|x-mac-japanese|Japanese (Mac)|||| -|10002|x-mac-chinesetrad|Chinese Traditional (Mac)|||| -|10003|x-mac-korean|Korean (Mac)|✓||| -|10004|x-mac-arabic|Arabic (Mac)|||| -|10005|x-mac-hebrew|Hebrew (Mac)|||| -|10006|x-mac-greek|Greek (Mac)|||| -|10007|x-mac-cyrillic|Cyrillic (Mac)|||| -|10008|x-mac-chinesesimp|Chinese Simplified (Mac)|✓||| -|10010|x-mac-romanian|Romanian (Mac)|||| -|10017|x-mac-ukrainian|Ukrainian (Mac)|||| -|10021|x-mac-thai|Thai (Mac)|||| -|10029|x-mac-ce|Central European (Mac)|||| -|10079|x-mac-icelandic|Icelandic (Mac)|||| -|10081|x-mac-turkish|Turkish (Mac)|||| -|10082|x-mac-croatian|Croatian (Mac)|||| -|12000|utf-32|Unicode (UTF-32)|✓|✓|✓| -|12001|utf-32BE|Unicode (UTF-32 Big endian)|✓|✓|✓| -|20000|x-Chinese-CNS|Chinese Traditional (CNS)|||| -|20001|x-cp20001|TCA Taiwan|||| -|20002|x-Chinese-Eten|Chinese Traditional (Eten)|||| -|20003|x-cp20003|IBM5550 Taiwan|||| -|20004|x-cp20004|TeleText Taiwan|||| -|20005|x-cp20005|Wang Taiwan|||| -|20105|x-IA5|Western European (IA5)|||| -|20106|x-IA5-German|German (IA5)|||| -|20107|x-IA5-Swedish|Swedish (IA5)|||| -|20108|x-IA5-Norwegian|Norwegian (IA5)|||| -|20127|us-ascii|US-ASCII|✓|✓|✓| -|20261|x-cp20261|T.61|||| -|20269|x-cp20269|ISO-6937|||| -|20273|IBM273|IBM EBCDIC (Germany)|||| -|20277|IBM277|IBM EBCDIC (Denmark-Norway)|||| -|20278|IBM278|IBM EBCDIC (Finland-Sweden)|||| -|20280|IBM280|IBM EBCDIC (Italy)|||| -|20284|IBM284|IBM EBCDIC (Spain)|||| -|20285|IBM285|IBM EBCDIC (UK)|||| -|20290|IBM290|IBM EBCDIC (Japanese katakana)|||| -|20297|IBM297|IBM EBCDIC (France)|||| -|20420|IBM420|IBM EBCDIC (Arabic)|||| -|20423|IBM423|IBM EBCDIC (Greek)|||| -|20424|IBM424|IBM EBCDIC (Hebrew)|||| -|20833|x-EBCDIC-KoreanExtended|IBM EBCDIC (Korean Extended)|||| -|20838|IBM-Thai|IBM EBCDIC (Thai)|||| -|20866|koi8-r|Cyrillic (KOI8-R)|||| -|20871|IBM871|IBM EBCDIC (Icelandic)|||| -|20880|IBM880|IBM EBCDIC (Cyrillic Russian)|||| -|20905|IBM905|IBM EBCDIC (Turkish)|||| -|20924|IBM00924|IBM Latin-1|||| -|20932|EUC-JP|Japanese (JIS 0208-1990 and 0212-1990)|||| -|20936|x-cp20936|Chinese Simplified (GB2312-80)|✓||| -|20949|x-cp20949|Korean Wansung|✓||| -|21025|cp1025|IBM EBCDIC (Cyrillic Serbian-Bulgarian)|||| -|21866|koi8-u|Cyrillic (KOI8-U)|||| -|28591|iso-8859-1|Western European (ISO)|✓|✓|✓| -|28592|iso-8859-2|Central European (ISO)|||| -|28593|iso-8859-3|Latin 3 (ISO)|||| -|28594|iso-8859-4|Baltic (ISO)|||| -|28595|iso-8859-5|Cyrillic (ISO)|||| -|28596|iso-8859-6|Arabic (ISO)|||| -|28597|iso-8859-7|Greek (ISO)|||| -|28598|iso-8859-8|Hebrew (ISO-Visual)|✓||| -|28599|iso-8859-9|Turkish (ISO)|||| -|28603|iso-8859-13|Estonian (ISO)|||| -|28605|iso-8859-15|Latin 9 (ISO)|||| -|29001|x-Europa|Europa|||| -|38598|iso-8859-8-i|Hebrew (ISO-Logical)|✓||| -|50220|iso-2022-jp|Japanese (JIS)|✓||| -|50221|csISO2022JP|Japanese (JIS-Allow 1 byte Kana)|✓||| -|50222|iso-2022-jp|Japanese (JIS-Allow 1 byte Kana - SO/SI)|✓||| -|50225|iso-2022-kr|Korean (ISO)|✓||| -|50227|x-cp50227|Chinese Simplified (ISO-2022)|✓||| -|51932|euc-jp|Japanese (EUC)|✓||| -|51936|EUC-CN|Chinese Simplified (EUC)|✓||| -|51949|euc-kr|Korean (EUC)|✓||| -|52936|hz-gb-2312|Chinese Simplified (HZ)|✓||| -|54936|GB18030|Chinese Simplified (GB18030)|✓||| -|57002|x-iscii-de|ISCII Devanagari|✓||| -|57003|x-iscii-be|ISCII Bengali|✓||| -|57004|x-iscii-ta|ISCII Tamil|✓||| -|57005|x-iscii-te|ISCII Telugu|✓||| -|57006|x-iscii-as|ISCII Assamese|✓||| -|57007|x-iscii-or|ISCII Oriya|✓||| -|57008|x-iscii-ka|ISCII Kannada|✓||| -|57009|x-iscii-ma|ISCII Malayalam|✓||| -|57010|x-iscii-gu|ISCII Gujarati|✓||| -|57011|x-iscii-pa|ISCII Punjabi|✓||| -|65000|utf-7|Unicode (UTF-7)|✓|✓|| -|65001|utf-8|Unicode (UTF-8)|✓|✓|✓| - - The following example calls the and methods to get the Greek (Windows) code page encoding. It compares the objects returned by the method calls to show that they are equal, and then maps displays the Unicode code point and the corresponding code page value for each character in the Greek alphabet. - - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Overview/getencoding1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.encoding/vb/getencoding1.vb" id="Snippet1"::: - - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - - The UTF-16 and the UTF-32 encoders can use the big endian byte order (most significant byte first) or the little endian byte order (least significant byte first). For example, the Latin Capital Letter A (U+0041) is serialized as follows (in hexadecimal): - -- UTF-16 big endian byte order: 00 41 - -- UTF-16 little endian byte order: 41 00 - -- UTF-32 big endian byte order: 00 00 00 41 - -- UTF-32 little endian byte order: 41 00 00 00 - - It is generally more efficient to store Unicode characters using the native byte order. For example, it is better to use the little endian byte order on little endian platforms, such as Intel computers. - - The method retrieves an array of bytes that includes the byte order mark (BOM). If this byte array is prefixed to an encoded stream, it helps the decoder to identify the encoding format used. - - For more information on byte order and the byte order mark, see The Unicode Standard at the [Unicode home page](https://home.unicode.org/). - - Note that the encoding classes allow errors to: - -- Silently change to a "?" character. - -- Use a "best fit" character. - -- Change to an application-specific behavior through use of the and classes with the U+FFFD Unicode replacement character. - - You should throw an exception on any data stream error. An app either uses a "throwonerror" flag when applicable or uses the and classes. Best fit fallback is often not recommended because it can cause data loss or confusion and is slower than simple character replacements. For ANSI encodings, the best fit behavior is the default. - -## Examples - The following example converts a string from one encoding to another. +The following example converts a string from one encoding to another. > [!NOTE] > The `byte[]` array is the only type in this example that contains the encoded data. The .NET `Char` and `String` types are themselves Unicode, so the call decodes the data back to Unicode. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/CPP/convert.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Overview/convert.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/VB/convert.vb" id="Snippet1"::: - - ]]> - - How to use character encoding classes in .NET - - - - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - Initializes a new instance of the class. - - - - - - - - - Constructor - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - Initializes a new instance of the class. - +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/CPP/convert.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Overview/convert.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/VB/convert.vb" id="Snippet1"::: + ]]> + + How to use character encoding classes in .NET + + + + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + Initializes a new instance of the class. + + + + + + + + + Constructor + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + Initializes a new instance of the class. + - - - - - - - - - - - - - Constructor - - System.Text.Encoding - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - - - + ]]> + + + + + + + + + + + + + Constructor + + System.Text.Encoding + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + + + The code page identifier of the preferred encoding. -or- - 0, to use the default encoding. - Initializes a new instance of the class that corresponds to the specified code page. - + 0, to use the default encoding. + Initializes a new instance of the class that corresponds to the specified code page. + object that uses best-fit fallback for both encoding and decoding operations. Both the and properties are read-only and cannot be modified. To control the fallback strategy for a class derived from , call the constructor. - ]]> - - - is less than zero. - - - - - - - - - - - - - Constructor - - System.Text.Encoding - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - - - - - - - The encoding code page identifier. - An object that provides an error-handling procedure when a character cannot be encoded with the current encoding. - An object that provides an error-handling procedure when a byte sequence cannot be decoded with the current encoding. - Initializes a new instance of the class that corresponds to the specified code page with the specified encoder and decoder fallback strategies. - + ]]> + + + is less than zero. + + + + + + + + + + + + + Constructor + + System.Text.Encoding + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + + + + + + + The encoding code page identifier. + An object that provides an error-handling procedure when a character cannot be encoded with the current encoding. + An object that provides an error-handling procedure when a byte sequence cannot be decoded with the current encoding. + Initializes a new instance of the class that corresponds to the specified code page with the specified encoder and decoder fallback strategies. + - - - is less than zero. - - - - - - - - - - Property - - System.Text.Encoding - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Text.Encoding - - - Gets an encoding for the ASCII (7-bit) character set. - An encoding for the ASCII (7-bit) character set. - + ]]> + + + is less than zero. + + + + + + + + + + Property + + System.Text.Encoding + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Text.Encoding + + + Gets an encoding for the ASCII (7-bit) character set. + An encoding for the ASCII (7-bit) character set. + - - - - - - How to use character encoding classes in .NET - - - - - - - - - - Property - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - Gets an encoding for the UTF-16 format that uses the big endian byte order. - An encoding object for the UTF-16 format that uses the big endian byte order. - + ]]> + + + + + + How to use character encoding classes in .NET + + + + + + + + + + Property + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + Gets an encoding for the UTF-16 format that uses the big endian byte order. + An encoding object for the UTF-16 format that uses the big endian byte order. + - - - - - How to use character encoding classes in .NET - - - - - - - - - - Property - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - System.String - - - When overridden in a derived class, gets a name for the current encoding that can be used with mail agent body tags. + ]]> + + + + + How to use character encoding classes in .NET + + + + + + + + + + Property + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + System.String + + + When overridden in a derived class, gets a name for the current encoding that can be used with mail agent body tags. A name for the current that can be used with mail agent body tags. -or- - An empty string (""), if the current cannot be used. - + An empty string (""), if the current cannot be used. + - - - - - - - - - - - - - - - Method - - M:System.ICloneable.Clone - - - System.Text.Encoding - 4.0.10.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.InteropServices.ComVisible(false)] - [<System.Runtime.InteropServices.ComVisible(false)>] - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Object - - - - When overridden in a derived class, creates a shallow copy of the current object. - A copy of the current object. - + ]]> + + + + + + + + + + + + + + + Method + + M:System.ICloneable.Clone + + + System.Text.Encoding + 4.0.10.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.InteropServices.ComVisible(false)] + [<System.Runtime.InteropServices.ComVisible(false)>] + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Object + + + + When overridden in a derived class, creates a shallow copy of the current object. + A copy of the current object. + - - - - - - - - - - - Property - - System.Text.Encoding - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - When overridden in a derived class, gets the code page identifier of the current . - The code page identifier of the current . - + ]]> + + + + + + + + + + + Property + + System.Text.Encoding + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + When overridden in a derived class, gets the code page identifier of the current . + The code page identifier of the current . + - - - - - - - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - Converts a byte array from one encoding to another. - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Byte[] - - - - - - - - The encoding format of . - The target encoding format. - The bytes to convert. - Converts an entire byte array from one encoding to another. - An array of type containing the results of converting from to . - + ]]> + + + + + + + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + Converts a byte array from one encoding to another. + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Byte[] + + + + + + + + The encoding format of . + The target encoding format. + The bytes to convert. + Converts an entire byte array from one encoding to another. + An array of type containing the results of converting from to . + - - + ]]> + + is . -or- @@ -916,74 +709,74 @@ The following example demonstrates the effect of the ASCII encoding on character -or- - is . + is . A fallback occurred (for more information, see Character Encoding in .NET) -and- - **srcEncoding.** is set to . + **srcEncoding.** is set to . A fallback occurred (for more information, see Character Encoding in .NET) -and- - **dstEncoding.** is set to . - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Byte[] - - - - - - - - - - The encoding of the source array, . - The encoding of the output array. - The array of bytes to convert. - The index of the first element of to convert. - The number of bytes to convert. - Converts a range of bytes in a byte array from one encoding to another. - An array of type containing the result of converting a range of bytes in from to . - To be added. - + **dstEncoding.** is set to . + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Byte[] + + + + + + + + + + The encoding of the source array, . + The encoding of the output array. + The array of bytes to convert. + The index of the first element of to convert. + The number of bytes to convert. + Converts a range of bytes in a byte array from one encoding to another. + An array of type containing the result of converting a range of bytes in from to . + To be added. + is . -or- @@ -992,122 +785,122 @@ The following example demonstrates the effect of the ASCII encoding on character -or- - is . - - and do not specify a valid range in the byte array. + is . + + and do not specify a valid range in the byte array. A fallback occurred (for more information, see Character Encoding in .NET) -and- - **srcEncoding.** is set to . + **srcEncoding.** is set to . A fallback occurred (for more information, see Character Encoding in .NET) -and- - **dstEncoding.** is set to . - - - - - - - - - Method - - System.Runtime - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - mscorlib - - - netstandard - - - System.IO.Stream - - - - - - - - - The stream to wrap. - The encoding associated with . - The encoding associated with the that's returned by this method. - - if disposing the returned by this method should not dispose . - Creates a that serves to transcode data between an inner and an outer , similar to . - A stream that transcodes the contents of as . - + **dstEncoding.** is set to . + + + + + + + + + Method + + System.Runtime + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + mscorlib + + + netstandard + + + System.IO.Stream + + + + + + + + + The stream to wrap. + The encoding associated with . + The encoding associated with the that's returned by this method. + + if disposing the returned by this method should not dispose . + Creates a that serves to transcode data between an inner and an outer , similar to . + A stream that transcodes the contents of as . + 's and properties will reflect whether `innerStream` is readable or writable. If `innerStream` is full-duplex, the returned will be as well. However, the returned is not seekable, even if `innerStream`'s property returns `true`. - ]]> - - - - - - - - - - - - - - - Property - - System.Text.Encoding - 4.0.10.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.InteropServices.ComVisible(false)] - [<System.Runtime.InteropServices.ComVisible(false)>] - - - - System.Text.DecoderFallback - - - Gets or sets the object for the current object. - The decoder fallback object for the current object. - + ]]> + + + + + + + + + + + + + + + Property + + System.Text.Encoding + 4.0.10.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.InteropServices.ComVisible(false)] + [<System.Runtime.InteropServices.ComVisible(false)>] + + + + System.Text.DecoderFallback + + + Gets or sets the object for the current object. + The decoder fallback object for the current object. + 's and , which throws a when bytes cannot be decoded. - ]]> - - The value in a set operation is . - A value cannot be assigned in a set operation because the current object is read-only. - - - How to use character encoding classes in .NET - - - - - - - - - - Property - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - - [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - [get: System.Security.SecuritySafeCritical] - [<get: System.Security.SecuritySafeCritical>] - - - - System.Text.Encoding - - - Gets the default encoding for this .NET implementation. - The default encoding for this .NET implementation. - + ]]> + + The value in a set operation is . + A value cannot be assigned in a set operation because the current object is read-only. + + + How to use character encoding classes in .NET + + + + + + + + + + Property + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + + [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + [get: System.Security.SecuritySafeCritical] + [<get: System.Security.SecuritySafeCritical>] + + + + System.Text.Encoding + + + Gets the default encoding for this .NET implementation. + The default encoding for this .NET implementation. + property always ge On .NET Core, the property always returns the . UTF-8 is supported on all the operating systems (Windows, Linux, and macOS) on which .NET Core applications run. - ]]> - - - - - - - - - - - - - - - Property - - System.Text.Encoding - 4.0.10.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.InteropServices.ComVisible(false)] - [<System.Runtime.InteropServices.ComVisible(false)>] - - - - System.Text.EncoderFallback - - - Gets or sets the object for the current object. - The encoder fallback object for the current object. - + ]]> + + + + + + + + + + + + + + + Property + + System.Text.Encoding + 4.0.10.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.InteropServices.ComVisible(false)] + [<System.Runtime.InteropServices.ComVisible(false)>] + + + + System.Text.EncoderFallback + + + Gets or sets the object for the current object. + The encoder fallback object for the current object. + property always returns - An exception fallback handler, which throws an exception when characters cannot be encoded. .NET includes one exception fallback handler, , which throws an when characters cannot be decoded. - ]]> - - The value in a set operation is . - A value cannot be assigned in a set operation because the current object is read-only. - - - How to use character encoding classes in .NET - - - - - - - - - - Property - - System.Text.Encoding - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.String - - - When overridden in a derived class, gets the human-readable description of the current encoding. - The human-readable description of the current . - + ]]> + + The value in a set operation is . + A value cannot be assigned in a set operation because the current object is read-only. + + + How to use character encoding classes in .NET + + + + + + + + + + Property + + System.Text.Encoding + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.String + + + When overridden in a derived class, gets the human-readable description of the current encoding. + The human-readable description of the current . + property always returns :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BodyName/names.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Names/VB/names.vb" id="Snippet1"::: - ]]> - - - - - - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - - System.Boolean - - - - - - [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] - [<System.Diagnostics.CodeAnalysis.NotNullWhen(true)>] - - - - - - The to compare with the current instance. - Determines whether the specified is equal to the current instance. - - if is an instance of and is equal to the current instance; otherwise, . - + ]]> + + + + + + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + + System.Boolean + + + + + + [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] + [<System.Diagnostics.CodeAnalysis.NotNullWhen(true)>] + + + + + + The to compare with the current instance. + Determines whether the specified is equal to the current instance. + + if is an instance of and is equal to the current instance; otherwise, . + property always returns :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Equals/equals.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Equals/VB/equals.vb" id="Snippet1"::: - ]]> - - - - - - - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters. - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - The character array containing the characters to encode. - When overridden in a derived class, calculates the number of bytes produced by encoding all the characters in the specified character array. - The number of bytes produced by encoding all the characters in the specified character array. - + ]]> + + + + + + + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters. + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + The character array containing the characters to encode. + When overridden in a derived class, calculates the number of bytes produced by encoding all the characters in the specified character array. + The number of bytes produced by encoding all the characters in the specified character array. + property always returns :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/getbytes_chararr.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/VB/getbytes_chararr.vb" id="Snippet1"::: - ]]> - - - is . + ]]> + + + is . A fallback occurred (for more information, see Character Encoding in .NET) -and- - is set to . - - - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.Encoding - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Int32 - - - - - - The span of characters to encode. - When overridden in a derived class, calculates the number of bytes produced by encoding the characters in the specified character span. - The number of bytes produced by encoding the specified character span. - + is set to . + + + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.Encoding + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Int32 + + + + + + The span of characters to encode. + When overridden in a derived class, calculates the number of bytes produced by encoding the characters in the specified character span. + The number of bytes produced by encoding the specified character span. + property always returns - Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output span buffer is too small. For continuous encoding of a stream, this method is often the best choice. - ]]> - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - The string containing the set of characters to encode. - When overridden in a derived class, calculates the number of bytes produced by encoding the characters in the specified string. - The number of bytes produced by encoding the specified characters. - + ]]> + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + The string containing the set of characters to encode. + When overridden in a derived class, calculates the number of bytes produced by encoding the characters in the specified string. + The number of bytes produced by encoding the specified characters. + property always returns :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_string.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/VB/getbytes_string.vb" id="Snippet1"::: - ]]> - - - is . + ]]> + + + is . A fallback occurred (for more information, see Character Encoding in .NET) -and- - is set to . - - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.10.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - [System.Security.SecurityCritical] - [<System.Security.SecurityCritical>] - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - [System.Runtime.InteropServices.ComVisible(false)] - [<System.Runtime.InteropServices.ComVisible(false)>] - - - - System.Int32 - - - - - - - A pointer to the first character to encode. - The number of characters to encode. - When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters starting at the specified character pointer. - The number of bytes produced by encoding the specified characters. - + is set to . + + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.10.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + [System.Security.SecurityCritical] + [<System.Security.SecurityCritical>] + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + [System.Runtime.InteropServices.ComVisible(false)] + [<System.Runtime.InteropServices.ComVisible(false)>] + + + + System.Int32 + + + + + + + A pointer to the first character to encode. + The number of characters to encode. + When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters starting at the specified character pointer. + The number of bytes produced by encoding the specified characters. + property always returns - Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - ]]> - - - is . - - is less than zero. + ]]> + + + is . + + is less than zero. A fallback occurred (for more information, see Character Encoding in .NET) -and- - is set to . - - - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - - - The character array containing the set of characters to encode. - The index of the first character to encode. - The number of characters to encode. - When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters from the specified character array. - The number of bytes produced by encoding the specified characters. - + is set to . + + + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + + + The character array containing the set of characters to encode. + The index of the first character to encode. + The number of characters to encode. + When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters from the specified character array. + The number of bytes produced by encoding the specified characters. + property always returns :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_chararric.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/VB/getbytes_chararric.vb" id="Snippet1"::: - ]]> - - - is . - + ]]> + + + is . + or is less than zero. -or- - and do not denote a valid range in . + and do not denote a valid range in . A fallback occurred (for more information, see Character Encoding in .NET) -and- - is set to . - - - - - - - - - - - - - Method - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.Encoding - - - System.Int32 - - - - - - - - The string containing the set of characters to encode. - The index of the first character to encode. - The number of characters to encode. - When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters from the specified string. - The number of bytes produced by encoding the string. - + is set to . + + + + + + + + + + + + + Method + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.Encoding + + + System.Int32 + + + + + + + + The string containing the set of characters to encode. + The index of the first character to encode. + The number of characters to encode. + When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters from the specified string. + The number of bytes produced by encoding the string. + property always returns :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_chararric.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/VB/getbytes_chararric.vb" id="Snippet1"::: - ]]> - - - - - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - When overridden in a derived class, encodes a set of characters into a sequence of bytes. - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Byte[] - - - - - - The character array containing the characters to encode. - When overridden in a derived class, encodes all the characters in the specified character array into a sequence of bytes. - A byte array containing the results of encoding the specified set of characters. - + ]]> + + + + + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + When overridden in a derived class, encodes a set of characters into a sequence of bytes. + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Byte[] + + + + + + The character array containing the characters to encode. + When overridden in a derived class, encodes all the characters in the specified character array into a sequence of bytes. + A byte array containing the results of encoding the specified set of characters. + property always returns :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/getbytes_chararr.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/VB/getbytes_chararr.vb" id="Snippet1"::: - ]]> - - - is . + ]]> + + + is . A fallback occurred (for more information, see Character Encoding in .NET) -and- - is set to . - - - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Byte[] - - - - - - The string containing the characters to encode. - When overridden in a derived class, encodes all the characters in the specified string into a sequence of bytes. - A byte array containing the results of encoding the specified set of characters. - + is set to . + + + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Byte[] + + + + + + The string containing the characters to encode. + When overridden in a derived class, encodes all the characters in the specified string into a sequence of bytes. + A byte array containing the results of encoding the specified set of characters. + property always returns :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_string.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/VB/getbytes_string.vb" id="Snippet1"::: - ]]> - - - is . + ]]> + + + is . A fallback occurred (for more information, see Character Encoding in .NET) -and- - is set to . - - - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.Encoding - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Int32 - - - - - - - The span containing the set of characters to encode. - The byte span to hold the encoded bytes. - When overridden in a derived class, encodes into a span of bytes a set of characters from the specified read-only span. - The number of encoded bytes. - + is set to . + + + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.Encoding + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Int32 + + + + + + + The span containing the set of characters to encode. + The byte span to hold the encoded bytes. + When overridden in a derived class, encodes into a span of bytes a set of characters from the specified read-only span. + The number of encoded bytes. + property always returns - Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - ]]> - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Byte[] - - - - - - - - The character array containing the set of characters to encode. - The index of the first character to encode. - The number of characters to encode. - When overridden in a derived class, encodes a set of characters from the specified character array into a sequence of bytes. - A byte array containing the results of encoding the specified set of characters. - + ]]> + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Byte[] + + + + + + + + The character array containing the set of characters to encode. + The index of the first character to encode. + The number of characters to encode. + When overridden in a derived class, encodes a set of characters from the specified character array into a sequence of bytes. + A byte array containing the results of encoding the specified set of characters. + property always returns :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_chararric.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/VB/getbytes_chararric.vb" id="Snippet1"::: - ]]> - - - is . - + ]]> + + + is . + or is less than zero. -or- - and do not denote a valid range in . + and do not denote a valid range in . A fallback occurred (for more information, see Character Encoding in .NET) -and- - is set to . - - - - - - - - - - - - - Method - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.Encoding - - - System.Byte[] - - - - - - - - The string containing the characters to encode. - The index inside the string to start the encoding from. - The number of characters to encode. - When overridden in a derived class, encodes into an array of bytes the number of characters specified by in the specified string, starting from the specified . - A byte array containing the results of encoding the specified set of characters. - + is set to . + + + + + + + + + + + + + Method + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.Encoding + + + System.Byte[] + + + + + + + + The string containing the characters to encode. + The index inside the string to start the encoding from. + The number of characters to encode. + When overridden in a derived class, encodes into an array of bytes the number of characters specified by in the specified string, starting from the specified . + A byte array containing the results of encoding the specified set of characters. + property always returns :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_string.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/VB/getbytes_string.vb" id="Snippet1"::: - ]]> - - - - - - - - - - Method - - System.Text.Encoding - 4.0.10.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - [System.Security.SecurityCritical] - [<System.Security.SecurityCritical>] - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - [System.Runtime.InteropServices.ComVisible(false)] - [<System.Runtime.InteropServices.ComVisible(false)>] - - - - System.Int32 - - - - - - - - - A pointer to the first character to encode. - The number of characters to encode. - A pointer to the location at which to start writing the resulting sequence of bytes. - The maximum number of bytes to write. - When overridden in a derived class, encodes a set of characters starting at the specified character pointer into a sequence of bytes that are stored starting at the specified byte pointer. - The actual number of bytes written at the location indicated by the parameter. - + ]]> + + + + + + + + + + Method + + System.Text.Encoding + 4.0.10.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + [System.Security.SecurityCritical] + [<System.Security.SecurityCritical>] + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + [System.Runtime.InteropServices.ComVisible(false)] + [<System.Runtime.InteropServices.ComVisible(false)>] + + + + System.Int32 + + + + + + + + + A pointer to the first character to encode. + The number of characters to encode. + A pointer to the location at which to start writing the resulting sequence of bytes. + The maximum number of bytes to write. + When overridden in a derived class, encodes a set of characters starting at the specified character pointer into a sequence of bytes that are stored starting at the specified byte pointer. + The actual number of bytes written at the location indicated by the parameter. + property always returns - Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - ]]> - - + ]]> + + is . -or- - is . - - or is less than zero. - - is less than the resulting number of bytes. + is . + + or is less than zero. + + is less than the resulting number of bytes. A fallback occurred (for more information, see Character Encoding in .NET) -and- - is set to . - - - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - - - - - The character array containing the set of characters to encode. - The index of the first character to encode. - The number of characters to encode. - The byte array to contain the resulting sequence of bytes. - The index at which to start writing the resulting sequence of bytes. - When overridden in a derived class, encodes a set of characters from the specified character array into the specified byte array. - The actual number of bytes written into . - + is set to . + + + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + + + + + The character array containing the set of characters to encode. + The index of the first character to encode. + The number of characters to encode. + The byte array to contain the resulting sequence of bytes. + The index at which to start writing the resulting sequence of bytes. + When overridden in a derived class, encodes a set of characters from the specified character array into the specified byte array. + The actual number of bytes written into . + property always returns :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_chararric.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/VB/getbytes_chararric.vb" id="Snippet1"::: - ]]> - - + ]]> + + is . -or- - is . - + is . + or or is less than zero. -or- @@ -2552,73 +2345,73 @@ On .NET Core, the property always returns -or- - is not a valid index in . - - does not have enough capacity from to the end of the array to accommodate the resulting bytes. + is not a valid index in . + + does not have enough capacity from to the end of the array to accommodate the resulting bytes. A fallback occurred (for more information, see Character Encoding in .NET) -and- - is set to . - - - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - - - - - The string containing the set of characters to encode. - The index of the first character to encode. - The number of characters to encode. - The byte array to contain the resulting sequence of bytes. - The index at which to start writing the resulting sequence of bytes. - When overridden in a derived class, encodes a set of characters from the specified string into the specified byte array. - The actual number of bytes written into . - + is set to . + + + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + + + + + The string containing the set of characters to encode. + The index of the first character to encode. + The number of characters to encode. + The byte array to contain the resulting sequence of bytes. + The index at which to start writing the resulting sequence of bytes. + When overridden in a derived class, encodes a set of characters from the specified string into the specified byte array. + The actual number of bytes written into . + property always returns :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_string.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/VB/getbytes_string.vb" id="Snippet1"::: - ]]> - - + ]]> + + is . -or- - is . - + is . + or or is less than zero. -or- @@ -2664,75 +2457,75 @@ On .NET Core, the property always returns -or- - is not a valid index in . - - does not have enough capacity from to the end of the array to accommodate the resulting bytes. + is not a valid index in . + + does not have enough capacity from to the end of the array to accommodate the resulting bytes. A fallback occurred (for more information, see Character Encoding in .NET) -and- - is set to . - - - - - - - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - When overridden in a derived class, calculates the number of characters produced by decoding a sequence of bytes. - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - The byte array containing the sequence of bytes to decode. - When overridden in a derived class, calculates the number of characters produced by decoding all the bytes in the specified byte array. - The number of characters produced by decoding the specified sequence of bytes. - + is set to . + + + + + + + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + When overridden in a derived class, calculates the number of characters produced by decoding a sequence of bytes. + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + The byte array containing the sequence of bytes to decode. + When overridden in a derived class, calculates the number of characters produced by decoding all the bytes in the specified byte array. + The number of characters produced by decoding the specified sequence of bytes. + property always returns :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getchars.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/VB/getchars.vb" id="Snippet1"::: - ]]> - - - is . + ]]> + + + is . A fallback occurred (for more information, see Character Encoding in .NET) -and- - is set to . - - - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.Encoding - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Int32 - - - - - - A read-only byte span to decode. - When overridden in a derived class, calculates the number of characters produced by decoding the provided read-only byte span. - The number of characters produced by decoding the byte span. - + is set to . + + + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.Encoding + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Int32 + + + + + + A read-only byte span to decode. + When overridden in a derived class, calculates the number of characters produced by decoding the provided read-only byte span. + The number of characters produced by decoding the byte span. + property always returns - Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. - ]]> - - - - - - - - - - Method - - System.Text.Encoding - 4.0.10.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - [System.Security.SecurityCritical] - [<System.Security.SecurityCritical>] - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - [System.Runtime.InteropServices.ComVisible(false)] - [<System.Runtime.InteropServices.ComVisible(false)>] - - - - System.Int32 - - - - - - - A pointer to the first byte to decode. - The number of bytes to decode. - When overridden in a derived class, calculates the number of characters produced by decoding a sequence of bytes starting at the specified byte pointer. - The number of characters produced by decoding the specified sequence of bytes. - + ]]> + + + + + + + + + + Method + + System.Text.Encoding + 4.0.10.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + [System.Security.SecurityCritical] + [<System.Security.SecurityCritical>] + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + [System.Runtime.InteropServices.ComVisible(false)] + [<System.Runtime.InteropServices.ComVisible(false)>] + + + + System.Int32 + + + + + + + A pointer to the first byte to decode. + The number of bytes to decode. + When overridden in a derived class, calculates the number of characters produced by decoding a sequence of bytes starting at the specified byte pointer. + The number of characters produced by decoding the specified sequence of bytes. + property always returns - Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. - ]]> - - - is . - - is less than zero. + ]]> + + + is . + + is less than zero. A fallback occurred (for more information, see Character Encoding in .NET) -and- - is set to . - - - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - - - The byte array containing the sequence of bytes to decode. - The index of the first byte to decode. - The number of bytes to decode. - When overridden in a derived class, calculates the number of characters produced by decoding a sequence of bytes from the specified byte array. - The number of characters produced by decoding the specified sequence of bytes. - + is set to . + + + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + + + The byte array containing the sequence of bytes to decode. + The index of the first byte to decode. + The number of bytes to decode. + When overridden in a derived class, calculates the number of characters produced by decoding a sequence of bytes from the specified byte array. + The number of characters produced by decoding the specified sequence of bytes. + property always returns :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getcharsic.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetCharsIC/VB/getcharsic.vb" id="Snippet1"::: - ]]> - - - is . - + ]]> + + + is . + or is less than zero. -or- - and do not denote a valid range in . + and do not denote a valid range in . A fallback occurred (for more information, see Character Encoding in .NET) -and- - is set to . - - - - - - - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - When overridden in a derived class, decodes a sequence of bytes into a set of characters. - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Char[] - - - - - - The byte array containing the sequence of bytes to decode. - When overridden in a derived class, decodes all the bytes in the specified byte array into a set of characters. - A character array containing the results of decoding the specified sequence of bytes. - + is set to . + + + + + + + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + When overridden in a derived class, decodes a sequence of bytes into a set of characters. + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Char[] + + + + + + The byte array containing the sequence of bytes to decode. + When overridden in a derived class, decodes all the bytes in the specified byte array into a set of characters. + A character array containing the results of decoding the specified sequence of bytes. + property always returns :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getchars.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/VB/getchars.vb" id="Snippet1"::: - ]]> - - - is . + ]]> + + + is . A fallback occurred (for more information, see Character Encoding in .NET) -and- - is set to . - - - - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.Encoding - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Int32 - - - - - - - A read-only span containing the sequence of bytes to decode. - The character span receiving the decoded bytes. - When overridden in a derived class, decodes all the bytes in the specified read-only byte span into a character span. - The actual number of characters written at the span indicated by the parameter. - + is set to . + + + + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.Encoding + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Int32 + + + + + + + A read-only span containing the sequence of bytes to decode. + The character span receiving the decoded bytes. + When overridden in a derived class, decodes all the bytes in the specified read-only byte span into a character span. + The actual number of characters written at the span indicated by the parameter. + property always returns - Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. - ]]> - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Char[] - - - - - - - - The byte array containing the sequence of bytes to decode. - The index of the first byte to decode. - The number of bytes to decode. - When overridden in a derived class, decodes a sequence of bytes from the specified byte array into a set of characters. - A character array containing the results of decoding the specified sequence of bytes. - + ]]> + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Char[] + + + + + + + + The byte array containing the sequence of bytes to decode. + The index of the first byte to decode. + The number of bytes to decode. + When overridden in a derived class, decodes a sequence of bytes from the specified byte array into a set of characters. + A character array containing the results of decoding the specified sequence of bytes. + property always returns :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getcharsic.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetCharsIC/VB/getcharsic.vb" id="Snippet1"::: - ]]> - - - is . - + ]]> + + + is . + or is less than zero. -or- - and do not denote a valid range in . + and do not denote a valid range in . A fallback occurred (for more information, see Character Encoding in .NET) -and- - is set to . - - - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.10.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - [System.Security.SecurityCritical] - [<System.Security.SecurityCritical>] - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - [System.Runtime.InteropServices.ComVisible(false)] - [<System.Runtime.InteropServices.ComVisible(false)>] - - - - System.Int32 - - - - - - - - - A pointer to the first byte to decode. - The number of bytes to decode. - A pointer to the location at which to start writing the resulting set of characters. - The maximum number of characters to write. - When overridden in a derived class, decodes a sequence of bytes starting at the specified byte pointer into a set of characters that are stored starting at the specified character pointer. - The actual number of characters written at the location indicated by the parameter. - + is set to . + + + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.10.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + [System.Security.SecurityCritical] + [<System.Security.SecurityCritical>] + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + [System.Runtime.InteropServices.ComVisible(false)] + [<System.Runtime.InteropServices.ComVisible(false)>] + + + + System.Int32 + + + + + + + + + A pointer to the first byte to decode. + The number of bytes to decode. + A pointer to the location at which to start writing the resulting set of characters. + The maximum number of characters to write. + When overridden in a derived class, decodes a sequence of bytes starting at the specified byte pointer into a set of characters that are stored starting at the specified character pointer. + The actual number of characters written at the location indicated by the parameter. + property always returns - Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. - ]]> - - + ]]> + + is . -or- - is . - - or is less than zero. - - is less than the resulting number of characters. + is . + + or is less than zero. + + is less than the resulting number of characters. A fallback occurred (for more information, see Character Encoding in .NET) -and- - is set to . - - - - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - - - - - The byte array containing the sequence of bytes to decode. - The index of the first byte to decode. - The number of bytes to decode. - The character array to contain the resulting set of characters. - The index at which to start writing the resulting set of characters. - When overridden in a derived class, decodes a sequence of bytes from the specified byte array into the specified character array. - The actual number of characters written into . - + is set to . + + + + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + + + + + The byte array containing the sequence of bytes to decode. + The index of the first byte to decode. + The number of bytes to decode. + The character array to contain the resulting set of characters. + The index at which to start writing the resulting set of characters. + When overridden in a derived class, decodes a sequence of bytes from the specified byte array into the specified character array. + The actual number of characters written into . + property always returns :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getcharsic.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetCharsIC/VB/getcharsic.vb" id="Snippet1"::: - ]]> - - + ]]> + + is . -or- - is . - + is . + or or is less than zero. -or- @@ -3539,205 +3332,205 @@ On .NET Core, the property always returns -or- - is not a valid index in . - - does not have enough capacity from to the end of the array to accommodate the resulting characters. + is not a valid index in . + + does not have enough capacity from to the end of the array to accommodate the resulting characters. A fallback occurred (for more information, see Character Encoding in .NET) -and- - is set to . - - - - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Decoder - - - - When overridden in a derived class, obtains a decoder that converts an encoded sequence of bytes into a sequence of characters. - A that converts an encoded sequence of bytes into a sequence of characters. - + is set to . + + + + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Decoder + + + + When overridden in a derived class, obtains a decoder that converts an encoded sequence of bytes into a sequence of characters. + A that converts an encoded sequence of bytes into a sequence of characters. + method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method of this class. However, a maintains state information between calls so it correctly decodes byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. - ]]> - - - The default implementation returns a that calls the and methods of the current . You must override this method to return a that maintains its state between calls. - - - - - - - How to use character encoding classes in .NET - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoder - - - - When overridden in a derived class, obtains an encoder that converts a sequence of Unicode characters into an encoded sequence of bytes. - A that converts a sequence of Unicode characters into an encoded sequence of bytes. - + ]]> + + + The default implementation returns a that calls the and methods of the current . You must override this method to return a that maintains its state between calls. + + + + + + + How to use character encoding classes in .NET + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoder + + + + When overridden in a derived class, obtains an encoder that converts a sequence of Unicode characters into an encoded sequence of bytes. + A that converts a sequence of Unicode characters into an encoded sequence of bytes. + method converts sequential blocks of characters into sequential blocks of bytes, in a manner similar to the method of this class. However, a maintains state information between calls so it correctly encodes character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. - ]]> - - - The default implementation returns a that calls the and methods of the current . You must override this method to return a that maintains its state between calls. - - - - - - How to use character encoding classes in .NET - - - - - System.Text.Encoding - 4.0.10.0 - - - Returns an encoding for the specified code page. - - - - - - - - - - Method - - System.Text.Encoding - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Text.Encoding - - - - - + ]]> + + + The default implementation returns a that calls the and methods of the current . You must override this method to return a that maintains its state between calls. + + + + + + How to use character encoding classes in .NET + + + + + System.Text.Encoding + 4.0.10.0 + + + Returns an encoding for the specified code page. + + + + + + + + + + Method + + System.Text.Encoding + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Text.Encoding + + + + + The code page identifier of the preferred encoding. For a list of possible values, see . -or- - 0 (zero), to use the default encoding. - Returns the encoding associated with the specified code page identifier. - The encoding that is associated with the specified code page. - + 0 (zero), to use the default encoding. + Returns the encoding associated with the specified code page identifier. + The encoding that is associated with the specified code page. + - - - is less than zero or greater than 65535. - - is not supported by the underlying platform. - - is not supported by the underlying platform. - - - - - How to use character encoding classes in .NET - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Text.Encoding - - - - - - The code page name of the preferred encoding. Any value returned by the property is valid. For a list of possible values, see . - Returns the encoding associated with the specified code page name. - The encoding associated with the specified code page. - + ]]> + + + is less than zero or greater than 65535. + + is not supported by the underlying platform. + + is not supported by the underlying platform. + + + + + How to use character encoding classes in .NET + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Text.Encoding + + + + + + The code page name of the preferred encoding. Any value returned by the property is valid. For a list of possible values, see . + Returns the encoding associated with the specified code page name. + The encoding associated with the specified code page. + - - + ]]> + + is not a valid code page name. -or- - The code page indicated by is not supported by the underlying platform. - - - - How to use character encoding classes in .NET - - - - - - - - - - Method - - System.Text.Encoding - 4.0.10.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Text.Encoding - - - - - - - + The code page indicated by is not supported by the underlying platform. + + + + How to use character encoding classes in .NET + + + + + + + + + + Method + + System.Text.Encoding + 4.0.10.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Text.Encoding + + + + + + + The code page identifier of the preferred encoding. For a list of possible values, see . -or- - 0 (zero), to use the default encoding. - An object that provides an error-handling procedure when a character cannot be encoded with the current encoding. - An object that provides an error-handling procedure when a byte sequence cannot be decoded with the current encoding. - Returns the encoding associated with the specified code page identifier. Parameters specify an error handler for characters that cannot be encoded and byte sequences that cannot be decoded. - The encoding that is associated with the specified code page. - + 0 (zero), to use the default encoding. + An object that provides an error-handling procedure when a character cannot be encoded with the current encoding. + An object that provides an error-handling procedure when a byte sequence cannot be decoded with the current encoding. + Returns the encoding associated with the specified code page identifier. Parameters specify an error handler for characters that cannot be encoded and byte sequences that cannot be decoded. + The encoding that is associated with the specified code page. + - - - is less than zero or greater than 65535. - - is not supported by the underlying platform. - - is not supported by the underlying platform. - - - - - How to use character encoding classes in .NET - - - - - - - - - - Method - - System.Text.Encoding - 4.0.10.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Text.Encoding - - - - - - - - The code page name of the preferred encoding. Any value returned by the property is valid. Possible values are listed in the Name column of the table that appears in the class topic. - An object that provides an error-handling procedure when a character cannot be encoded with the current encoding. - An object that provides an error-handling procedure when a byte sequence cannot be decoded with the current encoding. - Returns the encoding associated with the specified code page name. Parameters specify an error handler for characters that cannot be encoded and byte sequences that cannot be decoded. - The encoding that is associated with the specified code page. - + ]]> + + + is less than zero or greater than 65535. + + is not supported by the underlying platform. + + is not supported by the underlying platform. + + + + + How to use character encoding classes in .NET + + + + + + + + + + Method + + System.Text.Encoding + 4.0.10.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Text.Encoding + + + + + + + + The code page name of the preferred encoding. Any value returned by the property is valid. Possible values are listed in the Name column of the table that appears in the class topic. + An object that provides an error-handling procedure when a character cannot be encoded with the current encoding. + An object that provides an error-handling procedure when a byte sequence cannot be decoded with the current encoding. + Returns the encoding associated with the specified code page name. Parameters specify an error handler for characters that cannot be encoded and byte sequences that cannot be decoded. + The encoding that is associated with the specified code page. + - - + ]]> + + is not a valid code page name. -or- - The code page indicated by is not supported by the underlying platform. - - - - How to use character encoding classes in .NET - - - - - - - - - - Method - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - System.Text.EncodingInfo[] - - - - Returns an array that contains all encodings. - An array that contains all encodings. - + The code page indicated by is not supported by the underlying platform. + + + + How to use character encoding classes in .NET + + + + + + + + + + Method + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + System.Text.EncodingInfo[] + + + + Returns an array that contains all encodings. + An array that contains all encodings. + - - - How to use character encoding classes in .NET - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - Returns the hash code for the current instance. - The hash code for the current instance. - To be added. - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - The number of characters to encode. - When overridden in a derived class, calculates the maximum number of bytes produced by encoding the specified number of characters. - The maximum number of bytes produced by encoding the specified number of characters. - + ]]> + + + How to use character encoding classes in .NET + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + Returns the hash code for the current instance. + The hash code for the current instance. + To be added. + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + The number of characters to encode. + When overridden in a derived class, calculates the maximum number of bytes produced by encoding the specified number of characters. + The maximum number of bytes produced by encoding the specified number of characters. + - - - is less than zero. + ]]> + + + is less than zero. A fallback occurred (for more information, see Character Encoding in .NET) -and- - is set to . - - All implementations must guarantee that no buffer overflow exceptions occur if buffers are sized according to the results of this method's calculations. - - - - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - The number of bytes to decode. - When overridden in a derived class, calculates the maximum number of characters produced by decoding the specified number of bytes. - The maximum number of characters produced by decoding the specified number of bytes. - + is set to . + + All implementations must guarantee that no buffer overflow exceptions occur if buffers are sized according to the results of this method's calculations. + + + + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + The number of bytes to decode. + When overridden in a derived class, calculates the maximum number of characters produced by decoding the specified number of bytes. + The maximum number of characters produced by decoding the specified number of bytes. + - - - is less than zero. + ]]> + + + is less than zero. A fallback occurred (for more information, see Character Encoding in .NET) -and- - is set to . - - All implementations must guarantee that no buffer overflow exceptions occur if buffers are sized according to the results of this method's calculations. - - - - - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Byte[] - - - - When overridden in a derived class, returns a sequence of bytes that specifies the encoding used. + is set to . + + All implementations must guarantee that no buffer overflow exceptions occur if buffers are sized according to the results of this method's calculations. + + + + + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Byte[] + + + + When overridden in a derived class, returns a sequence of bytes that specifies the encoding used. A byte array containing a sequence of bytes that specifies the encoding used. -or- - A byte array of length zero, if a preamble is not required. - + A byte array of length zero, if a preamble is not required. + - - - - - - System.Text.Encoding - 4.0.10.0 - - - When overridden in a derived class, decodes a sequence of bytes into a string. - - - - - - - - - - Method - - System.Text.Encoding - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.String - - - - - - The byte array containing the sequence of bytes to decode. - When overridden in a derived class, decodes all the bytes in the specified byte array into a string. - A string that contains the results of decoding the specified sequence of bytes. - + ]]> + + + + + + System.Text.Encoding + 4.0.10.0 + + + When overridden in a derived class, decodes a sequence of bytes into a string. + + + + + + + + + + Method + + System.Text.Encoding + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.String + + + + + + The byte array containing the sequence of bytes to decode. + When overridden in a derived class, decodes all the bytes in the specified byte array into a string. + A string that contains the results of decoding the specified sequence of bytes. + - - The byte array contains invalid Unicode code points. - - is . + ]]> + + The byte array contains invalid Unicode code points. + + is . A fallback occurred (for more information, see Character Encoding in .NET) -and- - is set to . - - - - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.Encoding - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.String - - - - - - A read-only byte span to decode to a Unicode string. - When overridden in a derived class, decodes all the bytes in the specified byte span into a string. - A string that contains the decoded bytes from the provided read-only span. - + is set to . + + + + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.Encoding + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.String + + + + + + A read-only byte span to decode to a Unicode string. + When overridden in a derived class, decodes all the bytes in the specified byte span into a string. + A string that contains the decoded bytes from the provided read-only span. + method for a particular implementation depends on the fallback strategy defined for that object. For more information, see the "Choosing a Fallback Strategy" section of the [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding) topic. - ]]> - - - - - - - - - - Method - - System.Text.Encoding - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - [System.Security.SecurityCritical] - [<System.Security.SecurityCritical>] - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - [System.Runtime.InteropServices.ComVisible(false)] - [<System.Runtime.InteropServices.ComVisible(false)>] - - - - System.String - - - - - - - A pointer to a byte array. - The number of bytes to decode. - When overridden in a derived class, decodes a specified number of bytes starting at a specified address into a string. - A string that contains the results of decoding the specified sequence of bytes. - + ]]> + + + + + + + + + + Method + + System.Text.Encoding + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + [System.Security.SecurityCritical] + [<System.Security.SecurityCritical>] + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + [System.Runtime.InteropServices.ComVisible(false)] + [<System.Runtime.InteropServices.ComVisible(false)>] + + + + System.String + + + + + + + A pointer to a byte array. + The number of bytes to decode. + When overridden in a derived class, decodes a specified number of bytes starting at a specified address into a string. + A string that contains the results of decoding the specified sequence of bytes. + method for a particular implementation depends on the fallback strategy defined for that object. For more information, see the "Choosing a Fallback Strategy" section of the [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding) topic. - ]]> - - - is a null pointer. - - is less than zero. + ]]> + + + is a null pointer. + + is less than zero. A fallback occurred (see Character Encoding in .NET) for a complete explanation) -and- - is set to . - - - - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.String - - - - - - - - The byte array containing the sequence of bytes to decode. - The index of the first byte to decode. - The number of bytes to decode. - When overridden in a derived class, decodes a sequence of bytes from the specified byte array into a string. - A string that contains the results of decoding the specified sequence of bytes. - + is set to . + + + + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.String + + + + + + + + The byte array containing the sequence of bytes to decode. + The index of the first byte to decode. + The number of bytes to decode. + When overridden in a derived class, decodes a sequence of bytes from the specified byte array into a string. + A string that contains the results of decoding the specified sequence of bytes. + - - The byte array contains invalid Unicode code points. - - is . - + ]]> + + The byte array contains invalid Unicode code points. + + is . + or is less than zero. -or- - and do not denote a valid range in . + and do not denote a valid range in . A fallback occurred (for more information, see Character Encoding in .NET) -and- - is set to . - - - - - - - - - - - - - - Property - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - System.String - - - When overridden in a derived class, gets a name for the current encoding that can be used with mail agent header tags. + is set to . + + + + + + + + + + + + + + Property + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + System.String + + + When overridden in a derived class, gets a name for the current encoding that can be used with mail agent header tags. A name for the current to use with mail agent header tags. -or- - An empty string (""), if the current cannot be used. - + An empty string (""), if the current cannot be used. + - - - - - - - - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - Gets a value indicating whether the current encoding is always normalized. - - - - - - - - - - Method - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - - [System.Runtime.InteropServices.ComVisible(false)] - [<System.Runtime.InteropServices.ComVisible(false)>] - - - - System.Boolean - - - - Gets a value indicating whether the current encoding is always normalized, using the default normalization form. - - if the current is always normalized; otherwise, . The default is . - + ]]> + + + + + + + + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + Gets a value indicating whether the current encoding is always normalized. + + + + + + + + + + Method + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + + [System.Runtime.InteropServices.ComVisible(false)] + [<System.Runtime.InteropServices.ComVisible(false)>] + + + + System.Boolean + + + + Gets a value indicating whether the current encoding is always normalized, using the default normalization form. + + if the current is always normalized; otherwise, . The default is . + , which uses full canonical decomposition, followed by the replacement of sequences with their primary composites, if possible. - ]]> - - - - - - - - - - - - Method - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - - [System.Runtime.InteropServices.ComVisible(false)] - [<System.Runtime.InteropServices.ComVisible(false)>] - - - - System.Boolean - - - - - - One of the values. - When overridden in a derived class, gets a value indicating whether the current encoding is always normalized, using the specified normalization form. - - if the current object is always normalized using the specified value; otherwise, . The default is . - + ]]> + + + + + + + + + + + + Method + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + + [System.Runtime.InteropServices.ComVisible(false)] + [<System.Runtime.InteropServices.ComVisible(false)>] + + + + System.Boolean + + + + + + One of the values. + When overridden in a derived class, gets a value indicating whether the current encoding is always normalized, using the specified normalization form. + + if the current object is always normalized using the specified value; otherwise, . The default is . + , which uses full canonical decomposition, followed by the replacement of sequences with their primary composites, if possible. - ]]> - - - - - - - - - - - - Property - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - System.Boolean - - - When overridden in a derived class, gets a value indicating whether the current encoding can be used by browser clients for displaying content. - - if the current can be used by browser clients for displaying content; otherwise, . - + ]]> + + + + + + + + + + + + Property + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + System.Boolean + + + When overridden in a derived class, gets a value indicating whether the current encoding can be used by browser clients for displaying content. + + if the current can be used by browser clients for displaying content; otherwise, . + - - - - - - - - - - - - Property - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - System.Boolean - - - When overridden in a derived class, gets a value indicating whether the current encoding can be used by browser clients for saving content. - - if the current can be used by browser clients for saving content; otherwise, . - + ]]> + + + + + + + + + + + + Property + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + System.Boolean + + + When overridden in a derived class, gets a value indicating whether the current encoding can be used by browser clients for saving content. + + if the current can be used by browser clients for saving content; otherwise, . + - - - - - - - - - - - - Property - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - System.Boolean - - - When overridden in a derived class, gets a value indicating whether the current encoding can be used by mail and news clients for displaying content. - - if the current can be used by mail and news clients for displaying content; otherwise, . - + ]]> + + + + + + + + + + + + Property + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + System.Boolean + + + When overridden in a derived class, gets a value indicating whether the current encoding can be used by mail and news clients for displaying content. + + if the current can be used by mail and news clients for displaying content; otherwise, . + - - - - - - - - - - - - Property - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - System.Boolean - - - When overridden in a derived class, gets a value indicating whether the current encoding can be used by mail and news clients for saving content. - - if the current can be used by mail and news clients for saving content; otherwise, . - + ]]> + + + + + + + + + + + + Property + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + System.Boolean + + + When overridden in a derived class, gets a value indicating whether the current encoding can be used by mail and news clients for saving content. + + if the current can be used by mail and news clients for saving content; otherwise, . + - - - - - - - - - - - - Property - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - - [System.Runtime.InteropServices.ComVisible(false)] - [<System.Runtime.InteropServices.ComVisible(false)>] - - - - System.Boolean - - - When overridden in a derived class, gets a value indicating whether the current encoding is read-only. - - if the current is read-only; otherwise, . The default is . - To be added. - - - - - - - - - - Property - - System.Text.Encoding - 4.0.10.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.InteropServices.ComVisible(false)] - [<System.Runtime.InteropServices.ComVisible(false)>] - - - - System.Boolean - - - When overridden in a derived class, gets a value indicating whether the current encoding uses single-byte code points. - - if the current uses single-byte code points; otherwise, . - + ]]> + + + + + + + + + + + + Property + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + + [System.Runtime.InteropServices.ComVisible(false)] + [<System.Runtime.InteropServices.ComVisible(false)>] + + + + System.Boolean + + + When overridden in a derived class, gets a value indicating whether the current encoding is read-only. + + if the current is read-only; otherwise, . The default is . + To be added. + + + + + + + + + + Property + + System.Text.Encoding + 4.0.10.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.InteropServices.ComVisible(false)] + [<System.Runtime.InteropServices.ComVisible(false)>] + + + + System.Boolean + + + When overridden in a derived class, gets a value indicating whether the current encoding uses single-byte code points. + + if the current uses single-byte code points; otherwise, . + - - - - - - - - - - - Property - - System.Runtime - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - mscorlib - - - netstandard - - - System.Text.Encoding - - - Gets an encoding for the Latin1 character set (ISO-8859-1). - To be added. - To be added. - - - - - - - - - - Property - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.Encoding - - - - [System.Runtime.CompilerServices.Nullable(0)] - [<System.Runtime.CompilerServices.Nullable(0)>] - - - [get: System.Runtime.CompilerServices.NullableContext(0)] - [<get: System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.ReadOnlySpan<System.Byte> - - - When overridden in a derived class, returns a span containing the sequence of bytes that specifies the encoding used. - A byte span containing a sequence of bytes that specifies the encoding used, or a span of length zero, if a preamble is not required. - + ]]> + + + + + + + + + + + Property + + System.Runtime + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + mscorlib + + + netstandard + + + System.Text.Encoding + + + Gets an encoding for the Latin1 character set (ISO-8859-1). + To be added. + To be added. + + + + + + + + + + Property + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.Encoding + + + + [System.Runtime.CompilerServices.Nullable(0)] + [<System.Runtime.CompilerServices.Nullable(0)>] + + + [get: System.Runtime.CompilerServices.NullableContext(0)] + [<get: System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.ReadOnlySpan<System.Byte> + + + When overridden in a derived class, returns a span containing the sequence of bytes that specifies the encoding used. + A byte span containing a sequence of bytes that specifies the encoding used, or a span of length zero, if a preamble is not required. + [!CAUTION] > To ensure that the encoded bytes are decoded properly, you should prefix encoded bytes with a preamble. However, most encodings do not provide a preamble. To ensure that the encoded bytes are decoded properly, you should use a Unicode encoding, that is, , , or , with a preamble. - ]]> - - - - - - - - - - - Method - - System.Text.Encoding - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Security.SecurityCritical] - [<System.Security.SecurityCritical>] - - - - System.Void - - - - - - A subclass of that provides access to additional character encodings. - Registers an encoding provider. - + ]]> + + + + + + + + + + + Method + + System.Text.Encoding + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Security.SecurityCritical] + [<System.Security.SecurityCritical>] + + + + System.Void + + + + + + A subclass of that provides access to additional character encodings. + Registers an encoding provider. + method is called to register multiple providers that handle the same encoding, the last registered provider is the used for all encoding and decoding operations. Any previously registered providers are ignored. - ]]> - - - is . - - - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Text.Encoding - - - mscorlib - - - netstandard - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Boolean - - - - - - - - The span containing the set of characters to encode. - The byte span to hold the encoded bytes. - Upon successful completion of the operation, the number of bytes encoded into . - Encodes into a span of bytes a set of characters from the specified read-only span if the destination is large enough. - - if all of the characters were encoded into the destination; if the destination was too small to contain all the encoded bytes. - To be added. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Text.Encoding - - - mscorlib - - - netstandard - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Boolean - - - - - - - - A read-only span containing the sequence of bytes to decode. - The character span receiving the decoded bytes. - Upon successful completion of the operation, the number of chars decoded into . - Decodes into a span of chars a set of bytes from the specified read-only span if the destination is large enough. - - if all of the characters were decoded into the destination; if the destination was too small to contain all the decoded chars. - To be added. - - - - - - - - - - Property - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Text.Encoding - - - Gets an encoding for the UTF-16 format using the little endian byte order. - An encoding for the UTF-16 format using the little endian byte order. - + ]]> + + + is . + + + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Text.Encoding + + + mscorlib + + + netstandard + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Boolean + + + + + + + + The span containing the set of characters to encode. + The byte span to hold the encoded bytes. + Upon successful completion of the operation, the number of bytes encoded into . + Encodes into a span of bytes a set of characters from the specified read-only span if the destination is large enough. + + if all of the characters were encoded into the destination; if the destination was too small to contain all the encoded bytes. + To be added. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Text.Encoding + + + mscorlib + + + netstandard + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Boolean + + + + + + + + A read-only span containing the sequence of bytes to decode. + The character span receiving the decoded bytes. + Upon successful completion of the operation, the number of chars decoded into . + Decodes into a span of chars a set of bytes from the specified read-only span if the destination is large enough. + + if all of the characters were decoded into the destination; if the destination was too small to contain all the decoded chars. + To be added. + + + + + + + + + + Property + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Text.Encoding + + + Gets an encoding for the UTF-16 format using the little endian byte order. + An encoding for the UTF-16 format using the little endian byte order. + - - - - - How to use character encoding classes in .NET - - - - - - - - - - Property - - System.Text.Encoding - 4.0.10.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - Gets an encoding for the UTF-32 format using the little endian byte order. - An encoding object for the UTF-32 format using the little endian byte order. - + ]]> + + + + + How to use character encoding classes in .NET + + + + + + + + + + Property + + System.Text.Encoding + 4.0.10.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + Gets an encoding for the UTF-32 format using the little endian byte order. + An encoding object for the UTF-32 format using the little endian byte order. + - - - - - - How to use character encoding classes in .NET - - - - - - - - - - Property - - System.Text.Encoding - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Obsolete("The UTF-7 encoding is insecure and should not be used. Consider using UTF-8 instead.", DiagnosticId="SYSLIB0001", UrlFormat="https://aka.ms/dotnet-warnings/{0}")] - [<System.Obsolete("The UTF-7 encoding is insecure and should not be used. Consider using UTF-8 instead.", DiagnosticId="SYSLIB0001", UrlFormat="https://aka.ms/dotnet-warnings/{0}")>] - - - - System.Text.Encoding - - - Gets an encoding for the UTF-7 format. - An encoding for the UTF-7 format. - + ]]> + + + + + + How to use character encoding classes in .NET + + + + + + + + + + Property + + System.Text.Encoding + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Obsolete("The UTF-7 encoding is insecure and should not be used. Consider using UTF-8 instead.", DiagnosticId="SYSLIB0001", UrlFormat="https://aka.ms/dotnet-warnings/{0}")] + [<System.Obsolete("The UTF-7 encoding is insecure and should not be used. Consider using UTF-8 instead.", DiagnosticId="SYSLIB0001", UrlFormat="https://aka.ms/dotnet-warnings/{0}")>] + + + + System.Text.Encoding + + + Gets an encoding for the UTF-7 format. + An encoding for the UTF-7 format. + - - - - How to use character encoding classes in .NET - - - - - - - - - - Property - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Text.Encoding - - - Gets an encoding for the UTF-8 format. - An encoding for the UTF-8 format. - + ]]> + + + + How to use character encoding classes in .NET + + + + + + + + + + Property + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Text.Encoding + + + Gets an encoding for the UTF-8 format. + An encoding for the UTF-8 format. + - - - - How to use character encoding classes in .NET - - - - - - - - - - Property - - System.Text.Encoding - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - [get: System.Security.SecuritySafeCritical] - [<get: System.Security.SecuritySafeCritical>] - - - - System.String - - - When overridden in a derived class, gets the name registered with the Internet Assigned Numbers Authority (IANA) for the current encoding. - The IANA name for the current . - + ]]> + + + + How to use character encoding classes in .NET + + + + + + + + + + Property + + System.Text.Encoding + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + [get: System.Security.SecuritySafeCritical] + [<get: System.Security.SecuritySafeCritical>] + + + + System.String + + + When overridden in a derived class, gets the name registered with the Internet Assigned Numbers Authority (IANA) for the current encoding. + The IANA name for the current . + - - - - - - - - - - - - - - - Property - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Encoding - - - System.Int32 - - - When overridden in a derived class, gets the Windows operating system code page that most closely corresponds to the current encoding. - The Windows operating system code page that most closely corresponds to the current . - + ]]> + + + + + + + + + + + + + + + Property + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Encoding + + + System.Int32 + + + When overridden in a derived class, gets the Windows operating system code page that most closely corresponds to the current encoding. + The Windows operating system code page that most closely corresponds to the current . + - - - - - - - + ]]> + + + + + + + diff --git a/xml/System.Text/Rune.xml b/xml/System.Text/Rune.xml index 75aa37a309e..dcbbc8522a2 100644 --- a/xml/System.Text/Rune.xml +++ b/xml/System.Text/Rune.xml @@ -1,1002 +1,799 @@ - - - - - - - - - - - - - - - - - - - - - - - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.ValueType - - - - System.IComparable - - - System.IComparable<System.Text.Rune> - - - System.IEquatable<System.Text.Rune> - - - System.IFormattable - - - System.ISpanFormattable - - - System.IUtf8SpanFormattable - - - - - [System.Runtime.CompilerServices.IsReadOnly] - [<System.Runtime.CompilerServices.IsReadOnly>] - - - - Represents a Unicode scalar value ([ U+0000..U+D7FF ], inclusive; or [ U+E000..U+10FFFF ], inclusive). - - instance represents a Unicode scalar value, which means any code point excluding the surrogate range (U+D800..U+DFFF). The type's constructors and conversion operators validate the input, so consumers can call the APIs assuming that the underlying instance is well formed. - -If you aren't familiar with the terms Unicode scalar value, code point, surrogate range, and well-formed, see [Introduction to character encoding in .NET](/dotnet/standard/base-types/character-encoding-introduction). - -The following sections explain: - -* [When to use the Rune type](#when-to-use-the-rune-type) -* [When not to use the Rune type](#when-not-to-use-rune) -* [How to instantiate a Rune](#how-to-instantiate-a-rune) -* [How to query properties of a Rune instance](#query-properties-of-a-rune) -* [Convert a `Rune` to UTF-8 or UTF-16](#convert-a-rune-to-utf-8-or-utf-16) -* [Rune in .NET vs. other languages](#rune-in-net-vs-other-languages) - -### When to use the Rune type - -Consider using the `Rune` type if your code: - -* Calls APIs that require Unicode scalar values -* Explicitly handles surrogate pairs - -#### APIs that require Unicode scalar values - -If your code iterates through the `char` instances in a `string` or a `ReadOnlySpan`, some of the `char` methods won't work correctly on `char` instances that are in the surrogate range. For example, the following APIs require a scalar value `char` to work correctly: - -* -* -* -* -* -* -* -* -* -* - -The following example shows code that won't work correctly if any of the `char` instances are surrogate code points: - -:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/CountLettersInString.cs" id="SnippetBadExample"::: -:::code language="fsharp" source="~/snippets/fsharp/System.Text/Rune/Overview/CountLettersInString.fs" id="SnippetBadExample"::: - -Here's equivalent code that works with a `ReadOnlySpan`: - -:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/CountLettersInSpan.cs" id="SnippetBadExample"::: - -The preceding code works correctly with some languages such as English: - -```csharp -CountLettersInString("Hello") -// Returns 5 -``` - -But it won't work correctly for languages outside the Basic Multilingual Plane, such as Osage: - -```csharp -CountLettersInString("𐓏𐓘𐓻𐓘𐓻𐓟 𐒻𐓟") -// Returns 0 -``` - -The reason this method returns incorrect results for Osage text is that the `char` instances for Osage letters are surrogate code points. No single surrogate code point has enough information to determine if it's a letter. - -If you change this code to use `Rune` instead of `char`, the method works correctly with code points outside the Basic Multilingual Plane: - -:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/CountLettersInString.cs" id="SnippetGoodExample"::: -:::code language="fsharp" source="~/snippets/fsharp/System.Text/Rune/Overview/CountLettersInString.fs" id="SnippetGoodExample"::: - -Here's equivalent code that works with a `ReadOnlySpan`: - -:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/CountLettersInSpan.cs" id="SnippetGoodExample"::: - -The preceding code counts Osage letters correctly: - -```csharp -CountLettersInString("𐓏𐓘𐓻𐓘𐓻𐓟 𐒻𐓟") -// Returns 8 -``` - -#### Code that explicitly handles surrogate pairs - -Consider using the `Rune` type if your code calls APIs that explicitly operate on surrogate code points, such as the following methods: - -* -* -* -* -* -* - -For example, the following method has special logic to deal with surrogate `char` pairs: - -:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/WorkWithSurrogates.cs" id="SnippetUseChar"::: - -Such code is simpler if it uses `Rune`, as in the following example: - -:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/WorkWithSurrogates.cs" id="SnippetUseRune"::: - -### When not to use `Rune` - -You don't need to use the `Rune` type if your code: - -* Looks for exact `char` matches -* Splits a string on a known char value - -Using the `Rune` type may return incorrect results if your code: - -* Counts the number of display characters in a `string` - -#### Look for exact `char` matches - -The following code iterates through a `string` looking for specific characters, returning the index of the first match. There's no need to change this code to use `Rune`, as the code is looking for characters that are represented by a single `char`. - -:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/FindFirstLetter.cs" id="SnippetExample"::: - -#### Split a string on a known `char` - -It's common to call `string.Split` and use delimiters such as `' '` (space) or `','` (comma), as in the following example: - -:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/SplitStringOnChar.cs" id="SnippetExample"::: - -There is no need to use `Rune` here, because the code is looking for characters that are represented by a single `char`. - -#### Count the number of display characters in a `string` - -The number of `Rune` instances in a string might not match the number of user-perceivable characters shown when displaying the string. - -Since `Rune` instances represent Unicode scalar values, components that follow the [Unicode text segmentation guidelines](https://www.unicode.org/reports/tr29/) can use `Rune` as a building block for counting display characters. - -The type can be used to count display characters, but it doesn't count correctly in all scenarios for .NET implementations other than .NET 5+. - -For more information, see [Grapheme clusters](/dotnet/standard/base-types/character-encoding-introduction#grapheme-clusters). - -### How to instantiate a `Rune` - -There are several ways to get a `Rune` instance. You can use a constructor to create a `Rune` directly from: - -* A code point. - - :::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/InstantiateRunes.cs" id="SnippetCodePoint"::: - -* A single `char`. - - :::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/InstantiateRunes.cs" id="SnippetChar"::: - -* A surrogate `char` pair. - - :::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/InstantiateRunes.cs" id="SnippetSurrogate"::: - -All of the constructors throw an `ArgumentException` if the input doesn't represent a valid Unicode scalar value. - -There are methods available for callers who don't want exceptions to be thrown on failure. - -`Rune` instances can also be read from existing input sequences. For instance, given a `ReadOnlySpan` that represents UTF-16 data, the method returns the first `Rune` instance at the beginning of the input span. The method operates similarly, accepting a `ReadOnlySpan` parameter that represents UTF-8 data. There are equivalent methods to read from the end of the span instead of the beginning of the span. - -### Query properties of a `Rune` - -To get the integer code point value of a `Rune` instance, use the property. - -:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/InstantiateRunes.cs" id="SnippetValue"::: - -Many of the static APIs available on the `char` type are also available on the `Rune` type. For instance, and are equivalents to and methods. The `Rune` methods correctly handle surrogate pairs. - -The following example code takes a `ReadOnlySpan` as input and trims from both the start and the end of the span every `Rune` that isn't a letter or a digit. - -:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/TrimNonLettersAndNonDigits.cs" id="SnippetExample"::: - -There are some API differences between `char` and `Rune`. For example: - -* There is no `Rune` equivalent to , since `Rune` instances by definition can never be surrogate code points. -* The doesn't always return the same result as . It does return the same value as . For more information, see the **Remarks** on . - -### Convert a `Rune` to UTF-8 or UTF-16 - -Since a `Rune` is a Unicode scalar value, it can be converted to UTF-8, UTF-16, or UTF-32 encoding. The `Rune` type has built-in support for conversion to UTF-8 and UTF-16. - -The converts a `Rune` instance to `char` instances. To query the number of `char` instances that would result from converting a `Rune` instance to UTF-16, use the property. Similar methods exist for UTF-8 conversion. - -The following example converts a `Rune` instance to a `char` array. The code assumes you have a `Rune` instance in the `rune` variable: - -:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/EncodeRune.cs" id="SnippetUtf16CharArray"::: - -Since a `string` is a sequence of UTF-16 chars, the following example also converts a `Rune` instance to UTF-16: - -:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/EncodeRune.cs" id="SnippetUtf16String"::: - -The following example converts a `Rune` instance to a `UTF-8` byte array: - -:::code language="csharp" source="~/snippets/csharp/System.Text/Rune/Overview/EncodeRune.cs" id="SnippetUtf8ByteArray"::: - -The and methods return the actual number of elements written. They throw an exception if the destination buffer is too short to contain the result. There are non-throwing and methods as well for callers who want to avoid exceptions. - -### Rune in .NET vs. other languages - -The term "rune" is not defined in the Unicode Standard. The term dates back to [the creation of UTF-8](https://www.cl.cam.ac.uk/~mgk25/ucs/utf-8-history.txt). Rob Pike and Ken Thompson were looking for a term to describe what would eventually become known as a code point. [They settled on the term "rune"](https://twitter.com/rob_pike/status/732353233474064384), and Rob Pike's later influence over the Go programming language helped popularize the term. - -However, the .NET `Rune` type is not the equivalent of the Go `rune` type. In Go, the `rune` type is an [alias for `int32`](https://blog.golang.org/strings). A Go rune is intended to represent a Unicode code point, but it can be any 32-bit value, including surrogate code points and values that are not legal Unicode code points. - -For similar types in other programming languages, see [Rust's primitive `char` type](https://doc.rust-lang.org/std/primitive.char.html) or [Swift's `Unicode.Scalar` type](https://developer.apple.com/documentation/swift/unicode/scalar), both of which represent Unicode scalar values. They provide functionality similar to .NET's `Rune` type, and they disallow instantiation of values that are not legal Unicode scalar values. - - ]]> - - - - - - - - - - - Constructor - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - - - A UTF-16 code unit. - Creates a from the provided UTF-16 code unit. - To be added. - - represents a UTF-16 surrogate code point (U+D800..U+DFFF, inclusive). - - - - - - - - - - Constructor - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - - - A Unicode scalar value. - Creates a from the specified 32-bit integer that represents a Unicode scalar value. - To be added. - - does not represent a Unicode scalar value. - - - - - - - - - - Constructor - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - - - - - A Unicode scalar value. - Creates a from the specified 32-bit unsigned integer that represents a Unicode scalar value. - To be added. - - does not represent a Unicode scalar value. - - - - - - - - - - Constructor - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - - - - The high surrogate of the surrogate pair. - The low surrogate of the surrogate pair. - Creates a from the provided UTF-16 surrogate pair. - To be added. - + + + + + + + + + + + + + + + + + + + + + + + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.ValueType + + + + System.IComparable + + + System.IComparable<System.Text.Rune> + + + System.IEquatable<System.Text.Rune> + + + System.IFormattable + + + System.ISpanFormattable + + + System.IUtf8SpanFormattable + + + + + [System.Runtime.CompilerServices.IsReadOnly] + [<System.Runtime.CompilerServices.IsReadOnly>] + + + + Represents a Unicode scalar value ([ U+0000..U+D7FF ], inclusive; or [ U+E000..U+10FFFF ], inclusive). + For more information about this API, see Supplemental API remarks for Rune. + + + + + + + + + + Constructor + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + + + A UTF-16 code unit. + Creates a from the provided UTF-16 code unit. + To be added. + + represents a UTF-16 surrogate code point (U+D800..U+DFFF, inclusive). + + + + + + + + + + Constructor + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + + + A Unicode scalar value. + Creates a from the specified 32-bit integer that represents a Unicode scalar value. + To be added. + + does not represent a Unicode scalar value. + + + + + + + + + + Constructor + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + + + + + A Unicode scalar value. + Creates a from the specified 32-bit unsigned integer that represents a Unicode scalar value. + To be added. + + does not represent a Unicode scalar value. + + + + + + + + + + Constructor + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + + + + The high surrogate of the surrogate pair. + The low surrogate of the surrogate pair. + Creates a from the provided UTF-16 surrogate pair. + To be added. + does not represent a UTF-16 high surrogate code point. - + -or- - does not represent a UTF-16 low surrogate code point. - - - - - - - - - - Method - - M:System.IComparable`1.CompareTo(`0) - - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - The instance to compare with the current instance. - Compares the current instance to the specified instance. - A signed integer indicating the position of this instance in the sort order in relation to :
- Less than zero: This instance precedes . + does not represent a UTF-16 low surrogate code point. + + + + + + + + + + Method + + M:System.IComparable`1.CompareTo(`0) + + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + The instance to compare with the current instance. + Compares the current instance to the specified instance. + A signed integer indicating the position of this instance in the sort order in relation to :
- Less than zero: This instance precedes .
- Zero: The instance has the same position in the sort order as . -
- Greater than zero: This instance follows . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Buffers.OperationStatus - - - - - - - - A read-only UTF-16 character span. - When this method returns, the decoded rune. - When this method returns, the number of characters read to create the rune. - Decodes the at the beginning of the provided UTF-16 source buffer. - +
- Greater than zero: This instance follows . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Buffers.OperationStatus + + + + + + + + A read-only UTF-16 character span. + When this method returns, the decoded rune. + When this method returns, the number of characters read to create the rune. + Decodes the at the beginning of the provided UTF-16 source buffer. + if the source buffer begins with a valid UTF-16 encoded scalar value. then contains the decoded , and contains the number of values used in the input buffer to encode the . - + if the source buffer is empty or contains only a standalone UTF-16 high surrogate character. then contains , and contains the length of the input buffer. - + if the source buffer begins with an ill-formed UTF-16 encoded scalar value. then contains , and contains the number of values used to encode the ill-formed sequence. - . - + . + if the data was not successfully decoded. This pattern provides convenient automatic U+FFFD substitution of invalid sequences while iterating through the loop. - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Buffers.OperationStatus - - - - - - - - A read-only UTF-8 encoded byte span. - When this method returns, the decoded rune. - When this method returns, the number of bytes read to create the rune. - Decodes the at the beginning of the provided UTF-8 source buffer. - + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Buffers.OperationStatus + + + + + + + + A read-only UTF-8 encoded byte span. + When this method returns, the decoded rune. + When this method returns, the number of bytes read to create the rune. + Decodes the at the beginning of the provided UTF-8 source buffer. + if the source buffer begins with a valid UTF-8 encoded scalar value. then contains the decoded , and contains the number of values used in the input buffer to encode the . - + if the source buffer is empty or contains only a standalone UTF-8 high surrogate character. then contains , and contains the length of the input buffer. - + if the source buffer begins with an ill-formed UTF-8 encoded scalar value. then contains , and contains the number of values used in the input buffer to encode the ill-formed sequence. - . - + . + if the data could not be successfully decoded. This pattern provides convenient automatic U+FFFD substitution of invalid sequences while iterating through the loop. - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Buffers.OperationStatus - - - - - - - - A read-only UTF-16 encoded character span. - When this method returns, the decoded rune. - When this method returns, the number of bytes read to create the rune. - Decodes the at the end of the provided UTF-16 source buffer. - + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Buffers.OperationStatus + + + + + + + + A read-only UTF-16 encoded character span. + When this method returns, the decoded rune. + When this method returns, the number of bytes read to create the rune. + Decodes the at the end of the provided UTF-16 source buffer. + if the source buffer begins with a valid UTF-16 encoded scalar value. then contains the decoded , and contains the number of values used in the input buffer to encode the . - + if the source buffer is empty or contains only a standalone UTF-16 high surrogate character. then contains , and contains the length of the input buffer. - + if the source buffer begins with an ill-formed UTF-16 encoded scalar value. then contains , and contains the number of values used to encode the ill-formed sequence. - . - + . + , except it allows the caller to loop backward instead of forward. The typical calling convention is that on each iteration of the loop, the caller should slice off the final `charsConsumed` elements of the `source` buffer. - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Buffers.OperationStatus - - - - - - - - A read-only UTF-8 encoded byte span. - When this method returns, the decoded rune. - When this method returns, the number of bytes read to create the rune. - Decodes the at the end of the provided UTF-8 source buffer. - + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Buffers.OperationStatus + + + + + + + + A read-only UTF-8 encoded byte span. + When this method returns, the decoded rune. + When this method returns, the number of bytes read to create the rune. + Decodes the at the end of the provided UTF-8 source buffer. + if the source buffer ends with a valid UTF-8 encoded scalar value. then contains the decoded , and contains the number of values used in the input buffer to encode the . - + if the source buffer is empty or contains only a standalone UTF-8 high surrogate character. then contains , and contains the length of the input buffer. - + if the source buffer ends with an ill-formed UTF-8 encoded scalar value. then contains , and contains the number of values used in the input buffer to encode the ill-formed sequence. - - + + , except it allows the caller to loop backward instead of forward. The typical calling convention is that on each iteration of the loop, the caller should slice off the final `bytesConsumed` elements of the `source` buffer. - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - The buffer to which to write this value as UTF-16. - Encodes this to a UTF-16 destination buffer. - The number of values written to . - To be added. - - is not large enough to hold the output. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - The buffer to which to write this value as UTF-8. - Encodes this to a UTF-8 destination buffer. - The number of values written to . - To be added. - - is not large enough to hold the output. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - - System.Boolean - - - - - - [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] - [<System.Diagnostics.CodeAnalysis.NotNullWhen(true)>] - - - - - - The object to compare with the current instance. - Returns a value that indicates whether the current instance and a specified object are equal. - - if is of type and is equal to the current instance; otherwise, . - To be added. - - - - - - - - - - Method - - M:System.IEquatable`1.Equals(`0) - - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - The object to compare with the current instance. - Returns a value that indicates whether the current instance and a specified rune are equal. - - if the current instance and are equal; otherwise, . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - Returns the hash code for this instance. - The hash code for this instance. - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Double - - - - - - The rune for which to get the numeric value. - Gets the numeric value associated with the specified rune. - The numeric value associated with , or -1 if doesn't represent a numeric character. - + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + The buffer to which to write this value as UTF-16. + Encodes this to a UTF-16 destination buffer. + The number of values written to . + To be added. + + is not large enough to hold the output. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + The buffer to which to write this value as UTF-8. + Encodes this to a UTF-8 destination buffer. + The number of values written to . + To be added. + + is not large enough to hold the output. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + + System.Boolean + + + + + + [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] + [<System.Diagnostics.CodeAnalysis.NotNullWhen(true)>] + + + + + + The object to compare with the current instance. + Returns a value that indicates whether the current instance and a specified object are equal. + + if is of type and is equal to the current instance; otherwise, . + To be added. + + + + + + + + + + Method + + M:System.IEquatable`1.Equals(`0) + + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + The object to compare with the current instance. + Returns a value that indicates whether the current instance and a specified rune are equal. + + if the current instance and are equal; otherwise, . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + Returns the hash code for this instance. + The hash code for this instance. + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Double + + + + + + The rune for which to get the numeric value. + Gets the numeric value associated with the specified rune. + The numeric value associated with , or -1 if doesn't represent a numeric character. + . Refer to that documentation for more information. - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.Text.Rune - - - - - - - The string from which to create the rune. - The starting position in at which to create the rune. - Gets the that begins at a specified position in a string. - The rune obtained from at the specified . - + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.Text.Rune + + + + + + + The string from which to create the rune. + The starting position in at which to create the rune. + Gets the that begins at a specified position in a string. + The rune obtained from at the specified . + - - - is . - - does not reference the start of a valid scalar value in . - - is outside the range of . - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Globalization.UnicodeCategory - - - - - - The rune for which to get the Unicode category. - Gets the Unicode category associated with the specified rune. - The Unicode category associated with . - + ]]> + + + is . + + does not reference the start of a valid scalar value in . + + is outside the range of . + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Globalization.UnicodeCategory + + + + + + The rune for which to get the Unicode category. + Gets the Unicode category associated with the specified rune. + The Unicode category associated with . + . Refer to that documentation for more information. - ]]> - - - - - - - - - - - Property - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - Gets a value that indicates whether the scalar value associated with this is within the ASCII encoding range. - - if the scalar value associated is within the ASCII encoding range ([ U+0000..U+007F ]) and therefore representable by a single UTF-8 code unit; otherwise, . - To be added. - - - - - - - - - - Property - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - Gets a value that indicates whether the scalar value associated with this is within the BMP encoding range. - - if the scalar value associated is within the BMP encoding range ([ U+0000..U+FFFF ]) and therefore representable by a single UTF-16 code unit; otherwise, . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - The rune to evaluate. - Returns a value that indicates whether the specified rune is categorized as a control character. - - if is a control character; otherwise, . - + ]]> + + + + + + + + + + + Property + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + Gets a value that indicates whether the scalar value associated with this is within the ASCII encoding range. + + if the scalar value associated is within the ASCII encoding range ([ U+0000..U+007F ]) and therefore representable by a single UTF-8 code unit; otherwise, . + To be added. + + + + + + + + + + Property + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + Gets a value that indicates whether the scalar value associated with this is within the BMP encoding range. + + if the scalar value associated is within the BMP encoding range ([ U+0000..U+FFFF ]) and therefore representable by a single UTF-16 code unit; otherwise, . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + The rune to evaluate. + Returns a value that indicates whether the specified rune is categorized as a control character. + + if is a control character; otherwise, . + . - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - The rune to evaluate. - Returns a value that indicates whether the specified rune is categorized as a decimal digit. - - if is a decimal digit; otherwise, . - + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + The rune to evaluate. + Returns a value that indicates whether the specified rune is categorized as a decimal digit. + + if is a decimal digit; otherwise, . + . - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - The rune to evaluate. - Returns a value that indicates whether the specified rune is categorized as a letter. - - if is a letter; otherwise, . - + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + The rune to evaluate. + Returns a value that indicates whether the specified rune is categorized as a letter. + + if is a letter; otherwise, . + . - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - The rune to evaluate. - Returns a value that indicates whether the specified rune is categorized as a letter or a decimal digit. - - if is a letter or a decimal digit; otherwise, . - + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + The rune to evaluate. + Returns a value that indicates whether the specified rune is categorized as a letter or a decimal digit. + + if is a letter or a decimal digit; otherwise, . + . - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - The rune to evaluate. - Returns a value that indicates whether the specified rune is categorized as a lowercase letter. - - if is a lowercase letter; otherwise, . - + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + The rune to evaluate. + Returns a value that indicates whether the specified rune is categorized as a lowercase letter. + + if is a lowercase letter; otherwise, . + . - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - The rune to evaluate. - Returns a value that indicates whether the specified rune is categorized as a number. - - if is a number; otherwise, . - + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + The rune to evaluate. + Returns a value that indicates whether the specified rune is categorized as a number. + + if is a number; otherwise, . + . - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - The rune to evaluate. - Returns a value that indicates whether the specified rune is categorized as a punctuation mark. - - if is a punctuation mark; otherwise, . - + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + The rune to evaluate. + Returns a value that indicates whether the specified rune is categorized as a punctuation mark. + + if is a punctuation mark; otherwise, . + . - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - The rune to evaluate. - Returns a value that indicates whether the specified rune is categorized as a separator character. - - if is a separator character; otherwise, . - + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + The rune to evaluate. + Returns a value that indicates whether the specified rune is categorized as a separator character. + + if is a separator character; otherwise, . + . - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - The rune to evaluate. - Returns a value that indicates whether the specified rune is categorized as a symbol character. - - if is a symbol character; otherwise, . - + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + The rune to evaluate. + Returns a value that indicates whether the specified rune is categorized as a symbol character. + + if is a symbol character; otherwise, . + . - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - The rune to evaluate. - Returns a value that indicates whether the specified rune is categorized as an uppercase letter. - - if is an uppercase letter; otherwise,. - + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + The rune to evaluate. + Returns a value that indicates whether the specified rune is categorized as an uppercase letter. + + if is an uppercase letter; otherwise,. + . - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - The Unicode scalar value. - Returns a value that indicates whether a 32-bit signed integer represents a valid Unicode scalar value; that is, it is in the range [ U+0000..U+D7FF ], inclusive; or [ U+E000..U+10FFFF ], inclusive. - - if is a valid Unicode scalar value; otherwise, . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - - System.Boolean - - - - - - The Unicode scalar value. - Returns a value that indicates whether a 32-bit unsigned integer represents a valid Unicode scalar value; that is, it is in the range [ U+0000..U+D7FF ], inclusive, or [ U+E000..U+10FFFF ], inclusive. - - if is a valid Unicode scalar value; otherwise, . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - The rune to evaluate. - Returns a value that indicates whether the specified rune is categorized as a white space character. - - if is a white space character; otherwise, . - + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + The Unicode scalar value. + Returns a value that indicates whether a 32-bit signed integer represents a valid Unicode scalar value; that is, it is in the range [ U+0000..U+D7FF ], inclusive; or [ U+E000..U+10FFFF ], inclusive. + + if is a valid Unicode scalar value; otherwise, . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + + System.Boolean + + + + + + The Unicode scalar value. + Returns a value that indicates whether a 32-bit unsigned integer represents a valid Unicode scalar value; that is, it is in the range [ U+0000..U+D7FF ], inclusive, or [ U+E000..U+10FFFF ], inclusive. + + if is a valid Unicode scalar value; otherwise, . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + The rune to evaluate. + Returns a value that indicates whether the specified rune is categorized as a white space character. + + if is a white space character; otherwise, . + . - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - - The first value to compare. - The second value to compare. - Returns a value that indicates whether two instances are equal. - - if and are equal; otherwise, . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Rune - - - - - - The 16-bit Unicode character to convert. - Defines an explicit conversion of a 16-bit Unicode character to a . - - as a 32-bit Unicode character. - To be added. - - is a Unicode scalar that represents a surrogate code point. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Rune - - - - - - The 32-bit signed integer to convert. - Defines an explicit conversion of a 32-bit signed integer to a . - - as a 32-bit Unicode character. - To be added. - - is an invalid Unicode scalar. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - - System.Text.Rune - - - - - - The 32-bit signed integer to convert. - Defines an explicit conversion of a 32-bit unsigned integer to a . - - as a 32-bit Unicode character. - To be added. - - is an invalid Unicode scalar. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - - The first value to compare. - The second value to compare. - Returns a value indicating whether a specified is greater than another specified . - - if is greater than ; otherwise, . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - - The first value to compare. - The second value to compare. - Returns a value indicating whether a specified is greater than or equal to another specified . - - if is greater than or equal to ; otherwise, . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - - The first value to compare. - The second value to compare. - Returns a value that indicates whether two instances have different values. - - if and are not equal; otherwise, . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - - The first value to compare. - the second value to compare. - Returns a value indicating whether a specified is less than another specified . - - if is less than ; otherwise, . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - - The first value to compare. - The second value to compare. - Returns a value indicating whether a specified is less than or equal to another specified . - - if is less than or equal to ; otherwise, . - To be added. - - - - - - - - - - Property - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - Gets the Unicode plane (0 to 16, inclusive) that contains this scalar. - The Unicode plane (0 to 16, inclusive) that contains this scalar. - To be added. - - - - - - - - - - Property - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Rune - - - Gets a instance that represents the Unicode replacement character U+FFFD. - A instance that represents the Unicode replacement character U+FFFD. - To be added. - - - - - - - - - - Method - - M:System.IComparable.CompareTo(System.Object) - - - System.Runtime - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - The object to compare with the current instance. - Compares the current instance to the specified object. - A signed integer indicating the position of this instance in the sort order in relation to :
- Less than zero: This instance precedes . + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + + The first value to compare. + The second value to compare. + Returns a value that indicates whether two instances are equal. + + if and are equal; otherwise, . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Rune + + + + + + The 16-bit Unicode character to convert. + Defines an explicit conversion of a 16-bit Unicode character to a . + + as a 32-bit Unicode character. + To be added. + + is a Unicode scalar that represents a surrogate code point. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Rune + + + + + + The 32-bit signed integer to convert. + Defines an explicit conversion of a 32-bit signed integer to a . + + as a 32-bit Unicode character. + To be added. + + is an invalid Unicode scalar. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + + System.Text.Rune + + + + + + The 32-bit signed integer to convert. + Defines an explicit conversion of a 32-bit unsigned integer to a . + + as a 32-bit Unicode character. + To be added. + + is an invalid Unicode scalar. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + + The first value to compare. + The second value to compare. + Returns a value indicating whether a specified is greater than another specified . + + if is greater than ; otherwise, . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + + The first value to compare. + The second value to compare. + Returns a value indicating whether a specified is greater than or equal to another specified . + + if is greater than or equal to ; otherwise, . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + + The first value to compare. + The second value to compare. + Returns a value that indicates whether two instances have different values. + + if and are not equal; otherwise, . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + + The first value to compare. + the second value to compare. + Returns a value indicating whether a specified is less than another specified . + + if is less than ; otherwise, . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + + The first value to compare. + The second value to compare. + Returns a value indicating whether a specified is less than or equal to another specified . + + if is less than or equal to ; otherwise, . + To be added. + + + + + + + + + + Property + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + Gets the Unicode plane (0 to 16, inclusive) that contains this scalar. + The Unicode plane (0 to 16, inclusive) that contains this scalar. + To be added. + + + + + + + + + + Property + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Rune + + + Gets a instance that represents the Unicode replacement character U+FFFD. + A instance that represents the Unicode replacement character U+FFFD. + To be added. + + + + + + + + + + Method + + M:System.IComparable.CompareTo(System.Object) + + + System.Runtime + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + The object to compare with the current instance. + Compares the current instance to the specified object. + A signed integer indicating the position of this instance in the sort order in relation to :
- Less than zero: This instance precedes .
- Zero: The instance has the same position in the sort order as . -
- Greater than zero: This instance follows . - +
- Greater than zero: This instance follows . + instance is cast to an interface. - ]]> - - - - - - - - - - - - Method - - M:System.IFormattable.ToString(System.String,System.IFormatProvider) - - - System.Runtime - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.String - - - - - - - The format to use. - -or- - ( in Visual Basic) to use the default format defined for the type of the implementation. - The provider to use to format the value. - -or- - ( in Visual Basic) to obtain the numeric format information from the current locale setting of the operating system. - Formats the value of the current instance using the specified format. - The value of the current instance in the specified format. - To be added. - - - - - - - - - - Method - - M:System.ISpanFormattable.TryFormat(System.Span{System.Char},System.Int32@,System.ReadOnlySpan{System.Char},System.IFormatProvider) - - - System.Runtime - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - - - - When this method returns, contains this instance's value formatted as a span of characters. - When this method returns, contains the number of characters that were written in . - A span containing the characters that represent a standard or custom format string that defines the acceptable format for . - An optional object that supplies culture-specific formatting information for . - Tries to format the value of the current instance into the provided span of characters. - - if the formatting was successful; otherwise, . - To be added. - - - - - - - - - - Method - - M:System.IUtf8SpanFormattable.TryFormat(System.Span{System.Byte},System.Int32@,System.ReadOnlySpan{System.Char},System.IFormatProvider) - - - System.Runtime - 8.0.0.0 - - - System.Boolean - - - - - - - - - The span in which to write this instance's value formatted as a span of bytes. - When this method returns, contains the number of bytes that were written in . - A span containing the characters that represent a standard or custom format string that defines the acceptable format for . - An optional object that supplies culture-specific formatting information for . - Tries to format the value of the current instance as UTF-8 into the provided span of bytes. - - if the formatting was successful; otherwise, . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.Text.Rune - - - - - - - The 32-bit Unicode character to convert. - An object that supplies culture-specific casing rules. - Returns a copy of the specified converted to lowercase, using the casing rules of the specified culture. - The lowercase equivalent of . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Rune - - - - - - The 32-bit Unicode character to convert. - Returns a copy of the specified converted to lowercase using the casing rules of the invariant culture. - The lowercase equivalent of . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.String - - - - Returns the string representation of this instance. - The string representation of this rune. - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.Text.Rune - - - - - - - The 32-bit Unicode character to convert. - An object that supplies culture-specific casing rules. - Returns a copy of the specified converted to uppercase, using the casing rules of the specified culture. - The uppercase equivalent of . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Text.Rune - - - - - - The 32-bit Unicode character to convert. - Returns a copy of the specified converted to uppercase using the casing rules of the invariant culture. - The uppercase equivalent of . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - - The character from which to create the rune. - When this method returns, the rune that corresponds to . - Attempts to create a from a specified character and returns a value that indicates whether the operation succeeded. - - if the method succeeded; otherwise, . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - - The Unicode scalar value. - When this method returns, the rune that corresponds to . - Attempts to create a from a specified signed integer that represents a Unicode scalar value. - - if the method succeeded; otherwise, . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - - System.Boolean - - - - - - - The Unicode scalar value. - When this method returns, the rune that corresponds to . - Attempts to create a from the specified 32-bit unsigned integer that represents a Unicode scalar value. - - if the method succeeded; otherwise, . - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - - - The high surrogate of the surrogate pair. - The low surrogate of the surrogate pair. - The rune that corresponds to the specified surrogate pair. - Attempts to create a from the specified UTF-16 surrogate pair and returns a value that indicates whether the operation was successful. - - if the operation succeeded; if the input values don't represent a well-formed UTF-16 surrogate pair. - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - - The buffer to which to write this value as UTF-16 encoded value. - The number of values written to , or 0 if the destination buffer is not large enough to contain the output. - Encodes this to a UTF-16 encoded destination buffer. - - if the value was written to the buffer; otherwise, . - + ]]> + + + + + + + + + + + + Method + + M:System.IFormattable.ToString(System.String,System.IFormatProvider) + + + System.Runtime + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.String + + + + + + + The format to use. + -or- + ( in Visual Basic) to use the default format defined for the type of the implementation. + The provider to use to format the value. + -or- + ( in Visual Basic) to obtain the numeric format information from the current locale setting of the operating system. + Formats the value of the current instance using the specified format. + The value of the current instance in the specified format. + To be added. + + + + + + + + + + Method + + M:System.ISpanFormattable.TryFormat(System.Span{System.Char},System.Int32@,System.ReadOnlySpan{System.Char},System.IFormatProvider) + + + System.Runtime + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + + + + When this method returns, contains this instance's value formatted as a span of characters. + When this method returns, contains the number of characters that were written in . + A span containing the characters that represent a standard or custom format string that defines the acceptable format for . + An optional object that supplies culture-specific formatting information for . + Tries to format the value of the current instance into the provided span of characters. + + if the formatting was successful; otherwise, . + To be added. + + + + + + + + + + Method + + M:System.IUtf8SpanFormattable.TryFormat(System.Span{System.Byte},System.Int32@,System.ReadOnlySpan{System.Char},System.IFormatProvider) + + + System.Runtime + 8.0.0.0 + + + System.Boolean + + + + + + + + + The span in which to write this instance's value formatted as a span of bytes. + When this method returns, contains the number of bytes that were written in . + A span containing the characters that represent a standard or custom format string that defines the acceptable format for . + An optional object that supplies culture-specific formatting information for . + Tries to format the value of the current instance as UTF-8 into the provided span of bytes. + + if the formatting was successful; otherwise, . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.Text.Rune + + + + + + + The 32-bit Unicode character to convert. + An object that supplies culture-specific casing rules. + Returns a copy of the specified converted to lowercase, using the casing rules of the specified culture. + The lowercase equivalent of . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Rune + + + + + + The 32-bit Unicode character to convert. + Returns a copy of the specified converted to lowercase using the casing rules of the invariant culture. + The lowercase equivalent of . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.String + + + + Returns the string representation of this instance. + The string representation of this rune. + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.Text.Rune + + + + + + + The 32-bit Unicode character to convert. + An object that supplies culture-specific casing rules. + Returns a copy of the specified converted to uppercase, using the casing rules of the specified culture. + The uppercase equivalent of . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Text.Rune + + + + + + The 32-bit Unicode character to convert. + Returns a copy of the specified converted to uppercase using the casing rules of the invariant culture. + The uppercase equivalent of . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + + The character from which to create the rune. + When this method returns, the rune that corresponds to . + Attempts to create a from a specified character and returns a value that indicates whether the operation succeeded. + + if the method succeeded; otherwise, . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + + The Unicode scalar value. + When this method returns, the rune that corresponds to . + Attempts to create a from a specified signed integer that represents a Unicode scalar value. + + if the method succeeded; otherwise, . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + + System.Boolean + + + + + + + The Unicode scalar value. + When this method returns, the rune that corresponds to . + Attempts to create a from the specified 32-bit unsigned integer that represents a Unicode scalar value. + + if the method succeeded; otherwise, . + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + + + The high surrogate of the surrogate pair. + The low surrogate of the surrogate pair. + The rune that corresponds to the specified surrogate pair. + Attempts to create a from the specified UTF-16 surrogate pair and returns a value that indicates whether the operation was successful. + + if the operation succeeded; if the input values don't represent a well-formed UTF-16 surrogate pair. + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + + The buffer to which to write this value as UTF-16 encoded value. + The number of values written to , or 0 if the destination buffer is not large enough to contain the output. + Encodes this to a UTF-16 encoded destination buffer. + + if the value was written to the buffer; otherwise, . + property can be queried ahead of time to determine the required size of the `destination` buffer. - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - - The buffer to which to write the UTF-8 encoded value. - The number of values written to , or 0 if the destination buffer is not large enough to contain the output. - Encodes this to a UTF-8 encoded destination buffer. - - if the value was written to the buffer; otherwise, . - + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + + The buffer to which to write the UTF-8 encoded value. + The number of values written to , or 0 if the destination buffer is not large enough to contain the output. + Encodes this to a UTF-8 encoded destination buffer. + + if the value was written to the buffer; otherwise, . + property can be queried ahead of time to determine the required size of the `destination` buffer. - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - System.Boolean - - - - - - - - The string from which to extract the rune. - The zero-based index from which to extract the rune. - When this method returns, the decoded rune. - Attempts to get the that begins at a specified position in a string, and return a value that indicates whether the operation succeeded. - - if a scalar value was successfully extracted from the specified index; if a value could not be extracted because of invalid data. - + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + + System.Boolean + + + + + + + + The string from which to extract the rune. + The zero-based index from which to extract the rune. + When this method returns, the decoded rune. + Attempts to get the that begins at a specified position in a string, and return a value that indicates whether the operation succeeded. + + if a scalar value was successfully extracted from the specified index; if a value could not be extracted because of invalid data. + - - - is . - - is out of the range of . - - - - - - - - - - Property - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - Gets the length in code units () of the UTF-16 sequence required to represent this scalar value. - The length in code units () of the UTF-16 sequence required to represent this scalar value. - + ]]> + + + is . + + is out of the range of . + + + + + + + + + + Property + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + Gets the length in code units () of the UTF-16 sequence required to represent this scalar value. + The length in code units () of the UTF-16 sequence required to represent this scalar value. + - - - - - - - - - - - Property - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - Gets the length in code units of the UTF-8 sequence required to represent this scalar value. - The length in code units of the UTF-8 sequence required to represent this scalar value. - + ]]> + + + + + + + + + + + Property + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + Gets the length in code units of the UTF-8 sequence required to represent this scalar value. + The length in code units of the UTF-8 sequence required to represent this scalar value. + - - - - - - - - - - - Property - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - Gets the Unicode scalar value as an integer. - The Unicode scalar value as an integer. - To be added. - - - - + ]]> + + + + + + + + + + + Property + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + Gets the Unicode scalar value as an integer. + The Unicode scalar value as an integer. + To be added. + + + + diff --git a/xml/System.Text/StringBuilder.xml b/xml/System.Text/StringBuilder.xml index ca673ba4030..05bdda3efb5 100644 --- a/xml/System.Text/StringBuilder.xml +++ b/xml/System.Text/StringBuilder.xml @@ -1,384 +1,152 @@ - - - - - - - - - - - - - - - - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - - - - - - - System.Object - - - - System.Runtime.Serialization.ISerializable - - - - - [System.Runtime.CompilerServices.Nullable(0)] - [<System.Runtime.CompilerServices.Nullable(0)>] - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - [System.Serializable] - [<System.Serializable>] - - - [System.Runtime.InteropServices.ComVisible(true)] - [<System.Runtime.InteropServices.ComVisible(true)>] - - - - Represents a mutable string of characters. This class cannot be inherited. - + + + + + + + + + + + + + + + + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + + + + + + + System.Object + + + + System.Runtime.Serialization.ISerializable + + + + + [System.Runtime.CompilerServices.Nullable(0)] + [<System.Runtime.CompilerServices.Nullable(0)>] + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + [System.Serializable] + [<System.Serializable>] + + + [System.Runtime.InteropServices.ComVisible(true)] + [<System.Runtime.InteropServices.ComVisible(true)>] + + + + Represents a mutable string of characters. This class cannot be inherited. + For more information about this API, see Supplemental API remarks for StringBuilder. + -## The String and StringBuilder types - Although and both represent sequences of characters, they are implemented differently. is an immutable type. That is, each operation that appears to modify a object actually creates a new string. - - For example, the call to the method in the following C# example appears to change the value of a string variable named `value`. In fact, the method returns a `value` object that has a different value and address from the `value` object that was passed to the method. Note that the example must be compiled using the `/unsafe` compiler option. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/immutability2.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/immutability2.fs" id="Snippet1"::: - - For routines that perform extensive string manipulation (such as apps that modify a string numerous times in a loop), modifying a string repeatedly can exact a significant performance penalty. The alternative is to use , which is a mutable string class. Mutability means that once an instance of the class has been created, it can be modified by appending, removing, replacing, or inserting characters. A object maintains a buffer to accommodate expansions to the string. New data is appended to the buffer if room is available; otherwise, a new, larger buffer is allocated, data from the original buffer is copied to the new buffer, and the new data is then appended to the new buffer. - -> [!IMPORTANT] -> Although the class generally offers better performance than the class, you should not automatically replace with whenever you want to manipulate strings. Performance depends on the size of the string, the amount of memory to be allocated for the new string, the system on which your code is executing, and the type of operation. You should be prepared to test your code to determine whether actually offers a significant performance improvement. - - Consider using the class under these conditions: - -- When the number of changes that your code will make to a string is small. In these cases, might offer negligible or no performance improvement over . - -- When you are performing a fixed number of concatenation operations, particularly with string literals. In this case, the compiler might combine the concatenation operations into a single operation. - -- When you have to perform extensive search operations while you are building your string. The class lacks search methods such as `IndexOf` or `StartsWith`. You'll have to convert the object to a for these operations, and this can negate the performance benefit from using . For more information, see the [Searching the text in a StringBuilder object](#Searching) section. - - Consider using the class under these conditions: - -- When you expect your code to make an unknown number of changes to a string at design time (for example, when you are using a loop to concatenate a random number of strings that contain user input). - -- When you expect your code to make a significant number of changes to a string. - - -## How StringBuilder works - The property indicates the number of characters the object currently contains. If you add characters to the object, its length increases until it equals the size of the property, which defines the number of characters that the object can contain. If the number of added characters causes the length of the object to exceed its current capacity, new memory is allocated, the value of the property is doubled, new characters are added to the object, and its property is adjusted. Additional memory for the object is allocated dynamically until it reaches the value defined by the property. When the maximum capacity is reached, no further memory can be allocated for the object, and trying to add characters or expand it beyond its maximum capacity throws either an or an exception. - - The following example illustrates how a object allocates new memory and increases its capacity dynamically as the string assigned to the object expands. The code creates a object by calling its default (parameterless) constructor. The default capacity of this object is 16 characters, and its maximum capacity is more than 2 billion characters. Appending the string "This is a sentence." results in a new memory allocation because the string length (19 characters) exceeds the default capacity of the object. The capacity of the object doubles to 32 characters, the new string is added, and the length of the object now equals 19 characters. The code then appends the string "This is an additional sentence." to the value of the object 11 times. Whenever the append operation causes the length of the object to exceed its capacity, its existing capacity is doubled and the operation succeeds. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/default1.cs" interactive="try-dotnet" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/default1.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/default1.vb" id="Snippet3"::: - - -## Memory allocation - The default capacity of a object is 16 characters, and its default maximum capacity is . These default values are used if you call the and constructors. - - You can explicitly define the initial capacity of a object in the following ways: - -- By calling any of the constructors that includes a `capacity` parameter when you create the object. - -- By explicitly assigning a new value to the property to expand an existing object. Note that the property throws an exception if the new capacity is less than the existing capacity or greater than the object's maximum capacity. - -- By calling the method with the new capacity. The new capacity must not be greater than the object's maximum capacity. However, unlike an assignment to the property, does not throw an exception if the desired new capacity is less than the existing capacity; in this case, the method call has no effect. - - If the length of the string assigned to the object in the constructor call exceeds either the default capacity or the specified capacity, the property is set to the length of the string specified with the `value` parameter. - - You can explicitly define the maximum capacity of a object by calling the constructor. You can't change the maximum capacity by assigning a new value to the property, because it is read-only. - - As the previous section shows, whenever the existing capacity is inadequate, additional memory is allocated and the capacity of a object doubles up to the value defined by the property. - - In general, the default capacity and maximum capacity are adequate for most apps. You might consider setting these values under the following conditions: - -- If the eventual size of the object is likely to grow exceedingly large, typically in excess of several megabytes. In this case, there may be some performance benefit from setting the initial property to a significantly high value to eliminate the need for too many memory reallocations. - -- If your code is running on a system with limited memory. In this case, you may want to consider setting the property to less than if your code is handling large strings that may cause it to execute in a memory-constrained environment. - - -## Instantiating a StringBuilder object - You instantiate a object by calling one of its six overloaded class constructors, which are listed in the following table. Three of the constructors instantiate a object whose value is an empty string, but set its and values differently. The remaining three constructors define a object that has a specific string value and capacity. Two of the three constructors use the default maximum capacity of , whereas the third allows you to set the maximum capacity. - -|Constructor|String value|Capacity|Maximum capacity| -|-----------------|------------------|--------------|----------------------| -|||16|| -|||Defined by the `capacity` parameter|| -|||Defined by the `capacity` parameter|Defined by the `maxCapacity` parameter| -||Defined by the `value` parameter|16 or `value`. , whichever is greater|| -||Defined by the `value` parameter|Defined by the `capacity` parameter or `value`. , whichever is greater.|| -||Defined by `value`. (`startIndex`, `length`)|Defined by the `capacity` parameter or `value`. , whichever is greater.|| - - The following example uses three of these constructor overloads to instantiate objects. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/instantiate1.cs" interactive="try-dotnet" id="Snippet6"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/instantiate1.fs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/instantiate1.vb" id="Snippet6"::: - - -## Calling StringBuilder methods - Most of the methods that modify the string in a instance return a reference to that same instance. This enables you to call methods in two ways: - -- You can make individual method calls and ignore the return value, as the following example does. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/call1.cs" interactive="try-dotnet" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/call1.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/call1.vb" id="Snippet4"::: - -- You can make a series of method calls in a single statement. This can be convenient if you want to write a single statement that chains successive operations. The following example consolidates three method calls from the previous example into a single line of code. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/call2.cs" interactive="try-dotnet" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/call2.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/call2.vb" id="Snippet5"::: - - -## Performing StringBuilder operations - You can use the methods of the class to iterate, add, delete, or modify characters in a object. - - -### Iterating StringBuilder characters - You can access the characters in a object by using the property. In C#, is an indexer; in Visual Basic, it is the default property of the class. This enables you to set or retrieve individual characters by using their index only, without explicitly referencing the property. Characters in a object begin at index 0 (zero) and continue to index - 1. - - The following example illustrates the property. It appends ten random numbers to a object, and then iterates each character. If the character's Unicode category is , it decreases the number by 1 (or changes the number to 9 if its value is 0). The example displays the contents of the object both before and after the values of individual characters were changed. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/chars1.cs" interactive="try-dotnet" id="Snippet7"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/chars1.fs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/chars1.vb" id="Snippet7"::: - -[!INCLUDE[stringbuilder-performance-note](~/includes/stringbuilder-perf-note.md)] - - -### Adding text to a StringBuilder object - The class includes the following methods for expanding the contents of a object: - -- The method appends a string, a substring, a character array, a portion of a character array, a single character repeated multiple times, or the string representation of a primitive data type to a object. - -- The method appends a line terminator or a string along with a line terminator to a object. - -- The method appends a [composite format string](/dotnet/standard/base-types/composite-formatting) to a object. The string representations of objects included in the result string can reflect the formatting conventions of the current system culture or a specified culture. - -- The method inserts a string, a substring, multiple repetitions of a string, a character array, a portion of a character array, or the string representation of a primitive data type at a specified position in the object. The position is defined by a zero-based index. - - The following example uses the , , , and methods to expand the text of a object. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/expand1.cs" interactive="try-dotnet" id="Snippet9"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/expand1.fs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/expand1.vb" id="Snippet9"::: - - -### Deleting text from a StringBuilder object - The class includes methods that can reduce the size of the current instance. The method removes all characters and sets the property to zero. The method deletes a specified number of characters starting at a particular index position. In addition, you can remove characters from the end of a object by setting its property to a value that is less than the length of the current instance. - - The following example removes some of the text from a object, displays its resulting capacity, maximum capacity, and length property values, and then calls the method to remove all the characters from the object. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/delete1.cs" interactive="try-dotnet" id="Snippet10"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/delete1.fs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/delete1.vb" id="Snippet10"::: - - -### Modifying the text in a StringBuilder object - The method replaces all occurrences of a character or a string in the entire object or in a particular character range. The following example uses the method to replace all exclamation points (!) with question marks (?) in the object. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/replace1.cs" interactive="try-dotnet" id="Snippet11"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/replace1.fs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/replace1.vb" id="Snippet11"::: - - -## Searching the text in a StringBuilder object - The class does not include methods similar to the , , and methods provided by the class, which allow you to search the object for a particular character or a substring. Determining the presence or starting character position of a substring requires that you search a value by using either a string search method or a regular expression method. There are four ways to implement such searches, as the following table shows. - -|Technique|Pros|Cons| -|---------------|----------|----------| -|Search string values before adding them to the object.|Useful for determining whether a substring exists.|Cannot be used when the index position of a substring is important.| -|Call and search the returned object.|Easy to use if you assign all the text to a object, and then begin to modify it.|Cumbersome to repeatedly call if you must make modifications before all text is added to the object.

You must remember to work from the end of the object's text if you're making changes.| -|Use the property to sequentially search a range of characters.|Useful if you're concerned with individual characters or a small substring.|Cumbersome if the number of characters to search is large or if the search logic is complex.

Results in very poor performance for objects that have grown very large through repeated method calls. | -|Convert the object to a object, and perform modifications on the object.|Useful if the number of modifications is small.|Negates the performance benefit of the class if the number of modifications is large.| - - Let's examine these techniques in greater detail. - -- If the goal of the search is to determine whether a particular substring exists (that is, if you aren't interested in the position of the substring), you can search strings before storing them in the object. The following example provides one possible implementation. It defines a `StringBuilderFinder` class whose constructor is passed a reference to a object and the substring to find in the string. In this case, the example tries to determine whether recorded temperatures are in Fahrenheit or Celsius, and adds the appropriate introductory text to the beginning of the object. A random number generator is used to select an array that contains data in either degrees Celsius or degrees Fahrenheit. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/pattern1.cs" interactive="try-dotnet" id="Snippet12"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/pattern1.fs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/pattern1.vb" id="Snippet12"::: - -- Call the method to convert the object to a object. You can search the string by using methods such as or , or you can use regular expressions and the class to search for patterns. Because both and objects use UTF-16 encoding to store characters, the index positions of characters, substrings, and regular expression matches are the same in both objects. This enables you to use methods to make changes at the same position at which that text is found in the object. - - > [!NOTE] - > If you adopt this approach, you should work from the end of the object to its beginning so that you don't have to repeatedly convert the object to a string. - - The following example illustrates this approach. It stores four occurrences of each letter of the English alphabet in a object. It then converts the text to a object and uses a regular expression to identify the starting position of each four-character sequence. Finally, it adds an underscore before each four-character sequence except for the first sequence, and converts the first character of the sequence to uppercase. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/pattern2.cs" interactive="try-dotnet" id="Snippet13"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/pattern2.fs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/pattern2.vb" id="Snippet13"::: - -- Use the property to sequentially search a range of characters in a object. This approach may not be practical if the number of characters to be searched is large or the search logic is particularly complex. For the performance implications of character-by-character index-based access for very large, chunked objects, see the documentation for the property. - - The following example is identical in functionality to the previous example but differs in implementation. It uses the property to detect when a character value has changed, inserts an underscore at that position, and converts the first character in the new sequence to uppercase. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/pattern3.cs" interactive="try-dotnet" id="Snippet14"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/pattern3.fs" id="Snippet14"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/pattern3.vb" id="Snippet14"::: - -- Store all the unmodified text in the object, call the method to convert the object to a object, and perform the modifications on the object. You can use this approach if you have only a few modifications; otherwise, the cost of working with immutable strings may negate the performance benefits of using a object. - - The following example is identical in functionality to the previous two examples but differs in implementation. It creates a object, converts it to a object, and then uses a regular expression to perform all remaining modifications on the string. The method uses a lambda expression to perform the replacement on each match. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/pattern4.cs" interactive="try-dotnet" id="Snippet15"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/pattern4.fs" id="Snippet15"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/pattern4.vb" id="Snippet15"::: - - -## Converting the StringBuilder object to a string - You must convert the object to a object before you can pass the string represented by the object to a method that has a parameter or display it in the user interface. You perform this conversion by calling the method. For an illustration, see the previous example, which calls the method to convert a object to a string so that it can be passed to a regular expression method. - - - -## Examples - The following example shows how to call many of the methods defined by the class. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StringBuilder/cpp/StringBuilder.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/StringBuilder.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/StringBuilder.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StringBuilder/VB/StringBuilder.vb" id="Snippet1"::: - - ]]> - - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - - - Initializes a new instance of the class. - - - - - - - - - Constructor - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - - Initializes a new instance of the class. - +The following example shows how to call many of the methods defined by the class. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StringBuilder/cpp/StringBuilder.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/StringBuilder.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/StringBuilder.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StringBuilder/VB/StringBuilder.vb" id="Snippet1"::: + ]]> + + + In .NET Core and in .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + + + Initializes a new instance of the class. + + + + + + + + + Constructor + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + + Initializes a new instance of the class. + - - - - - - - - - - - Constructor - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - - - - The suggested starting size of this instance. - Initializes a new instance of the class using the specified capacity. - + ]]> + + + + + + + + + + + Constructor + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + + + + The suggested starting size of this instance. + Initializes a new instance of the class using the specified capacity. + - - - is less than zero. - - - - - - - - - - - - Constructor - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - - - - - The string used to initialize the value of the instance. If is , the new will contain the empty string (that is, it contains ). - Initializes a new instance of the class using the specified string. - + ]]> + + + is less than zero. + + + + + + + + + + + + Constructor + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + + + + + The string used to initialize the value of the instance. If is , the new will contain the empty string (that is, it contains ). + Initializes a new instance of the class using the specified string. + - - - - - - - - - - - Constructor - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - - - - - The suggested starting size of the . - The maximum number of characters the current string can contain. - Initializes a new instance of the class that starts with a specified capacity and can grow to a specified maximum. - + ]]> + + + + + + + + + + + Constructor + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + + + + + The suggested starting size of the . + The maximum number of characters the current string can contain. + Initializes a new instance of the class that starts with a specified capacity and can grow to a specified maximum. + - - - is less than one, is less than zero, or is greater than . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - - - Constructor - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - - - - - The string used to initialize the value of the instance. If is , the new will contain the empty string (that is, it contains ). - The suggested starting size of the . - Initializes a new instance of the class using the specified string and capacity. - + ]]> + + + is less than one, is less than zero, or is greater than . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + + + Constructor + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + + + + + The string used to initialize the value of the instance. If is , the new will contain the empty string (that is, it contains ). + The suggested starting size of the . + Initializes a new instance of the class using the specified string and capacity. + - - - is less than zero. - - - - - - - - - - - - Constructor - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - - - - - - - The string that contains the substring used to initialize the value of this instance. If is , the new will contain the empty string (that is, it contains ). - The position within where the substring begins. - The number of characters in the substring. - The suggested starting size of the . - Initializes a new instance of the class from the specified substring and capacity. - + ]]> + + + is less than zero. + + + + + + + + + + + + Constructor + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + + + + + + + The string that contains the substring used to initialize the value of this instance. If is , the new will contain the empty string (that is, it contains ). + The position within where the substring begins. + The number of characters in the substring. + The suggested starting size of the . + Initializes a new instance of the class from the specified substring and capacity. + - - + ]]> + + is less than zero. -or- - plus is not a position within . - - - - - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - - - Appends the string representation of a specified object to this instance. - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - The Boolean value to append. - Appends the string representation of a specified Boolean value to this instance. - A reference to this instance after the append operation has completed. - + plus is not a position within . + + + + + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + + + Appends the string representation of a specified object to this instance. + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + The Boolean value to append. + Appends the string representation of a specified Boolean value to this instance. + A reference to this instance after the append operation has completed. + method calls the method to get the string representation of `value`. The capacity of this instance is adjusted as needed. - ]]> - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - The value to append. - Appends the string representation of a specified 8-bit unsigned integer to this instance. - A reference to this instance after the append operation has completed. - + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + The value to append. + Appends the string representation of a specified 8-bit unsigned integer to this instance. + A reference to this instance after the append operation has completed. + - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Text.StringBuilder - - - - - - The UTF-16-encoded code unit to append. - Appends the string representation of a specified object to this instance. - A reference to this instance after the append operation has completed. - + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Text.StringBuilder + + + + + + The UTF-16-encoded code unit to append. + Appends the string representation of a specified object to this instance. + A reference to this instance after the append operation has completed. + - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - The array of characters to append. - Appends the string representation of the Unicode characters in a specified array to this instance. - A reference to this instance after the append operation has completed. - + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + The array of characters to append. + Appends the string representation of the Unicode characters in a specified array to this instance. + A reference to this instance after the append operation has completed. + - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - The value to append. - Appends the string representation of a specified decimal number to this instance. - A reference to this instance after the append operation has completed. - + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + The value to append. + Appends the string representation of a specified decimal number to this instance. + A reference to this instance after the append operation has completed. + - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - The value to append. - Appends the string representation of a specified double-precision floating-point number to this instance. - A reference to this instance after the append operation has completed. - + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + The value to append. + Appends the string representation of a specified double-precision floating-point number to this instance. + A reference to this instance after the append operation has completed. + - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - The value to append. - Appends the string representation of a specified 16-bit signed integer to this instance. - A reference to this instance after the append operation has completed. - + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + The value to append. + Appends the string representation of a specified 16-bit signed integer to this instance. + A reference to this instance after the append operation has completed. + - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Text.StringBuilder - - - - - - The value to append. - Appends the string representation of a specified 32-bit signed integer to this instance. - A reference to this instance after the append operation has completed. - + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Text.StringBuilder + + + + + + The value to append. + Appends the string representation of a specified 32-bit signed integer to this instance. + A reference to this instance after the append operation has completed. + - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - The value to append. - Appends the string representation of a specified 64-bit signed integer to this instance. - A reference to this instance after the append operation has completed. - + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + The value to append. + Appends the string representation of a specified 64-bit signed integer to this instance. + A reference to this instance after the append operation has completed. + - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - The object to append. - Appends the string representation of a specified object to this instance. - A reference to this instance after the append operation has completed. - + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + The object to append. + Appends the string representation of a specified object to this instance. + A reference to this instance after the append operation has completed. + - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Text.StringBuilder - - - - - - The read-only character memory region to append. - Appends the string representation of a specified read-only character memory region to this instance. - A reference to this instance after the append operation is completed. - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Text.StringBuilder - - - - - - The read-only character span to append. - Appends the string representation of a specified read-only character span to this instance. - A reference to this instance after the append operation is completed. - To be added. - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - - System.Text.StringBuilder - - - - - - The value to append. - Appends the string representation of a specified 8-bit signed integer to this instance. - A reference to this instance after the append operation has completed. - + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Text.StringBuilder + + + + + + The read-only character memory region to append. + Appends the string representation of a specified read-only character memory region to this instance. + A reference to this instance after the append operation is completed. + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Text.StringBuilder + + + + + + The read-only character span to append. + Appends the string representation of a specified read-only character span to this instance. + A reference to this instance after the append operation is completed. + To be added. + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + + System.Text.StringBuilder + + + + + + The value to append. + Appends the string representation of a specified 8-bit signed integer to this instance. + A reference to this instance after the append operation has completed. + - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - The value to append. - Appends the string representation of a specified single-precision floating-point number to this instance. - A reference to this instance after the append operation has completed. - + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + The value to append. + Appends the string representation of a specified single-precision floating-point number to this instance. + A reference to this instance after the append operation has completed. + - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - The string to append. - Appends a copy of the specified string to this instance. - A reference to this instance after the append operation has completed. - + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + The string to append. + Appends a copy of the specified string to this instance. + A reference to this instance after the append operation has completed. + - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - The string builder to append. - Appends the string representation of a specified string builder to this instance. - A reference to this instance after the append operation is completed. - To be added. - - - - - - - - - - Method - - System.Runtime - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.InterpolatedStringHandlerArgument("")] - [<System.Runtime.CompilerServices.InterpolatedStringHandlerArgument("")>] - - - - - - The interpolated string to append. - Appends the specified interpolated string to this instance. - A reference to this instance after the append operation has completed. - To be added. - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - - System.Text.StringBuilder - - - - - - The value to append. - Appends the string representation of a specified 16-bit unsigned integer to this instance. - A reference to this instance after the append operation has completed. - + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + The string builder to append. + Appends the string representation of a specified string builder to this instance. + A reference to this instance after the append operation is completed. + To be added. + + + + + + + + + + Method + + System.Runtime + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.InterpolatedStringHandlerArgument("")] + [<System.Runtime.CompilerServices.InterpolatedStringHandlerArgument("")>] + + + + + + The interpolated string to append. + Appends the specified interpolated string to this instance. + A reference to this instance after the append operation has completed. + To be added. + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + + System.Text.StringBuilder + + + + + + The value to append. + Appends the string representation of a specified 16-bit unsigned integer to this instance. + A reference to this instance after the append operation has completed. + - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - - System.Text.StringBuilder - - - - - - The value to append. - Appends the string representation of a specified 32-bit unsigned integer to this instance. - A reference to this instance after the append operation has completed. - + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + + System.Text.StringBuilder + + + + + + The value to append. + Appends the string representation of a specified 32-bit unsigned integer to this instance. + A reference to this instance after the append operation has completed. + - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - - System.Text.StringBuilder - - - - - - The value to append. - Appends the string representation of a specified 64-bit unsigned integer to this instance. - A reference to this instance after the append operation has completed. - + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + + System.Text.StringBuilder + + + + + + The value to append. + Appends the string representation of a specified 64-bit unsigned integer to this instance. + A reference to this instance after the append operation has completed. + - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Text.StringBuilder - - - - - - - The character to append. - The number of times to append . - Appends a specified number of copies of the string representation of a Unicode character to this instance. - A reference to this instance after the append operation has completed. - + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Text.StringBuilder + + + + + + + The character to append. + The number of times to append . + Appends a specified number of copies of the string representation of a Unicode character to this instance. + A reference to this instance after the append operation has completed. + - - + ]]> + + is less than zero. -or- - Enlarging the value of this instance would exceed . - Out of memory. - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - Method - - System.Runtime - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - [System.Security.SecurityCritical] - [<System.Security.SecurityCritical>] - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Text.StringBuilder - - - - - - - A pointer to an array of characters. - The number of characters in the array. - Appends an array of Unicode characters starting at a specified address to this instance. - A reference to this instance after the append operation has completed. - + Enlarging the value of this instance would exceed . + Out of memory. + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + Method + + System.Runtime + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + [System.Security.SecurityCritical] + [<System.Security.SecurityCritical>] + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Text.StringBuilder + + + + + + + A pointer to an array of characters. + The number of characters in the array. + Appends an array of Unicode characters starting at a specified address to this instance. + A reference to this instance after the append operation has completed. + - - - + ]]> + + + is less than zero. -or- - Enlarging the value of this instance would exceed . - - is a null pointer. - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - Method - - System.Runtime - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - [System.Runtime.CompilerServices.InterpolatedStringHandlerArgument(new System.String[] { "", "provider" })] - [<System.Runtime.CompilerServices.InterpolatedStringHandlerArgument(new System.String[] { "", "provider" })>] - - - - - - An object that supplies culture-specific formatting information. - The interpolated string to append. - Appends the specified interpolated string to this instance using the specified format. - A reference to this instance after the append operation has completed. - To be added. - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - A character array. - The starting position in . - The number of characters to append. - Appends the string representation of a specified subarray of Unicode characters to this instance. - A reference to this instance after the append operation has completed. - + Enlarging the value of this instance would exceed . + + is a null pointer. + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + Method + + System.Runtime + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + [System.Runtime.CompilerServices.InterpolatedStringHandlerArgument(new System.String[] { "", "provider" })] + [<System.Runtime.CompilerServices.InterpolatedStringHandlerArgument(new System.String[] { "", "provider" })>] + + + + + + An object that supplies culture-specific formatting information. + The interpolated string to append. + Appends the specified interpolated string to this instance using the specified format. + A reference to this instance after the append operation has completed. + To be added. + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + A character array. + The starting position in . + The number of characters to append. + Appends the string representation of a specified subarray of Unicode characters to this instance. + A reference to this instance after the append operation has completed. + - - - is , and and are not zero. - + ]]> + + + is , and and are not zero. + is less than zero. -or- @@ -2409,76 +2177,76 @@ -or- - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - The string that contains the substring to append. - The starting position of the substring within . - The number of characters in to append. - Appends a copy of a specified substring to this instance. - A reference to this instance after the append operation has completed. - + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + The string that contains the substring to append. + The starting position of the substring within . + The number of characters in to append. + Appends a copy of a specified substring to this instance. + A reference to this instance after the append operation has completed. + - - - is , and and are not zero. - + ]]> + + + is , and and are not zero. + less than zero. -or- @@ -2509,147 +2277,147 @@ -or- - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - The string builder that contains the substring to append. - The starting position of the substring within . - The number of characters in to append. - Appends a copy of a substring within a specified string builder to this instance. - A reference to this instance after the append operation has completed. - To be added. - - - - - System.Runtime - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - - - Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of a corresponding object argument. - Composite Formatting - Standard Numeric Format Strings - Custom Numeric Format Strings - Standard Date and Time Format Strings - Custom Date and Time Format Strings - Standard TimeSpan Format Strings - Custom TimeSpan Format Strings - Enumeration Format Strings - - - - - - - - - - - Method - - System.Runtime - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Text.StringBuilder - - - - - - [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] - [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - A composite format string. - An object to format. - Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of a single argument. - A reference to this instance with appended. Each format item in is replaced by the string representation of . - + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + The string builder that contains the substring to append. + The starting position of the substring within . + The number of characters in to append. + Appends a copy of a substring within a specified string builder to this instance. + A reference to this instance after the append operation has completed. + To be added. + + + + + System.Runtime + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + + + Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of a corresponding object argument. + Composite Formatting + Standard Numeric Format Strings + Custom Numeric Format Strings + Standard Date and Time Format Strings + Custom Date and Time Format Strings + Standard TimeSpan Format Strings + Custom TimeSpan Format Strings + Enumeration Format Strings + + + + + + + + + + + Method + + System.Runtime + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Text.StringBuilder + + + + + + [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] + [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + A composite format string. + An object to format. + Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of a single argument. + A reference to this instance with appended. Each format item in is replaced by the string representation of . + - - - is . - + ]]> + + + is . + is invalid. -or- - The index of a format item is less than 0 (zero), or greater than or equal to 1. - The length of the expanded string would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - Formatting Types in .NET - Composite Formatting - Standard Numeric Format Strings - Custom Numeric Format Strings - Standard Date and Time Format Strings - Custom Date and Time Format Strings - Standard TimeSpan Format Strings - Custom TimeSpan Format Strings - Enumeration Format Strings - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] - [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] - - - - - - - [System.ParamArray] - [<System.ParamArray>] - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] - - - - - - A composite format string. - An array of objects to format. - Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of a corresponding argument in a parameter array. - A reference to this instance with appended. Each format item in is replaced by the string representation of the corresponding object argument. - + The index of a format item is less than 0 (zero), or greater than or equal to 1. + The length of the expanded string would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + Formatting Types in .NET + Composite Formatting + Standard Numeric Format Strings + Custom Numeric Format Strings + Standard Date and Time Format Strings + Custom Date and Time Format Strings + Standard TimeSpan Format Strings + Custom TimeSpan Format Strings + Enumeration Format Strings + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] + [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] + + + + + + + [System.ParamArray] + [<System.ParamArray>] + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] + + + + + + A composite format string. + An array of objects to format. + Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of a corresponding argument in a parameter array. + A reference to this instance with appended. Each format item in is replaced by the string representation of the corresponding object argument. + - - - or is . - + ]]> + + + or is . + is invalid. -or- - The index of a format item is less than 0 (zero), or greater than or equal to the length of the array. - The length of the expanded string would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - Formatting Types in .NET - Composite Formatting - Standard Numeric Format Strings - Custom Numeric Format Strings - Standard Date and Time Format Strings - Custom Date and Time Format Strings - Standard TimeSpan Format Strings - Custom TimeSpan Format Strings - Enumeration Format Strings - - - - - - - - - - - Method - - System.Runtime - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] - [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - An object that supplies culture-specific formatting information. - A composite format string. - The object to format. - Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of a single argument using a specified format provider. - A reference to this instance after the append operation has completed. After the append operation, this instance contains any data that existed before the operation, suffixed by a copy of in which any format specification is replaced by the string representation of . - + The index of a format item is less than 0 (zero), or greater than or equal to the length of the array. + The length of the expanded string would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + Formatting Types in .NET + Composite Formatting + Standard Numeric Format Strings + Custom Numeric Format Strings + Standard Date and Time Format Strings + Custom Date and Time Format Strings + Standard TimeSpan Format Strings + Custom TimeSpan Format Strings + Enumeration Format Strings + + + + + + + + + + + Method + + System.Runtime + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] + [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + An object that supplies culture-specific formatting information. + A composite format string. + The object to format. + Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of a single argument using a specified format provider. + A reference to this instance after the append operation has completed. After the append operation, this instance contains any data that existed before the operation, suffixed by a copy of in which any format specification is replaced by the string representation of . + - - - is . - + ]]> + + + is . + is invalid. -or- - The index of a format item is less than 0 (zero), or greater than or equal to one (1). - The length of the expanded string would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - Formatting Types in .NET - Composite Formatting - How to: Define and Use Custom Numeric Format Providers - Standard Numeric Format Strings - Custom Numeric Format Strings - Standard Date and Time Format Strings - Custom Date and Time Format Strings - Standard TimeSpan Format Strings - Custom TimeSpan Format Strings - Enumeration Format Strings - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] - [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] - - - - - - - [System.ParamArray] - [<System.ParamArray>] - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] - - - - - - An object that supplies culture-specific formatting information. - A composite format string. - An array of objects to format. - Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of a corresponding argument in a parameter array using a specified format provider. - A reference to this instance after the append operation has completed. After the append operation, this instance contains any data that existed before the operation, suffixed by a copy of where any format specification is replaced by the string representation of the corresponding object argument. - + The index of a format item is less than 0 (zero), or greater than or equal to one (1). + The length of the expanded string would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + Formatting Types in .NET + Composite Formatting + How to: Define and Use Custom Numeric Format Providers + Standard Numeric Format Strings + Custom Numeric Format Strings + Standard Date and Time Format Strings + Custom Date and Time Format Strings + Standard TimeSpan Format Strings + Custom TimeSpan Format Strings + Enumeration Format Strings + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] + [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] + + + + + + + [System.ParamArray] + [<System.ParamArray>] + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] + + + + + + An object that supplies culture-specific formatting information. + A composite format string. + An array of objects to format. + Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of a corresponding argument in a parameter array using a specified format provider. + A reference to this instance after the append operation has completed. After the append operation, this instance contains any data that existed before the operation, suffixed by a copy of where any format specification is replaced by the string representation of the corresponding object argument. + - - - is . - + ]]> + + + is . + is invalid. -or- - The index of a format item is less than 0 (zero), or greater than or equal to the length of the array. - The length of the expanded string would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - Formatting Types in .NET - Composite Formatting - How to: Define and Use Custom Numeric Format Providers - Standard Numeric Format Strings - Custom Numeric Format Strings - Standard Date and Time Format Strings - Custom Date and Time Format Strings - Standard TimeSpan Format Strings - Custom TimeSpan Format Strings - Enumeration Format Strings - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - [System.ParamArray] - [<System.ParamArray>] - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] - - - - - - An object that supplies culture-specific formatting information. - A . - An array of objects to format. + The index of a format item is less than 0 (zero), or greater than or equal to the length of the array. + The length of the expanded string would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + Formatting Types in .NET + Composite Formatting + How to: Define and Use Custom Numeric Format Providers + Standard Numeric Format Strings + Custom Numeric Format Strings + Standard Date and Time Format Strings + Custom Date and Time Format Strings + Standard TimeSpan Format Strings + Custom TimeSpan Format Strings + Enumeration Format Strings + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + [System.ParamArray] + [<System.ParamArray>] + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] + + + + + + An object that supplies culture-specific formatting information. + A . + An array of objects to format. Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. - Each format item is replaced by the string representation of any of the arguments using a specified format provider. - A reference to this instance after the append operation has completed. - To be added. - - or is . - The index of a format item is greater than or equal to the number of supplied arguments. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 0, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 0, 2 })>] - - - - - - An object that supplies culture-specific formatting information. - A . - A span of objects to format. + Each format item is replaced by the string representation of any of the arguments using a specified format provider. + A reference to this instance after the append operation has completed. + To be added. + + or is . + The index of a format item is greater than or equal to the number of supplied arguments. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 0, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 0, 2 })>] + + + + + + An object that supplies culture-specific formatting information. + A . + A span of objects to format. Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. - Each format item is replaced by the string representation of any of the arguments using a specified format provider. - A reference to this instance after the append operation has completed. - To be added. - - is . - The index of a format item is greater than or equal to the number of supplied arguments. - - - - - - - - - - - Method - - System.Runtime - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] - [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - A composite format string. - The first object to format. - The second object to format. - Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of either of two arguments. - A reference to this instance with appended. Each format item in is replaced by the string representation of the corresponding object argument. - + Each format item is replaced by the string representation of any of the arguments using a specified format provider. + A reference to this instance after the append operation has completed. + To be added. + + is . + The index of a format item is greater than or equal to the number of supplied arguments. + + + + + + + + + + + Method + + System.Runtime + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] + [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + A composite format string. + The first object to format. + The second object to format. + Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of either of two arguments. + A reference to this instance with appended. Each format item in is replaced by the string representation of the corresponding object argument. + - - - is . - + ]]> + + + is . + is invalid. -or- - The index of a format item is less than 0 (zero), or greater than or equal to 2. - The length of the expanded string would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - Formatting Types in .NET - Composite Formatting - Standard Numeric Format Strings - Custom Numeric Format Strings - Standard Date and Time Format Strings - Custom Date and Time Format Strings - Standard TimeSpan Format Strings - Custom TimeSpan Format Strings - Enumeration Format Strings - - - - - - - - - - - Method - - System.Runtime - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - - System.Text.StringBuilder - - - - - - - [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] - [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] - - - [System.Runtime.CompilerServices.Nullable(1)] - [<System.Runtime.CompilerServices.Nullable(1)>] - - - - - - - - An object that supplies culture-specific formatting information. - A composite format string. - The first object to format. - The second object to format. - Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of either of two arguments using a specified format provider. - A reference to this instance after the append operation has completed. After the append operation, this instance contains any data that existed before the operation, suffixed by a copy of where any format specification is replaced by the string representation of the corresponding object argument. - + The index of a format item is less than 0 (zero), or greater than or equal to 2. + The length of the expanded string would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + Formatting Types in .NET + Composite Formatting + Standard Numeric Format Strings + Custom Numeric Format Strings + Standard Date and Time Format Strings + Custom Date and Time Format Strings + Standard TimeSpan Format Strings + Custom TimeSpan Format Strings + Enumeration Format Strings + + + + + + + + + + + Method + + System.Runtime + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + + System.Text.StringBuilder + + + + + + + [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] + [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] + + + [System.Runtime.CompilerServices.Nullable(1)] + [<System.Runtime.CompilerServices.Nullable(1)>] + + + + + + + + An object that supplies culture-specific formatting information. + A composite format string. + The first object to format. + The second object to format. + Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of either of two arguments using a specified format provider. + A reference to this instance after the append operation has completed. After the append operation, this instance contains any data that existed before the operation, suffixed by a copy of where any format specification is replaced by the string representation of the corresponding object argument. + - - - is . - + ]]> + + + is . + is invalid. -or- - The index of a format item is less than 0 (zero), or greater than or equal to 2 (two). - The length of the expanded string would exceed . - - IIn .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - Formatting Types in .NET - Composite Formatting - How to: Define and Use Custom Numeric Format Providers - Standard Numeric Format Strings - Custom Numeric Format Strings - Standard Date and Time Format Strings - Custom Date and Time Format Strings - Standard TimeSpan Format Strings - Custom TimeSpan Format Strings - Enumeration Format Strings - - - - - - - - - - - Method - - System.Runtime - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - - System.Text.StringBuilder - - - - - - [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] - [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] - - - [System.Runtime.CompilerServices.Nullable(1)] - [<System.Runtime.CompilerServices.Nullable(1)>] - - - - - - - - - A composite format string. - The first object to format. - The second object to format. - The third object to format. - Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of either of three arguments. - A reference to this instance with appended. Each format item in is replaced by the string representation of the corresponding object argument. - + The index of a format item is less than 0 (zero), or greater than or equal to 2 (two). + The length of the expanded string would exceed . + + IIn .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + Formatting Types in .NET + Composite Formatting + How to: Define and Use Custom Numeric Format Providers + Standard Numeric Format Strings + Custom Numeric Format Strings + Standard Date and Time Format Strings + Custom Date and Time Format Strings + Standard TimeSpan Format Strings + Custom TimeSpan Format Strings + Enumeration Format Strings + + + + + + + + + + + Method + + System.Runtime + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + + System.Text.StringBuilder + + + + + + [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] + [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] + + + [System.Runtime.CompilerServices.Nullable(1)] + [<System.Runtime.CompilerServices.Nullable(1)>] + + + + + + + + + A composite format string. + The first object to format. + The second object to format. + The third object to format. + Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of either of three arguments. + A reference to this instance with appended. Each format item in is replaced by the string representation of the corresponding object argument. + - - - is . - + ]]> + + + is . + is invalid. -or- - The index of a format item is less than 0 (zero), or greater than or equal to 3. - The length of the expanded string would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - Formatting Types in .NET - Composite Formatting - Standard Numeric Format Strings - Custom Numeric Format Strings - Standard Date and Time Format Strings - Custom Date and Time Format Strings - Standard TimeSpan Format Strings - Custom TimeSpan Format Strings - Enumeration Format Strings - - - - - - - - - - - Method - - System.Runtime - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - - System.Text.StringBuilder - - - - - - - [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] - [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] - - - [System.Runtime.CompilerServices.Nullable(1)] - [<System.Runtime.CompilerServices.Nullable(1)>] - - - - - - - - - An object that supplies culture-specific formatting information. - A composite format string. - The first object to format. - The second object to format. - The third object to format. - Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of either of three arguments using a specified format provider. - A reference to this instance after the append operation has completed. After the append operation, this instance contains any data that existed before the operation, suffixed by a copy of where any format specification is replaced by the string representation of the corresponding object argument. - + The index of a format item is less than 0 (zero), or greater than or equal to 3. + The length of the expanded string would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + Formatting Types in .NET + Composite Formatting + Standard Numeric Format Strings + Custom Numeric Format Strings + Standard Date and Time Format Strings + Custom Date and Time Format Strings + Standard TimeSpan Format Strings + Custom TimeSpan Format Strings + Enumeration Format Strings + + + + + + + + + + + Method + + System.Runtime + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + + System.Text.StringBuilder + + + + + + + [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] + [<System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")>] + + + [System.Runtime.CompilerServices.Nullable(1)] + [<System.Runtime.CompilerServices.Nullable(1)>] + + + + + + + + + An object that supplies culture-specific formatting information. + A composite format string. + The first object to format. + The second object to format. + The third object to format. + Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of either of three arguments using a specified format provider. + A reference to this instance after the append operation has completed. After the append operation, this instance contains any data that existed before the operation, suffixed by a copy of where any format specification is replaced by the string representation of the corresponding object argument. + - - - is . - + ]]> + + + is . + is invalid. -or- - The index of a format item is less than 0 (zero), or greater than or equal to 3 (three). - The length of the expanded string would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - Formatting Types in .NET - Composite Formatting - How to: Define and Use Custom Numeric Format Providers - Standard Numeric Format Strings - Custom Numeric Format Strings - Standard Date and Time Format Strings - Custom Date and Time Format Strings - Standard TimeSpan Format Strings - Custom TimeSpan Format Strings - Enumeration Format Strings - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - The type of the first object to format. - An object that supplies culture-specific formatting information. - A . - The first object to format. + The index of a format item is less than 0 (zero), or greater than or equal to 3 (three). + The length of the expanded string would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + Formatting Types in .NET + Composite Formatting + How to: Define and Use Custom Numeric Format Providers + Standard Numeric Format Strings + Custom Numeric Format Strings + Standard Date and Time Format Strings + Custom Date and Time Format Strings + Standard TimeSpan Format Strings + Custom TimeSpan Format Strings + Enumeration Format Strings + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + The type of the first object to format. + An object that supplies culture-specific formatting information. + A . + The first object to format. Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. - Each format item is replaced by the string representation of any of the arguments using a specified format provider. - A reference to this instance after the append operation has completed. - To be added. - - is . - The index of a format item is greater than or equal to the number of supplied arguments. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - The type of the first object to format. - The type of the second object to format. - An object that supplies culture-specific formatting information. - A . - The first object to format. - The second object to format. + Each format item is replaced by the string representation of any of the arguments using a specified format provider. + A reference to this instance after the append operation has completed. + To be added. + + is . + The index of a format item is greater than or equal to the number of supplied arguments. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + The type of the first object to format. + The type of the second object to format. + An object that supplies culture-specific formatting information. + A . + The first object to format. + The second object to format. Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. - Each format item is replaced by the string representation of any of the arguments using a specified format provider. - A reference to this instance after the append operation has completed. - To be added. - - is . - The index of a format item is greater than or equal to the number of supplied arguments. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - - The type of the first object to format. - The type of the second object to format. - The type of the third object to format. - An object that supplies culture-specific formatting information. - A . - The first object to format. - The second object to format. - The third object to format. + Each format item is replaced by the string representation of any of the arguments using a specified format provider. + A reference to this instance after the append operation has completed. + To be added. + + is . + The index of a format item is greater than or equal to the number of supplied arguments. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + + The type of the first object to format. + The type of the second object to format. + The type of the third object to format. + An object that supplies culture-specific formatting information. + A . + The first object to format. + The second object to format. + The third object to format. Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. - Each format item is replaced by the string representation of any of the arguments using a specified format provider. - A reference to this instance after the append operation has completed. - To be added. - - is . - The index of a format item is greater than or equal to the number of supplied arguments. - - - - - - - - - - - Method - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - - [System.ParamArray] - [<System.ParamArray>] - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] - - - - - - The character to use as a separator. is included in the joined strings only if has more than one element. - An array that contains the strings to concatenate and append to the current instance of the string builder. - Concatenates the string representations of the elements in the provided array of objects, using the specified char separator between each member, then appends the result to the current instance of the string builder. - A reference to this instance after the append operation has completed. - To be added. - - - - - - - - - - - Method - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - - [System.ParamArray] - [<System.ParamArray>] - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] - - - - - - The character to use as a separator. is included in the joined strings only if has more than one element. - An array that contains the strings to concatenate and append to the current instance of the string builder. - Concatenates the strings of the provided array, using the specified char separator between each string, then appends the result to the current instance of the string builder. - A reference to this instance after the append operation has completed. - To be added. - - - - - - - - - - - Method - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - [System.ParamArray] - [<System.ParamArray>] - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] - - - - - - The string to use as a separator. is included in the joined strings only if has more than one element. - An array that contains the strings to concatenate and append to the current instance of the string builder. - Concatenates the string representations of the elements in the provided array of objects, using the specified separator between each member, then appends the result to the current instance of the string builder. - A reference to this instance after the append operation has completed. - To be added. - - - - - - - - - - - Method - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - [System.ParamArray] - [<System.ParamArray>] - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] - - - - - - The string to use as a separator. is included in the joined strings only if has more than one element. - An array that contains the strings to concatenate and append to the current instance of the string builder. - Concatenates the strings of the provided array, using the specified separator between each string, then appends the result to the current instance of the string builder. - A reference to this instance after the append operation has completed. - To be added. - - - - - - - - - - Method - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - - The type of the members of . - The character to use as a separator. is included in the concatenated and appended strings only if has more than one element. - A collection that contains the objects to concatenate and append to the current instance of the string builder. - Concatenates and appends the members of a collection, using the specified char separator between each member. - A reference to this instance after the append operation has completed. - To be added. - - - - - - - - - - - Method - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - The type of the members of . - The string to use as a separator. is included in the concatenated and appended strings only if has more than one element. - A collection that contains the objects to concatenate and append to the current instance of the string builder. - Concatenates and appends the members of a collection, using the specified separator between each member. - A reference to this instance after the append operation has completed. - To be added. - - - - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - - - Appends the default line terminator, or a copy of a specified string and the default line terminator, to the end of this instance. - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.InteropServices.ComVisible(false)] - [<System.Runtime.InteropServices.ComVisible(false)>] - - - - System.Text.StringBuilder - - - - Appends the default line terminator to the end of the current object. - A reference to this instance after the append operation has completed. - + Each format item is replaced by the string representation of any of the arguments using a specified format provider. + A reference to this instance after the append operation has completed. + To be added. + + is . + The index of a format item is greater than or equal to the number of supplied arguments. + + + + + + + + + + + Method + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + + [System.ParamArray] + [<System.ParamArray>] + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] + + + + + + The character to use as a separator. is included in the joined strings only if has more than one element. + An array that contains the strings to concatenate and append to the current instance of the string builder. + Concatenates the string representations of the elements in the provided array of objects, using the specified char separator between each member, then appends the result to the current instance of the string builder. + A reference to this instance after the append operation has completed. + To be added. + + + + + + + + + + + Method + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + + [System.ParamArray] + [<System.ParamArray>] + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] + + + + + + The character to use as a separator. is included in the joined strings only if has more than one element. + An array that contains the strings to concatenate and append to the current instance of the string builder. + Concatenates the strings of the provided array, using the specified char separator between each string, then appends the result to the current instance of the string builder. + A reference to this instance after the append operation has completed. + To be added. + + + + + + + + + + + Method + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + [System.ParamArray] + [<System.ParamArray>] + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] + + + + + + The string to use as a separator. is included in the joined strings only if has more than one element. + An array that contains the strings to concatenate and append to the current instance of the string builder. + Concatenates the string representations of the elements in the provided array of objects, using the specified separator between each member, then appends the result to the current instance of the string builder. + A reference to this instance after the append operation has completed. + To be added. + + + + + + + + + + + Method + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + [System.ParamArray] + [<System.ParamArray>] + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] + + + + + + The string to use as a separator. is included in the joined strings only if has more than one element. + An array that contains the strings to concatenate and append to the current instance of the string builder. + Concatenates the strings of the provided array, using the specified separator between each string, then appends the result to the current instance of the string builder. + A reference to this instance after the append operation has completed. + To be added. + + + + + + + + + + Method + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + + The type of the members of . + The character to use as a separator. is included in the concatenated and appended strings only if has more than one element. + A collection that contains the objects to concatenate and append to the current instance of the string builder. + Concatenates and appends the members of a collection, using the specified char separator between each member. + A reference to this instance after the append operation has completed. + To be added. + + + + + + + + + + + Method + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + The type of the members of . + The string to use as a separator. is included in the concatenated and appended strings only if has more than one element. + A collection that contains the objects to concatenate and append to the current instance of the string builder. + Concatenates and appends the members of a collection, using the specified separator between each member. + A reference to this instance after the append operation has completed. + To be added. + + + + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + + + Appends the default line terminator, or a copy of a specified string and the default line terminator, to the end of this instance. + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.InteropServices.ComVisible(false)] + [<System.Runtime.InteropServices.ComVisible(false)>] + + + + System.Text.StringBuilder + + + + Appends the default line terminator to the end of the current object. + A reference to this instance after the append operation has completed. + - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.InteropServices.ComVisible(false)] - [<System.Runtime.InteropServices.ComVisible(false)>] - - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - The string to append. - Appends a copy of the specified string followed by the default line terminator to the end of the current object. - A reference to this instance after the append operation has completed. - + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.InteropServices.ComVisible(false)] + [<System.Runtime.InteropServices.ComVisible(false)>] + + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + The string to append. + Appends a copy of the specified string followed by the default line terminator to the end of the current object. + A reference to this instance after the append operation has completed. + - - Enlarging the value of this instance would exceed . - - In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - - - - - - - - - - - - Method - - System.Runtime - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.InterpolatedStringHandlerArgument("")] - [<System.Runtime.CompilerServices.InterpolatedStringHandlerArgument("")>] - - - - - - The interpolated string to append. - Appends the specified interpolated string followed by the default line terminator to the end of the current StringBuilder object. - A reference to this instance after the append operation has completed. - To be added. - - - - - - - - - - Method - - System.Runtime - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Text.StringBuilder - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - [System.Runtime.CompilerServices.InterpolatedStringHandlerArgument(new System.String[] { "", "provider" })] - [<System.Runtime.CompilerServices.InterpolatedStringHandlerArgument(new System.String[] { "", "provider" })>] - - - - - - An object that supplies culture-specific formatting information. - The interpolated string to append. - Appends the specified interpolated string using the specified format, followed by the default line terminator, to the end of the current StringBuilder object. - A reference to this instance after the append operation has completed. - To be added. - - - - - - - - - - Property - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Int32 - - - Gets or sets the maximum number of characters that can be contained in the memory allocated by the current instance. - The maximum number of characters that can be contained in the memory allocated by the current instance. Its value can range from to . - + ]]> + + Enlarging the value of this instance would exceed . + + In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + + + + + + + + + + + + Method + + System.Runtime + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.InterpolatedStringHandlerArgument("")] + [<System.Runtime.CompilerServices.InterpolatedStringHandlerArgument("")>] + + + + + + The interpolated string to append. + Appends the specified interpolated string followed by the default line terminator to the end of the current StringBuilder object. + A reference to this instance after the append operation has completed. + To be added. + + + + + + + + + + Method + + System.Runtime + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Text.StringBuilder + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + [System.Runtime.CompilerServices.InterpolatedStringHandlerArgument(new System.String[] { "", "provider" })] + [<System.Runtime.CompilerServices.InterpolatedStringHandlerArgument(new System.String[] { "", "provider" })>] + + + + + + An object that supplies culture-specific formatting information. + The interpolated string to append. + Appends the specified interpolated string using the specified format, followed by the default line terminator, to the end of the current StringBuilder object. + A reference to this instance after the append operation has completed. + To be added. + + + + + + + + + + Property + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Int32 + + + Gets or sets the maximum number of characters that can be contained in the memory allocated by the current instance. + The maximum number of characters that can be contained in the memory allocated by the current instance. Its value can range from to . + - + ]]> + The value specified for a set operation is less than the current length of this instance. -or- - The value specified for a set operation is greater than the maximum capacity. - - - - - - - - - - Property - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Char - - - - - - The position of the character. - Gets or sets the character at the specified character position in this instance. - The Unicode character at position . - + The value specified for a set operation is greater than the maximum capacity. + + + + + + + + + + Property + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Char + + + + + + The position of the character. + Gets or sets the character at the specified character position in this instance. + The Unicode character at position . + - - - is outside the bounds of this instance while setting a character. - - is outside the bounds of this instance while getting a character. - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Text.StringBuilder - - - - Removes all characters from the current instance. - An object whose is 0 (zero). - + ]]> + + + is outside the bounds of this instance while setting a character. + + is outside the bounds of this instance while getting a character. + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Text.StringBuilder + + + + Removes all characters from the current instance. + An object whose is 0 (zero). + object wit :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Clear/clear1.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.clear/vb/clear1.vb" id="Snippet1"::: - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Void - - - - - - - - The starting position in this instance where characters will be copied from. The index is zero-based. - The writable span where characters will be copied. - The number of characters to be copied. - Copies the characters from a specified segment of this instance to a destination span. - + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Void + + + + + + + + The starting position in this instance where characters will be copied from. The index is zero-based. + The writable span where characters will be copied. + The number of characters to be copied. + Copies the characters from a specified segment of this instance to a destination span. + object wit For example, your code could populate a object with a large number of characters then use the method to copy small, successive pieces of the object to an span where the pieces are processed. When all the data in the object is processed, the size of the object is set to zero and the cycle is repeated. - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.InteropServices.ComVisible(false)] - [<System.Runtime.InteropServices.ComVisible(false)>] - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Void - - - - - - - - - The starting position in this instance where characters will be copied from. The index is zero-based. - The array where characters will be copied. - The starting position in where characters will be copied. The index is zero-based. - The number of characters to be copied. - Copies the characters from a specified segment of this instance to a specified segment of a destination array. - + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.InteropServices.ComVisible(false)] + [<System.Runtime.InteropServices.ComVisible(false)>] + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Void + + + + + + + + + The starting position in this instance where characters will be copied from. The index is zero-based. + The array where characters will be copied. + The starting position in where characters will be copied. The index is zero-based. + The number of characters to be copied. + Copies the characters from a specified segment of this instance to a specified segment of a destination array. + object wit :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/CopyTo/ct2.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.copyto2/VB/ct2.vb" id="Snippet1"::: - ]]> - - - is . - + ]]> + + + is . + , , or , is less than zero. -or- - is greater than the length of this instance. - + is greater than the length of this instance. + + is greater than the length of this instance. -or- - + is greater than the length of . - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Int32 - - - - - - The minimum capacity to ensure. - Ensures that the capacity of this instance of is at least the specified value. - The new capacity of this instance. - + + is greater than the length of . + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Int32 + + + + + + The minimum capacity to ensure. + Ensures that the capacity of this instance of is at least the specified value. + The new capacity of this instance. + object wit :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Capacity/cap.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.ensurecapacity/VB/cap.vb" id="Snippet1"::: - ]]> - - + ]]> + + is less than zero. -or- - Enlarging the value of this instance would exceed . - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Boolean - - - - - - The character span to compare with the current instance. - Returns a value indicating whether the characters in this instance are equal to the characters in a specified read-only character span. - - if the characters in this instance and are the same; otherwise, . - + Enlarging the value of this instance would exceed . + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Boolean + + + + + + The character span to compare with the current instance. + Returns a value indicating whether the characters in this instance are equal to the characters in a specified read-only character span. + + if the characters in this instance and are the same; otherwise, . + - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - - System.Boolean - - - - - - [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] - [<System.Diagnostics.CodeAnalysis.NotNullWhen(true)>] - - - - - - An object to compare with this instance, or . - Returns a value indicating whether this instance is equal to a specified object. - - if this instance and have equal string, , and values; otherwise, . - + ]]> + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + + System.Boolean + + + + + + [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] + [<System.Diagnostics.CodeAnalysis.NotNullWhen(true)>] + + + + + + An object to compare with this instance, or . + Returns a value indicating whether this instance is equal to a specified object. + + if this instance and have equal string, , and values; otherwise, . + - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - - - System.Text.StringBuilder+ChunkEnumerator - - - - Returns an object that can be used to iterate through the chunks of characters represented in a created from this instance. - An enumerator for the chunks in the . - + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + + + System.Text.StringBuilder+ChunkEnumerator + + + + Returns an object that can be used to iterate through the chunks of characters represented in a created from this instance. + An enumerator for the chunks in the . + chunk in sb.GetChunks()) } ``` - ]]> - - - - - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - - - Inserts the string representation of a specified object into this instance at a specified character position. - + ]]> + + + + + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + + + Inserts the string representation of a specified object into this instance at a specified character position. + chunk in sb.GetChunks()) :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Insert/insert.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.insert/VB/insert.vb" id="Snippet1"::: - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - - The position in this instance where insertion begins. - The value to insert. - Inserts the string representation of a Boolean value into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + + The position in this instance where insertion begins. + The value to insert. + Inserts the string representation of a Boolean value into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed. - ]]> - - - is less than zero or greater than the length of this instance. - Enlarging the value of this instance would exceed . - - In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - - The position in this instance where insertion begins. - The value to insert. - Inserts the string representation of a specified 8-bit unsigned integer into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - + ]]> + + + is less than zero or greater than the length of this instance. + Enlarging the value of this instance would exceed . + + In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + + The position in this instance where insertion begins. + The value to insert. + Inserts the string representation of a specified 8-bit unsigned integer into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - ]]> - - - is less than zero or greater than the length of this instance. - Enlarging the value of this instance would exceed . - - In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Text.StringBuilder - - - - - - - The position in this instance where insertion begins. - The value to insert. - Inserts the string representation of a specified Unicode character into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - + ]]> + + + is less than zero or greater than the length of this instance. + Enlarging the value of this instance would exceed . + + In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Text.StringBuilder + + + + + + + The position in this instance where insertion begins. + The value to insert. + Inserts the string representation of a specified Unicode character into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - ]]> - - + ]]> + + is less than zero or greater than the length of this instance. -or- - Enlarging the value of this instance would exceed . - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - The position in this instance where insertion begins. - The character array to insert. - Inserts the string representation of a specified array of Unicode characters into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - + Enlarging the value of this instance would exceed . + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + The position in this instance where insertion begins. + The character array to insert. + Inserts the string representation of a specified array of Unicode characters into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + chunk in sb.GetChunks()) If `value` is `null`, the is not changed. - ]]> - - + ]]> + + is less than zero or greater than the length of this instance. -or- - Enlarging the value of this instance would exceed . - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - - The position in this instance where insertion begins. - The value to insert. - Inserts the string representation of a decimal number into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - + Enlarging the value of this instance would exceed . + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + + The position in this instance where insertion begins. + The value to insert. + Inserts the string representation of a decimal number into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - ]]> - - - is less than zero or greater than the length of this instance. - Enlarging the value of this instance would exceed . - - In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - - The position in this instance where insertion begins. - The value to insert. - Inserts the string representation of a double-precision floating-point number into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - + ]]> + + + is less than zero or greater than the length of this instance. + Enlarging the value of this instance would exceed . + + In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + + The position in this instance where insertion begins. + The value to insert. + Inserts the string representation of a double-precision floating-point number into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - ]]> - - - is less than zero or greater than the length of this instance. - Enlarging the value of this instance would exceed . - - In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - - The position in this instance where insertion begins. - The value to insert. - Inserts the string representation of a specified 16-bit signed integer into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - + ]]> + + + is less than zero or greater than the length of this instance. + Enlarging the value of this instance would exceed . + + In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + + The position in this instance where insertion begins. + The value to insert. + Inserts the string representation of a specified 16-bit signed integer into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - ]]> - - - is less than zero or greater than the length of this instance. - Enlarging the value of this instance would exceed . - - In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - - The position in this instance where insertion begins. - The value to insert. - Inserts the string representation of a specified 32-bit signed integer into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - + ]]> + + + is less than zero or greater than the length of this instance. + Enlarging the value of this instance would exceed . + + In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + + The position in this instance where insertion begins. + The value to insert. + Inserts the string representation of a specified 32-bit signed integer into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - ]]> - - - is less than zero or greater than the length of this instance. - Enlarging the value of this instance would exceed . - - In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - - The position in this instance where insertion begins. - The value to insert. - Inserts the string representation of a 64-bit signed integer into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - + ]]> + + + is less than zero or greater than the length of this instance. + Enlarging the value of this instance would exceed . + + In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + + The position in this instance where insertion begins. + The value to insert. + Inserts the string representation of a 64-bit signed integer into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - ]]> - - - is less than zero or greater than the length of this instance. - Enlarging the value of this instance would exceed . - - In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . - - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - The position in this instance where insertion begins. - The object to insert, or . - Inserts the string representation of an object into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - + ]]> + + + is less than zero or greater than the length of this instance. + Enlarging the value of this instance would exceed . + + In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . + + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + The position in this instance where insertion begins. + The object to insert, or . + Inserts the string representation of an object into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + chunk in sb.GetChunks()) If `value` is `null`, the value of this instance is unchanged. - ]]> - - - is less than zero or greater than the length of this instance. - Enlarging the value of this instance would exceed . - - In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . - - - - - - - - - - - - Method - - System.Runtime - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(0)] - [<System.Runtime.CompilerServices.NullableContext(0)>] - - - - System.Text.StringBuilder - - - - - - - The position in this instance where insertion begins. - The character span to insert. - Inserts the sequence of characters into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - + ]]> + + + is less than zero or greater than the length of this instance. + Enlarging the value of this instance would exceed . + + In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . + + + + + + + + + + + + Method + + System.Runtime + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(0)] + [<System.Runtime.CompilerServices.NullableContext(0)>] + + + + System.Text.StringBuilder + + + + + + + The position in this instance where insertion begins. + The character span to insert. + Inserts the sequence of characters into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - - System.Text.StringBuilder - - - - - - - The position in this instance where insertion begins. - The value to insert. - Inserts the string representation of a specified 8-bit signed integer into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + + System.Text.StringBuilder + + + + + + + The position in this instance where insertion begins. + The value to insert. + Inserts the string representation of a specified 8-bit signed integer into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed. - ]]> - - - is less than zero or greater than the length of this instance. - Enlarging the value of this instance would exceed . - - In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - - The position in this instance where insertion begins. - The value to insert. - Inserts the string representation of a single-precision floating point number into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - + ]]> + + + is less than zero or greater than the length of this instance. + Enlarging the value of this instance would exceed . + + In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + + The position in this instance where insertion begins. + The value to insert. + Inserts the string representation of a single-precision floating point number into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - ]]> - - - is less than zero or greater than the length of this instance. - Enlarging the value of this instance would exceed . - - In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . - - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Text.StringBuilder - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - The position in this instance where insertion begins. - The string to insert. - Inserts a string into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - + ]]> + + + is less than zero or greater than the length of this instance. + Enlarging the value of this instance would exceed . + + In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . + + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Text.StringBuilder + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + The position in this instance where insertion begins. + The string to insert. + Inserts a string into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + is not changed if `value` is `null`, or `value` is not `null` but its length is zero. - ]]> - - + ]]> + + is less than zero or greater than the current length of this instance. -or- - The current length of this object plus the length of exceeds . - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - - System.Text.StringBuilder - - - - - - - The position in this instance where insertion begins. - The value to insert. - Inserts the string representation of a 16-bit unsigned integer into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - + The current length of this object plus the length of exceeds . + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + + System.Text.StringBuilder + + + + + + + The position in this instance where insertion begins. + The value to insert. + Inserts the string representation of a 16-bit unsigned integer into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - ]]> - - - is less than zero or greater than the length of this instance. - Enlarging the value of this instance would exceed . - - In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - - System.Text.StringBuilder - - - - - - - The position in this instance where insertion begins. - The value to insert. - Inserts the string representation of a 32-bit unsigned integer into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - + ]]> + + + is less than zero or greater than the length of this instance. + Enlarging the value of this instance would exceed . + + In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + + System.Text.StringBuilder + + + + + + + The position in this instance where insertion begins. + The value to insert. + Inserts the string representation of a 32-bit unsigned integer into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - ]]> - - - is less than zero or greater than the length of this instance. - Enlarging the value of this instance would exceed . - - In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.CLSCompliant(false)] - [<System.CLSCompliant(false)>] - - - - System.Text.StringBuilder - - - - - - - The position in this instance where insertion begins. - The value to insert. - Inserts the string representation of a 64-bit unsigned integer into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - + ]]> + + + is less than zero or greater than the length of this instance. + Enlarging the value of this instance would exceed . + + In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.CLSCompliant(false)] + [<System.CLSCompliant(false)>] + + + + System.Text.StringBuilder + + + + + + + The position in this instance where insertion begins. + The value to insert. + Inserts the string representation of a 64-bit unsigned integer into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - ]]> - - - is less than zero or greater than the length of this instance. - Enlarging the value of this instance would exceed . - - In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . - - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Text.StringBuilder - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - The position in this instance where insertion begins. - The string to insert. - The number of times to insert . - Inserts one or more copies of a specified string into this instance at the specified character position. - A reference to this instance after insertion has completed. - + ]]> + + + is less than zero or greater than the length of this instance. + Enlarging the value of this instance would exceed . + + In the .NET Framework 3.5 Service Pack 1 and earlier versions, calls to this method threw an if inserting would cause the object's total length to exceed . Starting with the .NET Framework 4, the method throws an . + + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Text.StringBuilder + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + The position in this instance where insertion begins. + The string to insert. + The number of times to insert . + Inserts one or more copies of a specified string into this instance at the specified character position. + A reference to this instance after insertion has completed. + object is not changed if `value` is `null`, `value` is not `null` but its length is zero, or `count` is zero. - ]]> - - + ]]> + + is less than zero or greater than the current length of this instance. -or- - is less than zero. - The current length of this object plus the length of times exceeds . - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Text.StringBuilder - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - The position in this instance where insertion begins. - A character array. - The starting index within . - The number of characters to insert. - Inserts the string representation of a specified subarray of Unicode characters into this instance at the specified character position. - A reference to this instance after the insert operation has completed. - + is less than zero. + The current length of this object plus the length of times exceeds . + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Text.StringBuilder + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + The position in this instance where insertion begins. + A character array. + The starting index within . + The number of characters to insert. + Inserts the string representation of a specified subarray of Unicode characters into this instance at the specified character position. + A reference to this instance after the insert operation has completed. + - - - is , and and are not zero. - + ]]> + + + is , and and are not zero. + , , or is less than zero. -or- @@ -6497,60 +6265,60 @@ The existing characters are shifted to make room for the character sequence in t -or- - Enlarging the value of this instance would exceed . - - - - - - - - - - Property - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - [set: System.Security.SecuritySafeCritical] - [<set: System.Security.SecuritySafeCritical>] - - - - System.Int32 - - - Gets or sets the length of the current object. - The length of this instance. - + Enlarging the value of this instance would exceed . + + + + + + + + + + Property + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + [set: System.Security.SecuritySafeCritical] + [<set: System.Security.SecuritySafeCritical>] + + + + System.Int32 + + + Gets or sets the length of the current object. + The length of this instance. + - - The value specified for a set operation is less than zero or greater than . - - - - - - - - - - Property - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Int32 - - - Gets the maximum capacity of this instance. - The maximum number of characters this instance can hold. - + ]]> + + The value specified for a set operation is less than zero or greater than . + + + + + + + + + + Property + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Int32 + + + Gets the maximum capacity of this instance. + The maximum number of characters this instance can hold. + object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - ]]> - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Text.StringBuilder - - - - - - - The zero-based position in this instance where removal begins. - The number of characters to remove. - Removes the specified range of characters from this instance. - A reference to this instance after the excise operation has completed. - + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Text.StringBuilder + + + + + + + The zero-based position in this instance where removal begins. + The number of characters to remove. + Removes the specified range of characters from this instance. + A reference to this instance after the excise operation has completed. + - - If or is less than zero, or + is greater than the length of this instance. - - - - - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - - - Replaces all occurrences of a specified character or string in this instance with another specified character or string. - + ]]> + + If or is less than zero, or + is greater than the length of this instance. + + + + + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + + + Replaces all occurrences of a specified character or string in this instance with another specified character or string. + - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Text.StringBuilder - - - - - - - The character to replace. - The character that replaces . - Replaces all occurrences of a specified character in this instance with another specified character. - A reference to this instance with replaced by . - + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Text.StringBuilder + + + + + + + The character to replace. + The character that replaces . + Replaces all occurrences of a specified character in this instance with another specified character. + A reference to this instance with replaced by . + instance is unchanged after the replacement. - ]]> - - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Text.StringBuilder - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - The string to replace. - The string that replaces , or . - Replaces all occurrences of a specified string in this instance with another specified string. - A reference to this instance with all instances of replaced by . - + ]]> + + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Text.StringBuilder + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + The string to replace. + The string that replaces , or . + Replaces all occurrences of a specified string in this instance with another specified string. + A reference to this instance with all instances of replaced by . + , all occurrences of `oldValue` are removed. - ]]> - - - is . - The length of is zero. - Enlarging the value of this instance would exceed . - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Text.StringBuilder - - - - - - - - - The character to replace. - The character that replaces . - The position in this instance where the substring begins. - The length of the substring. - Replaces, within a substring of this instance, all occurrences of a specified character with another specified character. - A reference to this instance with replaced by in the range from to + -1. - + ]]> + + + is . + The length of is zero. + Enlarging the value of this instance would exceed . + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Text.StringBuilder + + + + + + + + + The character to replace. + The character that replaces . + The position in this instance where the substring begins. + The length of the substring. + Replaces, within a substring of this instance, all occurrences of a specified character with another specified character. + A reference to this instance with replaced by in the range from to + -1. + object is unchanged after the replacement. - ]]> - - + ]]> + + + is greater than the length of the value of this instance. -or- - or is less than zero. - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.Text.StringBuilder - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - The string to replace. - The string that replaces , or . - The position in this instance where the substring begins. - The length of the substring. - Replaces, within a substring of this instance, all occurrences of a specified string with another specified string. - A reference to this instance with all instances of replaced by in the range from to + - 1. - + or is less than zero. + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.Text.StringBuilder + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + The string to replace. + The string that replaces , or . + The position in this instance where the substring begins. + The length of the substring. + Replaces, within a substring of this instance, all occurrences of a specified string with another specified string. + A reference to this instance with all instances of replaced by in the range from to + - 1. + , all occurrences of `oldValue` are removed. - ]]> - - - is . - The length of is zero. - + ]]> + + + is . + The length of is zero. + or is less than zero. -or- @@ -7019,60 +6787,60 @@ In .NET Core and in the .NET Framework 4.0 and later versions, when you instanti -or- - Enlarging the value of this instance would exceed . - - - - - - - - - - - Method - - M:System.Runtime.Serialization.ISerializable.GetObjectData(System.Runtime.Serialization.SerializationInfo,System.Runtime.Serialization.StreamingContext) - - - mscorlib - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Security.SecurityCritical] - [<System.Security.SecurityCritical>] - - - - System.Void - - - - - - - The object to populate with serialization information. - The place to store and retrieve serialized data. Reserved for future use. - Populates a object with the data necessary to deserialize the current object. - + Enlarging the value of this instance would exceed . + + + + + + + + + + + Method + + M:System.Runtime.Serialization.ISerializable.GetObjectData(System.Runtime.Serialization.SerializationInfo,System.Runtime.Serialization.StreamingContext) + + + mscorlib + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Security.SecurityCritical] + [<System.Security.SecurityCritical>] + + + + System.Void + + + + + + + The object to populate with serialization information. + The place to store and retrieve serialized data. Reserved for future use. + Populates a object with the data necessary to deserialize the current object. + method. - ]]> - - - is . - - - - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - - - Converts the value of a to a . - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.String - - - - Converts the value of this instance to a . - A string whose value is the same as this instance. - + ]]> + + + is . + + + + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + + + Converts the value of a to a . + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.String + + + + Converts the value of this instance to a . + A string whose value is the same as this instance. + - - - - - - - - - - - Method - - System.Runtime - 4.0.0.0 - 4.0.10.0 - 4.0.20.0 - 4.1.0.0 - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - 1.0.5000.0 - 2.0.0.0 - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - - [System.Security.SecuritySafeCritical] - [<System.Security.SecuritySafeCritical>] - - - - System.String - - - - - - - The starting position of the substring in this instance. - The length of the substring. - Converts the value of a substring of this instance to a . - A string whose value is the same as the specified substring of this instance. - + ]]> + + + + + + + + + + + Method + + System.Runtime + 4.0.0.0 + 4.0.10.0 + 4.0.20.0 + 4.1.0.0 + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + 1.0.5000.0 + 2.0.0.0 + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + + [System.Security.SecuritySafeCritical] + [<System.Security.SecuritySafeCritical>] + + + + System.String + + + + + + + The starting position of the substring in this instance. + The length of the substring. + Converts the value of a substring of this instance to a . + A string whose value is the same as the specified substring of this instance. + method to convert the object to a object before you can pass the string represented by the object to a method that has a parameter or display it in the user interface. - ]]> - - + ]]> + + or is less than zero. -or- - The sum of and is greater than the length of the current instance. - - - - + The sum of and is greater than the length of the current instance. + + + + diff --git a/xml/System.Threading.Tasks/Task.xml b/xml/System.Threading.Tasks/Task.xml index 5df7c27cd2c..0deb71f34fa 100644 --- a/xml/System.Threading.Tasks/Task.xml +++ b/xml/System.Threading.Tasks/Task.xml @@ -1,253 +1,145 @@ - - - - - - - - - - - - - - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - - - - - - - - - - - - - - System.Object - - - - System.IAsyncResult - - - System.IDisposable - - - - - [System.Runtime.CompilerServices.Nullable(0)] - [<System.Runtime.CompilerServices.Nullable(0)>] - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - [System.Diagnostics.DebuggerDisplay("Id = {Id}, Status = {Status}, Method = {DebuggerDisplayMethodDescription}")] - [<System.Diagnostics.DebuggerDisplay("Id = {Id}, Status = {Status}, Method = {DebuggerDisplayMethodDescription}")>] - - - [System.Diagnostics.DebuggerTypeProxy(typeof(System.Threading.Tasks.SystemThreadingTasks_TaskDebugView))] - [<System.Diagnostics.DebuggerTypeProxy(typeof(System.Threading.Tasks.SystemThreadingTasks_TaskDebugView))>] - - - - Represents an asynchronous operation. - - class represents a single operation that does not return a value and that usually executes asynchronously. objects are one of the central components of the [task-based asynchronous pattern](/dotnet/standard/asynchronous-programming-patterns/task-based-asynchronous-pattern-tap) first introduced in the .NET Framework 4. Because the work performed by a object typically executes asynchronously on a thread pool thread rather than synchronously on the main application thread, you can use the property, as well as the , , and properties, to determine the state of a task. Most commonly, a lambda expression is used to specify the work that the task is to perform. - - For operations that return values, you use the class. - - In this section: - - [Task instantiation examples](#Instant) - [Creating and executing a task](#Creating) - [Separating task creation and execution](#Separating) - [Waiting for one or more tasks to complete](#WaitingForOne) - [Tasks and culture](#Culture) - [For debugger developers](#Debugger) - - -## Task instantiation - The following example creates and executes four tasks. Three tasks execute an delegate named `action`, which accepts an argument of type . A fourth task executes a lambda expression (an delegate) that is defined inline in the call to the task creation method. Each task is instantiated and run in a different way: - -- Task `t1` is instantiated by calling a Task class constructor, but is started by calling its method only after task `t2` has started. - -- Task `t2` is instantiated and started in a single method call by calling the method. - -- Task `t3` is instantiated and started in a single method call by calling the method. - -- Task `t4` is executed synchronously on the main thread by calling the method. - - Because task `t4` executes synchronously, it executes on the main application thread. The remaining tasks execute asynchronously typically on one or more thread pool threads. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Overview/startnew.cs" id="Snippet01"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Overview/startnew.fs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task/vb/startnew.vb" id="Snippet01"::: - - -## Creating and executing a task - -You can create instances in a variety of ways. The most common approach is to call the static method. The method provides a simple way to start a task using default values and without requiring additional parameters. The following example uses the method to start a task that loops and then displays the number of loop iterations: - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Overview/run1.cs" id="Snippet6"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Overview/run1.fs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task/vb/run1.vb" id="Snippet6"::: - - An alternative is the static method. The property returns a object. Overloads of the method let you specify parameters to pass to the task creation options and a task scheduler. The following example uses the method to start a task. It is functionally equivalent to the code in the previous example. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Overview/startnew1.cs" id="Snippet7"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Overview/startnew1.fs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task/vb/startnew1.vb" id="Snippet7"::: - - For more complete examples, see [Task-based Asynchronous Programming](/dotnet/standard/parallel-programming/task-based-asynchronous-programming). - - -## Separating task creation and execution - The class also provides constructors that initialize the task but that do not schedule it for execution. For performance reasons, the or method is the preferred mechanism for creating and scheduling computational tasks, but for scenarios where creation and scheduling must be separated, you can use the constructors and then call the method to schedule the task for execution at a later time. - - -## Waiting for one or more tasks to complete - Because tasks typically run asynchronously on a thread pool thread, the thread that creates and starts the task continues execution as soon as the task has been instantiated. In some cases, when the calling thread is the main application thread, the app may terminate before the task actually begins execution. In others, your application's logic may require that the calling thread continue execution only when one or more tasks have completed execution. You can synchronize the execution of the calling thread and the asynchronous tasks it launches by calling a `Wait` method to wait for one or more tasks to complete. - - To wait for a single task to complete, you can call its method. A call to the method blocks the calling thread until the single class instance has completed execution. - - The following example calls the parameterless method to wait unconditionally until a task completes. The task simulates work by calling the method to sleep for two seconds. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Overview/Wait1.cs" id="Snippet8"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Overview/Wait1.fs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task/vb/Wait1.vb" id="Snippet8"::: - - You can also conditionally wait for a task to complete. The and methods block the calling thread until the task finishes or a timeout interval elapses, whichever comes first. Since the following example launches a task that sleeps for two seconds but defines a one-second timeout value, the calling thread blocks until the timeout expires and before the task has completed execution. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Overview/Wait2.cs" id="Snippet9"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Overview/Wait2.fs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task/vb/Wait2.vb" id="Snippet9"::: - - You can also supply a cancellation token by calling the and methods. If the token's property is `true` or becomes `true` while the method is executing, the method throws an . - - In some cases, you may want to wait for the first of a series of executing tasks to complete, but don't care which task it is. For this purpose, you can call one of the overloads of the method. The following example creates three tasks, each of which sleeps for an interval determined by a random number generator. The method waits for the first task to complete. The example then displays information about the status of all three tasks. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Overview/WhenAny1.cs" id="Snippet10"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Overview/WhenAny1.fs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task/vb/WaitAny1.vb" id="Snippet10"::: - - You can also wait for all of a series of tasks to complete by calling the method. The following example creates ten tasks, waits for all ten to complete, and then displays their status. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Overview/WaitAll1.cs" id="Snippet11"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Overview/WaitAll1.fs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task/vb/WaitAll1.vb" id="Snippet11"::: - - Note that when you wait for one or more tasks to complete, any exceptions thrown in the running tasks are propagated on the thread that calls the `Wait` method, as the following example shows. It launches 12 tasks, three of which complete normally and three of which throw an exception. Of the remaining six tasks, three are cancelled before they start, and three are cancelled while they are executing. Exceptions are thrown in the method call and are handled by a `try`/`catch` block. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Overview/WaitAll2.cs" id="Snippet12"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Overview/WaitAll2.fs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task/vb/WaitAll2.vb" id="Snippet12"::: - - For more information on exception handling in task-based asynchronous operations, see [Exception Handling](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library). - - -## Tasks and culture - Starting with desktop apps that target the .NET Framework 4.6, the culture of the thread that creates and invokes a task becomes part of the thread's context. That is, regardless of the current culture of the thread on which the task executes, the current culture of the task is the culture of the calling thread. For apps that target versions of the .NET Framework prior to the .NET Framework 4.6, the culture of the task is the culture of the thread on which the task executes. For more information, see the "Culture and task-based asynchronous operations" section in the topic. - -> [!NOTE] -> Store apps follow the Windows Runtime in setting and getting the default culture. - - -## For debugger developers - For developers implementing custom debuggers, several internal and private members of task may be useful (these may change from release to release). The `m_taskId` field serves as the backing store for the property, however accessing this field directly from a debugger may be more efficient than accessing the same value through the property's getter method (the `s_taskIdCounter` counter is used to retrieve the next available ID for a task). Similarly, the `m_stateFlags` field stores information about the current lifecycle stage of the task, information also accessible through the property. The `m_action` field stores a reference to the task's delegate, and the `m_stateObject` field stores the async state passed to the task by the developer. Finally, for debuggers that parse stack frames, the `InternalWait` method serves a potential marker for when a task is entering a wait operation. - - ]]> - - All members of , except for , are thread-safe and may be used from multiple threads concurrently. - - Task Parallel Library (TPL) - Task-based asynchronous pattern (TAP) in .NET: Introduction and overview - Task-based Asynchronous Programming - Samples for Parallel Programming with the .NET Core and .NET Standard - - - - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - Initializes a new . - - - - - - - - - - Constructor - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - - - The delegate that represents the code to execute in the task. - Initializes a new with the specified action. - + + + + + + + + + + + + + + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + + + + + + + + + + + + + + System.Object + + + + System.IAsyncResult + + + System.IDisposable + + + + + [System.Runtime.CompilerServices.Nullable(0)] + [<System.Runtime.CompilerServices.Nullable(0)>] + + + [System.Runtime.CompilerServices.NullableContext(1)] + [<System.Runtime.CompilerServices.NullableContext(1)>] + + + [System.Diagnostics.DebuggerDisplay("Id = {Id}, Status = {Status}, Method = {DebuggerDisplayMethodDescription}")] + [<System.Diagnostics.DebuggerDisplay("Id = {Id}, Status = {Status}, Method = {DebuggerDisplayMethodDescription}")>] + + + [System.Diagnostics.DebuggerTypeProxy(typeof(System.Threading.Tasks.SystemThreadingTasks_TaskDebugView))] + [<System.Diagnostics.DebuggerTypeProxy(typeof(System.Threading.Tasks.SystemThreadingTasks_TaskDebugView))>] + + + + Represents an asynchronous operation. + For more information about this API, see Supplemental API remarks for Task. + All members of , except for , are thread-safe and may be used from multiple threads concurrently. + + Task Parallel Library (TPL) + Task-based asynchronous pattern (TAP) in .NET: Introduction and overview + Task-based Asynchronous Programming + Samples for Parallel Programming with the .NET Core and .NET Standard + + + + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + Initializes a new . + + + + + + + + + + Constructor + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + + + The delegate that represents the code to execute in the task. + Initializes a new with the specified action. + instances in a variety of ways :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/run2.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.run/vb/run2.vb" id="Snippet1"::: - ]]> - - The argument is . - - - - - - - - - - - Constructor - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - - - - The delegate that represents the code to execute in the task. - The that the new task will observe. - Initializes a new with the specified action and . - + ]]> + + The argument is . + + + + + + + + + + + Constructor + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + + + + The delegate that represents the code to execute in the task. + The that the new task will observe. + Initializes a new with the specified action and . + instances in a variety of ways :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/run4.fs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.ctor/vb/run4.vb" id="Snippet4"::: - ]]> - - The provided has already been disposed. - The argument is null. - - - - - - - - - - Constructor - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - - - - The delegate that represents the code to execute in the task. - The used to customize the task's behavior. - Initializes a new with the specified action and creation options. - + ]]> + + The provided has already been disposed. + The argument is null. + + + + + + + + + + Constructor + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + + + + The delegate that represents the code to execute in the task. + The used to customize the task's behavior. + Initializes a new with the specified action and creation options. + object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. - ]]> - - The argument is null. - The argument specifies an invalid value for . - - - - - - - - - - - Constructor - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] - - - - - - - The delegate that represents the code to execute in the task. - An object representing data to be used by the action. - Initializes a new with the specified action and state. - + ]]> + + The argument is null. + The argument specifies an invalid value for . + + + + + + + + + + + Constructor + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] + + + + + + + The delegate that represents the code to execute in the task. + An object representing data to be used by the action. + Initializes a new with the specified action and state. + instances in a variety of ways :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/startnew3.fs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.ctor/vb/startnew3.vb" id="Snippet3"::: - ]]> - - The argument is null. - - - - - - - - - - - Constructor - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - - - - - The delegate that represents the code to execute in the task. - The that the new task will observe. - The used to customize the task's behavior. - Initializes a new with the specified action and creation options. - + ]]> + + The argument is null. + + + + + + + + + + + Constructor + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + + + + + The delegate that represents the code to execute in the task. + The that the new task will observe. + The used to customize the task's behavior. + Initializes a new with the specified action and creation options. + instances in a variety of ways For more information, see [Task Parallelism (Task Parallel Library)](/dotnet/standard/parallel-programming/task-based-asynchronous-programming) and [Task Cancellation](/dotnet/standard/parallel-programming/task-cancellation). - ]]> - - The that created has already been disposed. - The argument is null. - The argument specifies an invalid value for . - - - - - - - - - - - Constructor - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] - - - - - - - - The delegate that represents the code to execute in the task. - An object representing data to be used by the action. - The that the new task will observe. - Initializes a new with the specified action, state, and options. - + ]]> + + The that created has already been disposed. + The argument is null. + The argument specifies an invalid value for . + + + + + + + + + + + Constructor + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] + + + + + + + + The delegate that represents the code to execute in the task. + An object representing data to be used by the action. + The that the new task will observe. + Initializes a new with the specified action, state, and options. + object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. - ]]> - - The that created has already been disposed. - The argument is null. - - - - - - - - - - - Constructor - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] - - - - - - - - The delegate that represents the code to execute in the task. - An object representing data to be used by the action. - The used to customize the task's behavior. - Initializes a new with the specified action, state, and options. - + ]]> + + The that created has already been disposed. + The argument is null. + + + + + + + + + + + Constructor + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] + + + + + + + + The delegate that represents the code to execute in the task. + An object representing data to be used by the action. + The used to customize the task's behavior. + Initializes a new with the specified action, state, and options. + object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. - ]]> - - The argument is null. - The argument specifies an invalid value for . - - - - - - - - - - - Constructor - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] - - - - - - - - - The delegate that represents the code to execute in the task. - An object representing data to be used by the action. - The that the new task will observe. - The used to customize the task's behavior. - Initializes a new with the specified action, state, and options. - + ]]> + + The argument is null. + The argument specifies an invalid value for . + + + + + + + + + + + Constructor + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] + + + + + + + + + The delegate that represents the code to execute in the task. + An object representing data to be used by the action. + The that the new task will observe. + The used to customize the task's behavior. + Initializes a new with the specified action, state, and options. + object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. - ]]> - - The that created has already been disposed. - The argument is null. - The argument specifies an invalid value for . - - - - - - - - - - - Property - - P:System.IAsyncResult.AsyncState - - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - [get: System.Runtime.CompilerServices.NullableContext(2)] - [<get: System.Runtime.CompilerServices.NullableContext(2)>] - - - - System.Object - - - Gets the state object supplied when the was created, or null if none was supplied. - An that represents the state data that was passed in to the task when it was created. - + ]]> + + The that created has already been disposed. + The argument is null. + The argument specifies an invalid value for . + + + + + + + + + + + Property + + P:System.IAsyncResult.AsyncState + + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + [get: System.Runtime.CompilerServices.NullableContext(2)] + [<get: System.Runtime.CompilerServices.NullableContext(2)>] + + + + System.Object + + + Gets the state object supplied when the was created, or null if none was supplied. + An that represents the state data that was passed in to the task when it was created. + - - - - - - - - - - - Property - - System.Threading.Tasks - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task - - - Gets a task that has already completed successfully. - The successfully completed task. - + ]]> + + + + + + + + + + + Property + + System.Threading.Tasks + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task + + + Gets a task that has already completed successfully. + The successfully completed task. + - - - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Runtime.CompilerServices.ConfiguredTaskAwaitable - - - - - - - to attempt to marshal the continuation back to the original context captured; otherwise, . - Configures an awaiter used to await this . - An object used to await this task. - + ]]> + + + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Runtime.CompilerServices.ConfiguredTaskAwaitable + + + + + + + to attempt to marshal the continuation back to the original context captured; otherwise, . + Configures an awaiter used to await this . + An object used to await this task. + directly, continuation usually occurs in the same thread that created the task, depending on the async context. This behavior can be costly in terms of performance and can result in a deadlock on the UI thread. To avoid these problems, call `Task.ConfigureAwait(false)`. For more information, see [ConfigureAwait FAQ](https://devblogs.microsoft.com/dotnet/configureawait-faq/). - ]]> - - ConfigureAwait FAQ - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Threading.Tasks - - - mscorlib - - - netstandard - - - System.Runtime.CompilerServices.ConfiguredTaskAwaitable - - - - - - Options used to configure how awaits on this task are performed. - Configures an awaiter used to await this . - An object used to await this task. - To be added. - The argument specifies an invalid value. - - - - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - Creates a continuation that executes asynchronously when the target completes. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task - - - - - - An action to run when the completes. When run, the delegate will be passed the completed task as an argument. - Creates a continuation that executes asynchronously when the target completes. - A new continuation . - + ]]> + + ConfigureAwait FAQ + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Threading.Tasks + + + mscorlib + + + netstandard + + + System.Runtime.CompilerServices.ConfiguredTaskAwaitable + + + + + + Options used to configure how awaits on this task are performed. + Configures an awaiter used to await this . + An object used to await this task. + To be added. + The argument specifies an invalid value. + + + + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + Creates a continuation that executes asynchronously when the target completes. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task + + + + + + An action to run when the completes. When run, the delegate will be passed the completed task as an argument. + Creates a continuation that executes asynchronously when the target completes. + A new continuation . + directly For an additional example, see [Chaining Tasks by Using Continuation Tasks](/dotnet/standard/parallel-programming/chaining-tasks-by-using-continuation-tasks). - ]]> - - The argument is . - - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2 })>] - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - An action to run when the task completes. When run, the delegate is passed the completed task and a caller-supplied state object as arguments. - An object representing data to be used by the continuation action. - Creates a continuation that receives caller-supplied state information and executes when the target completes. - A new continuation task. - + ]]> + + The argument is . + + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2 })>] + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + An action to run when the task completes. When run, the delegate is passed the completed task and a caller-supplied state object as arguments. + An object representing data to be used by the continuation action. + Creates a continuation that receives caller-supplied state information and executes when the target completes. + A new continuation task. + will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting early due to cancellation. - ]]> - - The argument is . - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task - - - - - - - An action to run when the completes. When run, the delegate will be passed the completed task as an argument. - The that will be assigned to the new continuation task. - Creates a continuation that receives a cancellation token and executes asynchronously when the target completes. - A new continuation . - + ]]> + + The argument is . + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task + + + + + + + An action to run when the completes. When run, the delegate will be passed the completed task as an argument. + The that will be assigned to the new continuation task. + Creates a continuation that receives a cancellation token and executes asynchronously when the target completes. + A new continuation . + will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. - ]]> - - The that created the token has already been disposed. - The argument is null. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task - - - - - - - An action to run according to the specified . When run, the delegate will be passed the completed task as an argument. - Options for when the continuation is scheduled and how it behaves. This includes criteria, such as , as well as execution options, such as . - Creates a continuation that executes when the target task completes according to the specified . - A new continuation . - + ]]> + + The that created the token has already been disposed. + The argument is null. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task + + + + + + + An action to run according to the specified . When run, the delegate will be passed the completed task as an argument. + Options for when the continuation is scheduled and how it behaves. This includes criteria, such as , as well as execution options, such as . + Creates a continuation that executes when the target task completes according to the specified . + A new continuation . + - - The argument is null. - The argument specifies an invalid value for . - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task - - - - - - - An action to run when the completes. When run, the delegate will be passed the completed task as an argument. - The to associate with the continuation task and to use for its execution. - Creates a continuation that executes asynchronously when the target completes. The continuation uses a specified scheduler. - A new continuation . - + ]]> + + The argument is null. + The argument specifies an invalid value for . + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task + + + + + + + An action to run when the completes. When run, the delegate will be passed the completed task as an argument. + The to associate with the continuation task and to use for its execution. + Creates a continuation that executes asynchronously when the target completes. The continuation uses a specified scheduler. + A new continuation . + will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. - ]]> - - The has been disposed. + ]]> + + The has been disposed. The argument is . -or- - The argument is null. - - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2 })>] - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - An action to run when the completes. When run, the delegate will be passed the completed task and the caller-supplied state object as arguments. - An object representing data to be used by the continuation action. - The that will be assigned to the new continuation task. - Creates a continuation that receives caller-supplied state information and a cancellation token and that executes asynchronously when the target completes. - A new continuation . - + The argument is null. + + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2 })>] + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + An action to run when the completes. When run, the delegate will be passed the completed task and the caller-supplied state object as arguments. + An object representing data to be used by the continuation action. + The that will be assigned to the new continuation task. + Creates a continuation that receives caller-supplied state information and a cancellation token and that executes asynchronously when the target completes. + A new continuation . + will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. - ]]> - - The argument is . - The provided has already been disposed. - - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2 })>] - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - An action to run when the completes. When run, the delegate will be passed the completed task and the caller-supplied state object as arguments. - An object representing data to be used by the continuation action. - Options for when the continuation is scheduled and how it behaves. This includes criteria, such as , as well as execution options, such as . - Creates a continuation that receives caller-supplied state information and executes when the target completes. The continuation executes based on a set of specified conditions. - A new continuation . - + ]]> + + The argument is . + The provided has already been disposed. + + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2 })>] + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + An action to run when the completes. When run, the delegate will be passed the completed task and the caller-supplied state object as arguments. + An object representing data to be used by the continuation action. + Options for when the continuation is scheduled and how it behaves. This includes criteria, such as , as well as execution options, such as . + Creates a continuation that receives caller-supplied state information and executes when the target completes. The continuation executes based on a set of specified conditions. + A new continuation . + will not be scheduled for execution until the current task has completed. If the continuation criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. - ]]> - - The argument is . - The argument specifies an invalid value for . - - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2 })>] - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - An action to run when the completes. When run, the delegate will be passed the completed task and the caller-supplied state object as arguments. - An object representing data to be used by the continuation action. - The to associate with the continuation task and to use for its execution. - Creates a continuation that receives caller-supplied state information and executes asynchronously when the target completes. The continuation uses a specified scheduler. - A new continuation . - + ]]> + + The argument is . + The argument specifies an invalid value for . + + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2 })>] + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + An action to run when the completes. When run, the delegate will be passed the completed task and the caller-supplied state object as arguments. + An object representing data to be used by the continuation action. + The to associate with the continuation task and to use for its execution. + Creates a continuation that receives caller-supplied state information and executes asynchronously when the target completes. The continuation uses a specified scheduler. + A new continuation . + will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. - ]]> - - The argument is . - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task - - - - - - - - - An action to run according to the specified . When run, the delegate will be passed the completed task as an argument. - The that will be assigned to the new continuation task. - Options for when the continuation is scheduled and how it behaves. This includes criteria, such as , as well as execution options, such as . - The to associate with the continuation task and to use for its execution. - Creates a continuation that executes when the target task competes according to the specified . The continuation receives a cancellation token and uses a specified scheduler. - A new continuation . - + ]]> + + The argument is . + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task + + + + + + + + + An action to run according to the specified . When run, the delegate will be passed the completed task as an argument. + The that will be assigned to the new continuation task. + Options for when the continuation is scheduled and how it behaves. This includes criteria, such as , as well as execution options, such as . + The to associate with the continuation task and to use for its execution. + Creates a continuation that executes when the target task competes according to the specified . The continuation receives a cancellation token and uses a specified scheduler. + A new continuation . + - - The that created the token has already been disposed. + ]]> + + The that created the token has already been disposed. The argument is null. -or- - The argument is null. - The argument specifies an invalid value for . - - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2 })>] - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - An action to run when the completes. When run, the delegate will be passed the completed task and the caller-supplied state object as arguments. - An object representing data to be used by the continuation action. - The that will be assigned to the new continuation task. - Options for when the continuation is scheduled and how it behaves. This includes criteria, such as , as well as execution options, such as . - The to associate with the continuation task and to use for its execution. - Creates a continuation that receives caller-supplied state information and a cancellation token and that executes when the target completes. The continuation executes based on a set of specified conditions and uses a specified scheduler. - A new continuation . - + The argument is null. + The argument specifies an invalid value for . + + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2 })>] + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + An action to run when the completes. When run, the delegate will be passed the completed task and the caller-supplied state object as arguments. + An object representing data to be used by the continuation action. + The that will be assigned to the new continuation task. + Options for when the continuation is scheduled and how it behaves. This includes criteria, such as , as well as execution options, such as . + The to associate with the continuation task and to use for its execution. + Creates a continuation that receives caller-supplied state information and a cancellation token and that executes when the target completes. The continuation executes based on a set of specified conditions and uses a specified scheduler. + A new continuation . + will not be scheduled for execution until the current task has completed. If the criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. - ]]> - - The argument is . - The argument specifies an invalid value for . - The provided has already been disposed. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task<TResult> - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - The type of the result produced by the continuation. - A function to run when the completes. When run, the delegate will be passed the completed task as an argument. - Creates a continuation that executes asynchronously when the target completes and returns a value. - A new continuation task. - + ]]> + + The argument is . + The argument specifies an invalid value for . + The provided has already been disposed. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task<TResult> + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + The type of the result produced by the continuation. + A function to run when the completes. When run, the delegate will be passed the completed task as an argument. + Creates a continuation that executes asynchronously when the target completes and returns a value. + A new continuation task. + - - The has been disposed. - The argument is null. - - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - - System.Threading.Tasks.Task<TResult> - - - - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2, 1 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2, 1 })>] - - - - - - - The type of the result produced by the continuation. - A function to run when the completes. When run, the delegate will be passed the completed task and the caller-supplied state object as arguments. - An object representing data to be used by the continuation function. - Creates a continuation that receives caller-supplied state information and executes asynchronously when the target completes and returns a value. - A new continuation . - + ]]> + + The has been disposed. + The argument is null. + + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + + System.Threading.Tasks.Task<TResult> + + + + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2, 1 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2, 1 })>] + + + + + + + The type of the result produced by the continuation. + A function to run when the completes. When run, the delegate will be passed the completed task and the caller-supplied state object as arguments. + An object representing data to be used by the continuation function. + Creates a continuation that receives caller-supplied state information and executes asynchronously when the target completes and returns a value. + A new continuation . + will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. - ]]> - - The argument is . - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task<TResult> - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - - The type of the result produced by the continuation. - A function to run when the completes. When run, the delegate will be passed the completed task as an argument. - The that will be assigned to the new continuation task. - Creates a continuation that executes asynchronously when the target completes and returns a value. The continuation receives a cancellation token. - A new continuation . - + ]]> + + The argument is . + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task<TResult> + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + + The type of the result produced by the continuation. + A function to run when the completes. When run, the delegate will be passed the completed task as an argument. + The that will be assigned to the new continuation task. + Creates a continuation that executes asynchronously when the target completes and returns a value. The continuation receives a cancellation token. + A new continuation . + will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. - ]]> - + ]]> + The has been disposed. -or- - The that created the token has already been disposed. - The argument is null. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task<TResult> - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - - The type of the result produced by the continuation. - A function to run according to the condition specified in . When run, the delegate will be passed the completed task as an argument. - Options for when the continuation is scheduled and how it behaves. This includes criteria, such as , as well as execution options, such as . - Creates a continuation that executes according to the specified continuation options and returns a value. - A new continuation . - + The that created the token has already been disposed. + The argument is null. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task<TResult> + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + + The type of the result produced by the continuation. + A function to run according to the condition specified in . When run, the delegate will be passed the completed task as an argument. + Options for when the continuation is scheduled and how it behaves. This includes criteria, such as , as well as execution options, such as . + Creates a continuation that executes according to the specified continuation options and returns a value. + A new continuation . + will not be scheduled for execution until the current task has completed. If the continuation criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. - ]]> - - The has been disposed. - The argument is null. - The argument specifies an invalid value for . - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task<TResult> - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - - The type of the result produced by the continuation. - A function to run when the completes. When run, the delegate will be passed the completed task as an argument. - The to associate with the continuation task and to use for its execution. - Creates a continuation that executes asynchronously when the target completes and returns a value. The continuation uses a specified scheduler. - A new continuation . - + ]]> + + The has been disposed. + The argument is null. + The argument specifies an invalid value for . + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task<TResult> + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + + The type of the result produced by the continuation. + A function to run when the completes. When run, the delegate will be passed the completed task as an argument. + The to associate with the continuation task and to use for its execution. + Creates a continuation that executes asynchronously when the target completes and returns a value. The continuation uses a specified scheduler. + A new continuation . + will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. - ]]> - - The has been disposed. + ]]> + + The has been disposed. The argument is null. -or- - The argument is null. - - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - - System.Threading.Tasks.Task<TResult> - - - - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2, 1 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2, 1 })>] - - - - - - - - The type of the result produced by the continuation. - A function to run when the completes. When run, the delegate will be passed the completed task and the caller-supplied state object as arguments. - An object representing data to be used by the continuation function. - The that will be assigned to the new continuation task. - Creates a continuation that executes asynchronously when the target completes and returns a value. The continuation receives caller-supplied state information and a cancellation token. - A new continuation . - + The argument is null. + + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + + System.Threading.Tasks.Task<TResult> + + + + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2, 1 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2, 1 })>] + + + + + + + + The type of the result produced by the continuation. + A function to run when the completes. When run, the delegate will be passed the completed task and the caller-supplied state object as arguments. + An object representing data to be used by the continuation function. + The that will be assigned to the new continuation task. + Creates a continuation that executes asynchronously when the target completes and returns a value. The continuation receives caller-supplied state information and a cancellation token. + A new continuation . + will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. - ]]> - - The argument is . - The provided has already been disposed. - - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - - System.Threading.Tasks.Task<TResult> - - - - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2, 1 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2, 1 })>] - - - - - - - - The type of the result produced by the continuation. - A function to run when the completes. When run, the delegate will be passed the completed task and the caller-supplied state object as arguments. - An object representing data to be used by the continuation function. - Options for when the continuation is scheduled and how it behaves. This includes criteria, such as , as well as execution options, such as . - Creates a continuation that executes based on the specified task continuation options when the target completes. The continuation receives caller-supplied state information. - A new continuation . - + ]]> + + The argument is . + The provided has already been disposed. + + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.CompilerServices.NullableContext(2)] + [<System.Runtime.CompilerServices.NullableContext(2)>] + + + + System.Threading.Tasks.Task<TResult> + + + + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2, 1 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2, 1 })>] + + + + + + + + The type of the result produced by the continuation. + A function to run when the completes. When run, the delegate will be passed the completed task and the caller-supplied state object as arguments. + An object representing data to be used by the continuation function. + Options for when the continuation is scheduled and how it behaves. This includes criteria, such as , as well as execution options, such as . + Creates a continuation that executes based on the specified task continuation options when the target completes. The continuation receives caller-supplied state information. + A new continuation . + will not be scheduled for execution until the current task has completed. If the continuation criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. - ]]> - - The argument is . - The argument specifies an invalid value for . - - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task<TResult> - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2, 1 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2, 1 })>] - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - The type of the result produced by the continuation. - A function to run when the completes. When run, the delegate will be passed the completed task and the caller-supplied state object as arguments. - An object representing data to be used by the continuation function. - The to associate with the continuation task and to use for its execution. - Creates a continuation that executes asynchronously when the target completes. The continuation receives caller-supplied state information and uses a specified scheduler. - A new continuation . - + ]]> + + The argument is . + The argument specifies an invalid value for . + + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task<TResult> + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2, 1 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2, 1 })>] + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + The type of the result produced by the continuation. + A function to run when the completes. When run, the delegate will be passed the completed task and the caller-supplied state object as arguments. + An object representing data to be used by the continuation function. + The to associate with the continuation task and to use for its execution. + Creates a continuation that executes asynchronously when the target completes. The continuation receives caller-supplied state information and uses a specified scheduler. + A new continuation . + will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. - ]]> - - The argument is . - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task<TResult> - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - - - - The type of the result produced by the continuation. - A function to run according to the specified continuationOptions. When run, the delegate will be passed the completed task as an argument. - The that will be assigned to the new continuation task. - Options for when the continuation is scheduled and how it behaves. This includes criteria, such as , as well as execution options, such as . - The to associate with the continuation task and to use for its execution. - Creates a continuation that executes according to the specified continuation options and returns a value. The continuation is passed a cancellation token and uses a specified scheduler. - A new continuation . - + ]]> + + The argument is . + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task<TResult> + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + + + + The type of the result produced by the continuation. + A function to run according to the specified continuationOptions. When run, the delegate will be passed the completed task as an argument. + The that will be assigned to the new continuation task. + Options for when the continuation is scheduled and how it behaves. This includes criteria, such as , as well as execution options, such as . + The to associate with the continuation task and to use for its execution. + Creates a continuation that executes according to the specified continuation options and returns a value. The continuation is passed a cancellation token and uses a specified scheduler. + A new continuation . + - + ]]> + The has been disposed. -or- - The that created the token has already been disposed. + The that created the token has already been disposed. The argument is null. -or- - The argument is null. - The argument specifies an invalid value for . - - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task<TResult> - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2, 1 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2, 1 })>] - - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - The type of the result produced by the continuation. - A function to run when the completes. When run, the delegate will be passed the completed task and the caller-supplied state object as arguments. - An object representing data to be used by the continuation function. - The that will be assigned to the new continuation task. - Options for when the continuation is scheduled and how it behaves. This includes criteria, such as , as well as execution options, such as . - The to associate with the continuation task and to use for its execution. - Creates a continuation that executes based on the specified task continuation options when the target completes and returns a value. The continuation receives caller-supplied state information and a cancellation token and uses the specified scheduler. - A new continuation . - + The argument is null. + The argument specifies an invalid value for . + + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task<TResult> + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2, 1 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 1, 2, 1 })>] + + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + The type of the result produced by the continuation. + A function to run when the completes. When run, the delegate will be passed the completed task and the caller-supplied state object as arguments. + An object representing data to be used by the continuation function. + The that will be assigned to the new continuation task. + Options for when the continuation is scheduled and how it behaves. This includes criteria, such as , as well as execution options, such as . + The to associate with the continuation task and to use for its execution. + Creates a continuation that executes based on the specified task continuation options when the target completes and returns a value. The continuation receives caller-supplied state information and a cancellation token and uses the specified scheduler. + A new continuation . + will not be scheduled for execution until the current task has completed. If the criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. - ]]> - - The argument is . - The argument specifies an invalid value for . - The provided has already been disposed. - - - - - - - - - - Property - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.TaskCreationOptions - - - Gets the used to create this task. - The used to create this task. - To be added. - - - - - - - - - - Property - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Nullable<System.Int32> - - - Returns the ID of the currently executing . - An integer that was assigned by the system to the currently-executing task. - + ]]> + + The argument is . + The argument specifies an invalid value for . + The provided has already been disposed. + + + + + + + + + + Property + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.TaskCreationOptions + + + Gets the used to create this task. + The used to create this task. + To be added. + + + + + + + + + + Property + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Nullable<System.Int32> + + + Returns the ID of the currently executing . + An integer that was assigned by the system to the currently-executing task. + - - - - - - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - Creates a task that will complete after a time delay. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task - - - - - - The number of milliseconds to wait before completing the returned task, or -1 to wait indefinitely. - Creates a task that completes after a specified number of milliseconds. - A task that represents the time delay. - + ]]> + + + + + + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + Creates a task that will complete after a time delay. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task + + + + + + The number of milliseconds to wait before completing the returned task, or -1 to wait indefinitely. + Creates a task that completes after a specified number of milliseconds. + A task that represents the time delay. + - - The argument is less than -1. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task - - - - - - The time span to wait before completing the returned task, or to wait indefinitely. - Creates a task that completes after a specified time interval. - A task that represents the time delay. - + ]]> + + The argument is less than -1. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task + + + + + + The time span to wait before completing the returned task, or to wait indefinitely. + Creates a task that completes after a specified time interval. + A task that represents the time delay. + - - + ]]> + + represents a negative time interval other than . -or- - The argument's property is greater than 4294967294 on .NET 6 and later versions, or Int32.MaxValue on all previous versions. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task - - - - - - - The number of milliseconds to wait before completing the returned task, or -1 to wait indefinitely. - A cancellation token to observe while waiting for the task to complete. - Creates a cancellable task that completes after a specified number of milliseconds. - A task that represents the time delay. - + The argument's property is greater than 4294967294 on .NET 6 and later versions, or Int32.MaxValue on all previous versions. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task + + + + + + + The number of milliseconds to wait before completing the returned task, or -1 to wait indefinitely. + A cancellation token to observe while waiting for the task to complete. + Creates a cancellable task that completes after a specified number of milliseconds. + A task that represents the time delay. + - - The argument is less than -1. - The task has been canceled. - The provided has already been disposed. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task - - - - - - - The time span to wait before completing the returned task, or to wait indefinitely. - A cancellation token to observe while waiting for the task to complete. - Creates a cancellable task that completes after a specified time interval. - A task that represents the time delay. - + ]]> + + The argument is less than -1. + The task has been canceled. + The provided has already been disposed. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task + + + + + + + The time span to wait before completing the returned task, or to wait indefinitely. + A cancellation token to observe while waiting for the task to complete. + Creates a cancellable task that completes after a specified time interval. + A task that represents the time delay. + - - + ]]> + + represents a negative time interval other than . -or- - The argument's property is greater than 4294967294 on .NET 6 and later versions, or Int32.MaxValue on all previous versions. - The task has been canceled. - The provided has already been disposed. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Threading.Tasks - - - mscorlib - - - netstandard - - - System.Threading.Tasks.Task - - - - - - - The to wait before completing the returned task, or to wait indefinitely. - The with which to interpret . - Creates a task that completes after a specified time interval. - A task that represents the time delay. - To be added. - - - represents a negative time interval other than . - -or- - - 's property is greater than 4294967294. - - The argument is . - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Threading.Tasks - - - mscorlib - - - netstandard - - - System.Threading.Tasks.Task - - - - - - - - The to wait before completing the returned task, or to wait indefinitely. - The with which to interpret . - A cancellation token to observe while waiting for the task to complete. - Creates a cancellable task that completes after a specified time interval. - A task that represents the time delay. - To be added. - - - represents a negative time interval other than . - -or- - - 's property is greater than 4294967294. - - The argument is . - The cancellation token was canceled. This exception is stored into the returned task. - - - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - Releases all resources used by the current instance of the class. - - - - - - - - - - Method - - M:System.IDisposable.Dispose - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks - - - System.Void - - - - Releases all resources used by the current instance of the class. - + The argument's property is greater than 4294967294 on .NET 6 and later versions, or Int32.MaxValue on all previous versions. + The task has been canceled. + The provided has already been disposed. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Threading.Tasks + + + mscorlib + + + netstandard + + + System.Threading.Tasks.Task + + + + + + + The to wait before completing the returned task, or to wait indefinitely. + The with which to interpret . + Creates a task that completes after a specified time interval. + A task that represents the time delay. + To be added. + + + represents a negative time interval other than . + -or- + + 's property is greater than 4294967294. + + The argument is . + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Threading.Tasks + + + mscorlib + + + netstandard + + + System.Threading.Tasks.Task + + + + + + + + The to wait before completing the returned task, or to wait indefinitely. + The with which to interpret . + A cancellation token to observe while waiting for the task to complete. + Creates a cancellable task that completes after a specified time interval. + A task that represents the time delay. + To be added. + + + represents a negative time interval other than . + -or- + + 's property is greater than 4294967294. + + The argument is . + The cancellation token was canceled. This exception is stored into the returned task. + + + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + Releases all resources used by the current instance of the class. + + + + + + + + + + Method + + M:System.IDisposable.Dispose + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks + + + System.Void + + + + Releases all resources used by the current instance of the class. + class implements the interface because internally it uses resources that also implement . However, particularly if your app targets the .NET Framework 4.5 or later, there is no need to call unless performance or scalability testing indicates that, based on your usage patterns, your app's performance would be improved by disposing of tasks. For more information, see [Do I need to dispose of Tasks?](https://devblogs.microsoft.com/pfxteam/do-i-need-to-dispose-of-tasks/) in the Parallel Programming with .NET blog. - ]]> - - The task is not in one of the final states: , , or . - - - - - - - - - - Method - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks - - - System.Void - - - - - - A Boolean value that indicates whether this method is being called due to a call to . - Disposes the , releasing all of its unmanaged resources. - + ]]> + + The task is not in one of the final states: , , or . + + + + + + + + + + Method + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks + + + System.Void + + + + + + A Boolean value that indicates whether this method is being called due to a call to . + Disposes the , releasing all of its unmanaged resources. + class implements the interface because internally it uses resources that also implement . However, particularly if your app targets the .NET Framework 4.5 or later, there is no need to call unless performance or scalability testing indicates that, based on your usage patterns, your app's performance would be improved by disposing of tasks. For more information, see [Do I need to dispose of Tasks?](https://devblogs.microsoft.com/pfxteam/do-i-need-to-dispose-of-tasks/) in the Parallel Programming with .NET blog. - ]]> - - The task is not in one of the final states: , , or . - Unlike most of the members of the class, this method is not thread-safe. - - - - - - - - - - - Property - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - [get: System.Runtime.CompilerServices.NullableContext(2)] - [<get: System.Runtime.CompilerServices.NullableContext(2)>] - - - - System.AggregateException - - - Gets the that caused the to end prematurely. If the completed successfully or has not yet thrown any exceptions, this will return . - The that caused the to end prematurely. - + ]]> + + The task is not in one of the final states: , , or . + Unlike most of the members of the class, this method is not thread-safe. + + + + + + + + + + + Property + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + [get: System.Runtime.CompilerServices.NullableContext(2)] + [<get: System.Runtime.CompilerServices.NullableContext(2)>] + + + + System.AggregateException + + + Gets the that caused the to end prematurely. If the completed successfully or has not yet thrown any exceptions, this will return . + The that caused the to end prematurely. + in calls to or in accesses to the property. On .NET Framework 4.0, any exceptions not observed by the time the task instance is garbage collected will be propagated on the finalizer thread, which crashes the process. On .NET Framework 4.5 and later the default behavior changed so unobserved exceptions are not rethrown from the Finalizer. .NET Core does not rethrow the exception on the Finalizer. For more information and an example, see [Exception Handling (Task Parallel Library)](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library). - ]]> - - - - - - - - - - - Property - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.TaskFactory - - - Provides access to factory methods for creating and configuring and instances. - A factory object that can create a variety of and objects. - + ]]> + + + + + + + + + + + Property + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.TaskFactory + + + Provides access to factory methods for creating and configuring and instances. + A factory object that can create a variety of and objects. + - - - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task - - - - - - The cancellation token with which to complete the task. - Creates a that's completed due to cancellation with a specified cancellation token. - The canceled task. - To be added. - Cancellation has not been requested for ; its property is . - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task<TResult> - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - The type of the result returned by the task. - The cancellation token with which to complete the task. - Creates a that's completed due to cancellation with a specified cancellation token. - The canceled task. - To be added. - Cancellation has not been requested for ; its property is . - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task - - - - - - The exception with which to complete the task. - Creates a that has completed with a specified exception. - The faulted task. - + ]]> + + + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task + + + + + + The cancellation token with which to complete the task. + Creates a that's completed due to cancellation with a specified cancellation token. + The canceled task. + To be added. + Cancellation has not been requested for ; its property is . + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task<TResult> + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + The type of the result returned by the task. + The cancellation token with which to complete the task. + Creates a that's completed due to cancellation with a specified cancellation token. + The canceled task. + To be added. + Cancellation has not been requested for ; its property is . + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task + + + + + + The exception with which to complete the task. + Creates a that has completed with a specified exception. + The faulted task. + object whose property is and whose property contains `exception`. The method is commonly used when you immediately know that the work that a task performs will throw an exception before executing a longer code path. For an example, see the overload. - ]]> - - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task<TResult> - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - The type of the result returned by the task. - The exception with which to complete the task. - Creates a that's completed with a specified exception. - The faulted task. - + ]]> + + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task<TResult> + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + The type of the result returned by the task. + The exception with which to complete the task. + Creates a that's completed with a specified exception. + The faulted task. + - - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task<TResult> - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - The type of the result returned by the task. - The result to store into the completed task. - Creates a that's completed successfully with the specified result. - The successfully completed task. - + ]]> + + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task<TResult> + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + The type of the result returned by the task. + The result to store into the completed task. + Creates a that's completed successfully with the specified result. + The successfully completed task. + - - - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Runtime.CompilerServices.TaskAwaiter - - - - Gets an awaiter used to await this . - An awaiter instance. - + ]]> + + + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Runtime.CompilerServices.TaskAwaiter + + + + Gets an awaiter used to await this . + An awaiter instance. + - - - - - - - - - - - Property - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - Gets an ID for this instance. - The identifier that is assigned by the system to this instance. - + ]]> + + + + + + + + + + + Property + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + Gets an ID for this instance. + The identifier that is assigned by the system to this instance. + property. - ]]> - - - - - - - - - - - - Property - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - Gets whether this instance has completed execution due to being canceled. - - if the task has completed due to being canceled; otherwise . - + ]]> + + + + + + + + + + + + Property + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + Gets whether this instance has completed execution due to being canceled. + + if the task has completed due to being canceled; otherwise . + [!IMPORTANT] > Retrieving the value of the property does not block the calling thread until the task has completed. - ]]> - - - - - - - - - - - Property - - P:System.IAsyncResult.IsCompleted - - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] - [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] - - - - System.Boolean - - - Gets a value that indicates whether the task has completed. - - if the task has completed (that is, the task is in one of the three final states: , , or ); otherwise, . - + ]]> + + + + + + + + + + + Property + + P:System.IAsyncResult.IsCompleted + + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")] + [<get: System.Runtime.TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")>] + + + + System.Boolean + + + Gets a value that indicates whether the task has completed. + + if the task has completed (that is, the task is in one of the three final states: , , or ); otherwise, . + [!IMPORTANT] > Retrieving the value of the property does not block the calling thread until the task has completed. - ]]> - - - - - - - - - - - Property - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - mscorlib - - - netstandard - 2.1.0.0 - - - System.Threading.Tasks - - - System.Boolean - - - Gets whether the task ran to completion. - - if the task ran to completion; otherwise . - To be added. - - - - - - - - - - Property - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Diagnostics.CodeAnalysis.MemberNotNullWhen(true, "Exception")] - [<System.Diagnostics.CodeAnalysis.MemberNotNullWhen(true, "Exception")>] - - - [get: System.Diagnostics.CodeAnalysis.MemberNotNullWhen(true, "Exception")] - [<get: System.Diagnostics.CodeAnalysis.MemberNotNullWhen(true, "Exception")>] - - - - System.Boolean - - - Gets whether the completed due to an unhandled exception. - - if the task has thrown an unhandled exception; otherwise . - + ]]> + + + + + + + + + + + Property + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + mscorlib + + + netstandard + 2.1.0.0 + + + System.Threading.Tasks + + + System.Boolean + + + Gets whether the task ran to completion. + + if the task ran to completion; otherwise . + To be added. + + + + + + + + + + Property + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Diagnostics.CodeAnalysis.MemberNotNullWhen(true, "Exception")] + [<System.Diagnostics.CodeAnalysis.MemberNotNullWhen(true, "Exception")>] + + + [get: System.Diagnostics.CodeAnalysis.MemberNotNullWhen(true, "Exception")] + [<get: System.Diagnostics.CodeAnalysis.MemberNotNullWhen(true, "Exception")>] + + + + System.Boolean + + + Gets whether the completed due to an unhandled exception. + + if the task has thrown an unhandled exception; otherwise . + [!IMPORTANT] > Retrieving the value of the property does not block the calling thread until the task has completed. - ]]> - - - - - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - Queues the specified work to run on the ThreadPool and returns a task or handle for that work. - + ]]> + + + + + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + Queues the specified work to run on the ThreadPool and returns a task or handle for that work. + method provides a set of overloads that make it easy to start a task by using default values. It is a lightweight alternative to the overloads. - ]]> - - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task - - - - - - The work to execute asynchronously. - Queues the specified work to run on the thread pool and returns a object that represents that work. - A task that represents the work queued to execute in the ThreadPool. - + ]]> + + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task + + + + + + The work to execute asynchronously. + Queues the specified work to run on the thread pool and returns a object that represents that work. + A task that represents the work queued to execute in the ThreadPool. + - - The parameter was . - Exception Handling (Task Parallel Library) - - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] - - - - - - The work to execute asynchronously. - Queues the specified work to run on the thread pool and returns a proxy for the task returned by . - A task that represents a proxy for the task returned by . - + ]]> + + The parameter was . + Exception Handling (Task Parallel Library) + + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] + + + + + + The work to execute asynchronously. + Queues the specified work to run on the thread pool and returns a proxy for the task returned by . + A task that represents a proxy for the task returned by . + - - The parameter was . - Exception Handling (Task Parallel Library) - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task - - - - - - - The work to execute asynchronously. - A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . - Queues the specified work to run on the thread pool and returns a object that represents that work. A cancellation token allows the work to be cancelled if it has not yet started. - A task that represents the work queued to execute in the thread pool. - + ]]> + + The parameter was . + Exception Handling (Task Parallel Library) + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task + + + + + + + The work to execute asynchronously. + A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . + Queues the specified work to run on the thread pool and returns a object that represents that work. A cancellation token allows the work to be cancelled if it has not yet started. + A task that represents the work queued to execute in the thread pool. + - - The parameter was . - The task has been canceled. - The associated with was disposed. - Exception Handling (Task Parallel Library) - - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] - - - - - - - The work to execute asynchronously. - A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . - Queues the specified work to run on the thread pool and returns a proxy for the task returned by . A cancellation token allows the work to be cancelled if it has not yet started. - A task that represents a proxy for the task returned by . - + ]]> + + The parameter was . + The task has been canceled. + The associated with was disposed. + Exception Handling (Task Parallel Library) + + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })>] + + + + + + + The work to execute asynchronously. + A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . + Queues the specified work to run on the thread pool and returns a proxy for the task returned by . A cancellation token allows the work to be cancelled if it has not yet started. + A task that represents a proxy for the task returned by . + - - The parameter was . - The task has been canceled. - The associated with was disposed. - Task Cancellation - Exception Handling (Task Parallel Library) - - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task<TResult> - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2, 1 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2, 1 })>] - - - - - - The type of the result returned by the proxy task. - The work to execute asynchronously. - Queues the specified work to run on the thread pool and returns a proxy for the returned by . A cancellation token allows the work to be cancelled if it has not yet started. - A that represents a proxy for the returned by . - + ]]> + + The parameter was . + The task has been canceled. + The associated with was disposed. + Task Cancellation + Exception Handling (Task Parallel Library) + + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task<TResult> + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2, 1 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2, 1 })>] + + + + + + The type of the result returned by the proxy task. + The work to execute asynchronously. + Queues the specified work to run on the thread pool and returns a proxy for the returned by . A cancellation token allows the work to be cancelled if it has not yet started. + A that represents a proxy for the returned by . + - - The parameter was . - Exception Handling (Task Parallel Library) - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task<TResult> - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - The return type of the task. - The work to execute asynchronously. - Queues the specified work to run on the thread pool and returns a object that represents that work. A cancellation token allows the work to be cancelled if it has not yet started. - A task object that represents the work queued to execute in the thread pool. - + ]]> + + The parameter was . + Exception Handling (Task Parallel Library) + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task<TResult> + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + The return type of the task. + The work to execute asynchronously. + Queues the specified work to run on the thread pool and returns a object that represents that work. A cancellation token allows the work to be cancelled if it has not yet started. + A task object that represents the work queued to execute in the thread pool. + - - The parameter is . - Exception Handling (Task Parallel Library) - - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task<TResult> - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2, 1 })] - [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2, 1 })>] - - - - - - - The type of the result returned by the proxy task. - The work to execute asynchronously. - A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . - Queues the specified work to run on the thread pool and returns a proxy for the returned by . - A that represents a proxy for the returned by . - + ]]> + + The parameter is . + Exception Handling (Task Parallel Library) + + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task<TResult> + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2, 1 })] + [<System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2, 1 })>] + + + + + + + The type of the result returned by the proxy task. + The work to execute asynchronously. + A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . + Queues the specified work to run on the thread pool and returns a proxy for the returned by . + A that represents a proxy for the returned by . + - - The parameter was . - The task has been canceled. - The associated with was disposed. - Task Cancellation - Exception Handling (Task Parallel Library) - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task<TResult> - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - - The result type of the task. - The work to execute asynchronously. - A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . - Queues the specified work to run on the thread pool and returns a object that represents that work. - A that represents the work queued to execute in the thread pool. - + ]]> + + The parameter was . + The task has been canceled. + The associated with was disposed. + Task Cancellation + Exception Handling (Task Parallel Library) + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task<TResult> + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + + The result type of the task. + The work to execute asynchronously. + A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . + Queues the specified work to run on the thread pool and returns a object that represents that work. + A that represents the work queued to execute in the thread pool. + exception, since any tasks that have not started when cancellation is requested still throw an exception. - ]]> - - The parameter is . - The task has been canceled. - The associated with was disposed. - Task Cancellation - Exception Handling (Task Parallel Library) - - - - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - Runs the synchronously on the current . - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Void - - - - Runs the synchronously on the current . - + ]]> + + The parameter is . + The task has been canceled. + The associated with was disposed. + Task Cancellation + Exception Handling (Task Parallel Library) + + + + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + Runs the synchronously on the current . + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Void + + + + Runs the synchronously on the current . + - - The instance has been disposed. - The is not in a valid state to be started. It may have already been started, executed, or canceled, or it may have been created in a manner that doesn't support direct scheduling. - Exception Handling (Task Parallel Library) - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Void - - - - - - The scheduler on which to attempt to run this task inline. - Runs the synchronously on the provided. - + ]]> + + The instance has been disposed. + The is not in a valid state to be started. It may have already been started, executed, or canceled, or it may have been created in a manner that doesn't support direct scheduling. + Exception Handling (Task Parallel Library) + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Void + + + + + + The scheduler on which to attempt to run this task inline. + Runs the synchronously on the provided. + to ensure that the task has completed execution. For more information on exception handling for task operations, see [Exception Handling](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library). - ]]> - - The instance has been disposed. - The argument is . - The is not in a valid state to be started. It may have already been started, executed, or canceled, or it may have been created in a manner that doesn't support direct scheduling. - - Exception Handling (Task Parallel Library) - - - - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - Starts the . - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Void - - - - Starts the , scheduling it for execution to the current . - + ]]> + + The instance has been disposed. + The argument is . + The is not in a valid state to be started. It may have already been started, executed, or canceled, or it may have been created in a manner that doesn't support direct scheduling. + + Exception Handling (Task Parallel Library) + + + + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + Starts the . + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Void + + + + Starts the , scheduling it for execution to the current . + - - The instance has been disposed. - The is not in a valid state to be started. It may have already been started, executed, or canceled, or it may have been created in a manner that doesn't support direct scheduling. - Exception Handling (Task Parallel Library) - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Void - - - - - - The with which to associate and execute this task. - Starts the , scheduling it for execution to the specified . - + ]]> + + The instance has been disposed. + The is not in a valid state to be started. It may have already been started, executed, or canceled, or it may have been created in a manner that doesn't support direct scheduling. + Exception Handling (Task Parallel Library) + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Void + + + + + + The with which to associate and execute this task. + Starts the , scheduling it for execution to the specified . + - - The argument is . - The is not in a valid state to be started. It may have already been started, executed, or canceled, or it may have been created in a manner that doesn't support direct scheduling. - The instance has been disposed. - The scheduler was unable to queue this task. - Exception Handling (Task Parallel Library) - - - - - - - - - - Property - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.TaskStatus - - - Gets the of this task. - The current of this task instance. - + ]]> + + The argument is . + The is not in a valid state to be started. It may have already been started, executed, or canceled, or it may have been created in a manner that doesn't support direct scheduling. + The instance has been disposed. + The scheduler was unable to queue this task. + Exception Handling (Task Parallel Library) + + + + + + + + + + Property + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.TaskStatus + + + Gets the of this task. + The current of this task instance. + - - - - - - - - - - - Property - - P:System.IAsyncResult.AsyncWaitHandle - - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.WaitHandle - - - Gets a that can be used to wait for the task to complete. - A that can be used to wait for the task to complete. - + ]]> + + + + + + + + + + + Property + + P:System.IAsyncResult.AsyncWaitHandle + + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.WaitHandle + + + Gets a that can be used to wait for the task to complete. + A that can be used to wait for the task to complete. + is preferable to using for similar functionality. For more information, see the "Waiting on Tasks" section in [Task-based Asynchronous Programming](/dotnet/standard/parallel-programming/task-based-asynchronous-programming) and [Using TPL with Other Asynchronous Patterns](/dotnet/standard/parallel-programming/using-tpl-with-other-asynchronous-patterns). - ]]> - - The has been disposed. - - - - - - - - - - Property - - P:System.IAsyncResult.CompletedSynchronously - - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - Gets an indication of whether the operation completed synchronously. - - if the operation completed synchronously; otherwise, . - + ]]> + + The has been disposed. + + + + + + + + + + Property + + P:System.IAsyncResult.CompletedSynchronously + + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + Gets an indication of whether the operation completed synchronously. + + if the operation completed synchronously; otherwise, . + instance is cast to an interface. - ]]> - - - - - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - Waits for the to complete execution. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Void - - - - Waits for the to complete execution. - + ]]> + + + + + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + Waits for the to complete execution. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Void + + + + Waits for the to complete execution. + - - The has been disposed. + ]]> + + The has been disposed. The task was canceled. The collection contains a object. -or- - An exception was thrown during the execution of the task. The collection contains information about the exception or exceptions. - Task.Wait and "Inlining" - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - The number of milliseconds to wait, or (-1) to wait indefinitely. - Waits for the to complete execution within a specified number of milliseconds. - - if the completed execution within the allotted time; otherwise, . - + An exception was thrown during the execution of the task. The collection contains information about the exception or exceptions. + Task.Wait and "Inlining" + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + The number of milliseconds to wait, or (-1) to wait indefinitely. + Waits for the to complete execution within a specified number of milliseconds. + + if the completed execution within the allotted time; otherwise, . + - - The has been disposed. - - is a negative number other than -1, which represents an infinite time-out. + ]]> + + The has been disposed. + + is a negative number other than -1, which represents an infinite time-out. The task was canceled. The collection contains a object. -or- - An exception was thrown during the execution of the task. The collection contains information about the exception or exceptions. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Void - - - - - - A cancellation token to observe while waiting for the task to complete. - Waits for the to complete execution. The wait terminates if a cancellation token is canceled before the task completes. - + An exception was thrown during the execution of the task. The collection contains information about the exception or exceptions. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Void + + + + + + A cancellation token to observe while waiting for the task to complete. + Waits for the to complete execution. The wait terminates if a cancellation token is canceled before the task completes. + - - The was canceled. - The task has been disposed. + ]]> + + The was canceled. + The task has been disposed. The task was canceled. The collection contains a object. -or- - An exception was thrown during the execution of the task. The collection contains information about the exception or exceptions. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - A that represents the number of milliseconds to wait, or a that represents -1 milliseconds to wait indefinitely. - Waits for the to complete execution within a specified time interval. - - if the completed execution within the allotted time; otherwise, . - + An exception was thrown during the execution of the task. The collection contains information about the exception or exceptions. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + A that represents the number of milliseconds to wait, or a that represents -1 milliseconds to wait indefinitely. + Waits for the to complete execution within a specified time interval. + + if the completed execution within the allotted time; otherwise, . + - - The has been disposed. - + ]]> + + The has been disposed. + is a negative number other than -1 milliseconds, which represents an infinite time-out. -or- - is greater than Int32.MaxValue. + is greater than Int32.MaxValue. The task was canceled. The collection contains a object. -or- - An exception was thrown during the execution of the task. The collection contains information about the exception or exceptions. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Boolean - - - - - - - The number of milliseconds to wait, or (-1) to wait indefinitely. - A cancellation token to observe while waiting for the task to complete. - Waits for the to complete execution. The wait terminates if a timeout interval elapses or a cancellation token is canceled before the task completes. - - if the completed execution within the allotted time; otherwise, . - + An exception was thrown during the execution of the task. The collection contains information about the exception or exceptions. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Boolean + + + + + + + The number of milliseconds to wait, or (-1) to wait indefinitely. + A cancellation token to observe while waiting for the task to complete. + Waits for the to complete execution. The wait terminates if a timeout interval elapses or a cancellation token is canceled before the task completes. + + if the completed execution within the allotted time; otherwise, . + - - The was canceled. - The has been disposed. - - is a negative number other than -1, which represents an infinite time-out. + ]]> + + The was canceled. + The has been disposed. + + is a negative number other than -1, which represents an infinite time-out. The task was canceled. The collection contains a object. -or- - An exception was thrown during the execution of the task. The collection contains information about the exception or exceptions. - - - - - - - - - - Method - - System.Runtime - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks - - - mscorlib - - - netstandard - - - System.Boolean - - - - - - - The time to wait, or to wait indefinitely - A to observe while waiting for the task to complete. - Waits for the to complete execution. - - if the completed execution within the allotted time; otherwise, . - To be added. + An exception was thrown during the execution of the task. The collection contains information about the exception or exceptions. + + + + + + + + + + Method + + System.Runtime + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks + + + mscorlib + + + netstandard + + + System.Boolean + + + + + + + The time to wait, or to wait indefinitely + A to observe while waiting for the task to complete. + Waits for the to complete execution. + + if the completed execution within the allotted time; otherwise, . + To be added. The was canceled -or- -an exception was thrown during the execution of the . - +an exception was thrown during the execution of the . + is a negative number other than -1 milliseconds, which represents an infinite time-out -or- timeout is greater than - . - The was canceled. - - - - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - Waits for all of the provided objects to complete execution. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.Versioning.UnsupportedOSPlatform("browser")] - [<System.Runtime.Versioning.UnsupportedOSPlatform("browser")>] - - - - System.Void - - - - - - [System.ParamArray] - [<System.ParamArray>] - - - - - - An array of instances on which to wait. - Waits for all of the provided objects to complete execution. - + . + The was canceled. + + + + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + Waits for all of the provided objects to complete execution. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.Versioning.UnsupportedOSPlatform("browser")] + [<System.Runtime.Versioning.UnsupportedOSPlatform("browser")>] + + + + System.Void + + + + + + [System.ParamArray] + [<System.ParamArray>] + + + + + + An array of instances on which to wait. + Waits for all of the provided objects to complete execution. + - - One or more of the objects in has been disposed. - The argument is . - The argument contains a null element. + ]]> + + One or more of the objects in has been disposed. + The argument is . + The argument contains a null element. At least one of the instances was canceled. If a task was canceled, the exception contains an exception in its collection. -or- - An exception was thrown during the execution of at least one of the instances. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.Versioning.UnsupportedOSPlatform("browser")] - [<System.Runtime.Versioning.UnsupportedOSPlatform("browser")>] - - - - System.Boolean - - - - - - - An array of instances on which to wait. - The number of milliseconds to wait, or (-1) to wait indefinitely. - Waits for all of the provided objects to complete execution within a specified number of milliseconds. - - if all of the instances completed execution within the allotted time; otherwise, . - To be added. - One or more of the objects in has been disposed. - The argument is . + An exception was thrown during the execution of at least one of the instances. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.Versioning.UnsupportedOSPlatform("browser")] + [<System.Runtime.Versioning.UnsupportedOSPlatform("browser")>] + + + + System.Boolean + + + + + + + An array of instances on which to wait. + The number of milliseconds to wait, or (-1) to wait indefinitely. + Waits for all of the provided objects to complete execution within a specified number of milliseconds. + + if all of the instances completed execution within the allotted time; otherwise, . + To be added. + One or more of the objects in has been disposed. + The argument is . At least one of the instances was canceled. If a task was canceled, the contains an in its collection. -or- - An exception was thrown during the execution of at least one of the instances. - - is a negative number other than -1, which represents an infinite time-out. - The argument contains a null element. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.Versioning.UnsupportedOSPlatform("browser")] - [<System.Runtime.Versioning.UnsupportedOSPlatform("browser")>] - - - - System.Void - - - - - - - An array of instances on which to wait. - A to observe while waiting for the tasks to complete. - Waits for all of the provided objects to complete execution unless the wait is cancelled. - + An exception was thrown during the execution of at least one of the instances. + + is a negative number other than -1, which represents an infinite time-out. + The argument contains a null element. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.Versioning.UnsupportedOSPlatform("browser")] + [<System.Runtime.Versioning.UnsupportedOSPlatform("browser")>] + + + + System.Void + + + + + + + An array of instances on which to wait. + A to observe while waiting for the tasks to complete. + Waits for all of the provided objects to complete execution unless the wait is cancelled. + as noted above. - ]]> - - The was canceled. - The argument is . + ]]> + + The was canceled. + The argument is . At least one of the instances was canceled. If a task was canceled, the contains an in its collection. -or- - An exception was thrown during the execution of at least one of the instances. - The argument contains a null element. - One or more of the objects in has been disposed. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.Versioning.UnsupportedOSPlatform("browser")] - [<System.Runtime.Versioning.UnsupportedOSPlatform("browser")>] - - - - System.Boolean - - - - - - - An array of instances on which to wait. - A that represents the number of milliseconds to wait, or a that represents -1 milliseconds to wait indefinitely. - Waits for all of the provided cancellable objects to complete execution within a specified time interval. - - if all of the instances completed execution within the allotted time; otherwise, . - To be added. - One or more of the objects in has been disposed. - The argument is . + An exception was thrown during the execution of at least one of the instances. + The argument contains a null element. + One or more of the objects in has been disposed. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.Versioning.UnsupportedOSPlatform("browser")] + [<System.Runtime.Versioning.UnsupportedOSPlatform("browser")>] + + + + System.Boolean + + + + + + + An array of instances on which to wait. + A that represents the number of milliseconds to wait, or a that represents -1 milliseconds to wait indefinitely. + Waits for all of the provided cancellable objects to complete execution within a specified time interval. + + if all of the instances completed execution within the allotted time; otherwise, . + To be added. + One or more of the objects in has been disposed. + The argument is . At least one of the instances was canceled. If a task was canceled, the contains an in its collection. -or- - An exception was thrown during the execution of at least one of the instances. - + An exception was thrown during the execution of at least one of the instances. + is a negative number other than -1 milliseconds, which represents an infinite time-out. -or- - is greater than Int32.MaxValue. - The argument contains a null element. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - - [System.Runtime.Versioning.UnsupportedOSPlatform("browser")] - [<System.Runtime.Versioning.UnsupportedOSPlatform("browser")>] - - - - System.Boolean - - - - - - - - An array of instances on which to wait. - The number of milliseconds to wait, or (-1) to wait indefinitely. - A to observe while waiting for the tasks to complete. - Waits for all of the provided objects to complete execution within a specified number of milliseconds or until the wait is cancelled. - - if all of the instances completed execution within the allotted time; otherwise, . - + is greater than Int32.MaxValue. + The argument contains a null element. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + + [System.Runtime.Versioning.UnsupportedOSPlatform("browser")] + [<System.Runtime.Versioning.UnsupportedOSPlatform("browser")>] + + + + System.Boolean + + + + + + + + An array of instances on which to wait. + The number of milliseconds to wait, or (-1) to wait indefinitely. + A to observe while waiting for the tasks to complete. + Waits for all of the provided objects to complete execution within a specified number of milliseconds or until the wait is cancelled. + + if all of the instances completed execution within the allotted time; otherwise, . + noted above. - ]]> - - One or more of the objects in has been disposed. - The argument is . + ]]> + + One or more of the objects in has been disposed. + The argument is . At least one of the instances was canceled. If a task was canceled, the contains an in its collection. -or- - An exception was thrown during the execution of at least one of the instances. - - is a negative number other than -1, which represents an infinite time-out. - The argument contains a null element. - The was canceled. - - - - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - Waits for any of the provided objects to complete execution. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - [System.ParamArray] - [<System.ParamArray>] - - - - - - An array of instances on which to wait. - Waits for any of the provided objects to complete execution. - The index of the completed object in the array. - + An exception was thrown during the execution of at least one of the instances. + + is a negative number other than -1, which represents an infinite time-out. + The argument contains a null element. + The was canceled. + + + + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + Waits for any of the provided objects to complete execution. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + [System.ParamArray] + [<System.ParamArray>] + + + + + + An array of instances on which to wait. + Waits for any of the provided objects to complete execution. + The index of the completed object in the array. + - - The has been disposed. - The argument is . - The argument contains a null element. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - - An array of instances on which to wait. - The number of milliseconds to wait, or (-1) to wait indefinitely. - Waits for any of the provided objects to complete execution within a specified number of milliseconds. - The index of the completed task in the array argument, or -1 if the timeout occurred. - To be added. - The has been disposed. - The argument is . - - is a negative number other than -1, which represents an infinite time-out. - The argument contains a null element. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - - An array of instances on which to wait. - A to observe while waiting for a task to complete. - Waits for any of the provided objects to complete execution unless the wait is cancelled. - The index of the completed task in the array argument. - To be added. - The has been disposed. - The argument is . - The argument contains a null element. - The was canceled. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - - An array of instances on which to wait. - A that represents the number of milliseconds to wait, or a that represents -1 milliseconds to wait indefinitely. - Waits for any of the provided objects to complete execution within a specified time interval. - The index of the completed task in the array argument, or -1 if the timeout occurred. - To be added. - The has been disposed. - The argument is . + ]]> + + The has been disposed. + The argument is . + The argument contains a null element. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + + An array of instances on which to wait. + The number of milliseconds to wait, or (-1) to wait indefinitely. + Waits for any of the provided objects to complete execution within a specified number of milliseconds. + The index of the completed task in the array argument, or -1 if the timeout occurred. + To be added. + The has been disposed. + The argument is . + + is a negative number other than -1, which represents an infinite time-out. + The argument contains a null element. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + + An array of instances on which to wait. + A to observe while waiting for a task to complete. + Waits for any of the provided objects to complete execution unless the wait is cancelled. + The index of the completed task in the array argument. + To be added. + The has been disposed. + The argument is . + The argument contains a null element. + The was canceled. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + + An array of instances on which to wait. + A that represents the number of milliseconds to wait, or a that represents -1 milliseconds to wait indefinitely. + Waits for any of the provided objects to complete execution within a specified time interval. + The index of the completed task in the array argument, or -1 if the timeout occurred. + To be added. + The has been disposed. + The argument is . The property of the argument is a negative number other than -1, which represents an infinite time-out. -or- - The property of the argument is greater than Int32.MaxValue. - The argument contains a null element. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Int32 - - - - - - - - An array of instances on which to wait. - The number of milliseconds to wait, or (-1) to wait indefinitely. - A to observe while waiting for a task to complete. - Waits for any of the provided objects to complete execution within a specified number of milliseconds or until a cancellation token is cancelled. - The index of the completed task in the array argument, or -1 if the timeout occurred. - To be added. - The has been disposed. - The argument is . - - is a negative number other than -1, which represents an infinite time-out. - The argument contains a null element. - The was canceled. - - - - - - - - - - Method - - System.Runtime - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks - - - mscorlib - - - netstandard - - - System.Threading.Tasks.Task - - - - - - The to monitor for a cancellation request. - Gets a that will complete when this completes or when the specified has cancellation requested. - The representing the asynchronous wait. It may or may not be the same instance as the current instance. - This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - The cancellation token was canceled. This exception is stored into the returned task. - - - - - - - - - - Method - - System.Runtime - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks - - - mscorlib - - - netstandard - - - System.Threading.Tasks.Task - - - - - - The timeout after which the should be faulted with a if it hasn't otherwise completed. - Gets a that will complete when this completes or when the specified timeout expires. - The representing the asynchronous wait. It may or may not be the same instance as the current instance. - This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - - - - - - - - - - Method - - System.Runtime - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks - - - mscorlib - - - netstandard - - - System.Threading.Tasks.Task - - - - - - - The timeout after which the should be faulted with a if it hasn't otherwise completed. - The to monitor for a cancellation request. - Gets a that will complete when this completes, when the specified timeout expires, or when the specified has cancellation requested. - The representing the asynchronous wait. It may or may not be the same instance as the current instance. - This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - The cancellation token was canceled. This exception is stored into the returned task. - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Threading.Tasks - - - mscorlib - - - netstandard - - - System.Threading.Tasks.Task - - - - - - - The timeout after which the should be faulted with a if it hasn't otherwise completed. - The with which to interpret . - Gets a that will complete when this completes or when the specified timeout expires. - The representing the asynchronous wait. It may or may not be the same instance as the current instance. - To be added. - The argument is . - - - - - - - - - - Method - - System.Runtime - 8.0.0.0 - - - System.Threading.Tasks - - - mscorlib - - - netstandard - - - System.Threading.Tasks.Task - - - - - - - - The timeout after which the should be faulted with a if it hasn't otherwise completed. - The with which to interpret . - The to monitor for a cancellation request. - Gets a that will complete when this completes, when the specified timeout expires, or when the specified has cancellation requested. - The representing the asynchronous wait. It may or may not be the same instance as the current instance. - To be added. - The argument is . - The cancellation token was canceled. This exception is stored into the returned task. - - - - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - Creates a task that will complete when all of the supplied tasks have completed. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task - - - - - - The tasks to wait on for completion. - Creates a task that will complete when all of the objects in an enumerable collection have completed. - A task that represents the completion of all of the supplied tasks. - + The property of the argument is greater than Int32.MaxValue. + The argument contains a null element. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Int32 + + + + + + + + An array of instances on which to wait. + The number of milliseconds to wait, or (-1) to wait indefinitely. + A to observe while waiting for a task to complete. + Waits for any of the provided objects to complete execution within a specified number of milliseconds or until a cancellation token is cancelled. + The index of the completed task in the array argument, or -1 if the timeout occurred. + To be added. + The has been disposed. + The argument is . + + is a negative number other than -1, which represents an infinite time-out. + The argument contains a null element. + The was canceled. + + + + + + + + + + Method + + System.Runtime + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks + + + mscorlib + + + netstandard + + + System.Threading.Tasks.Task + + + + + + The to monitor for a cancellation request. + Gets a that will complete when this completes or when the specified has cancellation requested. + The representing the asynchronous wait. It may or may not be the same instance as the current instance. + This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . + The cancellation token was canceled. This exception is stored into the returned task. + + + + + + + + + + Method + + System.Runtime + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks + + + mscorlib + + + netstandard + + + System.Threading.Tasks.Task + + + + + + The timeout after which the should be faulted with a if it hasn't otherwise completed. + Gets a that will complete when this completes or when the specified timeout expires. + The representing the asynchronous wait. It may or may not be the same instance as the current instance. + This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . + + + + + + + + + + Method + + System.Runtime + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks + + + mscorlib + + + netstandard + + + System.Threading.Tasks.Task + + + + + + + The timeout after which the should be faulted with a if it hasn't otherwise completed. + The to monitor for a cancellation request. + Gets a that will complete when this completes, when the specified timeout expires, or when the specified has cancellation requested. + The representing the asynchronous wait. It may or may not be the same instance as the current instance. + This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . + The cancellation token was canceled. This exception is stored into the returned task. + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Threading.Tasks + + + mscorlib + + + netstandard + + + System.Threading.Tasks.Task + + + + + + + The timeout after which the should be faulted with a if it hasn't otherwise completed. + The with which to interpret . + Gets a that will complete when this completes or when the specified timeout expires. + The representing the asynchronous wait. It may or may not be the same instance as the current instance. + To be added. + The argument is . + + + + + + + + + + Method + + System.Runtime + 8.0.0.0 + + + System.Threading.Tasks + + + mscorlib + + + netstandard + + + System.Threading.Tasks.Task + + + + + + + + The timeout after which the should be faulted with a if it hasn't otherwise completed. + The with which to interpret . + The to monitor for a cancellation request. + Gets a that will complete when this completes, when the specified timeout expires, or when the specified has cancellation requested. + The representing the asynchronous wait. It may or may not be the same instance as the current instance. + To be added. + The argument is . + The cancellation token was canceled. This exception is stored into the returned task. + + + + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + Creates a task that will complete when all of the supplied tasks have completed. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task + + + + + + The tasks to wait on for completion. + Creates a task that will complete when all of the objects in an enumerable collection have completed. + A task that represents the completion of all of the supplied tasks. + - - The argument was . - The collection contained a task. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task - - - - - - [System.ParamArray] - [<System.ParamArray>] - - - - - - The tasks to wait on for completion. - Creates a task that will complete when all of the objects in an array have completed. - A task that represents the completion of all of the supplied tasks. - + ]]> + + The argument was . + The collection contained a task. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task + + + + + + [System.ParamArray] + [<System.ParamArray>] + + + + + + The tasks to wait on for completion. + Creates a task that will complete when all of the objects in an array have completed. + A task that represents the completion of all of the supplied tasks. + - - The argument was . - The array contained a task. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task<TResult[]> - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - The type of the completed task. - The tasks to wait on for completion. - Creates a task that will complete when all of the objects in an enumerable collection have completed. - A task that represents the completion of all of the supplied tasks. - + ]]> + + The argument was . + The array contained a task. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task<TResult[]> + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + The type of the completed task. + The tasks to wait on for completion. + Creates a task that will complete when all of the objects in an enumerable collection have completed. + A task that represents the completion of all of the supplied tasks. + object. implements the interface. - ]]> - - The argument was . - The collection contained a task. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task<TResult[]> - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - [System.ParamArray] - [<System.ParamArray>] - - - - - - The type of the completed task. - The tasks to wait on for completion. - Creates a task that will complete when all of the objects in an array have completed. - A task that represents the completion of all of the supplied tasks. - + ]]> + + The argument was . + The collection contained a task. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task<TResult[]> + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + [System.ParamArray] + [<System.ParamArray>] + + + + + + The type of the completed task. + The tasks to wait on for completion. + Creates a task that will complete when all of the objects in an array have completed. + A task that represents the completion of all of the supplied tasks. + - - The argument was . - The array contained a task. - - - - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - Creates a task that will complete when any of the supplied tasks have completed. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task<System.Threading.Tasks.Task> - - - - - - The tasks to wait on for completion. - Creates a task that will complete when any of the supplied tasks have completed. - A task that represents the completion of one of the supplied tasks. The return task's Result is the task that completed. - + ]]> + + The argument was . + The array contained a task. + + + + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + Creates a task that will complete when any of the supplied tasks have completed. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task<System.Threading.Tasks.Task> + + + + + + The tasks to wait on for completion. + Creates a task that will complete when any of the supplied tasks have completed. + A task that represents the completion of one of the supplied tasks. The return task's Result is the task that completed. + - - The argument was . - The array contained a null task, or was empty. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task<System.Threading.Tasks.Task> - - - - - - [System.ParamArray] - [<System.ParamArray>] - - - - - - The tasks to wait on for completion. - Creates a task that will complete when any of the supplied tasks have completed. - A task that represents the completion of one of the supplied tasks. The return task's Result is the task that completed. - + ]]> + + The argument was . + The array contained a null task, or was empty. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task<System.Threading.Tasks.Task> + + + + + + [System.ParamArray] + [<System.ParamArray>] + + + + + + The tasks to wait on for completion. + Creates a task that will complete when any of the supplied tasks have completed. + A task that represents the completion of one of the supplied tasks. The return task's Result is the task that completed. + - - The argument was null. - The array contained a null task, or was empty. - - - - - - - - - - Method - - System.Runtime - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks - - - mscorlib - - - netstandard - - - System.Threading.Tasks.Task<System.Threading.Tasks.Task> - - - - - - - The first task to wait on for completion. - The second task to wait on for completion. - Creates a task that will complete when either of the supplied tasks have completed. - A new task that represents the completion of one of the supplied tasks. Its is the task that completed first. - + ]]> + + The argument was null. + The array contained a null task, or was empty. + + + + + + + + + + Method + + System.Runtime + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks + + + mscorlib + + + netstandard + + + System.Threading.Tasks.Task<System.Threading.Tasks.Task> + + + + + + + The first task to wait on for completion. + The second task to wait on for completion. + Creates a task that will complete when either of the supplied tasks have completed. + A new task that represents the completion of one of the supplied tasks. Its is the task that completed first. + - - - or was . - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task<System.Threading.Tasks.Task<TResult>> - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - The type of the completed task. - The tasks to wait on for completion. - Creates a task that will complete when any of the supplied tasks have completed. - A task that represents the completion of one of the supplied tasks. The return task's Result is the task that completed. - + ]]> + + + or was . + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task<System.Threading.Tasks.Task<TResult>> + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + The type of the completed task. + The tasks to wait on for completion. + Creates a task that will complete when any of the supplied tasks have completed. + A task that represents the completion of one of the supplied tasks. The return task's Result is the task that completed. + - - The argument was . - The array contained a null task, or was empty. - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks.Task<System.Threading.Tasks.Task<TResult>> - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - [System.ParamArray] - [<System.ParamArray>] - - - - - - The type of the completed task. - The tasks to wait on for completion. - Creates a task that will complete when any of the supplied tasks have completed. - A task that represents the completion of one of the supplied tasks. The return task's Result is the task that completed. - + ]]> + + The argument was . + The array contained a null task, or was empty. + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks.Task<System.Threading.Tasks.Task<TResult>> + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + [System.ParamArray] + [<System.ParamArray>] + + + + + + The type of the completed task. + The tasks to wait on for completion. + Creates a task that will complete when any of the supplied tasks have completed. + A task that represents the completion of one of the supplied tasks. The return task's Result is the task that completed. + - - The argument was null. - The array contained a null task, or was empty. - - - - - - - - - - Method - - System.Runtime - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Threading.Tasks - - - mscorlib - - - netstandard - - - System.Threading.Tasks.Task<System.Threading.Tasks.Task<TResult>> - - - - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - - - - - - - - The type of the result of the returned task. - The first task to wait on for completion. - The second task to wait on for completion. - Creates a task that will complete when either of the supplied tasks have completed. - A task that represents the completion of one of the supplied tasks. The returned task's is the task that completed first. - + ]]> + + The argument was null. + The array contained a null task, or was empty. + + + + + + + + + + Method + + System.Runtime + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Threading.Tasks + + + mscorlib + + + netstandard + + + System.Threading.Tasks.Task<System.Threading.Tasks.Task<TResult>> + + + + + + [System.Runtime.CompilerServices.Nullable(2)] + [<System.Runtime.CompilerServices.Nullable(2)>] + + + + + + + + + + The type of the result of the returned task. + The first task to wait on for completion. + The second task to wait on for completion. + Creates a task that will complete when either of the supplied tasks have completed. + A task that represents the completion of one of the supplied tasks. The returned task's is the task that completed first. + [!TIP] > In every overloaded version of Task.WhenAny() when this method returns the first completed task, the other tasks will continue running until completion, even any of them completed in the `Canceled` or `Faulted` state. So, if that behavior is not desired you may want to cancel all the remaining tasks once the first task complete. - ]]> - - - or was . - - - - - - - - - - Method - - System.Threading.Tasks - 4.0.0.0 - 4.0.10.0 - - - mscorlib - 2.0.5.0 - 4.0.0.0 - - - netstandard - 2.0.0.0 - 2.1.0.0 - - - System.Runtime - 4.2.0.0 - 4.2.1.0 - 4.2.2.0 - 5.0.0.0 - 6.0.0.0 - 7.0.0.0 - 8.0.0.0 - - - System.Runtime.CompilerServices.YieldAwaitable - - - - Creates an awaitable task that asynchronously yields back to the current context when awaited. - A context that, when awaited, will asynchronously transition back into the current context at the time of the await. If the current is non-null, it is treated as the current context. Otherwise, the task scheduler that is associated with the currently executing task is treated as the current context. - + ]]> + + + or was . + + + + + + + + + + Method + + System.Threading.Tasks + 4.0.0.0 + 4.0.10.0 + + + mscorlib + 2.0.5.0 + 4.0.0.0 + + + netstandard + 2.0.0.0 + 2.1.0.0 + + + System.Runtime + 4.2.0.0 + 4.2.1.0 + 4.2.2.0 + 5.0.0.0 + 6.0.0.0 + 7.0.0.0 + 8.0.0.0 + + + System.Runtime.CompilerServices.YieldAwaitable + + + + Creates an awaitable task that asynchronously yields back to the current context when awaited. + A context that, when awaited, will asynchronously transition back into the current context at the time of the await. If the current is non-null, it is treated as the current context. Otherwise, the task scheduler that is associated with the currently executing task is treated as the current context. + object), this will post the remainder of the method's execution back to that context. However, the context will decide how to prioritize this work relative to other work that may be pending. The synchronization context that is present on a UI thread in most UI environments will often prioritize work posted to the context higher than input and rendering work. For this reason, do not rely on `await Task.Yield();` to keep a UI responsive. For more information, see the entry [Useful Abstractions Enabled with ContinueWith](https://devblogs.microsoft.com/pfxteam/useful-abstractions-enabled-with-continuewith/) in the Parallel Programming with .NET blog. - ]]> - - - - - + ]]> + + + + + diff --git a/xml/System.Threading.Tasks/TaskScheduler.xml b/xml/System.Threading.Tasks/TaskScheduler.xml index 31d9326aad9..f23034bb32f 100644 --- a/xml/System.Threading.Tasks/TaskScheduler.xml +++ b/xml/System.Threading.Tasks/TaskScheduler.xml @@ -68,80 +68,15 @@ Represents an object that handles the low-level work of queuing tasks onto threads. - + For more information about this API, see Supplemental API remarks for TaskScheduler. + class represents a task scheduler. A task scheduler ensures that the work of a task is eventually executed. - - The default task scheduler is based on the .NET Framework 4 thread pool, which provides work-stealing for load-balancing, thread injection/retirement for maximum throughput, and overall good performance. It should be sufficient for most scenarios. - - The class also serves as the extension point for all customizable scheduling logic. This includes mechanisms such as how to schedule a task for execution, and how scheduled tasks should be exposed to debuggers. If you require special functionality, you can create a custom scheduler and enable it for specific tasks or queries. - - In this article: - -[The default task scheduler and the thread pool](#Default) - [The global queue vs. local queues](#Queues) - [Work stealing](#Stealing) - [Long-running tasks](#LongRunning) - [Task inlining](#Inlining) -[Specifying a synchronization context](#Sync) - - -## The default task scheduler and the thread pool - The default scheduler for the Task Parallel Library and PLINQ uses the .NET thread pool, which is represented by the class, to queue and execute work. The thread pool uses the information that is provided by the type to efficiently support the fine-grained parallelism (short-lived units of work) that parallel tasks and queries often represent. - - -### The global queue vs. local queues - The thread pool maintains a global FIFO (first-in, first-out) work queue for threads in each application domain. Whenever a program calls the (or ) method, the work is put on this shared queue and eventually de-queued onto the next thread that becomes available. Starting with .NET Framework 4, this queue uses a lock-free algorithm that resembles the class. By using this lock-free implementation, the thread pool spends less time when it queues and de-queues work items. This performance benefit is available to all programs that use the thread pool. - - Top-level tasks, which are tasks that are not created in the context of another task, are put on the global queue just like any other work item. However, nested or child tasks, which are created in the context of another task, are handled quite differently. A child or nested task is put on a local queue that is specific to the thread on which the parent task is executing. The parent task may be a top-level task or it also may be the child of another task. When this thread is ready for more work, it first looks in the local queue. If work items are waiting there, they can be accessed quickly. The local queues are accessed in last-in, first-out order (LIFO) to preserve cache locality and reduce contention. For more information about child tasks and nested tasks, see [Attached and Detached Child Tasks](/dotnet/standard/parallel-programming/attached-and-detached-child-tasks). - - The use of local queues not only reduces pressure on the global queue, but also takes advantage of data locality. Work items in the local queue frequently reference data structures that are physically near one another in memory. In these cases, the data is already in the cache after the first task has run and can be accessed quickly. Both [Parallel LINQ (PLINQ)](/dotnet/standard/parallel-programming/parallel-linq-plinq) and the class use nested tasks and child tasks extensively, and achieve significant speedups by using the local work queues. - - -### Work stealing - Starting with .NET Framework 4, the thread pool also features a work-stealing algorithm to help make sure that no threads are sitting idle while others still have work in their queues. When a thread-pool thread is ready for more work, it first looks at the head of its local queue, then in the global queue, and then in the local queues of other threads. If it finds a work item in the local queue of another thread, it first applies heuristics to make sure that it can run the work efficiently. If it can, it de-queues the work item from the tail (in FIFO order). This reduces contention on each local queue and preserves data locality. This architecture helps the thread pool load-balance work more efficiently than past versions did. - - -### Long-running tasks - You may want to explicitly prevent a task from being put on a local queue. For example, you may know that a particular work item will run for a relatively long time and is likely to block all other work items on the local queue. In this case, you can specify the option, which provides a hint to the scheduler that an additional thread might be required for the task so that it does not block the forward progress of other threads or work items on the local queue. By using this option you avoid the thread pool completely, including the global and local queues. - - -### Task inlining - In some cases when a is waited on, it may be executed synchronously on the thread that is performing the wait operation. This enhances performance by preventing the need for an additional thread and instead using the existing thread, which would have blocked otherwise. To prevent errors due to reentrancy, task inlining only occurs when the wait target is found in the relevant thread's local queue. - - -## Specifying a synchronization context - You can use the method to specify that a task should be scheduled to run on a particular thread. This is useful in frameworks such as Windows Forms and Windows Presentation Foundation where access to user interface objects is often restricted to code that is running on the same thread on which the UI object was created. - - The following example uses the method in a Windows Presentation Foundation (WPF) app to schedule a task on the same thread that the user interface (UI) control was created on. The example creates a mosaic of images that are randomly selected from a specified directory. The WPF objects are used to load and resize the images. The raw pixels are then passed to a task that uses a loop to write the pixel data into a large single-byte array. No synchronization is required because no two tiles occupy the same array elements. The tiles can also be written in any order because their position is calculated independently of any other tile. The large array is then passed to a task that runs on the UI thread, where the pixel data is loaded into an Image control. - - The example moves data off the UI thread, modifies it by using parallel loops and objects, and then passes it back to a task that runs on the UI thread. This approach is useful when you have to use the Task Parallel Library to perform operations that either are not supported by the WPF API, or are not sufficiently fast. Another way to create an image mosaic in WPF is to use a control and add images to it. The handles the work of positioning the tiles. However, this work can only be performed on the UI thread. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskScheduler/FromCurrentSynchronizationContext/mainwindow.xaml.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpl_synccontext/vb/MainWindow.xaml.vb" id="Snippet01"::: - - To create the example, create a WPF application project in Visual Studio and name it WPF_CS1 (for a C# WPF project) or WPF_VB1 (for a Visual Basic WPF project). Then do the following: - -1. In design view, drag an control from the **Toolbox** onto the upper left corner of the design surface. In the **Name** textbox of the **Properties** window, name the control "image". - -2. Drag a control from the **Toolbox** to the lower left part of the application window. In XAML view, specify the property of the button as "Make a mosaic", and specify its property as "100". Connect the event with the `button_Click` event handler defined in the example's code by adding `Click="button_Click"` to the `